@evolu/common 6.0.1-preview.3 → 6.0.1-preview.31

package/dist/src/Array.d.ts

@@ -1,3 +1,31 @@
+/**
+ * 🔒 Immutable, type-safe array operations
+ *
+ * Helpers that preserve immutability through the type system. Native array
+ * methods return mutable arrays even when called on readonly arrays. These
+ * helpers ensure transformations return readonly types.
+ *
+ * {@link NonEmptyArray} and {@link NonEmptyReadonlyArray} types represent arrays
+ * with at least one element, eliminating runtime length checks and making
+ * function requirements explicit.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // ❌ Native methods return mutable arrays
+ * const readonly: ReadonlyArray<number> = [1, 2, 3];
+ * const mapped = readonly.map((x) => x * 2); // Array<number> (mutable!)
+ *
+ * // ✅ Helpers preserve immutability
+ * const filtered = filterArray(readonly, (x) => x > 1); // ReadonlyArray<number>
+ *
+ * // ✅ NonEmptyArray enforces non-emptiness
+ * const value = firstInArray(["a", "b"]); // "a"
+ * firstInArray([]); // ❌ Compiler error
+ * ```
+ *
+ * @module
+ */
 /** An array with at least one element. */
 export type NonEmptyArray<T> = [T, ...Array<T>];
 /** Checks if an array is non-empty. */
@@ -6,12 +34,48 @@ export declare const isNonEmptyArray: <T>(array: Array<T>) => array is NonEmptyA
 export type NonEmptyReadonlyArray<T> = readonly [T, ...ReadonlyArray<T>];
 /** Checks if an array is non-empty. */
 export declare const isNonEmptyReadonlyArray: <T>(array: ReadonlyArray<T>) => array is NonEmptyReadonlyArray<T>;
-/** Appends an item to an array returning a non-empty array. */
+/**
+ * Appends an item to an array, returning a new non-empty readonly array.
+ *
+ * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ */
 export declare const appendToArray: <T>(item: T, array: ReadonlyArray<T>) => NonEmptyReadonlyArray<T>;
-/** Prepends an item to an array returning a non-empty array. */
+/**
+ * Prepends an item to an array, returning a new non-empty readonly array.
+ *
+ * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ */
 export declare const prependToArray: <T>(item: T, array: ReadonlyArray<T>) => NonEmptyReadonlyArray<T>;
-/** Maps a non-empty array using a mapper function. */
-export declare const mapNonEmptyArray: <T, U>(array: NonEmptyReadonlyArray<T>, mapper: (item: T, index: number) => U) => NonEmptyReadonlyArray<U>;
-/** Shifts an item from a non-empty array, guaranteed to return T. */
+/**
+ * Maps an array using a mapper function, preserving non-emptiness when
+ * applicable.
+ *
+ * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ */
+export declare function mapArray<T, U>(array: NonEmptyReadonlyArray<T> | NonEmptyArray<T>, mapper: (item: T, index: number) => U): NonEmptyReadonlyArray<U>;
+export declare function mapArray<T, U>(array: ReadonlyArray<T> | Array<T>, mapper: (item: T, index: number) => U): ReadonlyArray<U>;
+/**
+ * Filters an array using a predicate function, returning a new readonly array.
+ *
+ * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ */
+export declare const filterArray: <T>(array: ReadonlyArray<T>, predicate: (item: T, index: number) => boolean) => ReadonlyArray<T>;
+/**
+ * Shifts an item from a non-empty mutable array, guaranteed to return T.
+ *
+ * **Mutates** the original array. Use only with mutable arrays.
+ */
 export declare const shiftArray: <T>(array: NonEmptyArray<T>) => T;
+/**
+ * Returns the first element of a non-empty readonly array.
+ *
+ * Does not mutate the original array.
+ */
+export declare const firstInArray: <T>(array: NonEmptyReadonlyArray<T>) => T;
+/**
+ * Returns the last element of a non-empty readonly array.
+ *
+ * Does not mutate the original array.
+ */
+export declare const lastInArray: <T>(array: NonEmptyReadonlyArray<T>) => T;
 //# sourceMappingURL=Array.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Array.d.ts","sourceRoot":"","sources":["../../src/Array.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAEhD,uCAAuC;AACvC,eAAO,MAAM,eAAe,GAAI,CAAC,EAC/B,OAAO,KAAK,CAAC,CAAC,CAAC,KACd,KAAK,IAAI,aAAa,CAAC,CAAC,CAAqB,CAAC;AAEjD,kDAAkD;AAClD,MAAM,MAAM,qBAAqB,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;AAEzE,uCAAuC;AACvC,eAAO,MAAM,uBAAuB,GAAI,CAAC,EACvC,OAAO,aAAa,CAAC,CAAC,CAAC,KACtB,KAAK,IAAI,qBAAqB,CAAC,CAAC,CAAqB,CAAC;AAEzD,+DAA+D;AAC/D,eAAO,MAAM,aAAa,GAAI,CAAC,EAC7B,MAAM,CAAC,EACP,OAAO,aAAa,CAAC,CAAC,CAAC,KACtB,qBAAqB,CAAC,CAAC,CAC+B,CAAC;AAE1D,gEAAgE;AAChE,eAAO,MAAM,cAAc,GAAI,CAAC,EAC9B,MAAM,CAAC,EACP,OAAO,aAAa,CAAC,CAAC,CAAC,KACtB,qBAAqB,CAAC,CAAC,CAC+B,CAAC;AAE1D,sDAAsD;AACtD,eAAO,MAAM,gBAAgB,GAAI,CAAC,EAAE,CAAC,EACnC,OAAO,qBAAqB,CAAC,CAAC,CAAC,EAC/B,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,CAAC,KACpC,qBAAqB,CAAC,CAAC,CACgC,CAAC;AAE3D,qEAAqE;AACrE,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,OAAO,aAAa,CAAC,CAAC,CAAC,KAAG,CAAuB,CAAC"}
+{"version":3,"file":"Array.d.ts","sourceRoot":"","sources":["../../src/Array.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,0CAA0C;AAC1C,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAEhD,uCAAuC;AACvC,eAAO,MAAM,eAAe,GAAI,CAAC,EAC/B,OAAO,KAAK,CAAC,CAAC,CAAC,KACd,KAAK,IAAI,aAAa,CAAC,CAAC,CAAqB,CAAC;AAEjD,kDAAkD;AAClD,MAAM,MAAM,qBAAqB,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;AAEzE,uCAAuC;AACvC,eAAO,MAAM,uBAAuB,GAAI,CAAC,EACvC,OAAO,aAAa,CAAC,CAAC,CAAC,KACtB,KAAK,IAAI,qBAAqB,CAAC,CAAC,CAAqB,CAAC;AAEzD;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,EAC7B,MAAM,CAAC,EACP,OAAO,aAAa,CAAC,CAAC,CAAC,KACtB,qBAAqB,CAAC,CAAC,CACwC,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,EAC9B,MAAM,CAAC,EACP,OAAO,aAAa,CAAC,CAAC,CAAC,KACtB,qBAAqB,CAAC,CAAC,CAAiD,CAAC;AAE5E;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,EAC3B,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,EAClD,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,CAAC,GACpC,qBAAqB,CAAC,CAAC,CAAC,CAAC;AAC5B,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,EAC3B,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,EAClC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,CAAC,GACpC,aAAa,CAAC,CAAC,CAAC,CAAC;AAQpB;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,EAC3B,OAAO,aAAa,CAAC,CAAC,CAAC,EACvB,WAAW,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,KAC7C,aAAa,CAAC,CAAC,CAAgD,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,OAAO,aAAa,CAAC,CAAC,CAAC,KAAG,CAAuB,CAAC;AAEhF;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,EAAE,OAAO,qBAAqB,CAAC,CAAC,CAAC,KAAG,CAAa,CAAC;AAEhF;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,EAAE,OAAO,qBAAqB,CAAC,CAAC,CAAC,KAAG,CACxC,CAAC"}

package/dist/src/Array.js

@@ -1,12 +1,71 @@
+/**
+ * 🔒 Immutable, type-safe array operations
+ *
+ * Helpers that preserve immutability through the type system. Native array
+ * methods return mutable arrays even when called on readonly arrays. These
+ * helpers ensure transformations return readonly types.
+ *
+ * {@link NonEmptyArray} and {@link NonEmptyReadonlyArray} types represent arrays
+ * with at least one element, eliminating runtime length checks and making
+ * function requirements explicit.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // ❌ Native methods return mutable arrays
+ * const readonly: ReadonlyArray<number> = [1, 2, 3];
+ * const mapped = readonly.map((x) => x * 2); // Array<number> (mutable!)
+ *
+ * // ✅ Helpers preserve immutability
+ * const filtered = filterArray(readonly, (x) => x > 1); // ReadonlyArray<number>
+ *
+ * // ✅ NonEmptyArray enforces non-emptiness
+ * const value = firstInArray(["a", "b"]); // "a"
+ * firstInArray([]); // ❌ Compiler error
+ * ```
+ *
+ * @module
+ */
 /** Checks if an array is non-empty. */
 export const isNonEmptyArray = (array) => array.length > 0;
 /** Checks if an array is non-empty. */
 export const isNonEmptyReadonlyArray = (array) => array.length > 0;
-/** Appends an item to an array returning a non-empty array. */
+/**
+ * Appends an item to an array, returning a new non-empty readonly array.
+ *
+ * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ */
 export const appendToArray = (item, array) => [...array, item];
-/** Prepends an item to an array returning a non-empty array. */
+/**
+ * Prepends an item to an array, returning a new non-empty readonly array.
+ *
+ * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ */
 export const prependToArray = (item, array) => [item, ...array];
-/** Maps a non-empty array using a mapper function. */
-export const mapNonEmptyArray = (array, mapper) => array.map(mapper);
-/** Shifts an item from a non-empty array, guaranteed to return T. */
+export function mapArray(array, mapper) {
+    return array.map(mapper);
+}
+/**
+ * Filters an array using a predicate function, returning a new readonly array.
+ *
+ * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ */
+export const filterArray = (array, predicate) => array.filter(predicate);
+/**
+ * Shifts an item from a non-empty mutable array, guaranteed to return T.
+ *
+ * **Mutates** the original array. Use only with mutable arrays.
+ */
 export const shiftArray = (array) => array.shift();
+/**
+ * Returns the first element of a non-empty readonly array.
+ *
+ * Does not mutate the original array.
+ */
+export const firstInArray = (array) => array[0];
+/**
+ * Returns the last element of a non-empty readonly array.
+ *
+ * Does not mutate the original array.
+ */
+export const lastInArray = (array) => array[array.length - 1];

package/dist/src/Assert.d.ts

@@ -16,9 +16,12 @@
  * assert(true, "true is not true"); // no-op
  * assert(false, "true is not true"); // throws Error
  *
- * const size = fooSize - buffer.getLength();
- * // Ensure required type
- * assert(PositiveInt.is(size), "size is not positive int");
+ * const length = buffer.getLength();
+ * // We know length is logically non-negative, but TypeScript doesn't
+ * assert(
+ *   NonNegativeInt.is(length),
+ *   "buffer length should be non-negative",
+ * );
  * ```
  */
 export declare const assert: (condition: unknown, message: string) => asserts condition;
@@ -52,17 +55,4 @@ export declare const assertNonEmptyArray: <T>(arr: Array<T>, message?: string) =
  * ```
  */
 export declare const assertNonEmptyReadonlyArray: <T>(arr: ReadonlyArray<T>, message?: string) => asserts arr is readonly [T, ...Array<T>];
-/**
- * Asserts no error reaches a `.catch` block, throwing a developer error if it
- * does. Used in Promise chains where errors indicate bugs to be fixed.
- *
- * ### Example
- *
- * ```ts
- * Promise.reject("test").catch((e) =>
- *   assertNoErrorInCatch("WebSocket retry", e),
- * );
- * ```
- */
-export declare function assertNoErrorInCatch(context: string, error: unknown): never;
 //# sourceMappingURL=Assert.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Assert.d.ts","sourceRoot":"","sources":["../../src/Assert.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,MAAM,EAAE,CACnB,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,SAIZ,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB,EAAE,CAAC,CAAC,EAClC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,EACb,OAAO,CAAC,EAAE,MAAM,KACb,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAKlC,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,2BAA2B,EAAE,CAAC,CAAC,EAC1C,GAAG,EAAE,aAAa,CAAC,CAAC,CAAC,EACrB,OAAO,CAAC,EAAE,MAAM,KACb,OAAO,CAAC,GAAG,IAAI,SAAS,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAK3C,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,CAO3E"}
+{"version":3,"file":"Assert.d.ts","sourceRoot":"","sources":["../../src/Assert.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,MAAM,EAAE,CACnB,SAAS,EAAE,OAAO,EAClB,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,SAIZ,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB,EAAE,CAAC,CAAC,EAClC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,EACb,OAAO,CAAC,EAAE,MAAM,KACb,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAKlC,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,2BAA2B,EAAE,CAAC,CAAC,EAC1C,GAAG,EAAE,aAAa,CAAC,CAAC,CAAC,EACrB,OAAO,CAAC,EAAE,MAAM,KACb,OAAO,CAAC,GAAG,IAAI,SAAS,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAK3C,CAAC"}

package/dist/src/Assert.js

@@ -16,9 +16,12 @@
  * assert(true, "true is not true"); // no-op
  * assert(false, "true is not true"); // throws Error
  *
- * const size = fooSize - buffer.getLength();
- * // Ensure required type
- * assert(PositiveInt.is(size), "size is not positive int");
+ * const length = buffer.getLength();
+ * // We know length is logically non-negative, but TypeScript doesn't
+ * assert(
+ *   NonNegativeInt.is(length),
+ *   "buffer length should be non-negative",
+ * );
  * ```
  */
 export const assert = (condition, message) => {
@@ -60,18 +63,3 @@ export const assertNonEmptyArray = (arr, message = "Expected a non-empty array."
 export const assertNonEmptyReadonlyArray = (arr, message = "Expected a non-empty readonly array.") => {
     assert(arr.length > 0, message);
 };
-/**
- * Asserts no error reaches a `.catch` block, throwing a developer error if it
- * does. Used in Promise chains where errors indicate bugs to be fixed.
- *
- * ### Example
- *
- * ```ts
- * Promise.reject("test").catch((e) =>
- *   assertNoErrorInCatch("WebSocket retry", e),
- * );
- * ```
- */
-export function assertNoErrorInCatch(context, error) {
-    throw Object.assign(new Error(`Error in ${context}: an unexpected error reached a catch block and requires a fix`), { cause: error });
-}

package/dist/src/Brand.d.ts

@@ -0,0 +1,75 @@
+/**
+ * A utility interface for creating branded types.
+ *
+ * Branded types enhance type safety by differentiating otherwise identical base
+ * types, such as `number` or `string`, to enforce stricter type checks.
+ *
+ * Supports multiple brands, allowing types to act like flags.
+ *
+ * ### Example 1: Single Brand
+ *
+ * ```ts
+ * // A branded type definition
+ * type UserId = number & Brand<"UserId">;
+ *
+ * // A function that creates `UserId` values.
+ * // Casting with `as UserId` is unsafe, so `createUserId` must be unit-tested.
+ * const createUserId = (): UserId => {
+ *   return 123 as UserId; // Unsafe casting
+ * };
+ *
+ * const userId = createUserId();
+ *
+ * // A function that accepts only `UserId`.
+ * const getUser = (id: UserId) => {
+ *   // Implementation
+ * };
+ *
+ * getUser(userId); // ✅ Valid
+ * getUser(123); // ❌ TypeScript error
+ * getUser("123"); // ❌ TypeScript error
+ * ```
+ *
+ * ### Example 2: Multiple Brands
+ *
+ * ```ts
+ * // Define branded types
+ * type Min1 = string & Brand<"Min1">;
+ * type Max100 = string & Brand<"Max100">;
+ * type Min1Max100 = string & Brand<"Min1" | "Max100">;
+ *
+ * // Functions requiring specific brands
+ * const requiresMin1 = (value: Min1): void => {};
+ * const requiresMax100 = (value: Max100): void => {};
+ *
+ * // Values with single brands
+ * const min1Value: Min1 = "hello" as Min1;
+ * const max100Value: Max100 = "world" as Max100;
+ *
+ * // Value with multiple brands
+ * const min1Max100Value: Min1Max100 = "typescript" as Min1Max100;
+ *
+ * // Valid cases
+ * requiresMin1(min1Value); // ✅ Valid
+ * requiresMax100(max100Value); // ✅ Valid
+ * requiresMin1(min1Max100Value); // ✅ Valid: Min1Max100 satisfies Min1
+ * requiresMax100(min1Max100Value); // ✅ Valid: Min1Max100 satisfies Max100
+ * ```
+ */
+export interface Brand<B extends string> {
+    readonly [__brand]: Readonly<Record<B, true>>;
+}
+declare const __brand: unique symbol;
+/**
+ * Determines whether a type `T` is a branded type.
+ *
+ * Works with any base type intersected with a `Brand`.
+ *
+ * ### Examples
+ *
+ * - `IsBranded<string>` -> false
+ * - `IsBranded<string & Brand<"X">>` -> true
+ */
+export type IsBranded<T> = T extends Brand<string> ? true : false;
+export {};
+//# sourceMappingURL=Brand.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Brand.d.ts","sourceRoot":"","sources":["../../src/Brand.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,MAAM,WAAW,KAAK,CAAC,CAAC,SAAS,MAAM;IACrC,QAAQ,CAAC,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;CAC/C;AAED,OAAO,CAAC,MAAM,OAAO,EAAE,OAAO,MAAM,CAAC;AAErC;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI,GAAG,KAAK,CAAC"}

package/dist/src/Brand.js

@@ -0,0 +1 @@
+export {};

package/dist/src/Buffer.d.ts

@@ -1,5 +1,5 @@
 import { NonNegativeInt } from "./Type.js";
-export { bytesToHex, bytesToUtf8, concatBytes, hexToBytes, utf8ToBytes, } from "@noble/ciphers/utils";
+export { bytesToHex, bytesToUtf8, concatBytes, hexToBytes, utf8ToBytes, } from "@noble/ciphers/utils.js";
 /**
  * Custom error for {@link Buffer}-related failures like premature end of data.
  * Provides better stack traces for debugging binary protocol issues.

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

@@ -1 +1 @@
-{"version":3,"file":"Buffer.d.ts","sourceRoot":"","sources":["../../src/Buffer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EACL,UAAU,EACV,WAAW,EACX,WAAW,EACX,UAAU,EACV,WAAW,GACZ,MAAM,sBAAsB,CAAC;AAE9B;;;GAGG;AACH,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAM5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,WAAW,MAAM;IACrB,sDAAsD;IACtD,WAAW,EAAE,MAAM,cAAc,CAAC;IAElC,gEAAgE;IAChE,SAAS,EAAE,MAAM,cAAc,CAAC;IAEhC;;;OAGG;IACH,MAAM,EAAE,CAAC,GAAG,EAAE,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;IAEtD;;;OAGG;IACH,KAAK,EAAE,MAAM,cAAc,CAAC;IAE5B;;;OAGG;IACH,MAAM,EAAE,CAAC,CAAC,EAAE,cAAc,KAAK,UAAU,CAAC;IAE1C;;;OAGG;IACH,QAAQ,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,CAAC;IAE3C;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;IAElB;;;;OAIG;IACH,MAAM,EAAE,MAAM,UAAU,CAAC;CAC1B;AAED,eAAO,MAAM,YAAY,GACvB,YAAY,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC,KACzC,MA4DF,CAAC"}
+{"version":3,"file":"Buffer.d.ts","sourceRoot":"","sources":["../../src/Buffer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EACL,UAAU,EACV,WAAW,EACX,WAAW,EACX,UAAU,EACV,WAAW,GACZ,MAAM,yBAAyB,CAAC;AAEjC;;;GAGG;AACH,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAM5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,WAAW,MAAM;IACrB,sDAAsD;IACtD,WAAW,EAAE,MAAM,cAAc,CAAC;IAElC,gEAAgE;IAChE,SAAS,EAAE,MAAM,cAAc,CAAC;IAEhC;;;OAGG;IACH,MAAM,EAAE,CAAC,GAAG,EAAE,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;IAEtD;;;OAGG;IACH,KAAK,EAAE,MAAM,cAAc,CAAC;IAE5B;;;OAGG;IACH,MAAM,EAAE,CAAC,CAAC,EAAE,cAAc,KAAK,UAAU,CAAC;IAE1C;;;OAGG;IACH,QAAQ,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,CAAC;IAE3C;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;IAElB;;;;OAIG;IACH,MAAM,EAAE,MAAM,UAAU,CAAC;CAC1B;AAED,eAAO,MAAM,YAAY,GACvB,YAAY,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC,KACzC,MA4DF,CAAC"}

package/dist/src/Buffer.js

@@ -1,4 +1,5 @@
-export { bytesToHex, bytesToUtf8, concatBytes, hexToBytes, utf8ToBytes, } from "@noble/ciphers/utils";
+import { NonNegativeInt } from "./Type.js";
+export { bytesToHex, bytesToUtf8, concatBytes, hexToBytes, utf8ToBytes, } from "@noble/ciphers/utils.js";
 /**
  * Custom error for {@link Buffer}-related failures like premature end of data.
  * Provides better stack traces for debugging binary protocol issues.
@@ -14,9 +15,9 @@ export const createBuffer = (arrayLike) => {
     let value = arrayLike
         ? new globalThis.Uint8Array(arrayLike)
         : new globalThis.Uint8Array(512);
-    let length = (arrayLike ? arrayLike.length : 0);
+    let length = NonNegativeInt.orThrow(arrayLike ? arrayLike.length : 0);
     const buffer = {
-        getCapacity: () => value.length,
+        getCapacity: () => NonNegativeInt.orThrow(value.length),
         getLength: () => length,
         extend: (arg) => {
             const targetSize = length + arg.length;
@@ -27,7 +28,7 @@ export const createBuffer = (arrayLike) => {
                 value.set(oldValue);
             }
             value.set(arg, length);
-            length = (length + arg.length);
+            length = NonNegativeInt.orThrow(length + arg.length);
         },
         shift: () => {
             if (length === 0) {
@@ -36,7 +37,7 @@ export const createBuffer = (arrayLike) => {
             const first = value[0];
             value = value.subarray(1);
             length--;
-            return first;
+            return NonNegativeInt.orThrow(first);
         },
         shiftN: (n) => {
             if (length < n) {
@@ -44,7 +45,7 @@ export const createBuffer = (arrayLike) => {
             }
             const subarray = value.subarray(0, n);
             value = value.subarray(n);
-            length = (length - n);
+            length = NonNegativeInt.orThrow(length - n);
             return subarray;
         },
         truncate: (newLength) => {
@@ -54,7 +55,7 @@ export const createBuffer = (arrayLike) => {
             length = newLength;
         },
         reset: () => {
-            length = 0;
+            length = NonNegativeInt.orThrow(0);
         },
         unwrap: () => value.subarray(0, length),
     };

package/dist/src/Cache.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 🗄️ Generic cache interface and LRU cache implementation.
+ *
+ * @module
+ */
+import { PositiveInt } from "./Type.js";
+/**
+ * Generic cache interface providing basic key-value storage operations.
+ *
+ * Keys are compared by reference (standard Map semantics).
+ *
+ * Note: Cache does not extend Map because eviction policies (like in LRU)
+ * violate the Liskov Substitution Principle.
+ */
+export interface Cache<K, V> {
+    /** Checks if a key exists in the cache. */
+    has: (key: K) => boolean;
+    /** Retrieves the value for a key, or undefined if not present. */
+    get: (key: K) => V | undefined;
+    /** Stores a key-value pair in the cache. */
+    set: (key: K, val: V) => void;
+    /** Removes a key from the cache. */
+    delete: (key: K) => void;
+    /** Returns a readonly view of the internal Map. */
+    readonly map: ReadonlyMap<K, V>;
+}
+/**
+ * Creates a Least Recently Used (LRU) cache with a maximum capacity.
+ *
+ * When the cache reaches capacity, the least recently used entry is evicted.
+ * Both `get` and `set` operations update the access order.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const cache = createLruCache<string, number>(2);
+ * cache.set("a", 1);
+ * cache.set("b", 2);
+ * cache.set("c", 3); // Evicts "a"
+ * cache.has("a"); // false
+ * ```
+ */
+export declare const createLruCache: <K, V>(capacity: PositiveInt) => Cache<K, V>;
+//# sourceMappingURL=Cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Cache.d.ts","sourceRoot":"","sources":["../../src/Cache.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC;;;;;;;GAOG;AACH,MAAM,WAAW,KAAK,CAAC,CAAC,EAAE,CAAC;IACzB,2CAA2C;IAC3C,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC;IAEzB,kEAAkE;IAClE,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC;IAE/B,4CAA4C;IAC5C,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC;IAE9B,oCAAoC;IACpC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC;IAEzB,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,CAAC,EAAE,UAAU,WAAW,KAAG,KAAK,CAAC,CAAC,EAAE,CAAC,CAmCtE,CAAC"}

package/dist/src/Cache.js

@@ -0,0 +1,52 @@
+/**
+ * 🗄️ Generic cache interface and LRU cache implementation.
+ *
+ * @module
+ */
+/**
+ * Creates a Least Recently Used (LRU) cache with a maximum capacity.
+ *
+ * When the cache reaches capacity, the least recently used entry is evicted.
+ * Both `get` and `set` operations update the access order.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const cache = createLruCache<string, number>(2);
+ * cache.set("a", 1);
+ * cache.set("b", 2);
+ * cache.set("c", 3); // Evicts "a"
+ * cache.has("a"); // false
+ * ```
+ */
+export const createLruCache = (capacity) => {
+    const internalMap = new Map();
+    return {
+        has: (key) => internalMap.has(key),
+        get: (key) => {
+            const value = internalMap.get(key);
+            if (value === undefined)
+                return undefined;
+            // Move to end (most recently used)
+            internalMap.delete(key);
+            internalMap.set(key, value);
+            return value;
+        },
+        set: (key, val) => {
+            // If key exists, delete it first to update order
+            if (internalMap.has(key)) {
+                internalMap.delete(key);
+            }
+            else if (internalMap.size === capacity) {
+                // Evict least recently used (first entry)
+                const firstKey = internalMap.keys().next().value;
+                internalMap.delete(firstKey);
+            }
+            internalMap.set(key, val);
+        },
+        delete: (key) => {
+            internalMap.delete(key);
+        },
+        map: internalMap,
+    };
+};

package/dist/src/Callbacks.d.ts

@@ -1,20 +1,53 @@
-import { NanoIdLibDep } from "./NanoId.js";
-import { Brand } from "./Types.js";
+import { Brand } from "./Brand.js";
+import { RandomBytesDep } from "./Crypto.js";
+import { Id } from "./Type.js";
 /**
- * Manages one-time callback functions.
+ * Request-response correlation for callbacks across boundaries.
  *
- * Allows registering callbacks with a unique ID and executing them once with an
- * optional argument. Executed callbacks are automatically removed.
+ * Stores callbacks with unique IDs and executes them once with an optional
+ * argument. Executed callbacks are automatically removed.
  *
- * This is useful for managing event-driven or asynchronous workflows where
- * callbacks need to be invoked only once.
+ * This is useful for correlating asynchronous request-response operations
+ * across boundaries where callback functions cannot be passed directly (e.g.,
+ * web workers, message queues).
+ *
+ * The `execute` method intentionally does not use try-catch or {@link Result}
+ * because it's the callback's responsibility to handle its own errors.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // No-argument callbacks
+ * const callbacks = createCallbacks(deps);
+ * const id = callbacks.register(() => console.log("called"));
+ * callbacks.execute(id);
+ *
+ * // With argument callbacks
+ * const stringCallbacks = createCallbacks<string>(deps);
+ * const id = stringCallbacks.register((value) => {
+ *   console.log(value);
+ * });
+ * stringCallbacks.execute(id, "hello");
+ *
+ * // Promise.withResolvers pattern
+ * const promiseCallbacks = createCallbacks<string>(deps);
+ * const { promise, resolve } = Promise.withResolvers<string>();
+ * const id = promiseCallbacks.register(resolve);
+ * promiseCallbacks.execute(id, "resolved value");
+ * await promise; // "resolved value"
+ * ```
+ *
+ * @template T - The type of argument passed to callbacks (defaults to undefined
+ *   for no-argument callbacks)
  */
-export interface Callbacks {
+export interface Callbacks<T = undefined> {
     /** Registers a callback function and returns a unique ID. */
-    readonly register: (callback: (arg?: unknown) => void) => CallbackId;
+    readonly register: (callback: (arg: T) => void) => CallbackId;
     /** Executes and removes a callback associated with the given ID. */
-    readonly execute: (id: CallbackId, arg?: unknown) => void;
+    readonly execute: T extends undefined ? (id: CallbackId) => undefined : (id: CallbackId, arg: T) => undefined;
 }
-export type CallbackId = string & Brand<"CallbackId">;
-export declare const createCallbacks: (deps: NanoIdLibDep) => Callbacks;
+/** Unique identifier for a callback in {@link Callbacks}. */
+export type CallbackId = Id & Brand<"Callback">;
+/** Creates a new {@link Callbacks}. */
+export declare const createCallbacks: <T = undefined>(deps: RandomBytesDep) => Callbacks<T>;
 //# sourceMappingURL=Callbacks.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Callbacks.d.ts","sourceRoot":"","sources":["../../src/Callbacks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,KAAK,UAAU,CAAC;IAErE,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,UAAU,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3D;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC;AAEtD,eAAO,MAAM,eAAe,GAAI,MAAM,YAAY,KAAG,SAoBpD,CAAC"}
+{"version":3,"file":"Callbacks.d.ts","sourceRoot":"","sources":["../../src/Callbacks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAY,EAAE,EAAE,MAAM,WAAW,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,SAAS;IACtC,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,KAAK,UAAU,CAAC;IAE9D,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,CAAC,SAAS,SAAS,GACjC,CAAC,EAAE,EAAE,UAAU,KAAK,SAAS,GAC7B,CAAC,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,KAAK,SAAS,CAAC;CAC3C;AAED,6DAA6D;AAC7D,MAAM,MAAM,UAAU,GAAG,EAAE,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC;AAEhD,uCAAuC;AACvC,eAAO,MAAM,eAAe,GAAI,CAAC,GAAG,SAAS,EAC3C,MAAM,cAAc,KACnB,SAAS,CAAC,CAAC,CAsBb,CAAC"}

package/dist/src/Callbacks.js

@@ -1,18 +1,25 @@
+import { createId } from "./Type.js";
+/** Creates a new {@link Callbacks}. */
 export const createCallbacks = (deps) => {
     const callbackMap = new Map();
-    const callbacks = {
+    return {
         register: (callback) => {
-            const id = deps.nanoIdLib.nanoid();
+            const id = createId(deps);
             callbackMap.set(id, callback);
             return id;
         },
-        execute: (id, arg) => {
+        execute: (id, ...args) => {
             const callback = callbackMap.get(id);
-            if (callback) {
-                callbackMap.delete(id);
-                callback(arg);
+            if (!callback)
+                return;
+            callbackMap.delete(id);
+            if (args.length === 0) {
+                // Called without argument (undefined case)
+                callback();
+            }
+            else {
+                callback(args[0]);
             }
         },
     };
-    return callbacks;
 };