@evolu/common 8.0.0-next.4 → 8.0.0

package/src/Assert.ts

@@ -4,9 +4,7 @@
  * @module
  */
 
-import type { Ok, Result } from "./Result.js";
-import type { AbortError } from "./Task.js";
-import type { AnyType, InferType, Type } from "./Type.js";
+import type { Type } from "./Type.ts";
 
 /**
  * Ensures a condition is true, throwing an error with the provided message if
@@ -22,8 +20,12 @@ import type { AnyType, InferType, Type } from "./Type.js";
  * ### Example
  *
  * ```ts
- * assert(true, "true is not true"); // no-op
- * assert(false, "true is not true"); // throws Error
+ * import { assert as assertInvariant } from "@evolu/common";
+ *
+ * expect(() => assertInvariant(true, "Expected true.")).not.toThrow();
+ * expect(() => assertInvariant(false, "Expected true.")).toThrow(
+ *   "Expected true.",
+ * );
  * ```
  */
 export const assert: (
@@ -35,6 +37,22 @@ export const assert: (
   }
 };
 
+/**
+ * Asserts that a value is non-nullable.
+ *
+ * Narrows a nullable value to {@link NonNullable} when null or undefined is
+ * logically impossible but TypeScript cannot prove it.
+ */
+export const assertNonNullable: <T>(
+  value: T,
+  message?: string,
+) => asserts value is NonNullable<T> = (
+  value,
+  message = "Expected value to be non-nullable.",
+) => {
+  assert(value != null, message);
+};
+
 /**
  * Asserts that an array is non-empty.
  *
@@ -45,8 +63,13 @@ export const assert: (
  * ### Example
  *
  * ```ts
- * assertNonEmptyArray([1, 2, 3]); // no-op
- * assertNonEmptyArray([]); // throws Error
+ * import { assertNonEmptyArray } from "@evolu/common";
+ *
+ * const values = [1, 2, 3];
+ * assertNonEmptyArray(values);
+ * expectTypeOf(values).toEqualTypeOf<[number, ...Array<number>]>();
+ * expect(values[0]).toBe(1);
+ * expect(() => assertNonEmptyArray([])).toThrow();
  * ```
  */
 export const assertNonEmptyArray: <T>(
@@ -69,8 +92,15 @@ export const assertNonEmptyArray: <T>(
  * ### Example
  *
  * ```ts
- * assertNonEmptyReadonlyArray([1, 2, 3]); // no-op
- * assertNonEmptyReadonlyArray([]); // throws Error
+ * import { assertNonEmptyReadonlyArray } from "@evolu/common";
+ *
+ * const values: ReadonlyArray<number> = [1, 2, 3];
+ * assertNonEmptyReadonlyArray(values);
+ * expectTypeOf(values).toEqualTypeOf<
+ *   readonly [number, ...Array<number>]
+ * >();
+ * expect(values[0]).toBe(1);
+ * expect(() => assertNonEmptyReadonlyArray([])).toThrow();
  * ```
  */
 export const assertNonEmptyReadonlyArray: <T>(
@@ -83,61 +113,6 @@ 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.
  *
@@ -146,14 +121,24 @@ export function assertNotAborted<T, E>(
  * ### Example
  *
  * ```ts
- * using disposer = new globalThis.AsyncDisposableStack();
- * assertNotDisposed(disposer); // no-op
+ * import { assertNotDisposed } from "@evolu/common";
+ *
+ * await using disposer = new globalThis.AsyncDisposableStack();
+ * expect(() => assertNotDisposed(disposer)).not.toThrow();
  * await disposer.disposeAsync();
- * assertNotDisposed(disposer); // throws Error
+ * expect(() => assertNotDisposed(disposer)).toThrow(
+ *   "Cannot use a disposed object.",
+ * );
  * ```
+ *
+ * This is the JavaScript equivalent of the .NET `ObjectDisposedException`
+ * pattern: once a helper has been disposed, calling its synchronous methods is
+ * a programmer error and should throw immediately instead of continuing with
+ * invalid state.
  */
 export const assertNotDisposed = (
-  value: DisposableStack | AsyncDisposableStack,
+  value:
+    DisposableStack | AsyncDisposableStack | { readonly disposed: boolean },
 ): void => {
-  assert(!value.disposed, "Expected value to not be disposed.");
+  assert(!value.disposed, "Cannot use a disposed object.");
 };

package/src/BigInt.ts

@@ -4,7 +4,7 @@
  * @module
  */
 
-import type { Predicate } from "./Types.js";
+import type { Predicate } from "./Types.ts";
 
 /** Increments a bigint by 1. */
 export const incrementBigInt = (n: bigint): bigint => n + 1n;
@@ -24,9 +24,12 @@ export const clampBigInt =
  * ### Example
  *
  * ```ts
+ * import { isBetweenBigInt } from "@evolu/common";
+ *
  * const isBetween10And20 = isBetweenBigInt(10n, 20n);
- * console.log(isBetween10And20(15n)); // true
- * console.log(isBetween10And20(25n)); // false
+ *
+ * expect(isBetween10And20(20n)).toBe(true);
+ * expect(isBetween10And20(25n)).toBe(false);
  * ```
  */
 export const isBetweenBigInt =

package/src/Brand.ts

@@ -15,57 +15,42 @@
  * Avoid primitive types in domain code—brand everything. Evolu Type provides
  * many brand helpers.
  *
- * ### Single Brand
+ * ### 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
- * };
+ * import type { Brand } from "@evolu/common";
  *
- * const userId = createUserId();
- *
- * // A function that accepts only `UserId`.
- * const getUser = (id: UserId) => {
- *   // Implementation
- * };
+ * type UserId = number & Brand<"UserId">;
  *
- * getUser(userId); // Valid
- * getUser(123); // TypeScript error
- * getUser("123"); // TypeScript error
+ * // Branding does not validate at runtime, so isolate the cast in a trusted
+ * // factory.
+ * const createUserId = (value: number): UserId => value as UserId;
+ * const getUser = (id: UserId): number => id;
+ * const userId = createUserId(123);
+ * expect(getUser(userId)).toBe(123);
+ * // @ts-expect-error A plain number is not a UserId.
+ * getUser(123);
  * ```
  *
- * ### Multiple Brands (to act like flags)
+ * ### Multiple brands
  *
  * ```ts
- * // Define branded types
+ * import type { Brand } from "@evolu/common";
+ *
  * 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;
+ * const requiresMin1 = (value: Min1): string => value;
+ * const requiresMax100 = (value: Max100): string => value;
  *
- * // 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
+ * expect(requiresMin1(min1Max100Value)).toBe("typescript");
+ * expect(requiresMax100(min1Max100Value)).toBe("typescript");
  * ```
  *
- * ### Standalone Brand
+ * ### 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
@@ -74,15 +59,17 @@
  * code platform-agnostic.
  *
  * ```ts
- * // A nominal type with no underlying structure exposed
+ * import type { Brand } from "@evolu/common";
+ *
  * type NativePort = Brand<"NativePort">;
  *
- * // Only values explicitly cast to NativePort are accepted
- * const requiresNativePort = (port: NativePort): void => {};
+ * const requiresNativePort = (port: NativePort): NativePort => port;
  *
- * const port: NativePort = nativeValue as NativePort;
- * requiresNativePort(port); // Valid
- * requiresNativePort(nativeValue); // TypeScript error
+ * const nativeValue: unknown = { id: 1 };
+ * const port = nativeValue as NativePort;
+ * expect(requiresNativePort(port)).toBe(nativeValue);
+ * // @ts-expect-error An unknown value is not a NativePort.
+ * requiresNativePort(nativeValue);
  * ```
  */
 export interface Brand<B extends string> {

package/src/Buffer.ts

@@ -4,8 +4,8 @@
  * @module
  */
 
-import type { Result } from "./Result.js";
-import { NonNegativeInt, zeroNonNegativeInt } from "./Type.js";
+import type { Result } from "./Result.ts";
+import { NonNegativeInt, zeroNonNegativeInt } from "./Type.ts";
 export {
   bytesToHex,
   bytesToUtf8,
@@ -51,18 +51,34 @@ export class BufferError extends Error {
  * ### Example
  *
  * ```ts
+ * import {
+ *   createBuffer,
+ *   createIdFromString,
+ *   IdBytes,
+ *   idBytesToId,
+ *   idBytesTypeValueLength,
+ *   idToIdBytes,
+ *   NonNegativeInt,
+ * } from "@evolu/common";
+ * import {
+ *   decodeNonNegativeInt,
+ *   encodeNonNegativeInt,
+ * } from "@evolu/common/local-first";
+ *
  * const buffer = createBuffer();
- * encodeNonNegativeInt(buffer, someInt);
- * encodeId(buffer, someId);
- * const result = buffer.unwrap(); // Final serialized data
+ * const id = createIdFromString("buffer-example");
+ * encodeNonNegativeInt(buffer, NonNegativeInt.orThrow(300));
+ * buffer.extend(idToIdBytes(id));
  *
- * // Decoding example (throws on error)
- * try {
- *   const num = decodeNonNegativeInt(buffer);
- *   const id = decodeId(buffer);
- * } catch (e) {
- *   console.error(e.stack); // Stack trace for debugging
- * }
+ * const decoder = createBuffer(buffer.unwrap());
+ * expect(decodeNonNegativeInt(decoder)).toBe(300);
+ * const decodedId = idBytesToId(
+ *   IdBytes.orThrow(decoder.shiftN(idBytesTypeValueLength)),
+ * );
+ * expect(decodedId).toBe(id);
+ * expect(() => decodeNonNegativeInt(decoder)).toThrow(
+ *   "Buffer parse ended prematurely",
+ * );
  * ```
  *
  * For more on exponential growth, see:

package/src/Cache.ts

@@ -4,7 +4,7 @@
  * @module
  */
 
-import { PositiveInt } from "./Type.js";
+import { PositiveInt } from "./Type.ts";
 
 /**
  * Generic cache interface providing basic key-value storage operations.
@@ -43,11 +43,16 @@ export interface Cache<K, V> {
  * ### Example
  *
  * ```ts
- * const cache = createLruCache<string, number>(2);
+ * import { createLruCache, PositiveInt } from "@evolu/common";
+ *
+ * const cache = createLruCache<string, number>(PositiveInt.orThrow(2));
  * cache.set("a", 1);
  * cache.set("b", 2);
- * cache.set("c", 3); // Evicts "a"
- * cache.has("a"); // false
+ * // Reading "a" makes "b" the least recently used entry.
+ * expect(cache.get("a")).toBe(1);
+ * cache.set("c", 3);
+ *
+ * expect(cache.has("b")).toBe(false);
  * ```
  */
 export const createLruCache = <K, V>(capacity: PositiveInt): Cache<K, V> => {

package/src/Callbacks.ts

@@ -4,10 +4,10 @@
  * @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";
+import type { RandomBytesDep } from "./Crypto.ts";
+import type { Result } from "./Result.ts";
+import { createId, Id } from "./Type.ts";
+import type { Callback } from "./Types.ts";
 
 /**
  * Request-response correlation for callbacks across boundaries.
@@ -22,27 +22,38 @@ import type { Callback } from "./Types.js";
  * The `execute` method intentionally does not use try-catch or {@link Result}
  * because it's the callback's responsibility to handle its own errors.
  *
- * ### Example
+ * ### Correlating callback responses
  *
  * ```ts
- * // No-argument callbacks
- * const callbacks = createCallbacks(deps);
- * const id = callbacks.register(() => console.log("called"));
- * callbacks.execute(id);
+ * import { createCallbacks, testCreateDeps } from "@evolu/common";
  *
- * // With argument callbacks
- * const stringCallbacks = createCallbacks<string>(deps);
- * const id = stringCallbacks.register((value) => {
- *   console.log(value);
+ * const deps = testCreateDeps();
+ *
+ * // No-argument callback
+ * using callbacks = createCallbacks(deps);
+ * let noArgumentCalls = 0;
+ * const noArgumentId = callbacks.register(() => {
+ *   noArgumentCalls++;
+ * });
+ * callbacks.execute(noArgumentId);
+ * callbacks.execute(noArgumentId);
+ * expect(noArgumentCalls).toBe(1);
+ *
+ * // Typed callback
+ * using stringCallbacks = createCallbacks<string>(deps);
+ * let received = "";
+ * const stringCallbackId = stringCallbacks.register((value) => {
+ *   received = value;
  * });
- * stringCallbacks.execute(id, "hello");
+ * stringCallbacks.execute(stringCallbackId, "hello");
+ * expect(received).toBe("hello");
  *
- * // Promise.withResolvers pattern
- * const promiseCallbacks = createCallbacks<string>(deps);
+ * // Promise.withResolvers
+ * using promiseCallbacks = createCallbacks<string>(deps);
  * const { promise, resolve } = Promise.withResolvers<string>();
- * const id = promiseCallbacks.register(resolve);
- * promiseCallbacks.execute(id, "resolved value");
- * await promise; // "resolved value"
+ * const promiseCallbackId = promiseCallbacks.register(resolve);
+ * promiseCallbacks.execute(promiseCallbackId, "resolved value");
+ * expect(await promise).toBe("resolved value");
  * ```
  *
  * @template T - The type of argument passed to callbacks (defaults to undefined