@evolu/common 7.4.0 → 8.0.0-next.0

package/src/Assert.ts

@@ -1,4 +1,12 @@
-import type { Type } from "./Type.js";
+/**
+ * Runtime assertions for invariant checking.
+ *
+ * @module
+ */
+
+import type { Ok, Result } from "./Result.js";
+import type { AbortError } from "./Task.js";
+import type { AnyType, InferType, Type } from "./Type.js";
 
 /**
  * Ensures a condition is true, throwing an error with the provided message if
@@ -7,23 +15,15 @@ import type { Type } from "./Type.js";
  * 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: (
@@ -82,3 +82,78 @@ export const assertNonEmptyReadonlyArray: <T>(
 ) => {
   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: <T extends AnyType>(
+  type: T,
+  value: unknown,
+  message?: string,
+) => asserts value is InferType<T> = (type, value, message) => {
+  assert(type.is(value), message ?? `Expected ${type.name}.`);
+};
+
+/**
+ * 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 function assertNotAborted<T>(
+  result: Result<T, AbortError>,
+  message?: string,
+): asserts result is Ok<T>;
+export function assertNotAborted<T, E>(
+  result: Result<T, E | AbortError>,
+  message?: string,
+): asserts result is Result<T, E>;
+export function assertNotAborted<T, E>(
+  result: Result<T, E | AbortError>,
+  message = "Expected result to not be aborted.",
+): asserts result is Result<T, E> {
+  const isAbortError =
+    !result.ok &&
+    (result.error as { readonly type?: unknown }).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: globalThis.DisposableStack | globalThis.AsyncDisposableStack,
+): void => {
+  assert(!value.disposed, "Expected value to not be disposed.");
+};

package/src/BigInt.ts

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

package/src/Brand.ts

@@ -1,12 +1,21 @@
 /**
  * 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.
  *
- * Supports multiple brands, allowing types to act like flags.
+ * 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`.
  *
- * ### Example 1: Single Brand
+ * Avoid primitive types in domain code—brand everything. Evolu Type provides
+ * many brand helpers.
+ *
+ * ### Single Brand
  *
  * ```ts
  * // A branded type definition
@@ -25,12 +34,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 +59,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/src/Buffer.ts

@@ -1,5 +1,11 @@
-import { Result } from "./Result.js";
-import { NonNegativeInt } from "./Type.js";
+/**
+ * Binary data handling and byte array utilities.
+ *
+ * @module
+ */
+
+import type { Result } from "./Result.js";
+import { NonNegativeInt, zeroNonNegativeInt } from "./Type.js";
 export {
   bytesToHex,
   bytesToUtf8,
@@ -27,7 +33,7 @@ export class BufferError extends Error {
  * its capacity) to minimize memory reallocations and uses `subarray` for
  * efficient, copy-free data access in methods like `unwrap` and `shift`.
  *
- * ### Recommended Usage
+ * ## 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
@@ -166,7 +172,7 @@ export const createBuffer = (
     },
 
     reset: () => {
-      length = NonNegativeInt.orThrow(0);
+      length = zeroNonNegativeInt;
     },
 
     unwrap: () => value.subarray(0, length),

package/src/Cache.ts

@@ -1,3 +1,9 @@
+/**
+ * Cache implementations including LRU eviction.
+ *
+ * @module
+ */
+
 import { PositiveInt } from "./Type.js";
 
 /**
@@ -5,8 +11,11 @@ import { PositiveInt } from "./Type.js";
  *
  * 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.
+ * Note: Cache has a Map-like API but does not extend Map because it behaves
+ * differently. Eviction policies (like LRU) can remove entries implicitly, and
+ * code that accepts a Map can assume values remain until deleted explicitly. An
+ * evicting cache is not a safe substitute for Map (Liskov Substitution
+ * Principle).
  */
 export interface Cache<K, V> {
   /** Checks if a key exists in the cache. */

package/src/Callbacks.ts

@@ -1,7 +1,13 @@
-import { Brand } from "./Brand.js";
-import { RandomBytesDep } from "./Crypto.js";
-import { Result } from "./Result.js";
+/**
+ * Request-response correlation for callbacks across boundaries.
+ *
+ * @module
+ */
+
+import type { RandomBytesDep } from "./Crypto.js";
+import type { Result } from "./Result.js";
 import { createId, Id } from "./Type.js";
+import type { Callback } from "./Types.js";
 
 /**
  * Request-response correlation for callbacks across boundaries.
@@ -42,42 +48,46 @@ import { createId, Id } from "./Type.js";
  * @template T - The type of argument passed to callbacks (defaults to undefined
  *   for no-argument callbacks)
  */
-export interface Callbacks<T = undefined> {
+export interface Callbacks<T = undefined> extends Disposable {
   /** Registers a callback function and returns a unique ID. */
-  readonly register: (callback: (arg: T) => void) => CallbackId;
+  readonly register: (callback: Callback<T>) => Id;
 
   /** Executes and removes a callback associated with the given ID. */
   readonly execute: T extends undefined
-    ? (id: CallbackId) => undefined
-    : (id: CallbackId, arg: T) => undefined;
+    ? (id: Id) => undefined
+    : (id: Id, arg: T) => undefined;
 }
 
-/** Unique identifier for a callback in {@link Callbacks}. */
-export type CallbackId = Id & Brand<"Callback">;
-
 /** Creates a {@link Callbacks} registry for managing callbacks. */
 export const createCallbacks = <T = undefined>(
   deps: RandomBytesDep,
 ): Callbacks<T> => {
-  const callbackMap = new Map<CallbackId, (arg: T) => void>();
+  const callbackMap = new Map<Id, Callback<T>>();
+
+  const execute: Callbacks<T>["execute"] = ((id: Id, ...args: Array<T>) => {
+    const callback = callbackMap.get(id);
+    if (!callback) return undefined;
+    callbackMap.delete(id);
+    if (args.length === 0) {
+      // Called without argument (undefined case)
+      (callback as () => void)();
+    } else {
+      callback(args[0]);
+    }
+    return undefined;
+  }) as Callbacks<T>["execute"];
 
   return {
     register: (callback) => {
-      const id = createId<"Callback">(deps);
+      const id = createId(deps);
       callbackMap.set(id, callback);
       return id;
     },
 
-    execute: (id: CallbackId, ...args: T extends undefined ? [] : [T]) => {
-      const callback = callbackMap.get(id);
-      if (!callback) return;
-      callbackMap.delete(id);
-      if (args.length === 0) {
-        // Called without argument (undefined case)
-        (callback as () => void)();
-      } else {
-        callback(args[0]);
-      }
+    execute,
+
+    [Symbol.dispose]: () => {
+      callbackMap.clear();
     },
-  } as Callbacks<T>;
+  };
 };