@evolu/common 8.0.0-next.4 → 8.0.0

package/src/Eq.ts

@@ -4,30 +4,85 @@
  * @module
  */
 
-import type { Order } from "./Order.js";
+import type { Order } from "./Order.ts";
 import type {
   JsonArray,
   JsonObject,
   JsonValue,
   JsonValueInput,
-} from "./Type.js";
+} 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 const eqStrict = <A>(x: A, y: A): boolean => 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 = <A>(x: A, y: A): boolean =>
+  x === y || Object.is(x, y);
+
+/** An {@link Eq} for strings using strict equality. */
 export const eqString: Eq<string> = eqStrict;
-export const eqNumber: Eq<number> = eqStrict;
+
+/** An {@link Eq} for numbers using {@link eqSameValueZero}. */
+export const eqNumber: Eq<number> = eqSameValueZero;
+
+/** An {@link Eq} for bigints using strict equality. */
 export const eqBigInt: Eq<bigint> = eqStrict;
+
+/** An {@link Eq} for booleans using strict equality. */
 export const eqBoolean: Eq<boolean> = eqStrict;
+
+/** An {@link Eq} for `undefined`. */
 export const eqUndefined: Eq<undefined> = eqStrict;
+
+/** An {@link Eq} for `null`. */
 export const eqNull: Eq<null> = eqStrict;
 
 /** Derives an {@link Eq} from an {@link Order}. */
@@ -43,10 +98,15 @@ export const eqFromOrder =
  * ### 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 =
@@ -70,10 +130,12 @@ export const createEqArrayLike =
  * ### 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);
@@ -84,9 +146,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);
@@ -98,9 +160,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 =
@@ -122,7 +187,8 @@ export const createEqObject =
  *
  * - 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.
@@ -130,9 +196,12 @@ export const createEqObject =
  * ### 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: JsonValue, b: JsonValue): boolean => {
@@ -212,7 +281,8 @@ export 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.
@@ -220,9 +290,12 @@ export 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 const eqJsonValueInput = (

package/src/Error.ts

@@ -4,7 +4,7 @@
  * @module
  */
 
-import type { Typed } from "./Type.js";
+import { type InferType, typed, type TypedType, Unknown } from "./Type.ts";
 
 /**
  * A wrapper for unknown errors caught at runtime.
@@ -18,9 +18,13 @@ import type { Typed } from "./Type.js";
  *
  * Use {@link createUnknownError} to create instances.
  */
-export interface UnknownError extends Typed<"UnknownError"> {
-  readonly error: unknown;
-}
+export const UnknownError: TypedType<
+  "UnknownError",
+  { readonly error: typeof Unknown }
+> = /*#__PURE__*/ typed("UnknownError", {
+  error: Unknown,
+});
+export interface UnknownError extends InferType<typeof UnknownError> {}
 
 /**
  * Creates an {@link UnknownError} from an unknown error.

package/src/Function.ts

@@ -4,6 +4,10 @@
  * @module
  */
 
+import { assertNotDisposed } from "./Assert.ts";
+import { isFunction } from "./Object.ts";
+import type { Writable } from "./Types.ts";
+
 /**
  * Helper function to ensure exhaustive matching in a switch statement. Throws
  * an error if an unhandled case is encountered.
@@ -11,32 +15,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";
@@ -51,11 +59,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 =
@@ -63,7 +71,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) {
@@ -78,12 +86,10 @@
  *       break;
  *   }
  *
- *   handleKind(result);
+ *   return result;
  * };
  *
- * const handleKind = (kind: "A" | "B" | "C"): void => {
- *   console.log(kind);
- * };
+ * expect(inputToKind({ type: "Query" })).toBe("B");
  * ```
  */
 export const exhaustiveCheck = (value: never): never => {
@@ -99,81 +105,181 @@ export 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 const identity = <A>(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 function disposable<T extends object>(
+  value: T extends Disposable ? Omit<T, typeof Symbol.dispose> : T,
+  disposer?: DisposableStack,
+): T extends Disposable ? T : T & Disposable;
+export function disposable<T extends object>(
+  value: T extends AsyncDisposable ? Omit<T, typeof Symbol.asyncDispose> : T,
+  disposer: AsyncDisposableStack,
+): T extends AsyncDisposable ? T : T & AsyncDisposable;
+export function disposable<T extends object>(
+  value: T,
+  disposer: DisposableStack | AsyncDisposableStack | null = null,
+): T & (Disposable | AsyncDisposable) {
+  const mutableValue = value as Writable<Record<string, unknown>>;
+  const ownedDisposer = disposer?.move() ?? new DisposableStack();
+
+  for (const [key, property] of Object.entries(value)) {
+    if (!isFunction(property)) continue;
+
+    mutableValue[key] = (...args: Array<unknown>): unknown => {
+      assertNotDisposed(ownedDisposer);
+      return (property as (...args: Array<unknown>) => unknown)(...args);
+    };
+  }
+
+  if (ownedDisposer instanceof AsyncDisposableStack) {
+    (value as T & AsyncDisposable)[Symbol.asyncDispose] = () =>
+      ownedDisposer.disposeAsync();
+  } else {
+    (value as T & Disposable)[Symbol.dispose] = () => ownedDisposer.dispose();
+  }
+
+  return value as T & (Disposable | AsyncDisposable);
+}
+
+export const isDisposable = (
+  value: unknown,
+): value is Disposable | AsyncDisposable => {
+  if (typeof value !== "object" || value === null) return false;
+
+  return (
+    isFunction((value as Partial<Disposable>)[Symbol.dispose]) ||
+    isFunction((value as Partial<AsyncDisposable>)[Symbol.asyncDispose])
+  );
+};
+
+/**
+ * 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 const lazy =
-  <T>(value: T): Lazy<T> =>
+export const constant =
+  <T>(value: T): Thunk<T> =>
   () =>
     value;
 
-/** A {@link Lazy} that returns `true`. */
-export const lazyTrue: Lazy<true> = /*#__PURE__*/ lazy(true);
+/** A {@link Thunk} that returns `true`. */
+export const constTrue: Thunk<true> = /*#__PURE__*/ constant(true);
 
-/** A {@link Lazy} that returns `false`. */
-export const lazyFalse: Lazy<false> = /*#__PURE__*/ lazy(false);
+/** A {@link Thunk} that returns `false`. */
+export const constFalse: Thunk<false> = /*#__PURE__*/ constant(false);
 
-/** A {@link Lazy} that returns `null`. */
-export const lazyNull: Lazy<null> = /*#__PURE__*/ lazy(null);
+/** A {@link Thunk} that returns `null`. */
+export const constNull: Thunk<null> = /*#__PURE__*/ constant(null);
 
-/** A {@link Lazy} that returns `undefined`. */
-export const lazyUndefined: Lazy<undefined> = /*#__PURE__*/ lazy(undefined);
+/** A {@link Thunk} that returns `undefined`. */
+export const constUndefined: Thunk<undefined> =
+  /*#__PURE__*/ constant(undefined);
 
-/** A {@link Lazy} that returns `undefined` for void callbacks. */
-export const lazyVoid: Lazy<void> = lazyUndefined;
+/** A {@link Thunk} that returns `undefined` for void callbacks. */
+export const constVoid: Thunk<void> = constUndefined;
 
 /**
  * Development placeholder that always throws.
@@ -185,17 +291,19 @@ export const lazyVoid: Lazy<void> = lazyUndefined;
  * ### 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");
  * ```
  */
 // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters