@evolu/common 6.0.1-preview.8 → 7.0.0

package/README.md

@@ -1,6 +1,6 @@
 # Evolu
 
-Evolu is TypeScript library and local-first framework.
+Evolu is TypeScript library and local-first platform.
 
 ## Documentation
 
@@ -24,7 +24,7 @@ The Evolu Relay source along with the Docker files can be in the [/apps/relay](/
 
 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.
+For more information, reference the [Evolu Relay](https://www.evolu.dev/docs/relay) documentation.
 
 ## Developing
 

package/dist/src/Array.d.ts

@@ -1,17 +1,261 @@
-/** An array with at least one element. */
+/**
+ * 🔒 Type-safe array helpers that do not mutate
+ *
+ * Array types, guards, operations, transformations, accessors, and (rare)
+ * mutations.
+ *
+ * Functions are intentionally data-first to be prepared for the upcoming
+ * JavaScript pipe operator.
+ *
+ * ```ts
+ * // Data-first is natural for single operations.
+ * const timestamps = mapArray(messages, (m) => m.timestamp);
+ *
+ * // But data-first can be hard to read for nested calls.
+ * const result = firstInArray(
+ *   mapArray(dedupeArray(appendToArray(value, 2)), (x) => x * 2),
+ * );
+ *
+ * // With the upcoming pipe operator, it's clear.
+ * // const result = value
+ * //   |> appendToArray(%, 2)
+ * //   |> dedupeArray(%)
+ * //   |> mapArray(%, (x) => x * 2)
+ * //   |> firstInArray(%);
+ *
+ * // Until the pipe operator lands, use nested calls or name each step:
+ * const appended = appendToArray(value, 2);
+ * const deduped = dedupeArray(appended);
+ * const mapped = mapArray(deduped, (x) => x * 2);
+ * const result = firstInArray(mapped);
+ * ```
+ *
+ * ### Why data-first?
+ *
+ * Evolu optimizes for consistent code style. We can't have both data-first
+ * single operations and curried data-last helpers without sacrificing
+ * consistency. We chose data-first because:
+ *
+ * - It's natural for single operations (for example `mapArray(messages, (m) =>
+ *   m.timestamp)`).
+ * - It aligns with the upcoming JavaScript pipe operator.
+ *
+ * **Note**: Feel free to use Array instance methods (mutation) if you think
+ * it's better (performance, local scope, etc.).
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Types - compile-time guarantee of at least one element
+ * const _valid: NonEmptyReadonlyArray<number> = [1, 2, 3];
+ * // ts-expect-error - empty array is not a valid NonEmptyReadonlyArray
+ * const _invalid: NonEmptyReadonlyArray<number> = [];
+ *
+ * // Guards
+ * const arr: ReadonlyArray<number> = [1, 2, 3];
+ * if (isNonEmptyReadonlyArray(arr)) {
+ *   firstInArray(arr);
+ * }
+ *
+ * // Operations
+ * const appended = appendToArray([1, 2, 3], 4); // [1, 2, 3, 4]
+ * const prepended = prependToArray([2, 3], 1); // [1, 2, 3]
+ *
+ * // Transformations
+ * const readonly: ReadonlyArray<number> = [1, 2, 3];
+ * const mapped = mapArray(readonly, (x) => x * 2); // [2, 4, 6]
+ * const filtered = filterArray(readonly, (x) => x > 1); // [2, 3]
+ * const deduped = dedupeArray([1, 2, 1, 3, 2]); // [1, 2, 3]
+ *
+ * // Accessors
+ * const first = firstInArray(["a", "b", "c"]); // "a"
+ * const last = lastInArray(["a", "b", "c"]); // "c"
+ *
+ * // Mutations
+ * const mutable: NonEmptyArray<number> = [1, 2, 3];
+ * shiftArray(mutable); // 1 (guaranteed to exist)
+ * mutable; // [2, 3]
+ * ```
+ *
+ * @module
+ */
+/**
+ * An array with at least one element.
+ *
+ * @category Types
+ */
 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. */
+/**
+ * A readonly array with at least one element.
+ *
+ * @category Types
+ */
 export type NonEmptyReadonlyArray<T> = readonly [T, ...ReadonlyArray<T>];
-/** Checks if an array is non-empty. */
+/**
+ * Checks if an array is non-empty and narrows its type to {@link NonEmptyArray}.
+ *
+ * Use `if (!isNonEmptyArray(arr))` for empty checks.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const arr: Array<number> = [1, 2, 3];
+ * if (isNonEmptyArray(arr)) {
+ *   firstInArray(arr); // arr is NonEmptyArray<number>
+ * }
+ * ```
+ *
+ * @category Type Guards
+ */
+export declare const isNonEmptyArray: <T>(array: Array<T>) => array is NonEmptyArray<T>;
+/**
+ * Checks if a readonly array is non-empty and narrows its type to
+ * {@link NonEmptyReadonlyArray}.
+ *
+ * Use `if (!isNonEmptyReadonlyArray(arr))` for empty checks.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const arr: ReadonlyArray<number> = [1, 2, 3];
+ * if (isNonEmptyReadonlyArray(arr)) {
+ *   firstInArray(arr); // arr is NonEmptyReadonlyArray<number>
+ * }
+ * ```
+ *
+ * @category Type Guards
+ */
 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. */
+/**
+ * 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.
+ *
+ * ### Example
+ *
+ * ```ts
+ * appendToArray([1, 2, 3], 4); // [1, 2, 3, 4]
+ * ```
+ *
+ * @category Operations
+ */
+export declare const appendToArray: <T>(array: ReadonlyArray<T>, item: T) => NonEmptyReadonlyArray<T>;
+/**
+ * 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.
+ *
+ * ### Example
+ *
+ * ```ts
+ * prependToArray([2, 3], 1); // [1, 2, 3]
+ * ```
+ *
+ * @category Operations
+ */
+export declare const prependToArray: <T>(array: ReadonlyArray<T>, item: T) => NonEmptyReadonlyArray<T>;
+/**
+ * Maps an array using a mapper function.
+ *
+ * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ * Preserves non-empty type.
+ *
+ * ### Example
+ *
+ * ```ts
+ * mapArray([1, 2, 3], (x) => x * 2); // [2, 4, 6]
+ * ```
+ *
+ * @category Transformations
+ */
+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.
+ *
+ * ### Example
+ *
+ * ```ts
+ * filterArray([1, 2, 3, 4, 5], (x) => x % 2 === 0); // [2, 4]
+ * ```
+ *
+ * @category Transformations
+ */
+export declare const filterArray: <T>(array: ReadonlyArray<T>, predicate: (item: T, index: number) => boolean) => ReadonlyArray<T>;
+/**
+ * Returns a new readonly array with duplicate items removed. If `by` is
+ * provided, it will be used to derive the key for uniqueness; otherwise values
+ * are used directly. Dedupes by reference equality of values (or extracted keys
+ * when `by` is used).
+ *
+ * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ * Preserves non-empty type.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Dedupe primitives by value
+ * dedupeArray([1, 2, 1, 3, 2]); // [1, 2, 3]
+ *
+ * // Dedupe objects by property
+ * dedupeArray(
+ *   [
+ *     { id: 1, name: "Alice" },
+ *     { id: 2, name: "Bob" },
+ *     { id: 1, name: "Alice 2" },
+ *   ],
+ *   (item) => item.id,
+ * ); // [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }]
+ * ```
+ *
+ * @category Transformations
+ */
+export declare function dedupeArray<T>(array: NonEmptyReadonlyArray<T> | NonEmptyArray<T>, by?: (item: T) => unknown): NonEmptyReadonlyArray<T>;
+export declare function dedupeArray<T>(array: ReadonlyArray<T> | Array<T>, by?: (item: T) => unknown): ReadonlyArray<T>;
+/**
+ * Returns the first element of a non-empty array.
+ *
+ * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ *
+ * ### Example
+ *
+ * ```ts
+ * firstInArray(["a", "b", "c"]); // "a"
+ * ```
+ *
+ * @category Accessors
+ */
+export declare const firstInArray: <T>(array: NonEmptyReadonlyArray<T>) => T;
+/**
+ * Returns the last element of a non-empty array.
+ *
+ * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ *
+ * ### Example
+ *
+ * ```ts
+ * lastInArray(["a", "b", "c"]); // "c"
+ * ```
+ *
+ * @category Accessors
+ */
+export declare const lastInArray: <T>(array: NonEmptyReadonlyArray<T>) => T;
+/**
+ * Shifts an item from a non-empty mutable array, guaranteed to return T.
+ *
+ * **Mutates** the original array.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const arr: NonEmptyArray<number> = [1, 2, 3];
+ * shiftArray(arr); // 1
+ * arr; // [2, 3]
+ * ```
+ *
+ * @category Mutations
+ */
 export declare const shiftArray: <T>(array: NonEmptyArray<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":"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"}

package/dist/src/Array.js

@@ -1,12 +1,218 @@
-/** Checks if an array is non-empty. */
+/**
+ * 🔒 Type-safe array helpers that do not mutate
+ *
+ * Array types, guards, operations, transformations, accessors, and (rare)
+ * mutations.
+ *
+ * Functions are intentionally data-first to be prepared for the upcoming
+ * JavaScript pipe operator.
+ *
+ * ```ts
+ * // Data-first is natural for single operations.
+ * const timestamps = mapArray(messages, (m) => m.timestamp);
+ *
+ * // But data-first can be hard to read for nested calls.
+ * const result = firstInArray(
+ *   mapArray(dedupeArray(appendToArray(value, 2)), (x) => x * 2),
+ * );
+ *
+ * // With the upcoming pipe operator, it's clear.
+ * // const result = value
+ * //   |> appendToArray(%, 2)
+ * //   |> dedupeArray(%)
+ * //   |> mapArray(%, (x) => x * 2)
+ * //   |> firstInArray(%);
+ *
+ * // Until the pipe operator lands, use nested calls or name each step:
+ * const appended = appendToArray(value, 2);
+ * const deduped = dedupeArray(appended);
+ * const mapped = mapArray(deduped, (x) => x * 2);
+ * const result = firstInArray(mapped);
+ * ```
+ *
+ * ### Why data-first?
+ *
+ * Evolu optimizes for consistent code style. We can't have both data-first
+ * single operations and curried data-last helpers without sacrificing
+ * consistency. We chose data-first because:
+ *
+ * - It's natural for single operations (for example `mapArray(messages, (m) =>
+ *   m.timestamp)`).
+ * - It aligns with the upcoming JavaScript pipe operator.
+ *
+ * **Note**: Feel free to use Array instance methods (mutation) if you think
+ * it's better (performance, local scope, etc.).
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Types - compile-time guarantee of at least one element
+ * const _valid: NonEmptyReadonlyArray<number> = [1, 2, 3];
+ * // ts-expect-error - empty array is not a valid NonEmptyReadonlyArray
+ * const _invalid: NonEmptyReadonlyArray<number> = [];
+ *
+ * // Guards
+ * const arr: ReadonlyArray<number> = [1, 2, 3];
+ * if (isNonEmptyReadonlyArray(arr)) {
+ *   firstInArray(arr);
+ * }
+ *
+ * // Operations
+ * const appended = appendToArray([1, 2, 3], 4); // [1, 2, 3, 4]
+ * const prepended = prependToArray([2, 3], 1); // [1, 2, 3]
+ *
+ * // Transformations
+ * const readonly: ReadonlyArray<number> = [1, 2, 3];
+ * const mapped = mapArray(readonly, (x) => x * 2); // [2, 4, 6]
+ * const filtered = filterArray(readonly, (x) => x > 1); // [2, 3]
+ * const deduped = dedupeArray([1, 2, 1, 3, 2]); // [1, 2, 3]
+ *
+ * // Accessors
+ * const first = firstInArray(["a", "b", "c"]); // "a"
+ * const last = lastInArray(["a", "b", "c"]); // "c"
+ *
+ * // Mutations
+ * const mutable: NonEmptyArray<number> = [1, 2, 3];
+ * shiftArray(mutable); // 1 (guaranteed to exist)
+ * mutable; // [2, 3]
+ * ```
+ *
+ * @module
+ */
+/**
+ * Checks if an array is non-empty and narrows its type to {@link NonEmptyArray}.
+ *
+ * Use `if (!isNonEmptyArray(arr))` for empty checks.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const arr: Array<number> = [1, 2, 3];
+ * if (isNonEmptyArray(arr)) {
+ *   firstInArray(arr); // arr is NonEmptyArray<number>
+ * }
+ * ```
+ *
+ * @category Type Guards
+ */
 export const isNonEmptyArray = (array) => array.length > 0;
-/** Checks if an array is non-empty. */
+/**
+ * Checks if a readonly array is non-empty and narrows its type to
+ * {@link NonEmptyReadonlyArray}.
+ *
+ * Use `if (!isNonEmptyReadonlyArray(arr))` for empty checks.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const arr: ReadonlyArray<number> = [1, 2, 3];
+ * if (isNonEmptyReadonlyArray(arr)) {
+ *   firstInArray(arr); // arr is NonEmptyReadonlyArray<number>
+ * }
+ * ```
+ *
+ * @category Type Guards
+ */
 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. */
+/**
+ * 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.
+ *
+ * ### Example
+ *
+ * ```ts
+ * appendToArray([1, 2, 3], 4); // [1, 2, 3, 4]
+ * ```
+ *
+ * @category Operations
+ */
+export const appendToArray = (array, item) => [...array, item];
+/**
+ * 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.
+ *
+ * ### Example
+ *
+ * ```ts
+ * prependToArray([2, 3], 1); // [1, 2, 3]
+ * ```
+ *
+ * @category Operations
+ */
+export const prependToArray = (array, item) => [item, ...array];
+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.
+ *
+ * ### Example
+ *
+ * ```ts
+ * filterArray([1, 2, 3, 4, 5], (x) => x % 2 === 0); // [2, 4]
+ * ```
+ *
+ * @category Transformations
+ */
+export const filterArray = (array, predicate) => array.filter(predicate);
+export function dedupeArray(array, by) {
+    if (by == null) {
+        return Array.from(new Set(array));
+    }
+    const seen = new Set();
+    return array.filter((item) => {
+        const key = by(item);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/**
+ * Returns the first element of a non-empty array.
+ *
+ * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ *
+ * ### Example
+ *
+ * ```ts
+ * firstInArray(["a", "b", "c"]); // "a"
+ * ```
+ *
+ * @category Accessors
+ */
+export const firstInArray = (array) => array[0];
+/**
+ * Returns the last element of a non-empty array.
+ *
+ * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ *
+ * ### Example
+ *
+ * ```ts
+ * lastInArray(["a", "b", "c"]); // "c"
+ * ```
+ *
+ * @category Accessors
+ */
+export const lastInArray = (array) => array[array.length - 1];
+/**
+ * Shifts an item from a non-empty mutable array, guaranteed to return T.
+ *
+ * **Mutates** the original array.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const arr: NonEmptyArray<number> = [1, 2, 3];
+ * shiftArray(arr); // 1
+ * arr; // [2, 3]
+ * ```
+ *
+ * @category Mutations
+ */
 export const shiftArray = (array) => array.shift();

package/dist/src/Assert.d.ts

@@ -55,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;;;;;;;;;;;;;;;;;;;;;;;;;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;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

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