1/**
2 * Shared error type for encoding and decoding operations.
3 *
4 * @since 4.0.0
5 */
6import * as Data from "../Data.ts"
7import { hasProperty } from "../Predicate.ts"
8
9/**
10 * Type identifier stored on `EncodingError` values and used by
11 * `isEncodingError`.
12 *
13 * **When to use**
14 *
15 * Use when implementing low-level `EncodingError`-compatible values that need
16 * to carry the runtime marker.
17 *
18 * **Details**
19 *
20 * This marker is part of the runtime representation of `EncodingError`. Prefer
21 * `isEncodingError` when narrowing unknown values.
22 *
23 * @see {@link isEncodingError} for the public guard that checks this marker
24 *
25 * @category type IDs
26 * @since 4.0.0
27 */
28export const EncodingErrorTypeId = "~effect/encoding/EncodingError" as const
29
30/**
31 * Literal type of the `EncodingErrorTypeId` marker.
32 *
33 * **When to use**
34 *
35 * Use to type the marker carried by `EncodingError` values.
36 *
37 * @category type IDs
38 * @since 4.0.0
39 */
40export type EncodingErrorTypeId = typeof EncodingErrorTypeId
41
42/**
43 * Error returned when an encoding or decoding operation cannot process its input.
44 *
45 * **When to use**
46 *
47 * Use when you need to handle or inspect failures from encoding or decoding
48 * operations.
49 *
50 * **Details**
51 *
52 * The error records whether the failure happened during encoding or decoding,
53 * which encoding module reported it, the original input, and a human-readable
54 * message.
55 *
56 * @see {@link isEncodingError} for checking whether a value is an EncodingError
57 *
58 * @category errors
59 * @since 4.0.0
60 */
61export class EncodingError extends Data.TaggedError("EncodingError")<{
62 kind: "Decode" | "Encode"
63 module: string
64 input: unknown
65 message: string
66}> {
67 /**
68 * Marks this value as an encoding or decoding error for runtime guards.
69 *
70 * **When to use**
71 *
72 * Use to identify `EncodingError` instances through `isEncodingError`.
73 *
74 * @since 4.0.0
75 */
76 readonly [EncodingErrorTypeId]: EncodingErrorTypeId = EncodingErrorTypeId
77}
78
79/**
80 * Checks whether a value is an `EncodingError`.
81 *
82 * **When to use**
83 *
84 * Use to narrow an unknown value before handling it as an `EncodingError` from
85 * encoding or decoding code.
86 *
87 * **Details**
88 *
89 * Returns `true` when the value carries the `EncodingErrorTypeId` marker and
90 * narrows the value to `EncodingError`.
91 *
92 * @see {@link EncodingError} for the structured error produced by failed
93 * encoding and decoding operations
94 *
95 * @category guards
96 * @since 4.0.0
97 */
98export const isEncodingError = (u: unknown): u is EncodingError => hasProperty(u, EncodingErrorTypeId)