@evolu/common 8.0.0-next.4 → 8.0.0

package/dist/src/Eq.d.ts

@@ -3,22 +3,70 @@
  *
  * @module
  */
-import type { Order } from "./Order.js";
-import type { JsonValue, JsonValueInput } from "./Type.js";
+import type { Order } from "./Order.ts";
+import type { JsonValue, JsonValueInput } from "./Type.ts";
 /**
  * Compares two values of the same type `A` for equality.
  *
  * Equality functions start with an 'eq' prefix, e.g., `eqString`.
  *
- * TODO: Explain, examples (composition etc.)
+ * An `Eq` must define an equivalence relation over its intended domain:
+ *
+ * - **Reflexive**: `eq(a, a)` is `true`.
+ * - **Symmetric**: `eq(a, b)` equals `eq(b, a)`.
+ * - **Transitive**: if `eq(a, b)` and `eq(b, c)` are `true`, then `eq(a, c)` is
+ *   `true`.
+ *
+ * Use {@link eqFromOrder} to derive equality from an {@link Order}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { createEqObject, eqNumber } from "@evolu/common";
+ *
+ * const eqPoint = createEqObject({ x: eqNumber, y: eqNumber });
+ *
+ * expect(eqPoint({ x: 1, y: 2 }, { x: 1, y: 2 })).toBe(true);
+ * expect(eqPoint({ x: 1, y: 2 }, { x: 2, y: 1 })).toBe(false);
+ * ```
  */
 export type Eq<in A> = (x: A, y: A) => boolean;
+/**
+ * Compares two values with strict equality (`===`).
+ *
+ * Strict equality considers `NaN` unequal to itself. Use {@link eqSameValueZero}
+ * when values can contain `NaN` and equality must be reflexive.
+ */
 export declare const eqStrict: <A>(x: A, y: A) => boolean;
+/**
+ * Compares two values using SameValueZero equality.
+ *
+ * SameValueZero is the standard equality algorithm used by `Map`, `Set`, and
+ * `Array.prototype.includes`. It behaves like strict equality except that `NaN`
+ * equals itself. Both algorithms consider `0` and `-0` equal.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { eqSameValueZero } from "@evolu/common";
+ *
+ * expect(eqSameValueZero(NaN, NaN)).toBe(true);
+ * expect(eqSameValueZero(0, -0)).toBe(true);
+ * expect(eqSameValueZero({}, {})).toBe(false);
+ * ```
+ */
+export declare const eqSameValueZero: <A>(x: A, y: A) => boolean;
+/** An {@link Eq} for strings using strict equality. */
 export declare const eqString: Eq<string>;
+/** An {@link Eq} for numbers using {@link eqSameValueZero}. */
 export declare const eqNumber: Eq<number>;
+/** An {@link Eq} for bigints using strict equality. */
 export declare const eqBigInt: Eq<bigint>;
+/** An {@link Eq} for booleans using strict equality. */
 export declare const eqBoolean: Eq<boolean>;
+/** An {@link Eq} for `undefined`. */
 export declare const eqUndefined: Eq<undefined>;
+/** An {@link Eq} for `null`. */
 export declare const eqNull: Eq<null>;
 /** Derives an {@link Eq} from an {@link Order}. */
 export declare const eqFromOrder: <A>(order: Order<A>) => Eq<A>;
@@ -29,10 +77,15 @@ export declare const eqFromOrder: <A>(order: Order<A>) => Eq<A>;
  * ### Example
  *
  * ```ts
+ * import { createEqArrayLike, eqNumber } from "@evolu/common";
+ *
  * const eqArrayNumber = createEqArrayLike(eqNumber);
- * eqArrayNumber([1, 2, 3], [1, 2, 3]); // true (works with regular arrays)
- * eqArrayNumber(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3])); // true (works with Uint8Array)
- * eqArrayNumber([1, 2, 3], [1, 2, 4]); // false
+ *
+ * expect(eqArrayNumber([1, 2, 3], [1, 2, 3])).toBe(true);
+ * expect(
+ *   eqArrayNumber(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3])),
+ * ).toBe(true);
+ * expect(eqArrayNumber([1, 2, 3], [1, 2, 4])).toBe(false);
  * ```
  */
 export declare const createEqArrayLike: <A>(item: Eq<A>) => Eq<ArrayLike<A>>;
@@ -44,10 +97,12 @@ export declare const createEqArrayLike: <A>(item: Eq<A>) => Eq<ArrayLike<A>>;
  * ### Example
  *
  * ```ts
+ * import { eqArrayStrict } from "@evolu/common";
+ *
  * const a = { x: 1 };
  * const b = { x: 1 };
- * eqArrayStrict([a, a], [a, a]); // true (same references)
- * eqArrayStrict([a], [b]); // false (different references, even if equal values)
+ * expect(eqArrayStrict([a, a], [a, a])).toBe(true);
+ * expect(eqArrayStrict([a], [b])).toBe(false);
  * ```
  */
 export declare const eqArrayStrict: <A>(x: ArrayLike<A>, y: ArrayLike<A>) => boolean;
@@ -57,9 +112,9 @@ export declare const eqArrayStrict: <A>(x: ArrayLike<A>, y: ArrayLike<A>) => boo
  * ### Example
  *
  * ```ts
- * eqArrayNumber([1, 2, 3], [1, 2, 3]); // true (works with regular arrays)
- * eqArrayNumber(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3])); // true (works with Uint8Array)
- * eqArrayNumber([1, 2, 3], [1, 2, 4]); // false
+ * import { eqArrayNumber } from "@evolu/common";
+ *
+ * expect(eqArrayNumber([1, NaN], [1, NaN])).toBe(true);
  * ```
  */
 export declare const eqArrayNumber: Eq<ArrayLike<number>>;
@@ -70,9 +125,12 @@ export declare const eqArrayNumber: Eq<ArrayLike<number>>;
  * ### Example
  *
  * ```ts
+ * import { createEqObject, eqNumber } from "@evolu/common";
+ *
  * const eqObjectNumber = createEqObject({ a: eqNumber });
- * eqObjectNumber({ a: 1 }, { a: 1 }); // true
- * eqObjectNumber({ a: 1 }, { a: 2 }); // false
+ *
+ * expect(eqObjectNumber({ a: 1 }, { a: 1 })).toBe(true);
+ * expect(eqObjectNumber({ a: 1 }, { a: 2 })).toBe(false);
  * ```
  */
 export declare const createEqObject: <A>(eqs: { [K in keyof A]: Eq<A[K]>; }) => Eq<{ readonly [K in keyof A]: A[K]; }>;
@@ -81,7 +139,8 @@ export declare const createEqObject: <A>(eqs: { [K in keyof A]: Eq<A[K]>; }) =>
  *
  * - Uses an iterative approach with a stack to handle large or deeply nested
  *   objects without risking stack overflow.
- * - Handles circular references with a WeakMap to prevent infinite loops.
+ * - Defensively handles circular references in runtime values without looping,
+ *   although cyclic values are not valid JSON.
  * - Unlike JSON.stringify, this function directly compares values, avoiding
  *   serialization overhead and leveraging short-circuit evaluation for faster
  *   failure on mismatched structures.
@@ -89,9 +148,12 @@ export declare const createEqObject: <A>(eqs: { [K in keyof A]: Eq<A[K]>; }) =>
  * ### Example
  *
  * ```ts
- * const obj1: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
- * const obj2: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
- * console.log(eqJson(obj1, obj2)); // true
+ * import { eqJsonValue, type JsonValue } from "@evolu/common";
+ *
+ * const first: JsonValue = { profile: { name: "Ada" } };
+ * const second: JsonValue = { profile: { name: "Ada" } };
+ *
+ * expect(eqJsonValue(first, second)).toBe(true);
  * ```
  */
 export declare const eqJsonValue: (a: JsonValue, b: JsonValue) => boolean;
@@ -100,7 +162,8 @@ export declare const eqJsonValue: (a: JsonValue, b: JsonValue) => boolean;
  *
  * - Uses an iterative approach with a stack to handle large or deeply nested
  *   objects without risking stack overflow.
- * - Handles circular references with a WeakMap to prevent infinite loops.
+ * - Defensively handles circular references in runtime values without looping,
+ *   although cyclic values are not valid JSON.
  * - Unlike JSON.stringify, this function directly compares values, avoiding
  *   serialization overhead and leveraging short-circuit evaluation for faster
  *   failure on mismatched structures.
@@ -108,9 +171,12 @@ export declare const eqJsonValue: (a: JsonValue, b: JsonValue) => boolean;
  * ### Example
  *
  * ```ts
- * const obj1: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
- * const obj2: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
- * console.log(eqJson(obj1, obj2)); // true
+ * import { eqJsonValueInput, type JsonValueInput } from "@evolu/common";
+ *
+ * const first: JsonValueInput = { profile: { name: "Ada" } };
+ * const second: JsonValueInput = { profile: { name: "Ada" } };
+ *
+ * expect(eqJsonValueInput(first, second)).toBe(true);
  * ```
  */
 export declare const eqJsonValueInput: (a: JsonValueInput, b: JsonValueInput) => boolean;

package/dist/src/Eq.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Eq.d.ts","sourceRoot":"","sources":["../../src/Eq.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAGV,SAAS,EACT,cAAc,EACf,MAAM,WAAW,CAAC;AAEnB;;;;;;GAMG;AACH,MAAM,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;AAE/C,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,GAAG,CAAC,EAAE,GAAG,CAAC,KAAG,OAAkB,CAAC;AAE5D,eAAO,MAAM,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAY,CAAC;AAC7C,eAAO,MAAM,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAY,CAAC;AAC7C,eAAO,MAAM,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAY,CAAC;AAC7C,eAAO,MAAM,SAAS,EAAE,EAAE,CAAC,OAAO,CAAY,CAAC;AAC/C,eAAO,MAAM,WAAW,EAAE,EAAE,CAAC,SAAS,CAAY,CAAC;AACnD,eAAO,MAAM,MAAM,EAAE,EAAE,CAAC,IAAI,CAAY,CAAC;AAEzC,mDAAmD;AACnD,eAAO,MAAM,WAAW,GACrB,CAAC,EAAE,OAAO,KAAK,CAAC,CAAC,CAAC,KAAG,EAAE,CAAC,CAAC,CAEP,CAAC;AAEtB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,GAC3B,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,KAAG,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAUhC,CAAC;AAEJ;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa,GAvDD,CAAC,uCAFa,OAyD+B,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,uBAA4C,CAAC;AAEvE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,GACxB,CAAC,EAAE,KAAK,GAAG,CAAC,IAAI,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAE,KAAG,EAAE,CAAC,EACzC,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAC9B,CASA,CAAC;AAEJ;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,WAAW,GAAI,GAAG,SAAS,EAAE,GAAG,SAAS,KAAG,OAsExD,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,gBAAgB,GAC3B,GAAG,cAAc,EACjB,GAAG,cAAc,KAChB,OAAsD,CAAC"}
+{"version":3,"file":"Eq.d.ts","sourceRoot":"","sources":["../../src/Eq.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAGV,SAAS,EACT,cAAc,EACf,MAAM,WAAW,CAAC;AAEnB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAG,OAAkB,CAAC;AAE5D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAG,OACpB,CAAC;AAE7B,uDAAuD;AACvD,eAAO,MAAM,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAY,CAAC;AAE7C,+DAA+D;AAC/D,eAAO,MAAM,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAmB,CAAC;AAEpD,uDAAuD;AACvD,eAAO,MAAM,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAY,CAAC;AAE7C,wDAAwD;AACxD,eAAO,MAAM,SAAS,EAAE,EAAE,CAAC,OAAO,CAAY,CAAC;AAE/C,qCAAqC;AACrC,eAAO,MAAM,WAAW,EAAE,EAAE,CAAC,SAAS,CAAY,CAAC;AAEnD,gCAAgC;AAChC,eAAO,MAAM,MAAM,EAAE,EAAE,CAAC,IAAI,CAAY,CAAC;AAEzC,mDAAmD;AACnD,eAAO,MAAM,WAAW,GACrB,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,KAAG,EAAE,CAAC,CAAC,CAEP,CAAC;AAEtB;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,iBAAiB,GAC3B,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,KAAG,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAUhC,CAAC;AAEJ;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,aAAa,GA7FD,CAAC,uCARa,OAqG+B,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,uBAA4C,CAAC;AAEvE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,GACxB,CAAC,OAAO,GAAG,CAAC,IAAI,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAE,KAAG,EAAE,CAAC,EACzC,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAC9B,CASA,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,WAAW,MAAO,SAAS,KAAK,SAAS,KAAG,OAsExD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,gBAAgB,MACxB,cAAc,KACd,cAAc,KAChB,OAAsD,CAAC"}

package/dist/src/Eq.js

@@ -3,12 +3,42 @@
  *
  * @module
  */
+/**
+ * Compares two values with strict equality (`===`).
+ *
+ * Strict equality considers `NaN` unequal to itself. Use {@link eqSameValueZero}
+ * when values can contain `NaN` and equality must be reflexive.
+ */
 export const eqStrict = (x, y) => x === y;
+/**
+ * Compares two values using SameValueZero equality.
+ *
+ * SameValueZero is the standard equality algorithm used by `Map`, `Set`, and
+ * `Array.prototype.includes`. It behaves like strict equality except that `NaN`
+ * equals itself. Both algorithms consider `0` and `-0` equal.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { eqSameValueZero } from "@evolu/common";
+ *
+ * expect(eqSameValueZero(NaN, NaN)).toBe(true);
+ * expect(eqSameValueZero(0, -0)).toBe(true);
+ * expect(eqSameValueZero({}, {})).toBe(false);
+ * ```
+ */
+export const eqSameValueZero = (x, y) => x === y || Object.is(x, y);
+/** An {@link Eq} for strings using strict equality. */
 export const eqString = eqStrict;
-export const eqNumber = eqStrict;
+/** An {@link Eq} for numbers using {@link eqSameValueZero}. */
+export const eqNumber = eqSameValueZero;
+/** An {@link Eq} for bigints using strict equality. */
 export const eqBigInt = eqStrict;
+/** An {@link Eq} for booleans using strict equality. */
 export const eqBoolean = eqStrict;
+/** An {@link Eq} for `undefined`. */
 export const eqUndefined = eqStrict;
+/** An {@link Eq} for `null`. */
 export const eqNull = eqStrict;
 /** Derives an {@link Eq} from an {@link Order}. */
 export const eqFromOrder = (order) => (x, y) => order(x, y) === 0;
@@ -19,10 +49,15 @@ export const eqFromOrder = (order) => (x, y) => order(x, y) === 0;
  * ### Example
  *
  * ```ts
+ * import { createEqArrayLike, eqNumber } from "@evolu/common";
+ *
  * const eqArrayNumber = createEqArrayLike(eqNumber);
- * eqArrayNumber([1, 2, 3], [1, 2, 3]); // true (works with regular arrays)
- * eqArrayNumber(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3])); // true (works with Uint8Array)
- * eqArrayNumber([1, 2, 3], [1, 2, 4]); // false
+ *
+ * expect(eqArrayNumber([1, 2, 3], [1, 2, 3])).toBe(true);
+ * expect(
+ *   eqArrayNumber(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3])),
+ * ).toBe(true);
+ * expect(eqArrayNumber([1, 2, 3], [1, 2, 4])).toBe(false);
  * ```
  */
 export const createEqArrayLike = (item) => (x, y) => {
@@ -44,10 +79,12 @@ export const createEqArrayLike = (item) => (x, y) => {
  * ### Example
  *
  * ```ts
+ * import { eqArrayStrict } from "@evolu/common";
+ *
  * const a = { x: 1 };
  * const b = { x: 1 };
- * eqArrayStrict([a, a], [a, a]); // true (same references)
- * eqArrayStrict([a], [b]); // false (different references, even if equal values)
+ * expect(eqArrayStrict([a, a], [a, a])).toBe(true);
+ * expect(eqArrayStrict([a], [b])).toBe(false);
  * ```
  */
 export const eqArrayStrict = /*#__PURE__*/ createEqArrayLike(eqStrict);
@@ -57,9 +94,9 @@ export const eqArrayStrict = /*#__PURE__*/ createEqArrayLike(eqStrict);
  * ### Example
  *
  * ```ts
- * eqArrayNumber([1, 2, 3], [1, 2, 3]); // true (works with regular arrays)
- * eqArrayNumber(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3])); // true (works with Uint8Array)
- * eqArrayNumber([1, 2, 3], [1, 2, 4]); // false
+ * import { eqArrayNumber } from "@evolu/common";
+ *
+ * expect(eqArrayNumber([1, NaN], [1, NaN])).toBe(true);
  * ```
  */
 export const eqArrayNumber = /*#__PURE__*/ createEqArrayLike(eqNumber);
@@ -70,9 +107,12 @@ export const eqArrayNumber = /*#__PURE__*/ createEqArrayLike(eqNumber);
  * ### Example
  *
  * ```ts
+ * import { createEqObject, eqNumber } from "@evolu/common";
+ *
  * const eqObjectNumber = createEqObject({ a: eqNumber });
- * eqObjectNumber({ a: 1 }, { a: 1 }); // true
- * eqObjectNumber({ a: 1 }, { a: 2 }); // false
+ *
+ * expect(eqObjectNumber({ a: 1 }, { a: 1 })).toBe(true);
+ * expect(eqObjectNumber({ a: 1 }, { a: 2 })).toBe(false);
  * ```
  */
 export const createEqObject = (eqs) => (x, y) => {
@@ -90,7 +130,8 @@ export const createEqObject = (eqs) => (x, y) => {
  *
  * - Uses an iterative approach with a stack to handle large or deeply nested
  *   objects without risking stack overflow.
- * - Handles circular references with a WeakMap to prevent infinite loops.
+ * - Defensively handles circular references in runtime values without looping,
+ *   although cyclic values are not valid JSON.
  * - Unlike JSON.stringify, this function directly compares values, avoiding
  *   serialization overhead and leveraging short-circuit evaluation for faster
  *   failure on mismatched structures.
@@ -98,9 +139,12 @@ export const createEqObject = (eqs) => (x, y) => {
  * ### Example
  *
  * ```ts
- * const obj1: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
- * const obj2: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
- * console.log(eqJson(obj1, obj2)); // true
+ * import { eqJsonValue, type JsonValue } from "@evolu/common";
+ *
+ * const first: JsonValue = { profile: { name: "Ada" } };
+ * const second: JsonValue = { profile: { name: "Ada" } };
+ *
+ * expect(eqJsonValue(first, second)).toBe(true);
  * ```
  */
 export const eqJsonValue = (a, b) => {
@@ -171,7 +215,8 @@ export const eqJsonValue = (a, b) => {
  *
  * - Uses an iterative approach with a stack to handle large or deeply nested
  *   objects without risking stack overflow.
- * - Handles circular references with a WeakMap to prevent infinite loops.
+ * - Defensively handles circular references in runtime values without looping,
+ *   although cyclic values are not valid JSON.
  * - Unlike JSON.stringify, this function directly compares values, avoiding
  *   serialization overhead and leveraging short-circuit evaluation for faster
  *   failure on mismatched structures.
@@ -179,9 +224,12 @@ export const eqJsonValue = (a, b) => {
  * ### Example
  *
  * ```ts
- * const obj1: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
- * const obj2: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
- * console.log(eqJson(obj1, obj2)); // true
+ * import { eqJsonValueInput, type JsonValueInput } from "@evolu/common";
+ *
+ * const first: JsonValueInput = { profile: { name: "Ada" } };
+ * const second: JsonValueInput = { profile: { name: "Ada" } };
+ *
+ * expect(eqJsonValueInput(first, second)).toBe(true);
  * ```
  */
 export const eqJsonValueInput = (a, b) => eqJsonValue(a, b);

package/dist/src/Error.d.ts

@@ -3,7 +3,7 @@
  *
  * @module
  */
-import type { Typed } from "./Type.js";
+import { type InferType, type TypedType, Unknown } from "./Type.ts";
 /**
  * A wrapper for unknown errors caught at runtime.
  *
@@ -16,8 +16,10 @@ import type { Typed } from "./Type.js";
  *
  * Use {@link createUnknownError} to create instances.
  */
-export interface UnknownError extends Typed<"UnknownError"> {
-    readonly error: unknown;
+export declare const UnknownError: TypedType<"UnknownError", {
+    readonly error: typeof Unknown;
+}>;
+export interface UnknownError extends InferType<typeof UnknownError> {
 }
 /**
  * Creates an {@link UnknownError} from an unknown error.

package/dist/src/Error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Error.d.ts","sourceRoot":"","sources":["../../src/Error.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAEvC;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAa,SAAQ,KAAK,CAAC,cAAc,CAAC;IACzD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,OAAO,KAAG,YAkDnD,CAAC"}
+{"version":3,"file":"Error.d.ts","sourceRoot":"","sources":["../../src/Error.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAS,KAAK,SAAS,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE3E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,CAClC,cAAc,EACd;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,OAAO,CAAA;CAAE,CAGlC,CAAC;AACH,MAAM,WAAW,YAAa,SAAQ,SAAS,CAAC,OAAO,YAAY,CAAC;CAAG;AAEvE;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,UAAW,OAAO,KAAG,YAkDnD,CAAC"}

package/dist/src/Error.js

@@ -3,6 +3,22 @@
  *
  * @module
  */
+import { typed, Unknown } from "./Type.js";
+/**
+ * A wrapper for unknown errors caught at runtime.
+ *
+ * When catching errors from unsafe code (third-party libraries, worker
+ * boundaries, etc.), we wrap them in `UnknownError` so they can be used in
+ * union types and distinguished from other error types.
+ *
+ * The `error` property contains error details (including `message`, `stack`,
+ * and `cause` if available), a string, or a fallback value.
+ *
+ * Use {@link createUnknownError} to create instances.
+ */
+export const UnknownError = /*#__PURE__*/ typed("UnknownError", {
+    error: Unknown,
+});
 /**
  * Creates an {@link UnknownError} from an unknown error.
  *