@evolu/common 7.4.1 → 8.0.0-next.0

package/dist/src/Array.js

@@ -1,8 +1,67 @@
 /**
- * Array types, type guards, operations, transformations, accessors, and (rare)
- * mutations
+ * Array helpers that help TypeScript help you.
  *
- * ### Example
+ * - **Non-empty arrays**: compile-time guarantee of at least one element
+ * - **Readonly arrays**: prevents accidental mutation
+ *
+ * Instead of checking array length at runtime, use {@link NonEmptyReadonlyArray}
+ * so TypeScript rejects empty arrays at compile time. Functions like
+ * {@link firstInArray} require a non-empty array — TypeScript won't let us pass
+ * an empty one. {@link mapArray} preserves non-emptiness (native `map` doesn't),
+ * while {@link appendToArray} and {@link prependToArray} guarantee the result is
+ * non-empty.
+ *
+ * All helpers return readonly arrays for safety. Consider how dangerous native
+ * `sort()` is — it mutates the original array and returns it, making bugs hard
+ * to track:
+ *
+ * ```ts
+ * const sortScores = (arr: number[]) => arr.sort((a, b) => a - b);
+ *
+ * const scores = [3, 1, 2];
+ * const leaderboard = sortScores(scores);
+ * leaderboard; // [1, 2, 3]
+ * scores; // [1, 2, 3] — original order lost!
+ * ```
+ *
+ * Imagine every method doing that.
+ *
+ * On a `ReadonlyArray`, `.sort()` doesn't even exist. Use {@link sortArray}
+ * instead:
+ *
+ * ```ts
+ * const sortScores = (arr: ReadonlyArray<number>) =>
+ *   sortArray(arr, (a, b) => a - b);
+ *
+ * const scores: ReadonlyArray<number> = [3, 1, 2];
+ * const leaderboard = sortScores(scores);
+ * leaderboard; // [1, 2, 3]
+ * scores; // [3, 1, 2] — safe!
+ * ```
+ *
+ * Even better, require a {@link NonEmptyReadonlyArray} — there's nothing to sort
+ * if the array is empty anyway:
+ *
+ * ```ts
+ * const sortScores = (arr: NonEmptyReadonlyArray<number>) =>
+ *   sortArray(arr, (a, b) => a - b);
+ * ```
+ *
+ * Sorting an empty array isn't expensive, but functions can have side effects
+ * like database queries or network requests. Using non-empty arrays whenever
+ * possible is a good convention.
+ *
+ * For performance-critical cases where mutation is needed, Evolu provides
+ * {@link shiftFromArray} and {@link popFromArray} — but only because they improve
+ * type safety by returning a guaranteed `T` rather than an optional value.
+ *
+ * ### When to use native methods
+ *
+ * These helpers only exist where they add type-level value. Native methods like
+ * `find`, `some`, `every`, `includes`, `indexOf`, and `findIndex` work well on
+ * readonly arrays without mutation — use them directly.
+ *
+ * ## Examples
  *
  * ```ts
  * // Types - compile-time guarantee of at least one element
@@ -12,15 +71,13 @@
  *
  * // Type guards
  * const arr: ReadonlyArray<number> = [1, 2, 3];
- * if (isNonEmptyReadonlyArray(arr)) {
+ * if (isNonEmptyArray(arr)) {
  *   firstInArray(arr);
  * }
  *
- * // Operations
+ * // Transformations
  * 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]
@@ -28,7 +85,7 @@
  * const [evens, odds] = partitionArray(
  *   [1, 2, 3, 4, 5],
  *   (x) => x % 2 === 0,
- * ); // [[2, 4], [1, 3, 5]]
+ * );
  *
  * // Accessors
  * const first = firstInArray(["a", "b", "c"]); // "a"
@@ -36,116 +93,123 @@
  *
  * // Mutations
  * const mutable: NonEmptyArray<number> = [1, 2, 3];
- * shiftArray(mutable); // 1 (guaranteed to exist)
+ * shiftFromArray(mutable); // 1 (guaranteed to exist)
  * mutable; // [2, 3]
  * ```
  *
- * Functions are intentionally data-first to be prepared for the upcoming
- * JavaScript pipe operator.
+ * ## Composition
+ *
+ * All array helpers use a data-first style (the array is the first argument)
+ * because it's natural for single operations:
  *
  * ```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),
- * );
+ * Data-first style also reads well for a few operations, often fitting on a
+ * line:
  *
- * // 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);
+ * ```ts
+ * const cheapest = firstInArray(sortArray(prices, orderNumber));
+ * const uniqueNames = dedupeArray(mapArray(users, (u) => u.name));
+ * const latestDone = lastInArray(filterArray(jobs, isCompletedJob));
  * ```
  *
- * ### Why data-first?
+ * For more operations, create a function like `getOldestActiveUser` or a
+ * generic helper.
  *
- * 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:
+ * Some libraries provide dual APIs with data-last for pipe-based composition.
+ * Evolu prefers simplicity (in Latin, simplex means "one") so we don't have to
+ * choose between seemingly equivalent options (Buridan's ass dilemma).
  *
- * - 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.).
+ * Evolu doesn't provide `pipe` because few operations compose well without it,
+ * and for more operations, well-named functions communicate intent better.
  *
  * @module
  */
+import { identity } from "./Function.js";
 /**
- * Checks if an array is non-empty and narrows its type to {@link NonEmptyArray}.
- *
- * Use `if (!isNonEmptyArray(arr))` for empty checks.
+ * An empty readonly array.
  *
- * ### Example
+ * Use as a default or initial value to avoid allocating new empty arrays.
  *
- * ```ts
- * const arr: Array<number> = [1, 2, 3];
- * if (isNonEmptyArray(arr)) {
- *   firstInArray(arr); // arr is NonEmptyArray<number>
- * }
- * ```
- *
- * @category Type Guards
+ * @group Constants
  */
-export const isNonEmptyArray = (array) => array.length > 0;
+export const emptyArray = [];
+export function arrayFrom(iterableOrLength, map) {
+    if (typeof iterableOrLength === "number") {
+        return Array.from({ length: iterableOrLength }, (_, i) => map(i));
+    }
+    return Array.isArray(iterableOrLength)
+        ? iterableOrLength
+        : [...iterableOrLength];
+}
 /**
- * Checks if a readonly array is non-empty and narrows its type to
- * {@link NonEmptyReadonlyArray}.
+ * Better `Array.fromAsync`.
  *
- * Use `if (!isNonEmptyReadonlyArray(arr))` for empty checks.
+ * Returns a readonly array and awaits promised items from sync or async
+ * iterables.
  *
  * ### Example
  *
  * ```ts
- * const arr: ReadonlyArray<number> = [1, 2, 3];
- * if (isNonEmptyReadonlyArray(arr)) {
- *   firstInArray(arr); // arr is NonEmptyReadonlyArray<number>
- * }
+ * await arrayFromAsync(new Set([1, 2, 3])); // ReadonlyArray<number>
+ * await arrayFromAsync(
+ *   (async function* () {
+ *     yield Promise.resolve(1);
+ *     yield Promise.resolve(2);
+ *   })(),
+ * ); // [1, 2]
  * ```
  *
- * @category Type Guards
+ * Unlike `Array.fromAsync`, there's no map parameter — map the result with
+ * {@link mapArray} or use
+ * {@link https://web.dev/blog/baseline-iterator-helpers | iterator helpers}
+ * directly on iterables.
+ *
+ * @group Constructors
  */
-export const isNonEmptyReadonlyArray = (array) => array.length > 0;
+export const arrayFromAsync = async (iterable) => Array.fromAsync(iterable);
+export function isNonEmptyArray(array) {
+    return array.length > 0;
+}
 /**
  * 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
+ * @group Transformations
  */
 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
+ * @group Transformations
  */
 export const prependToArray = (array, item) => [item, ...array];
 export function mapArray(array, mapper) {
-    return array.map(mapper);
+    // For loop is faster than array.map.
+    const length = array.length;
+    const result = new Array(length);
+    for (let i = 0; i < length; i++)
+        result[i] = mapper(array[i], i);
+    return result;
+}
+export function flatMapArray(array, mapper = identity) {
+    return array.flatMap(mapper);
+}
+export function concatArrays(first, second) {
+    return [...first, ...second];
 }
 export function filterArray(array, predicate) {
     return array.filter(predicate);
@@ -176,10 +240,39 @@ export function partitionArray(array, predicate) {
     }
     return [trueArray, falseArray];
 }
+export function sortArray(array, compareFn) {
+    return array.toSorted(compareFn);
+}
+export function reverseArray(array) {
+    return array.toReversed();
+}
 /**
- * Returns the first element of a non-empty array.
+ * Returns a new readonly array with elements removed and/or replaced.
+ *
+ * Wraps native `toSpliced`.
+ *
+ * ### Example
+ *
+ * ```ts
+ * spliceArray([1, 2, 3, 4], 1, 2); // [1, 4]
+ * spliceArray([1, 2, 3], 1, 1, 10, 11); // [1, 10, 11, 3]
+ * ```
  *
- * Accepts both mutable and readonly arrays. Does not mutate the original array.
+ * @group Transformations
+ */
+export const spliceArray = (array, start, deleteCount, ...items) => array.toSpliced(start, deleteCount, ...items);
+export function zipArray(arrays) {
+    if (arrays.length === 0)
+        return emptyArray;
+    const minLength = Math.min(...mapArray(arrays, (a) => a.length));
+    const result = new Array(minLength);
+    for (let i = 0; i < minLength; i++) {
+        result[i] = mapArray(arrays, (a) => a[i]);
+    }
+    return result;
+}
+/**
+ * Returns the first element of a non-empty array.
  *
  * ### Example
  *
@@ -187,52 +280,55 @@ export function partitionArray(array, predicate) {
  * firstInArray(["a", "b", "c"]); // "a"
  * ```
  *
- * @category Accessors
+ * @group 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
+ * @group Accessors
  */
 export const lastInArray = (array) => array[array.length - 1];
 /**
- * Shifts an item from a non-empty mutable array, guaranteed to return T.
+ * Shifts (removes and returns) the first element from a non-empty mutable
+ * array.
  *
  * **Mutates** the original array.
  *
  * ### Example
  *
  * ```ts
- * const arr: NonEmptyArray<number> = [1, 2, 3];
- * shiftArray(arr); // 1
- * arr; // [2, 3]
+ * // Process a queue of callbacks
+ * const waitingQueue: Array<() => void> = [callback1, callback2];
+ * if (isNonEmptyArray(waitingQueue)) {
+ *   shiftFromArray(waitingQueue)(); // Remove and immediately invoke
+ * }
  * ```
  *
- * @category Mutations
+ * @group Mutations
  */
-export const shiftArray = (array) => array.shift();
+export const shiftFromArray = (array) => array.shift();
 /**
- * Pops an item from a non-empty mutable array, guaranteed to return T.
+ * Pops (removes and returns) the last element from a non-empty mutable array.
  *
  * **Mutates** the original array.
  *
  * ### Example
  *
  * ```ts
- * const arr: NonEmptyArray<number> = [1, 2, 3];
- * popArray(arr); // 3
- * arr; // [1, 2]
+ * // Process a stack of callbacks (LIFO)
+ * const callbackStack: Array<() => void> = [callback1, callback2];
+ * if (isNonEmptyArray(callbackStack)) {
+ *   popFromArray(callbackStack)(); // Remove and immediately invoke
+ * }
  * ```
  *
- * @category Mutations
+ * @group Mutations
  */
-export const popArray = (array) => array.pop();
+export const popFromArray = (array) => array.pop();

package/dist/src/Assert.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Runtime assertions for invariant checking.
+ *
+ * @module
+ */
+import type { Ok, Result } from "./Result.js";
+import type { AbortError } from "./Task.js";
+import type { AnyType, InferType } from "./Type.js";
 /**
  * Ensures a condition is true, throwing an error with the provided message if
  * not.
@@ -5,23 +13,15 @@
  * 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).
+ * 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.
  *
  * ### Example
  *
  * ```ts
  * assert(true, "true is not true"); // no-op
  * assert(false, "true is not true"); // throws Error
- *
- * 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;
@@ -55,4 +55,50 @@ 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>];
+/**
+ * Ensures a value conforms to a {@link Type}.
+ *
+ * Uses the Type name for the default error message.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const length = buffer.getLength();
+ *
+ * // We know length is logically non-negative, but TypeScript doesn't.
+ * assertType(NonNegativeInt, length);
+ * ```
+ */
+export declare const assertType: <T extends AnyType>(type: T, value: unknown, message?: string) => asserts value is InferType<T>;
+/**
+ * Asserts that a {@link Result} did not fail with `AbortError`.
+ *
+ * Use when abort would indicate a programmer error rather than ordinary control
+ * flow.
+ *
+ * In general, abort is normal control flow. Stopping work and returning
+ * `AbortError` is the correct behavior when a `Run` or `Fiber` is cancelled.
+ *
+ * Use `assertNotAborted` only to protect invariants in code that has already
+ * decided abort must not happen, such as resource helpers built on
+ * `unabortable`. In those places it helps fail fast on mistakes, because
+ * TypeScript cannot fully enforce that lifecycle logic is correct.
+ */
+export declare function assertNotAborted<T>(result: Result<T, AbortError>, message?: string): asserts result is Ok<T>;
+export declare function assertNotAborted<T, E>(result: Result<T, E | AbortError>, message?: string): asserts result is Result<T, E>;
+/**
+ * Guards synchronous methods on objects that may be called after disposal.
+ *
+ * Use when an API must fail fast before touching already-disposed state.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const stack = new globalThis.AsyncDisposableStack();
+ * assertNotDisposed(stack); // no-op
+ * await stack.disposeAsync();
+ * assertNotDisposed(stack); // throws Error
+ * ```
+ */
+export declare const assertNotDisposed: (value: globalThis.DisposableStack | globalThis.AsyncDisposableStack) => void;
 //# 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":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;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"}
+{"version":3,"file":"Assert.d.ts","sourceRoot":"","sources":["../../src/Assert.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAQ,MAAM,WAAW,CAAC;AAE1D;;;;;;;;;;;;;;;;;GAiBG;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;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,UAAU,EAAE,CAAC,CAAC,SAAS,OAAO,EACzC,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,MAAM,KACb,OAAO,CAAC,KAAK,IAAI,SAAS,CAAC,CAAC,CAEhC,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,UAAU,CAAC,EAC7B,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAC3B,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,CAAC,EACnC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,EACjC,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAYlC;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,GAC5B,OAAO,UAAU,CAAC,eAAe,GAAG,UAAU,CAAC,oBAAoB,KAClE,IAEF,CAAC"}

package/dist/src/Assert.js

@@ -1,3 +1,8 @@
+/**
+ * Runtime assertions for invariant checking.
+ *
+ * @module
+ */
 /**
  * Ensures a condition is true, throwing an error with the provided message if
  * not.
@@ -5,23 +10,15 @@
  * 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).
+ * 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.
  *
  * ### Example
  *
  * ```ts
  * assert(true, "true is not true"); // no-op
  * assert(false, "true is not true"); // throws Error
- *
- * 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) => {
@@ -63,3 +60,42 @@ 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);
 };
+/**
+ * Ensures a value conforms to a {@link Type}.
+ *
+ * Uses the Type name for the default error message.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const length = buffer.getLength();
+ *
+ * // We know length is logically non-negative, but TypeScript doesn't.
+ * assertType(NonNegativeInt, length);
+ * ```
+ */
+export const assertType = (type, value, message) => {
+    assert(type.is(value), message ?? `Expected ${type.name}.`);
+};
+export function assertNotAborted(result, message = "Expected result to not be aborted.") {
+    const isAbortError = !result.ok &&
+        result.error.type === "AbortError";
+    assert(!isAbortError, message);
+}
+/**
+ * Guards synchronous methods on objects that may be called after disposal.
+ *
+ * Use when an API must fail fast before touching already-disposed state.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const stack = new globalThis.AsyncDisposableStack();
+ * assertNotDisposed(stack); // no-op
+ * await stack.disposeAsync();
+ * assertNotDisposed(stack); // throws Error
+ * ```
+ */
+export const assertNotDisposed = (value) => {
+    assert(!value.disposed, "Expected value to not be disposed.");
+};

package/dist/src/BigInt.d.ts

@@ -1,4 +1,9 @@
-import { Predicate } from "./Types.js";
+/**
+ * BigInt arithmetic and comparison utilities.
+ *
+ * @module
+ */
+import type { Predicate } from "./Types.js";
 /** Increments a bigint by 1. */
 export declare const incrementBigInt: (n: bigint) => bigint;
 /** Decrements a bigint by 1. */

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

@@ -1 +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"}
+{"version":3,"file":"BigInt.d.ts","sourceRoot":"","sources":["../../src/BigInt.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,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

@@ -1,3 +1,8 @@
+/**
+ * BigInt arithmetic and comparison utilities.
+ *
+ * @module
+ */
 /** Increments a bigint by 1. */
 export const incrementBigInt = (n) => n + 1n;
 /** Decrements a bigint by 1. */

package/dist/src/Brand.d.ts

@@ -1,12 +1,20 @@
 /**
  * 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.
+ * @module
+ */
+/**
+ * An interface for creating branded types.
+ *
+ * Branded types enhance type safety by distinguishing otherwise identical
+ * types, such as `number` or `string`, to enforce stricter type checks. For
+ * example, instead of a plain `number`, use `PositiveInt`. Instead of a plain
+ * `string`, use `TrimmedString`.
  *
- * Supports multiple brands, allowing types to act like flags.
+ * Avoid primitive types in domain code—brand everything. Evolu Type provides
+ * many brand helpers.
  *
- * ### Example 1: Single Brand
+ * ### Single Brand
  *
  * ```ts
  * // A branded type definition
@@ -25,12 +33,12 @@
  *   // Implementation
  * };
  *
- * getUser(userId); // ✅ Valid
- * getUser(123); // ❌ TypeScript error
- * getUser("123"); // ❌ TypeScript error
+ * getUser(userId); // Valid
+ * getUser(123); // TypeScript error
+ * getUser("123"); // TypeScript error
  * ```
  *
- * ### Example 2: Multiple Brands
+ * ### Multiple Brands (to act like flags)
  *
  * ```ts
  * // Define branded types
@@ -50,10 +58,30 @@
  * 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
+ * requiresMin1(min1Value); // Valid
+ * requiresMax100(max100Value); // Valid
+ * requiresMin1(min1Max100Value); // Valid: Min1Max100 satisfies Min1
+ * requiresMax100(min1Max100Value); // Valid: Min1Max100 satisfies Max100
+ * ```
+ *
+ * ### Standalone Brand
+ *
+ * Brand can be used alone without a base type for purely nominal typing. This
+ * is useful for opaque values where the internal structure is hidden and type
+ * identity is based on name only. For example, platform-specific handles can be
+ * branded to prevent accidental mixing of implementations while keeping common
+ * code platform-agnostic.
+ *
+ * ```ts
+ * // A nominal type with no underlying structure exposed
+ * type NativePort = Brand<"NativePort">;
+ *
+ * // Only values explicitly cast to NativePort are accepted
+ * const requiresNativePort = (port: NativePort): void => {};
+ *
+ * const port: NativePort = nativeValue as NativePort;
+ * requiresNativePort(port); // Valid
+ * requiresNativePort(nativeValue); // TypeScript error
  * ```
  */
 export interface Brand<B extends string> {

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

@@ -1 +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"}
+{"version":3,"file":"Brand.d.ts","sourceRoot":"","sources":["../../src/Brand.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;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"}