@evolu/common 5.4.7 → 6.0.0-preview.0

package/README.md

@@ -1,33 +1,10 @@
 # Evolu
 
-[Local-first](https://www.inkandswitch.com/local-first) platform designed for privacy, ease of use, and no vendor lock-in
-
-- [SQLite](https://sqlite.org) in all browsers, Electron, and React Native
-- [CRDT](https://crdt.tech) for merging changes without conflicts
-- End-to-end encrypted sync and backup
-- Free Evolu sync and backup server, or you can run your own
-- Typed database schema (with branded types like `NonEmptyString1000`, `PositiveInt`, etc.)
-- Typed SQL via [Kysely](https://kysely.dev)
-- Reactive queries with full React Suspense support
-- Real-time experience via revalidation on focus and network recovery
-- No signup/login, only bitcoin-like mnemonic (12 words)
-- Ad-hoc migration
-- Sqlite JSON support with automatic stringifying and parsing
-- Support for [Kysely Relations](https://kysely.dev/docs/recipes/relations) (loading nested objects and arrays in a single SQL query)
-- Local-only tables (tables with \_ prefix are not synced)
-- Evolu Solid/Vue/Svelte soon
-
-## Local-first apps
-
-Local-first apps allow users to own their data by storing them on their devices. Modern browsers provide API designed precisely for that. How is it different from keeping files on disk? Files are not the right abstraction for apps and cannot synchronize among devices. That's why traditional apps use the client-server architecture. But using client-server architecture also means that users' ability to use an app depends on some server that can be offline, temporarily or forever, if a company decides to ban a user or even goes bankrupt. That's unfortunate. Luckily, a way to restore data ownership exists. It's Evolu.
+Evolu is TypeScript library and local-first framework.
 
 ## Documentation
 
-For detailed information and usage examples, please visit [evolu.dev](https://www.evolu.dev).
-
-## API Reference
-
-[evoluhq.github.io/evolu](https://evoluhq.github.io/evolu)
+Please visit [evolu.dev](https://www.evolu.dev).
 
 ## Community
 
@@ -35,40 +12,59 @@ The Evolu community is on [GitHub Discussions](https://github.com/evoluhq/evolu/
 
 To chat with other community members, you can join the [Evolu Discord](https://discord.gg/2J8yyyyxtZ).
 
-[![Twitter URL](https://img.shields.io/twitter/url/https/x.com/evoluhq.svg?style=social&label=Follow%20%40evoluhq)](https://x.com/evoluhq)
+[![Twitter URL](https://img.shields.io/twitter/url/https/twitter.com/evoluhq.svg?style=social&label=Follow%20%40evoluhq)](https://twitter.com/evoluhq)
+
+## Hosting Evolu Relay
+
+[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https%3A%2F%2Fgithub.com%2Fevoluhq%2Fevolu)
+
+We provide a free relay `free.evoluhq.com` for testing and personal usage.
+
+The Evolu Relay source along with the Docker files can be in the [/apps/relay](/apps/relay) directory.
 
-## Contributing
+Alternatively, a pre-built image `evoluhq/relay:latest` is hosted on [Docker Hub](https://hub.docker.com/r/evoluhq/relay).
+
+For more information, reference the [Evolu Relay](https://www.evolu.dev/docs/evolu-relay) documentation.
+
+## Developing
 
 Evolu monorepo uses [pnpm](https://pnpm.io).
 
-Install the dependencies with:
+Install dependencies:
 
 ```
 pnpm install
 ```
 
-Build Evolu monorepo:
+Build monorepo:
 
 ```
 pnpm build
+pnpm build:web
 ```
 
-Start developing and watch for code changes:
+Start dev:
 
 ```
+# web
 pnpm dev
+
+# expo (pnpm dev must be running too)
+pnpm ios
+pnpm android
 ```
 
-Start iOS developing (pnpm dev must be running too):
+Linting:
 
 ```
-pnpm ios
+pnpm lint
+pnpm lint-monorepo
 ```
 
-Lint and tests:
+Tests
 
 ```
-pnpm lint test
+pnpm test
 ```
 
 Describe changes for release log:

package/dist/src/Array.d.ts

@@ -0,0 +1,17 @@
+/** An array with at least one element. */
+export type NonEmptyArray<T> = [T, ...Array<T>];
+/** Checks if an array is non-empty. */
+export declare const isNonEmptyArray: <T>(array: Array<T>) => array is NonEmptyArray<T>;
+/** A readonly array with at least one element. */
+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. */
+export declare const appendToArray: <T>(item: T, array: ReadonlyArray<T>) => NonEmptyReadonlyArray<T>;
+/** Prepends an item to an array returning a non-empty 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. */
+export declare const shiftArray: <T>(array: NonEmptyArray<T>) => T;
+//# sourceMappingURL=Array.d.ts.map

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

@@ -0,0 +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"}

package/dist/src/Array.js

@@ -0,0 +1,12 @@
+/** 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. */
+export const appendToArray = (item, array) => [...array, item];
+/** Prepends an item to an array returning a non-empty 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 const shiftArray = (array) => array.shift();

package/dist/src/Assert.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Ensures a condition is true, throwing an error with the provided message if
+ * not.
+ *
+ * Prevents invalid states from propagating through the system by halting
+ * execution when a condition fails, improving reliability and debuggability.
+ *
+ * **Warning**: Do not use this instead of {@link Type}. Assertions are intended
+ * for conditions that are logically guaranteed but not statically known by
+ * TypeScript, or for catching and signaling developer mistakes eagerly (e.g.,
+ * invalid configuration).
+ *
+ * ### Example
+ *
+ * ```ts
+ * 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");
+ * ```
+ */
+export declare const assert: (condition: unknown, message: string) => asserts condition;
+/**
+ * Asserts that an array is non-empty.
+ *
+ * Ensures the provided array has at least one element, helping TypeScript infer
+ * the array as non-empty when this is logically guaranteed but not statically
+ * known.
+ *
+ * ### Example
+ *
+ * ```ts
+ * assertNonEmptyArray([1, 2, 3]); // no-op
+ * assertNonEmptyArray([]); // throws Error
+ * ```
+ */
+export declare const assertNonEmptyArray: <T>(arr: Array<T>, message?: string) => asserts arr is [T, ...Array<T>];
+/**
+ * Asserts that a readonly array is non-empty.
+ *
+ * Ensures the provided readonly array has at least one element, helping
+ * TypeScript infer non-emptiness when this is logically guaranteed but not
+ * statically known.
+ *
+ * ### Example
+ *
+ * ```ts
+ * assertNonEmptyReadonlyArray([1, 2, 3]); // no-op
+ * assertNonEmptyReadonlyArray([]); // throws Error
+ * ```
+ */
+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

@@ -0,0 +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"}

package/dist/src/Assert.js

@@ -0,0 +1,77 @@
+/**
+ * Ensures a condition is true, throwing an error with the provided message if
+ * not.
+ *
+ * Prevents invalid states from propagating through the system by halting
+ * execution when a condition fails, improving reliability and debuggability.
+ *
+ * **Warning**: Do not use this instead of {@link Type}. Assertions are intended
+ * for conditions that are logically guaranteed but not statically known by
+ * TypeScript, or for catching and signaling developer mistakes eagerly (e.g.,
+ * invalid configuration).
+ *
+ * ### Example
+ *
+ * ```ts
+ * 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");
+ * ```
+ */
+export const assert = (condition, message) => {
+    if (!condition) {
+        throw new Error(message);
+    }
+};
+/**
+ * Asserts that an array is non-empty.
+ *
+ * Ensures the provided array has at least one element, helping TypeScript infer
+ * the array as non-empty when this is logically guaranteed but not statically
+ * known.
+ *
+ * ### Example
+ *
+ * ```ts
+ * assertNonEmptyArray([1, 2, 3]); // no-op
+ * assertNonEmptyArray([]); // throws Error
+ * ```
+ */
+export const assertNonEmptyArray = (arr, message = "Expected a non-empty array.") => {
+    assert(arr.length > 0, message);
+};
+/**
+ * Asserts that a readonly array is non-empty.
+ *
+ * Ensures the provided readonly array has at least one element, helping
+ * TypeScript infer non-emptiness when this is logically guaranteed but not
+ * statically known.
+ *
+ * ### Example
+ *
+ * ```ts
+ * assertNonEmptyReadonlyArray([1, 2, 3]); // no-op
+ * assertNonEmptyReadonlyArray([]); // throws Error
+ * ```
+ */
+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/BigInt.d.ts

@@ -0,0 +1,20 @@
+import { Predicate } from "./Types.js";
+/** Increments a bigint by 1. */
+export declare const incrementBigInt: (n: bigint) => bigint;
+/** Decrements a bigint by 1. */
+export declare const decrementBigInt: (n: bigint) => bigint;
+/** Clamps a bigint within a given range. */
+export declare const clampBigInt: (min: bigint, max: bigint) => (n: bigint) => bigint;
+/**
+ * Creates a predicate that checks if a BigInt is within a range, inclusive.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const isBetween10And20 = isBetweenBigInt(10n, 20n);
+ * console.log(isBetween10And20(15n)); // true
+ * console.log(isBetween10And20(25n)); // false
+ * ```
+ */
+export declare const isBetweenBigInt: (min: bigint, max: bigint) => Predicate<bigint>;
+//# sourceMappingURL=BigInt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BigInt.d.ts","sourceRoot":"","sources":["../../src/BigInt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,gCAAgC;AAChC,eAAO,MAAM,eAAe,GAAI,GAAG,MAAM,KAAG,MAAgB,CAAC;AAE7D,gCAAgC;AAChC,eAAO,MAAM,eAAe,GAAI,GAAG,MAAM,KAAG,MAAgB,CAAC;AAE7D,4CAA4C;AAC5C,eAAO,MAAM,WAAW,GACrB,KAAK,MAAM,EAAE,KAAK,MAAM,MACxB,GAAG,MAAM,KAAG,MACsB,CAAC;AAEtC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,GACzB,KAAK,MAAM,EAAE,KAAK,MAAM,KAAG,SAAS,CAAC,MAAM,CAEd,CAAC"}

package/dist/src/BigInt.js

@@ -0,0 +1,18 @@
+/** Increments a bigint by 1. */
+export const incrementBigInt = (n) => n + 1n;
+/** Decrements a bigint by 1. */
+export const decrementBigInt = (n) => n - 1n;
+/** Clamps a bigint within a given range. */
+export const clampBigInt = (min, max) => (n) => n < min ? min : n > max ? max : n;
+/**
+ * Creates a predicate that checks if a BigInt is within a range, inclusive.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const isBetween10And20 = isBetweenBigInt(10n, 20n);
+ * console.log(isBetween10And20(15n)); // true
+ * console.log(isBetween10And20(25n)); // false
+ * ```
+ */
+export const isBetweenBigInt = (min, max) => (value) => value >= min && value <= max;

package/dist/src/Buffer.d.ts

@@ -0,0 +1,92 @@
+import { NonNegativeInt } from "./Type.js";
+export { bytesToHex, bytesToUtf8, concatBytes, hexToBytes, utf8ToBytes, } from "@noble/ciphers/utils";
+/**
+ * Custom error for {@link Buffer}-related failures like premature end of data.
+ * Provides better stack traces for debugging binary protocol issues.
+ */
+export declare class BufferError extends Error {
+    constructor(message: string);
+}
+/**
+ * A Buffer is a dynamic, resizable container for binary data, optimized for
+ * scenarios where the final size is unknown. It grows exponentially (doubling
+ * its capacity) to minimize memory reallocations and uses `subarray` for
+ * efficient, copy-free data access in methods like `unwrap` and `shift`.
+ *
+ * ### Recommended Usage
+ *
+ * Create as few Buffers as possible—typically one main Buffer for the final
+ * output. Temporary Buffers are allowed when necessary (e.g., for
+ * variable-length headers), but avoid excessive allocations. Buffers can be
+ * reused within functions by leveraging `reset` to clear contents while
+ * preserving capacity, or `truncate` to adjust the length to a specific size,
+ * reducing the need for new allocations. Pass Buffers to `encode*` functions to
+ * append serialized data and use `decode*` functions to extract data. Both
+ * `shift` and `shiftN` throw an {@link BufferError} with message "Buffer parse
+ * ended prematurely" on failure, as do higher-level `decode*` functions,
+ * providing stack traces for debugging instead of using {@link Result}. This
+ * avoids allocation overhead in success cases and leverages exceptions'
+ * diagnostic benefits.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const buffer = createBuffer();
+ * encodeNonNegativeInt(buffer, someInt);
+ * encodeId(buffer, someId);
+ * const result = buffer.unwrap(); // Final serialized data
+ *
+ * // Decoding example (throws on error)
+ * try {
+ *   const num = decodeNonNegativeInt(buffer);
+ *   const id = decodeId(buffer);
+ * } catch (e) {
+ *   console.error(e.stack); // Stack trace for debugging
+ * }
+ * ```
+ *
+ * For more on exponential growth, see:
+ * https://blog.mozilla.org/nnethercote/2014/11/04/please-grow-your-buffers-exponentially
+ */
+export interface Buffer {
+    /** Returns the total allocated size of the buffer. */
+    getCapacity: () => NonNegativeInt;
+    /** Returns the current number of bytes stored in the buffer. */
+    getLength: () => NonNegativeInt;
+    /**
+     * Appends binary data to the buffer, resizing if necessary. Throws if
+     * `arg.length` is not a non-negative integer.
+     */
+    extend: (arg: Uint8Array | ArrayLike<number>) => void;
+    /**
+     * Removes and returns the first byte. Throws an `Error` with message "Buffer
+     * parse ended prematurely" if the buffer is empty.
+     */
+    shift: () => NonNegativeInt;
+    /**
+     * Removes and returns the first `n` bytes. Throws an `Error` with message
+     * "Buffer parse ended prematurely" if fewer than `n` bytes remain.
+     */
+    shiftN: (n: NonNegativeInt) => Uint8Array;
+    /**
+     * Truncates the buffer to the specified length, discarding data from the end.
+     * Throws if the new length is greater than the current length.
+     */
+    truncate: (length: NonNegativeInt) => void;
+    /**
+     * Resets the buffer to its initial empty state, preserving its capacity.
+     *
+     * This allows efficient buffer reuse without reallocating memory. Use this
+     * when you want to clear the buffer and write new data, avoiding unnecessary
+     * allocations.
+     */
+    reset: () => void;
+    /**
+     * Returns a view of the buffer’s current data. Do not modify this array, as
+     * it directly alters the buffer’s internal state, potentially breaking
+     * subsequent operations.
+     */
+    unwrap: () => Uint8Array;
+}
+export declare const createBuffer: (arrayLike?: Uint8Array | ArrayLike<number>) => Buffer;
+//# sourceMappingURL=Buffer.d.ts.map

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

@@ -0,0 +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"}

package/dist/src/Buffer.js

@@ -0,0 +1,62 @@
+export { bytesToHex, bytesToUtf8, concatBytes, hexToBytes, utf8ToBytes, } from "@noble/ciphers/utils";
+/**
+ * Custom error for {@link Buffer}-related failures like premature end of data.
+ * Provides better stack traces for debugging binary protocol issues.
+ */
+export class BufferError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = this.constructor.name;
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+export const createBuffer = (arrayLike) => {
+    let value = arrayLike
+        ? new globalThis.Uint8Array(arrayLike)
+        : new globalThis.Uint8Array(512);
+    let length = (arrayLike ? arrayLike.length : 0);
+    const buffer = {
+        getCapacity: () => value.length,
+        getLength: () => length,
+        extend: (arg) => {
+            const targetSize = length + arg.length;
+            if (value.length < targetSize) {
+                const oldValue = value;
+                const newCapacity = Math.max(value.length * 2, targetSize);
+                value = new globalThis.Uint8Array(newCapacity);
+                value.set(oldValue);
+            }
+            value.set(arg, length);
+            length = (length + arg.length);
+        },
+        shift: () => {
+            if (length === 0) {
+                throw new BufferError("Buffer parse ended prematurely");
+            }
+            const first = value[0];
+            value = value.subarray(1);
+            length--;
+            return first;
+        },
+        shiftN: (n) => {
+            if (length < n) {
+                throw new BufferError("Buffer parse ended prematurely");
+            }
+            const subarray = value.subarray(0, n);
+            value = value.subarray(n);
+            length = (length - n);
+            return subarray;
+        },
+        truncate: (newLength) => {
+            if (newLength > length) {
+                throw new BufferError("Cannot truncate to a length greater than current");
+            }
+            length = newLength;
+        },
+        reset: () => {
+            length = 0;
+        },
+        unwrap: () => value.subarray(0, length),
+    };
+    return buffer;
+};

package/dist/src/Callbacks.d.ts

@@ -0,0 +1,20 @@
+import { NanoIdLibDep } from "./NanoId.js";
+import { Brand } from "./Types.js";
+/**
+ * Manages one-time callback functions.
+ *
+ * Allows registering callbacks with a unique ID and executing 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.
+ */
+export interface Callbacks {
+    /** Registers a callback function and returns a unique ID. */
+    readonly register: (callback: (arg?: unknown) => void) => CallbackId;
+    /** Executes and removes a callback associated with the given ID. */
+    readonly execute: (id: CallbackId, arg?: unknown) => void;
+}
+export type CallbackId = string & Brand<"CallbackId">;
+export declare const createCallbacks: (deps: NanoIdLibDep) => Callbacks;
+//# sourceMappingURL=Callbacks.d.ts.map

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

@@ -0,0 +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"}

package/dist/src/Callbacks.js

@@ -0,0 +1,18 @@
+export const createCallbacks = (deps) => {
+    const callbackMap = new Map();
+    const callbacks = {
+        register: (callback) => {
+            const id = deps.nanoIdLib.nanoid();
+            callbackMap.set(id, callback);
+            return id;
+        },
+        execute: (id, arg) => {
+            const callback = callbackMap.get(id);
+            if (callback) {
+                callbackMap.delete(id);
+                callback(arg);
+            }
+        },
+    };
+    return callbacks;
+};

package/dist/src/Console.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 📝 Cross-platform console
+ *
+ * Console abstraction for Chrome 123+, Firefox 125+, Safari 18.1+, Node.js
+ * 22.x+, and React Native 0.75+. Includes methods guaranteed to be available in
+ * these environments and expected to remain compatible in future versions.
+ * Output formatting may vary (e.g., interactive UI in browsers vs. text in
+ * Node.js/React Native), but functionality is consistent across platforms.
+ *
+ * **Convention**: Use a tag (e.g., `[db]`) as the first argument for log
+ * filtering.
+ *
+ * ### Example
+ *
+ * ```ts
+ * deps.console.log("[db]", "send data message", protocolMessage);
+ * ```
+ *
+ * **Tip**: In browser dev tools, you can filter logs by tag (e.g., `[db]`) to
+ * quickly find relevant messages.
+ *
+ * **Warning**: If you encounter platform-specific issues or missing methods,
+ * please contribute a PR with details about the environment and behavior.
+ *
+ * @module
+ */
+/**
+ * Cross-platform Console interface for Chrome 123+, Firefox 125+, Safari 18.1+,
+ * Node.js 22.x+, and React Native 0.75+
+ */
+export interface Console {
+    /** Controls whether console methods produce output (default: true) */
+    enabled?: boolean;
+    /** Outputs a message to the console */
+    log: (...args: Array<any>) => void;
+    /** Outputs an informational message (often same as log) */
+    info: (...args: Array<any>) => void;
+    /** Outputs a warning message */
+    warn: (...args: Array<any>) => void;
+    /** Outputs an error message */
+    error: (...args: Array<any>) => void;
+    /** Outputs a debug message */
+    debug: (...args: Array<any>) => void;
+    /** Starts a timer with an optional label */
+    time: (label?: string) => void;
+    /** Ends a timer and logs the elapsed time */
+    timeEnd: (label?: string) => void;
+    /** Displays an object's properties in a detailed format */
+    dir: (object: any, options?: any) => void;
+    /** Displays tabular data as a table */
+    table: (tabularData: any, properties?: Array<string>) => void;
+    /** Logs the number of times this has been called with the given label */
+    count: (label?: string) => void;
+    /** Resets the counter for the given label */
+    countReset: (label?: string) => void;
+    /** Writes a message if the value is falsy, otherwise does nothing */
+    assert: (value: any, message?: string, ...optionalParams: Array<any>) => void;
+    /** Logs the elapsed time for a timer without ending it */
+    timeLog: (label?: string, ...data: Array<any>) => void;
+    /** Prints a stack trace with an optional message */
+    trace: (message?: any, ...optionalParams: Array<any>) => void;
+}
+/** Dependency interface for injecting a Console instance. */
+export interface ConsoleDep {
+    readonly console: Console;
+}
+export interface ConsoleConfig {
+    /**
+     * Enable or disable console logging (default: false). When true, logs are
+     * output to the {@link Console}; when false, logging is disabled for all
+     * methods except `error`, which always outputs to ensure critical issues are
+     * not missed.
+     */
+    readonly enableLogging?: boolean;
+}
+/** Creates a console instance using the global console. */
+export declare const createConsole: (config?: ConsoleConfig) => Console;
+//# sourceMappingURL=Console.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Console.d.ts","sourceRoot":"","sources":["../../src/Console.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,sEAAsE;IACtE,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,uCAAuC;IACvC,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;IAEnC,2DAA2D;IAC3D,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;IAEpC,gCAAgC;IAChC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;IAEpC,+BAA+B;IAC/B,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;IAErC,8BAA8B;IAC9B,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;IAErC,4CAA4C;IAC5C,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAE/B,6CAA6C;IAC7C,OAAO,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAElC,2DAA2D;IAC3D,GAAG,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC;IAE1C,uCAAuC;IACvC,KAAK,EAAE,CAAC,WAAW,EAAE,GAAG,EAAE,UAAU,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;IAE9D,yEAAyE;IACzE,KAAK,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAEhC,6CAA6C;IAC7C,UAAU,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAErC,qEAAqE;IACrE,MAAM,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,cAAc,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;IAE9E,0DAA0D;IAC1D,OAAO,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;IAEvD,oDAAoD;IACpD,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,GAAG,cAAc,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;CAC/D;AAED,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,2DAA2D;AAC3D,eAAO,MAAM,aAAa,GAAI,SAAQ,aAAkB,KAAG,OAgE1D,CAAC"}