@evolu/common 7.4.1 → 8.0.0-next.0

package/dist/src/Crypto.js

@@ -1,7 +1,7 @@
 /**
- * Cryptographic utilities
+ * Cryptographic utilities.
  *
- * Type-safe cryptographic operations including random number generation, SLIP21
+ * Type-safe cryptographic operations including random bytes generation, SLIP21
  * key derivation, XChaCha20-Poly1305 symmetric encryption, PADMÉ padding, and
  * timing-safe comparisons.
  *
@@ -11,15 +11,24 @@ import { xchacha20poly1305 } from "@noble/ciphers/chacha.js";
 import { hmac } from "@noble/hashes/hmac.js";
 import { sha512 } from "@noble/hashes/sha2.js";
 import { randomBytes, utf8ToBytes } from "@noble/hashes/utils.js";
+import { arrayFrom } from "./Array.js";
 import { trySync } from "./Result.js";
-import { brand, length, NonNegativeInt, Uint8Array } from "./Type.js";
-const Entropy = brand("Entropy", Uint8Array);
-export const Entropy16 = length(16)(Entropy);
-export const Entropy32 = length(32)(Entropy);
-export const Entropy64 = length(64)(Entropy);
+import { brand, length, NonNegativeInt, Uint8Array, zeroNonNegativeInt, } from "./Type.js";
+const Entropy = /*#__PURE__*/ brand("Entropy", Uint8Array);
+export const Entropy16 = /*#__PURE__*/ length(16)(Entropy);
+export const Entropy24 = /*#__PURE__*/ length(24)(Entropy);
+export const Entropy32 = /*#__PURE__*/ length(32)(Entropy);
+export const Entropy64 = /*#__PURE__*/ length(64)(Entropy);
 export const createRandomBytes = () => ({
     create: randomBytes,
 });
+/** Creates seeded random bytes for deterministic tests. */
+export const testCreateRandomBytes = (deps) => ({
+    create: (bytesLength) => {
+        const array = arrayFrom(bytesLength, () => deps.randomLib.int(0, 255));
+        return new globalThis.Uint8Array(array);
+    },
+});
 /**
  * SLIP21.
  *
@@ -45,29 +54,65 @@ export const deriveSlip21Node = (label, parentNode) => {
     message.set(labelBytes, 1);
     return hmac(sha512, parentNode.slice(0, 32), message);
 };
-/** The encryption key for {@link SymmetricCrypto}. */
-export const EncryptionKey = brand("EncryptionKey", Entropy32);
+/** The encryption key for symmetric encryption. */
+export const EncryptionKey = /*#__PURE__*/ brand("EncryptionKey", Entropy32);
+/** The nonce length for XChaCha20-Poly1305 encryption. */
+export const xChaCha20Poly1305NonceLength = 24;
+/**
+ * Branded Uint8Array for XChaCha20-Poly1305 encryption.
+ *
+ * @see {@link encryptWithXChaCha20Poly1305}
+ */
+export const XChaCha20Poly1305Ciphertext = /*#__PURE__*/ brand("XChaCha20Poly1305Ciphertext", Uint8Array);
 /**
- * XChaCha20-Poly1305 encryption
+ * Encrypts plaintext with XChaCha20-Poly1305.
+ *
+ * Generates a random nonce internally and returns both the ciphertext and
+ * nonce. The nonce must be stored alongside the ciphertext for decryption.
+ *
+ * ### Example
  *
- * https://github.com/paulmillr/noble-ciphers?tab=readme-ov-file#which-cipher-should-i-pick
+ * ```ts
+ * const deps = { randomBytes: createRandomBytes() };
+ * const [ciphertext, nonce] = encryptWithXChaCha20Poly1305(deps)(
+ *   utf8ToBytes("secret message"),
+ *   encryptionKey,
+ * );
+ * ```
+ *
+ * @see https://github.com/paulmillr/noble-ciphers
  */
-export const createSymmetricCrypto = (deps) => {
-    const nonceLength = NonNegativeInt.orThrow(24);
-    const symmetricCrypto = {
-        nonceLength,
-        encrypt: (plaintext, encryptionKey) => {
-            const nonce = deps.randomBytes.create(nonceLength);
-            const ciphertext = xchacha20poly1305(encryptionKey, nonce).encrypt(plaintext);
-            return { nonce, ciphertext };
-        },
-        decrypt: (ciphertext, encryptionKey, nonce) => trySync(() => xchacha20poly1305(encryptionKey, nonce).decrypt(ciphertext), (error) => ({
-            type: "SymmetricCryptoDecryptError",
-            error,
-        })),
-    };
-    return symmetricCrypto;
+export const encryptWithXChaCha20Poly1305 = (deps) => (plaintext, encryptionKey) => {
+    const nonce = deps.randomBytes.create(xChaCha20Poly1305NonceLength);
+    const ciphertext = XChaCha20Poly1305Ciphertext.orThrow(xchacha20poly1305(encryptionKey, nonce).encrypt(plaintext));
+    return [ciphertext, nonce];
 };
+/**
+ * Decrypts ciphertext with XChaCha20-Poly1305.
+ *
+ * Requires the same nonce that was used during encryption. Returns a
+ * {@link Result} that may contain a decryption error if the ciphertext was
+ * tampered with or the wrong key/nonce was used.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const result = decryptWithXChaCha20Poly1305(
+ *   ciphertext,
+ *   nonce,
+ *   encryptionKey,
+ * );
+ * if (!result.ok) {
+ *   // Handle decryption error
+ *   return result;
+ * }
+ * const plaintext = result.value;
+ * ```
+ */
+export const decryptWithXChaCha20Poly1305 = (ciphertext, nonce, encryptionKey) => trySync(() => xchacha20poly1305(encryptionKey, nonce).decrypt(ciphertext), (error) => ({
+    type: "DecryptWithXChaCha20Poly1305Error",
+    error,
+}));
 /**
  * Returns the PADMÉ padded length for a given input length.
  *
@@ -78,7 +123,7 @@ export const createSymmetricCrypto = (deps) => {
  */
 export const createPadmePaddedLength = (length) => {
     if (length <= 0)
-        return NonNegativeInt.orThrow(0);
+        return zeroNonNegativeInt;
     const e = 31 - Math.clz32(length >>> 0);
     const s = 32 - Math.clz32(e >>> 0);
     const z = Math.max(0, e - s);

package/dist/src/Eq.d.ts

@@ -1,5 +1,10 @@
-import { JsonValue, JsonValueInput } from "./Type.js";
-import { Order } from "./Order.js";
+/**
+ * Equality comparison functions and utilities.
+ *
+ * @module
+ */
+import type { Order } from "./Order.js";
+import type { JsonValue, JsonValueInput } from "./Type.js";
 /**
  * Compares two values of the same type `A` for equality.
  *
@@ -31,6 +36,21 @@ export declare const eqFromOrder: <A>(order: Order<A>) => Eq<A>;
  * ```
  */
 export declare const createEqArrayLike: <A>(item: Eq<A>) => Eq<ArrayLike<A>>;
+/**
+ * Compares two array-like structures by strict reference equality (`===`).
+ *
+ * Useful for structural sharing checks where elements are compared by identity.
+ *
+ * ### Example
+ *
+ * ```ts
+ * 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)
+ * ```
+ */
+export declare const eqArrayStrict: <A>(x: ArrayLike<A>, y: ArrayLike<A>) => boolean;
 /**
  * Compares two array-like structures of numbers for equality.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"Eq.d.ts","sourceRoot":"","sources":["../../src/Eq.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,SAAS,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC7E,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC;;;;;;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;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,uBAA8B,CAAC;AAEzD;;;;;;;;;;;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;;;;;;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"}

package/dist/src/Eq.js

@@ -1,3 +1,8 @@
+/**
+ * Equality comparison functions and utilities.
+ *
+ * @module
+ */
 export const eqStrict = (x, y) => x === y;
 export const eqString = eqStrict;
 export const eqNumber = eqStrict;
@@ -31,6 +36,21 @@ export const createEqArrayLike = (item) => (x, y) => {
     }
     return true;
 };
+/**
+ * Compares two array-like structures by strict reference equality (`===`).
+ *
+ * Useful for structural sharing checks where elements are compared by identity.
+ *
+ * ### Example
+ *
+ * ```ts
+ * 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)
+ * ```
+ */
+export const eqArrayStrict = /*#__PURE__*/ createEqArrayLike(eqStrict);
 /**
  * Compares two array-like structures of numbers for equality.
  *
@@ -42,7 +62,7 @@ export const createEqArrayLike = (item) => (x, y) => {
  * eqArrayNumber([1, 2, 3], [1, 2, 4]); // false
  * ```
  */
-export const eqArrayNumber = createEqArrayLike(eqNumber);
+export const eqArrayNumber = /*#__PURE__*/ createEqArrayLike(eqNumber);
 /**
  * Creates an equivalence function for objects based on an equivalence for their
  * fields.

package/dist/src/Error.d.ts

@@ -1,19 +1,30 @@
 /**
- * A serializable representation of an error for safe transfer between execution
- * contexts, such as Web Workers and the main thread.
+ * Error types and utilities for safe error handling.
  *
- * Use this type for unknown (unexpected) errors that need to be transferred
- * across boundaries where native Error objects cannot be sent directly. Not
- * intended for regular (expected) errors.
+ * @module
+ */
+import type { Typed } 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.
  *
- * The `error` property contains a plain object with error details, a string, or
- * a fallback value if serialization fails to preserve as much debugging
- * information as possible.
+ * Use {@link createUnknownError} to create instances.
  */
-export interface TransferableError {
-    readonly type: "TransferableError";
+export interface UnknownError extends Typed<"UnknownError"> {
     readonly error: unknown;
 }
-/** Creates a {@link TransferableError} from an unknown error. */
-export declare const createTransferableError: (error: unknown) => TransferableError;
+/**
+ * Creates an {@link UnknownError} from an unknown error.
+ *
+ * Error objects cannot be directly structured-cloned (for worker messaging) or
+ * JSON-serialized because their properties (`message`, `stack`, `cause`) are
+ * non-enumerable. This function extracts those properties into a plain object.
+ */
+export declare const createUnknownError: (error: unknown) => UnknownError;
 //# sourceMappingURL=Error.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Error.d.ts","sourceRoot":"","sources":["../../src/Error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,iEAAiE;AACjE,eAAO,MAAM,uBAAuB,GAAI,OAAO,OAAO,KAAG,iBA+CxD,CAAC"}
+{"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"}

package/dist/src/Error.js

@@ -1,7 +1,18 @@
-/** Creates a {@link TransferableError} from an unknown error. */
-export const createTransferableError = (error) => {
+/**
+ * Error types and utilities for safe error handling.
+ *
+ * @module
+ */
+/**
+ * Creates an {@link UnknownError} from an unknown error.
+ *
+ * Error objects cannot be directly structured-cloned (for worker messaging) or
+ * JSON-serialized because their properties (`message`, `stack`, `cause`) are
+ * non-enumerable. This function extracts those properties into a plain object.
+ */
+export const createUnknownError = (error) => {
     const convertError = (err) => {
-        const transferableError = Object.getOwnPropertyNames(err).reduce((acc, key) => {
+        const result = Object.getOwnPropertyNames(err).reduce((acc, key) => {
             const value = err[key];
             if (key === "cause" && value instanceof Error) {
                 // Recursively process the `cause` property
@@ -12,33 +23,38 @@ export const createTransferableError = (error) => {
             }
             return acc;
         }, {});
-        return transferableError;
+        // Firefox defines `stack` as a getter on Error.prototype, not as an own
+        // property, so getOwnPropertyNames misses it. Explicitly include it.
+        if (err.stack !== undefined && !("stack" in result)) {
+            result.stack = err.stack;
+        }
+        return result;
     };
     if (error instanceof Error) {
         return {
-            type: "TransferableError",
+            type: "UnknownError",
             error: convertError(error),
         };
     }
     try {
-        // Clone other values that are transferable
+        // Clone other values that are structured-clonable
         return {
-            type: "TransferableError",
+            type: "UnknownError",
             error: structuredClone(error),
         };
     }
     catch {
-        // Fallback for non-transferable or problematic values
+        // Fallback for non-clonable values
         try {
             return {
-                type: "TransferableError",
-                error: String(error), // Attempt to convert to a string
+                type: "UnknownError",
+                error: String(error),
             };
         }
         catch {
             // Final fallback if even `String(error)` fails
             return {
-                type: "TransferableError",
+                type: "UnknownError",
                 error: "[Unserializable Object]",
             };
         }

package/dist/src/Function.d.ts

@@ -1,18 +1,18 @@
-import { NonEmptyArray, NonEmptyReadonlyArray } from "./Array.js";
-import { ReadonlyRecord } from "./Object.js";
+/**
+ * Function utilities including exhaustive checks and composition.
+ *
+ * @module
+ */
 /**
  * Helper function to ensure exhaustive matching in a switch statement. Throws
  * an error if an unhandled case is encountered.
  *
- * Remember, it's useful only when we don't return anything from the switch
- * statement. Otherwise, a return type of a function is enough.
- *
  * ### Example
  *
  * ```ts
  * type Color = "red" | "green" | "blue";
  *
- * function handleColor(color: Color): void {
+ * const handleColor = (color: Color): void => {
  *   switch (color) {
  *     case "red":
  *       console.log("Handling red");
@@ -26,12 +26,68 @@ import { ReadonlyRecord } from "./Object.js";
  *     default:
  *       exhaustiveCheck(color); // Ensures all cases are handled
  *   }
- * }
+ * };
+ * ```
+ *
+ * Use this primarily in side-effect switches (`void` branches). For
+ * value-producing switches, TypeScript can enforce exhaustiveness without a
+ * `default` branch.
+ *
+ * ### Example
+ *
+ * Return from each case for value-producing switches.
+ *
+ * ```ts
+ * type Color = "red" | "green" | "blue";
+ *
+ * const colorToHex = (color: Color): string => {
+ *   switch (color) {
+ *     case "red":
+ *       return "#ff0000";
+ *     case "green":
+ *       return "#00ff00";
+ *     case "blue":
+ *       return "#0000ff";
+ *   }
+ * };
+ * ```
+ *
+ * ### Example
+ *
+ * Use assignment + no `default` to get exhaustiveness by definite assignment.
+ *
+ * ```ts
+ * type Input =
+ *   | { readonly type: "Mutate" }
+ *   | { readonly type: "Query" }
+ *   | { readonly type: "Export" };
+ *
+ * const onInput = (input: Input): void => {
+ *   let result: "A" | "B" | "C";
+ *
+ *   switch (input.type) {
+ *     case "Mutate":
+ *       result = "A";
+ *       break;
+ *     case "Query":
+ *       result = "B";
+ *       break;
+ *     case "Export":
+ *       result = "C";
+ *       break;
+ *   }
+ *
+ *   handleKind(result);
+ * };
+ *
+ * const handleKind = (kind: "A" | "B" | "C"): void => {
+ *   console.log(kind);
+ * };
  * ```
  */
 export declare const exhaustiveCheck: (value: never) => never;
 /**
- * Returns the input value unchanged.
+ * Returns the value unchanged.
  *
  * Useful as a default transformation, placeholder callback, or when a function
  * is required but no transformation is needed.
@@ -48,68 +104,84 @@ export declare const exhaustiveCheck: (value: never) => never;
  */
 export declare const identity: <A>(a: A) => A;
 /**
- * Casts an array, set, record, or map to its readonly counterpart.
+ * A function that takes no arguments and returns a value of type T. Also known
+ * as a thunk.
+ *
+ * Useful for:
  *
- * Zero runtime cost — returns the same value with a readonly type. Use this to
- * enforce immutability at the type level. Preserves {@link NonEmptyArray} as
- * {@link NonEmptyReadonlyArray}.
+ * - Providing default callbacks (see {@link lazyVoid}, {@link lazyTrue}, etc.)
+ * - Delaying expensive operations until actually needed
+ * - Deferring side effects so the callee controls when they run
  *
  * ### Example
  *
  * ```ts
- * // Array literals become NonEmptyReadonlyArray
- * const items = readonly([1, 2, 3]);
- * // Type: NonEmptyReadonlyArray<number>
- *
- * // NonEmptyArray is preserved as NonEmptyReadonlyArray
- * const nonEmpty: NonEmptyArray<number> = [1, 2, 3];
- * const readonlyNonEmpty = readonly(nonEmpty);
- * // Type: NonEmptyReadonlyArray<number>
- *
- * // Regular arrays become ReadonlyArray
- * const arr: Array<number> = getNumbers();
- * const readonlyArr = readonly(arr);
- * // Type: ReadonlyArray<number>
- *
- * // Sets, Records, and Maps
- * const ids = readonly(new Set(["a", "b"]));
- * // Type: ReadonlySet<string>
- *
- * const users: Record<UserId, string> = { ... };
- * const readonlyUsers = readonly(users);
- * // Type: ReadonlyRecord<UserId, string>
- *
- * const lookup = readonly(new Map([["key", "value"]]));
- * // Type: ReadonlyMap<string, string>
+ * // Default callback
+ * const notify = (onDone: Lazy<void> = lazyVoid) => {
+ *   onDone();
+ * };
+ *
+ * // Delay computation
+ * const getData: Lazy<Data> = () => compute();
+ * const data = getData();
+ *
+ * // Defer side effects
+ * const schedule = (job: Lazy<void>) => {
+ *   queueMicrotask(job);
+ * };
+ * schedule(() => logMetric("loaded"));
  * ```
- *
- * @experimental
  */
-export declare function readonly<T>(array: NonEmptyArray<T>): NonEmptyReadonlyArray<T>;
-export declare function readonly<T>(array: Array<T>): ReadonlyArray<T>;
-export declare function readonly<T>(set: Set<T>): ReadonlySet<T>;
-export declare function readonly<K, V>(map: Map<K, V>): ReadonlyMap<K, V>;
-export declare function readonly<K extends keyof any, V>(record: Record<K, V>): ReadonlyRecord<K, V>;
+export type Lazy<T> = () => T;
 /**
- * A function that delays computation and returns a value of type T.
+ * Creates a {@link Lazy} from a precomputed value.
  *
- * Useful for:
+ * Use when the value is expensive to compute and want to compute it once at
+ * definition time rather than on every call.
  *
- * - Lazy evaluation
- * - Returning constant values
- * - Providing default or placeholder behaviors
+ * ### Example
+ *
+ * ```ts
+ * // Computed once at definition, returned on every call
+ * const getConfig = lazy(parseConfig(rawConfig));
+ *
+ * // vs. computed on every call
+ * const getConfig = () => parseConfig(rawConfig);
+ * ```
+ */
+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>;
+/**
+ * Development placeholder that always throws.
+ *
+ * Use to sketch function bodies before implementing them. TypeScript infers the
+ * return type from context, so surrounding code still type-checks. Use an
+ * explicit generic when there is no return type annotation.
  *
  * ### Example
  *
  * ```ts
- * const getRandomNumber: LazyValue<number> = () => Math.random();
- * const randomValue = getRandomNumber();
+ * // Type inferred from return type annotation
+ * const fetchUser = (id: UserId): Result<User, FetchError> => todo();
+ *
+ * expectTypeOf(fetchUser).returns.toEqualTypeOf<
+ *   Result<User, FetchError>
+ * >();
+ *
+ * // Explicit generic when no return type
+ * const getConfig = () => todo<Config>();
+ *
+ * expectTypeOf(getConfig).returns.toEqualTypeOf<Config>();
  * ```
  */
-export type LazyValue<T> = () => T;
-export declare const constVoid: LazyValue<void>;
-export declare const constUndefined: LazyValue<undefined>;
-export declare const constNull: LazyValue<null>;
-export declare const constTrue: LazyValue<true>;
-export declare const constFalse: LazyValue<false>;
+export declare const todo: <T>() => T;
 //# sourceMappingURL=Function.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Function.d.ts","sourceRoot":"","sources":["../../src/Function.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,qBAAqB,CAAC,CAAC,CAAC,CAAC;AAC/E,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;AAC/D,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;AACzD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAClE,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,GAAG,EAAE,CAAC,EAC7C,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GACnB,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAWxB;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC;AAEnC,eAAO,MAAM,SAAS,EAAE,SAAS,CAAC,IAAI,CAAmB,CAAC;AAC1D,eAAO,MAAM,cAAc,EAAE,SAAS,CAAC,SAAS,CAAmB,CAAC;AACpE,eAAO,MAAM,SAAS,EAAE,SAAS,CAAC,IAAI,CAAc,CAAC;AACrD,eAAO,MAAM,SAAS,EAAE,SAAS,CAAC,IAAI,CAAc,CAAC;AACrD,eAAO,MAAM,UAAU,EAAE,SAAS,CAAC,KAAK,CAAe,CAAC"}
+{"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"}