@evolu/common 8.0.0-next.5 → 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 InferType } from "./Type.js";
+import { type InferType, type TypedType, Unknown } from "./Type.ts";
 /**
  * A wrapper for unknown errors caught at runtime.
  *
@@ -16,8 +16,8 @@ import { type InferType } from "./Type.js";
  *
  * Use {@link createUnknownError} to create instances.
  */
-export declare const UnknownError: import("./Type.js").TypedType<"UnknownError", {
-    error: import("./Type.js").Type<"Unknown", unknown, unknown, never, unknown, never>;
+export declare const UnknownError: TypedType<"UnknownError", {
+    readonly error: typeof Unknown;
 }>;
 export interface UnknownError extends InferType<typeof UnknownError> {
 }

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,EAAE,KAAK,SAAS,EAAkB,MAAM,WAAW,CAAC;AAE3D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY;;EAEvB,CAAC;AACH,MAAM,WAAW,YAAa,SAAQ,SAAS,CAAC,OAAO,YAAY,CAAC;CAAG;AAEvE;;;;;;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/Function.d.ts

@@ -10,32 +10,36 @@
  * ### Example
  *
  * ```ts
+ * import { exhaustiveCheck } from "@evolu/common";
+ *
  * type Color = "red" | "green" | "blue";
+ * const handled: Array<string> = [];
  *
  * const handleColor = (color: Color): void => {
  *   switch (color) {
  *     case "red":
- *       console.log("Handling red");
+ *       handled.push("Handling red");
  *       break;
  *     case "green":
- *       console.log("Handling green");
+ *       handled.push("Handling green");
  *       break;
  *     case "blue":
- *       console.log("Handling blue");
+ *       handled.push("Handling blue");
  *       break;
  *     default:
- *       exhaustiveCheck(color); // Ensures all cases are handled
+ *       exhaustiveCheck(color);
  *   }
  * };
+ *
+ * handleColor("blue");
+ * expect(handled).toEqual(["Handling blue"]);
  * ```
  *
  * Use this primarily in side-effect switches (`void` branches). For
  * value-producing switches, TypeScript can enforce exhaustiveness without a
- * `default` branch.
- *
- * ### Example
+ * `default` branch in either of the following styles.
  *
- * Return from each case for value-producing switches.
+ * ### Return from every case
  *
  * ```ts
  * type Color = "red" | "green" | "blue";
@@ -50,11 +54,11 @@
  *       return "#0000ff";
  *   }
  * };
- * ```
  *
- * ### Example
+ * expect(colorToHex("green")).toBe("#00ff00");
+ * ```
  *
- * Use assignment + no `default` to get exhaustiveness by definite assignment.
+ * ### Assign in every case
  *
  * ```ts
  * type Input =
@@ -62,7 +66,7 @@
  *   | { readonly type: "Query" }
  *   | { readonly type: "Export" };
  *
- * const onInput = (input: Input): void => {
+ * const inputToKind = (input: Input): "A" | "B" | "C" => {
  *   let result: "A" | "B" | "C";
  *
  *   switch (input.type) {
@@ -77,12 +81,10 @@
  *       break;
  *   }
  *
- *   handleKind(result);
+ *   return result;
  * };
  *
- * const handleKind = (kind: "A" | "B" | "C"): void => {
- *   console.log(kind);
- * };
+ * expect(inputToKind({ type: "Query" })).toBe("B");
  * ```
  */
 export declare const exhaustiveCheck: (value: never) => never;
@@ -95,71 +97,128 @@ export declare const exhaustiveCheck: (value: never) => never;
  * ### Example
  *
  * ```ts
- * const values = [1, 2, 3];
- * const same = values.map(identity); // [1, 2, 3]
+ * import { identity } from "@evolu/common";
  *
+ * const values = [1, 2, 3];
+ * const object = { value: 1 };
  * const getTransform = (shouldDouble: boolean) =>
- *   shouldDouble ? (x: number) => x * 2 : identity;
+ *   shouldDouble ? (value: number) => value * 2 : identity;
+ *
+ * expect(values.map(identity)).toEqual([1, 2, 3]);
+ * expect(identity(object)).toBe(object);
+ * expect(getTransform(false)(2)).toBe(2);
  * ```
  */
 export declare const identity: <A>(a: A) => A;
 /**
- * A function that takes no arguments and returns a value of type T. Also known
- * as a thunk.
+ * Creates an object that follows JavaScript disposal semantics.
+ *
+ * The first argument is the object to make disposable. The returned object gets
+ * a disposal method and its functions are wrapped with a disposal guard. This
+ * is the JavaScript equivalent of .NET `ObjectDisposedException`: once an
+ * object has been disposed, calling its methods is a programmer error and
+ * should throw immediately instead of continuing with invalid state. Evolu
+ * asserts this invariant with the "Cannot use a disposed object." message.
+ *
+ * The second argument is an optional disposer. When provided, it is
+ * [moved](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DisposableStack/move)
+ * into the returned object, and the returned object's disposal method disposes
+ * it. Omit it when the object has no cleanup resources but still must become
+ * unusable after disposal, such as with reference count helpers where disposal
+ * enforces correct ownership tracking.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { disposable } from "@evolu/common";
+ *
+ * let cleaned = false;
+ * const createResource = () => {
+ *   using disposer = new DisposableStack();
+ *   disposer.defer(() => {
+ *     cleaned = true;
+ *   });
+ *   return disposable({ read: () => "ready" }, disposer);
+ * };
+ *
+ * const resource = createResource();
+ * expect(resource.read()).toBe("ready");
+ * resource[Symbol.dispose]();
+ *
+ * expect(cleaned).toBe(true);
+ * expect(() => resource.read()).toThrow("Cannot use a disposed object.");
+ * ```
+ */
+export declare function disposable<T extends object>(value: T extends Disposable ? Omit<T, typeof Symbol.dispose> : T, disposer?: DisposableStack): T extends Disposable ? T : T & Disposable;
+export declare function disposable<T extends object>(value: T extends AsyncDisposable ? Omit<T, typeof Symbol.asyncDispose> : T, disposer: AsyncDisposableStack): T extends AsyncDisposable ? T : T & AsyncDisposable;
+export declare const isDisposable: (value: unknown) => value is Disposable | AsyncDisposable;
+/**
+ * A function that takes no arguments and returns a value.
  *
  * Useful for:
  *
- * - Providing default callbacks (see {@link lazyVoid}, {@link lazyTrue}, etc.)
+ * - Providing default callbacks (see {@link constVoid}, {@link constTrue}, etc.)
  * - Delaying expensive operations until actually needed
  * - Deferring side effects so the callee controls when they run
  *
  * ### Example
  *
  * ```ts
- * // Default callback
- * const notify = (onDone: Lazy<void> = lazyVoid) => {
- *   onDone();
- * };
+ * import { constVoid, type Thunk } from "@evolu/common";
  *
- * // Delay computation
- * const getData: Lazy<Data> = () => compute();
- * const data = getData();
+ * const notify = (onDone: Thunk<void> = constVoid) => onDone();
+ * notify();
  *
- * // Defer side effects
- * const schedule = (job: Lazy<void>) => {
- *   queueMicrotask(job);
+ * let value = 0;
+ * const compute: Thunk<number> = () => ++value;
+ * const jobs: Array<Thunk<void>> = [];
+ * const schedule = (job: Thunk<void>): void => {
+ *   jobs.push(job);
  * };
- * schedule(() => logMetric("loaded"));
+ * schedule(() => {
+ *   value += 10;
+ * });
+ *
+ * const computed = compute();
+ * jobs.shift()?.();
+ * expect(computed).toBe(1);
+ * expect(value).toBe(11);
  * ```
  */
-export type Lazy<T> = () => T;
+export type Thunk<T> = () => T;
 /**
- * Creates a {@link Lazy} from a precomputed value.
+ * Creates a {@link Thunk} that always returns a precomputed value.
  *
- * Use when the value is expensive to compute and want to compute it once at
+ * Use when the value is expensive to compute and you want to compute it once at
  * definition time rather than on every call.
  *
  * ### Example
  *
  * ```ts
- * // Computed once at definition, returned on every call
- * const getConfig = lazy(parseConfig(rawConfig));
+ * import { constant } from "@evolu/common";
+ *
+ * let version = 0;
+ * const readConfig = () => ({ version: ++version });
+ * const getConstantConfig = constant(readConfig());
+ * const getFreshConfig = () => readConfig();
  *
- * // vs. computed on every call
- * const getConfig = () => parseConfig(rawConfig);
+ * expect(getConstantConfig()).toBe(getConstantConfig());
+ * expect(getConstantConfig().version).toBe(1);
+ * expect(getFreshConfig().version).toBe(2);
+ * expect(getFreshConfig().version).toBe(3);
  * ```
  */
-export declare const lazy: <T>(value: T) => Lazy<T>;
-/** A {@link Lazy} that returns `true`. */
-export declare const lazyTrue: Lazy<true>;
-/** A {@link Lazy} that returns `false`. */
-export declare const lazyFalse: Lazy<false>;
-/** A {@link Lazy} that returns `null`. */
-export declare const lazyNull: Lazy<null>;
-/** A {@link Lazy} that returns `undefined`. */
-export declare const lazyUndefined: Lazy<undefined>;
-/** A {@link Lazy} that returns `undefined` for void callbacks. */
-export declare const lazyVoid: Lazy<void>;
+export declare const constant: <T>(value: T) => Thunk<T>;
+/** A {@link Thunk} that returns `true`. */
+export declare const constTrue: Thunk<true>;
+/** A {@link Thunk} that returns `false`. */
+export declare const constFalse: Thunk<false>;
+/** A {@link Thunk} that returns `null`. */
+export declare const constNull: Thunk<null>;
+/** A {@link Thunk} that returns `undefined`. */
+export declare const constUndefined: Thunk<undefined>;
+/** A {@link Thunk} that returns `undefined` for void callbacks. */
+export declare const constVoid: Thunk<void>;
 /**
  * Development placeholder that always throws.
  *
@@ -170,17 +229,19 @@ export declare const lazyVoid: Lazy<void>;
  * ### Example
  *
  * ```ts
- * // Type inferred from return type annotation
- * const fetchUser = (id: UserId): Result<User, FetchError> => todo();
+ * import { todo } from "@evolu/common";
  *
- * expectTypeOf(fetchUser).returns.toEqualTypeOf<
- *   Result<User, FetchError>
- * >();
+ * interface Config {
+ *   readonly theme: string;
+ * }
  *
- * // Explicit generic when no return type
+ * const getCount = (): number => todo();
  * const getConfig = () => todo<Config>();
  *
- * expectTypeOf(getConfig).returns.toEqualTypeOf<Config>();
+ * expectTypeOf<
+ *   [ReturnType<typeof getCount>, ReturnType<typeof getConfig>]
+ * >().toEqualTypeOf<[number, Config]>();
+ * expect(getCount).toThrow("not yet implemented");
  * ```
  */
 export declare const todo: <T>() => T;

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

@@ -1 +1 @@
-{"version":3,"file":"Function.d.ts","sourceRoot":"","sources":["../../src/Function.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,KAAK,KAAG,KAE9C,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,GAAG,CAAC,KAAG,CAAM,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,IAAI,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC;AAE9B;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,IAAI,GACd,CAAC,EAAE,OAAO,CAAC,KAAG,IAAI,CAAC,CAAC,CAEd,CAAC;AAEV,0CAA0C;AAC1C,eAAO,MAAM,QAAQ,EAAE,IAAI,CAAC,IAAI,CAA4B,CAAC;AAE7D,2CAA2C;AAC3C,eAAO,MAAM,SAAS,EAAE,IAAI,CAAC,KAAK,CAA6B,CAAC;AAEhE,0CAA0C;AAC1C,eAAO,MAAM,QAAQ,EAAE,IAAI,CAAC,IAAI,CAA4B,CAAC;AAE7D,+CAA+C;AAC/C,eAAO,MAAM,aAAa,EAAE,IAAI,CAAC,SAAS,CAAiC,CAAC;AAE5E,kEAAkE;AAClE,eAAO,MAAM,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAiB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,eAAO,MAAM,IAAI,GAAI,CAAC,OAAK,CAE1B,CAAC"}
+{"version":3,"file":"Function.d.ts","sourceRoot":"","sources":["../../src/Function.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AACH,eAAO,MAAM,eAAe,UAAW,KAAK,KAAG,KAE9C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,KAAK,CAAC,KAAG,CAAM,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACzC,KAAK,EAAE,CAAC,SAAS,UAAU,GAAG,IAAI,CAAC,CAAC,EAAE,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAChE,QAAQ,CAAC,EAAE,eAAe,GACzB,CAAC,SAAS,UAAU,GAAG,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC;AAC7C,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACzC,KAAK,EAAE,CAAC,SAAS,eAAe,GAAG,IAAI,CAAC,CAAC,EAAE,OAAO,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,EAC1E,QAAQ,EAAE,oBAAoB,GAC7B,CAAC,SAAS,eAAe,GAAG,CAAC,GAAG,CAAC,GAAG,eAAe,CAAC;AA2BvD,eAAO,MAAM,YAAY,UAChB,OAAO,KACb,KAAK,IAAI,UAAU,GAAG,eAOxB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,QAAQ,GAClB,CAAC,SAAS,CAAC,KAAG,KAAK,CAAC,CAAC,CAEf,CAAC;AAEV,2CAA2C;AAC3C,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,IAAI,CAAgC,CAAC;AAEnE,4CAA4C;AAC5C,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,KAAK,CAAiC,CAAC;AAEtE,2CAA2C;AAC3C,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,IAAI,CAAgC,CAAC;AAEnE,gDAAgD;AAChD,eAAO,MAAM,cAAc,EAAE,KAAK,CAAC,SAAS,CACT,CAAC;AAEpC,mEAAmE;AACnE,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,IAAI,CAAkB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,eAAO,MAAM,IAAI,GAAI,CAAC,OAAK,CAE1B,CAAC"}