@evolu/common 7.4.0 → 8.0.0-next.0

package/src/Polyfills.ts

@@ -0,0 +1,465 @@
+/**
+ * Polyfills.
+ *
+ * @module
+ */
+
+/**
+ * Installs polyfills required by `@evolu/common`.
+ *
+ * Installs resource-management polyfills (`Symbol.dispose`,
+ * `Symbol.asyncDispose`, `DisposableStack`, `AsyncDisposableStack`, and
+ * `SuppressedError`), which are not yet supported by Safari and React Native.
+ *
+ * Evolu currently does not require any additional polyfills. If that changes,
+ * this is where they will be installed.
+ *
+ * `@evolu/react-native` has its own `Polyfills` module and its
+ * `installPolyfills` calls this function first, then installs React Native
+ * specific polyfills.
+ *
+ * Call this explicitly from the app entry point.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Resource_management
+ * @see https://github.com/es-shims/DisposableStack
+ * @see https://github.com/es-shims/DisposableStack/issues/9
+ */
+export const installPolyfills = (): void => {
+  /**
+   * This module intentionally owns `DisposableStack` and `AsyncDisposableStack`
+   * polyfills instead of depending on `es-shims/DisposableStack` at runtime.
+   *
+   * Evolu originally used the upstream package, but WebKit hit a known async
+   * disposal completion bug (`completion["?"]` crash, see issue #9). The local
+   * implementation applies the fix and keeps behavior deterministic across
+   * runtimes used by Evolu.
+   *
+   * Conformance is validated by tests that combine upstream-style and test262
+   * parity cases with Evolu-specific regressions. Those tests run against
+   * native Node.js behavior and against this polyfill path in browser projects,
+   * including WebKit.
+   */
+  installDisposableStack();
+};
+
+interface DisposableResource {
+  readonly dispose: () => void;
+}
+
+interface AsyncDisposableResource {
+  readonly dispose: () => Promise<void>;
+}
+
+/** Installs `DisposableStack`-related polyfills missing from the runtime. */
+const installDisposableStack = (): void => {
+  installSuppressedError();
+
+  const symbolDispose = getOrInstallSymbol("dispose", "Symbol.dispose");
+  const symbolAsyncDispose = getOrInstallSymbol(
+    "asyncDispose",
+    "Symbol.asyncDispose",
+  );
+
+  if (typeof globalThis.DisposableStack !== "function") {
+    defineGlobalValue(
+      globalThis,
+      "DisposableStack",
+      createDisposableStackPolyfill(symbolDispose),
+    );
+  }
+
+  if (typeof globalThis.AsyncDisposableStack !== "function") {
+    defineGlobalValue(
+      globalThis,
+      "AsyncDisposableStack",
+      createAsyncDisposableStackPolyfill(symbolDispose, symbolAsyncDispose),
+    );
+  }
+};
+
+type SymbolWithDisposable = SymbolConstructor & {
+  dispose?: symbol;
+  asyncDispose?: symbol;
+};
+
+const suppressedErrorMessage = "An error was suppressed during disposal.";
+
+const disposedMessage = (className: string, method: string): string =>
+  `Cannot call ${className}.prototype.${method} on an already-disposed DisposableStack`;
+
+const defineGlobalValue = (
+  target: object,
+  key: PropertyKey,
+  value: unknown,
+): void => {
+  Object.defineProperty(target, key, {
+    configurable: true,
+    enumerable: false,
+    writable: true,
+    value,
+  });
+};
+
+const defineMethodAlias = (
+  target: object,
+  alias: symbol,
+  methodName: string,
+): void => {
+  defineGlobalValue(
+    target,
+    alias,
+    Object.getOwnPropertyDescriptor(target, methodName)?.value,
+  );
+};
+
+const throwIfDisposed = (disposed: boolean, message: string): void => {
+  if (disposed) {
+    throw new ReferenceError(message);
+  }
+};
+
+const appendDisposeError = (
+  currentError: unknown,
+  previousError: unknown,
+): unknown =>
+  new globalThis.SuppressedError(
+    currentError,
+    previousError,
+    suppressedErrorMessage,
+  );
+
+const assertObjectOrFunction = (value: unknown): object => {
+  if (
+    (typeof value !== "object" || value === null) &&
+    typeof value !== "function"
+  ) {
+    throw new TypeError("Disposable value must be an object or function.");
+  }
+
+  return value;
+};
+
+const getMethod = (
+  value: object,
+  key: symbol,
+): ((this: unknown) => unknown) | undefined => {
+  const method = (value as Record<symbol, unknown>)[key];
+  if (method === undefined) return undefined;
+  if (typeof method !== "function") {
+    throw new TypeError("Disposable method must be a function.");
+  }
+  return method as (this: unknown) => unknown;
+};
+
+const getOrInstallSymbol = (
+  key: "dispose" | "asyncDispose",
+  description: string,
+): symbol => {
+  const SymbolCtor = globalThis.Symbol as SymbolWithDisposable;
+  const installedValue = Object.getOwnPropertyDescriptor(SymbolCtor, key)
+    ?.value as unknown;
+  const installed =
+    typeof installedValue === "symbol" ? installedValue : undefined;
+  if (installed != null) return installed;
+
+  const symbol = Symbol(description);
+  Object.defineProperty(SymbolCtor, key, {
+    configurable: false,
+    enumerable: false,
+    writable: false,
+    value: symbol,
+  });
+  return symbol;
+};
+
+const installSuppressedError = (): void => {
+  if (typeof globalThis.SuppressedError === "function") return;
+
+  class SuppressedErrorPolyfill
+    extends Error
+    implements globalThis.SuppressedError
+  {
+    readonly error: unknown;
+    readonly suppressed: unknown;
+
+    constructor(error: unknown, suppressed: unknown, message?: string) {
+      super(message ?? suppressedErrorMessage);
+      this.name = "SuppressedError";
+      this.error = error;
+      this.suppressed = suppressed;
+    }
+  }
+
+  defineGlobalValue(globalThis, "SuppressedError", SuppressedErrorPolyfill);
+};
+
+const createDisposableStackPolyfill = (
+  symbolDispose: symbol,
+): new () => DisposableStack => {
+  class DisposableStackPolyfill implements DisposableStack {
+    #disposed = false;
+    #resources: Array<DisposableResource> = [];
+
+    declare readonly [Symbol.toStringTag]: "DisposableStack";
+    declare [Symbol.dispose]: () => void;
+
+    get disposed(): boolean {
+      return this.#disposed;
+    }
+
+    use<T extends object | null | undefined>(value: T): T {
+      throwIfDisposed(
+        this.#disposed,
+        disposedMessage("DisposableStack", "use"),
+      );
+      if (value == null) return value;
+
+      const target = assertObjectOrFunction(value);
+      const method = getMethod(target, symbolDispose);
+      if (method == null) {
+        throw new TypeError("Resource does not implement Symbol.dispose.");
+      }
+
+      this.#resources.push({
+        dispose: () => {
+          method.call(target);
+        },
+      });
+
+      return value;
+    }
+
+    adopt<T>(value: T, onDispose: (value: T) => void): T {
+      throwIfDisposed(
+        this.#disposed,
+        disposedMessage("DisposableStack", "adopt"),
+      );
+      if (typeof onDispose !== "function") {
+        throw new TypeError("onDispose must be a function.");
+      }
+
+      this.#resources.push({
+        dispose: () => {
+          onDispose(value);
+        },
+      });
+
+      return value;
+    }
+
+    defer(onDispose: () => void): void {
+      throwIfDisposed(
+        this.#disposed,
+        disposedMessage("DisposableStack", "defer"),
+      );
+      if (typeof onDispose !== "function") {
+        throw new TypeError("onDispose must be a function.");
+      }
+
+      this.#resources.push({
+        dispose: () => {
+          onDispose();
+        },
+      });
+    }
+
+    move(): DisposableStack {
+      throwIfDisposed(
+        this.#disposed,
+        disposedMessage("DisposableStack", "move"),
+      );
+
+      const moved = new DisposableStackPolyfill();
+      moved.#resources = this.#resources;
+
+      this.#resources = [];
+      this.#disposed = true;
+
+      return moved;
+    }
+
+    dispose(): void {
+      if (this.#disposed) return;
+
+      this.#disposed = true;
+      const resources = this.#resources;
+      this.#resources = [];
+
+      let completionError: unknown = undefined;
+      let hasCompletionError = false;
+
+      for (let i = resources.length - 1; i >= 0; i--) {
+        try {
+          resources[i].dispose();
+        } catch (error) {
+          completionError = hasCompletionError
+            ? appendDisposeError(error, completionError)
+            : error;
+          hasCompletionError = true;
+        }
+      }
+
+      if (hasCompletionError) {
+        throw completionError;
+      }
+    }
+  }
+
+  defineMethodAlias(
+    DisposableStackPolyfill.prototype,
+    symbolDispose,
+    "dispose",
+  );
+
+  Object.defineProperty(DisposableStackPolyfill.prototype, Symbol.toStringTag, {
+    configurable: true,
+    enumerable: false,
+    writable: false,
+    value: "DisposableStack",
+  });
+
+  return DisposableStackPolyfill;
+};
+
+const createAsyncDisposableStackPolyfill = (
+  symbolDispose: symbol,
+  symbolAsyncDispose: symbol,
+): new () => AsyncDisposableStack => {
+  class AsyncDisposableStackPolyfill implements AsyncDisposableStack {
+    #disposed = false;
+    #resources: Array<AsyncDisposableResource> = [];
+
+    declare readonly [Symbol.toStringTag]: "AsyncDisposableStack";
+    declare [Symbol.asyncDispose]: () => Promise<void>;
+
+    get disposed(): boolean {
+      return this.#disposed;
+    }
+
+    use<T extends object | null | undefined>(value: T): T {
+      throwIfDisposed(
+        this.#disposed,
+        disposedMessage("AsyncDisposableStack", "use"),
+      );
+      if (value == null) return value;
+
+      const target = assertObjectOrFunction(value);
+      const asyncMethod = getMethod(target, symbolAsyncDispose);
+
+      if (asyncMethod != null) {
+        this.#resources.push({
+          dispose: async () => {
+            await asyncMethod.call(target);
+          },
+        });
+        return value;
+      }
+
+      const syncMethod = getMethod(target, symbolDispose);
+
+      if (syncMethod != null) {
+        this.#resources.push({
+          dispose: () =>
+            Promise.resolve().then(() => {
+              syncMethod.call(target);
+            }),
+        });
+        return value;
+      }
+
+      throw new TypeError(
+        "Resource does not implement Symbol.asyncDispose or Symbol.dispose.",
+      );
+    }
+
+    adopt<T>(value: T, onDisposeAsync: (value: T) => void | Promise<void>): T {
+      throwIfDisposed(
+        this.#disposed,
+        disposedMessage("AsyncDisposableStack", "adopt"),
+      );
+      if (typeof onDisposeAsync !== "function") {
+        throw new TypeError("onDisposeAsync must be a function.");
+      }
+
+      this.#resources.push({
+        dispose: () => Promise.resolve().then(() => onDisposeAsync(value)),
+      });
+
+      return value;
+    }
+
+    defer(onDisposeAsync: () => void | Promise<void>): void {
+      throwIfDisposed(
+        this.#disposed,
+        disposedMessage("AsyncDisposableStack", "defer"),
+      );
+      if (typeof onDisposeAsync !== "function") {
+        throw new TypeError("onDisposeAsync must be a function.");
+      }
+
+      this.#resources.push({
+        dispose: () => Promise.resolve().then(() => onDisposeAsync()),
+      });
+    }
+
+    move(): AsyncDisposableStack {
+      throwIfDisposed(
+        this.#disposed,
+        disposedMessage("AsyncDisposableStack", "move"),
+      );
+
+      const moved = new AsyncDisposableStackPolyfill();
+      moved.#resources = this.#resources;
+
+      this.#resources = [];
+      this.#disposed = true;
+
+      return moved;
+    }
+
+    async disposeAsync(): Promise<void> {
+      if (this.#disposed) return;
+
+      this.#disposed = true;
+      const resources = this.#resources;
+      this.#resources = [];
+
+      let completionError: unknown = undefined;
+      let hasCompletionError = false;
+
+      for (let i = resources.length - 1; i >= 0; i--) {
+        try {
+          await resources[i].dispose();
+        } catch (error) {
+          completionError = hasCompletionError
+            ? appendDisposeError(error, completionError)
+            : error;
+          hasCompletionError = true;
+        }
+      }
+
+      if (hasCompletionError) {
+        throw completionError;
+      }
+    }
+  }
+
+  defineMethodAlias(
+    AsyncDisposableStackPolyfill.prototype,
+    symbolAsyncDispose,
+    "disposeAsync",
+  );
+
+  Object.defineProperty(
+    AsyncDisposableStackPolyfill.prototype,
+    Symbol.toStringTag,
+    {
+      configurable: true,
+      enumerable: false,
+      writable: false,
+      value: "AsyncDisposableStack",
+    },
+  );
+
+  return AsyncDisposableStackPolyfill;
+};

package/src/Random.ts

@@ -1,4 +1,18 @@
+/**
+ * Seeded random number generation.
+ *
+ * @module
+ */
+
 import { Random as RandomLib } from "random";
+import type { Brand } from "./Brand.js";
+
+/**
+ * A random floating point number in [0, 1).
+ *
+ * Branded to distinguish random values from arbitrary numbers.
+ */
+export type RandomNumber = number & Brand<"RandomNumber">;
 
 /**
  * A simple wrapper around Math.random().
@@ -19,7 +33,7 @@ import { Random as RandomLib } from "random";
  */
 export interface Random {
   /** Returns a floating point number in [0, 1). Just like Math.random(). */
-  next: () => number;
+  next: () => RandomNumber;
 }
 
 export interface RandomDep {
@@ -28,9 +42,13 @@ export interface RandomDep {
 
 /** Creates a {@link Random} using Math.random(). */
 export const createRandom = (): Random => ({
-  next: () => Math.random(),
+  next: () => Math.random() as RandomNumber,
 });
 
+/** Creates a seeded {@link Random} for deterministic tests. Default seed "evolu". */
+export const testCreateRandom = (seed = "evolu"): Random =>
+  createRandomWithSeed(seed);
+
 /**
  * Creates {@link Random} using {@link RandomLibDep} with a seed which is useful
  * for tests.
@@ -38,7 +56,7 @@ export const createRandom = (): Random => ({
 export const createRandomWithSeed = (seed: string): Random => {
   const random = new RandomLib(seed);
   return {
-    next: () => random.next(),
+    next: () => random.next() as RandomNumber,
   };
 };
 
@@ -48,16 +66,12 @@ export const createRandomWithSeed = (seed: string): Random => {
  * https://github.com/transitive-bullshit/random
  */
 export interface RandomLibDep {
-  random: RandomLib;
+  readonly randomLib: RandomLib;
 }
 
 /** Creates a `RandomLib` using the NPM `random` package. */
 export const createRandomLib = (): RandomLib => new RandomLib();
 
-/**
- * Creates {@link RandomLibDep} using the NPM `random` package with a seed which
- * is useful for tests.
- */
-export const createRandomLibWithSeed = (seed: string): RandomLibDep => ({
-  random: new RandomLib(seed),
-});
+/** Creates a seeded `RandomLib` for deterministic tests. Default seed "evolu". */
+export const testCreateRandomLib = (seed = "evolu"): RandomLib =>
+  new RandomLib(seed);

package/src/Redacted.ts

@@ -1,3 +1,9 @@
+/**
+ * Sensitive value protection against accidental exposure.
+ *
+ * @module
+ */
+
 import { assert } from "./Assert.js";
 import type { Brand } from "./Brand.js";
 import type { Eq } from "./Eq.js";
@@ -44,8 +50,8 @@ import type { Eq } from "./Eq.js";
  *   // use value...
  * };
  *
- * fetchUser(redactedKey); // ✅
- * // fetchUser(createRedacted("x" as DbPassword)); // ❌ type error
+ * fetchUser(redactedKey); // ok
+ * // fetchUser(createRedacted("x" as DbPassword)); // type error
  *
  * // Automatic cleanup with `using`
  * {
@@ -53,8 +59,6 @@ import type { Eq } from "./Eq.js";
  *   // ... use secret ...
  * } // automatically wiped from memory
  * ```
- *
- * @experimental
  */
 export interface Redacted<A> extends Brand<"Redacted">, Disposable {
   /** The inner type. Useful for inference via `typeof redacted.Type`. */

package/src/Ref.ts

@@ -1,23 +1,29 @@
+/**
+ * Mutable reference to an immutable value.
+ *
+ * @module
+ */
+
 import type { Store } from "./Store.js";
 
 /**
- * `Ref` provides a simple API to hold and update a value, similar to a "ref" in
- * functional programming or React. It exposes methods to get, set, and modify
- * the current state.
+ * Mutable reference to an immutable value.
  *
- * Use a Ref instead of a variable when you want to pass state around as an
- * object or update it in a controlled way. If you need subscriptions, see
- * {@link Store}.
+ * `Ref` holds the current value and exposes explicit `get`, `set`, `update`,
+ * and `modify` operations. The reference is mutable, but the value inside it
+ * must be immutable and replaced with a new value rather than mutated in place.
+ * Storing a mutable value in `Ref` does not make sense, because callers could
+ * mutate that value directly and pass it around without `Ref`.
  *
- * Updating in a controlled way means all changes go through specific methods
- * (`set` or `modify`), making state updates predictable and easy to track.
+ * Use it when mutable ownership of a value needs to be passed around as a
+ * value. For reactive state with subscriptions, see {@link Store}.
  *
  * ### Example
  *
  * ```ts
  * const count = createRef(0);
  * count.set(1);
- * count.modify((n) => n + 1);
+ * count.update((n) => n + 1);
  * console.log(count.get()); // 2
  * ```
  *
@@ -30,29 +36,74 @@ import type { Store } from "./Store.js";
  * ```
  */
 export interface Ref<T> {
-  /** Returns the current state. */
+  /** Returns the current value. */
   readonly get: () => T;
 
-  /** Sets the state. */
-  readonly set: (state: T) => void;
+  /** Sets the current value. */
+  readonly set: (value: T) => void;
+
+  /** Sets the current value and returns the previous value. */
+  readonly getAndSet: (value: T) => T;
 
-  /** Modifies the state using an updater function. */
-  readonly modify: (updater: (current: T) => T) => void;
+  /** Sets the current value and returns it. */
+  readonly setAndGet: (value: T) => T;
+
+  /** Updates the current value. */
+  readonly update: (updater: (current: T) => T) => void;
+
+  /** Updates the current value and returns the previous value. */
+  readonly getAndUpdate: (updater: (current: T) => T) => T;
+
+  /** Updates the current value and returns it. */
+  readonly updateAndGet: (updater: (current: T) => T) => T;
+
+  /** Modifies the current value and returns a computed result. */
+  readonly modify: <R>(
+    updater: (current: T) => readonly [result: R, nextValue: T],
+  ) => R;
 }
 
-/** Creates a {@link Ref} with the given initial state. */
-export const createRef = <T>(initialState: T): Ref<T> => {
-  let currentState = initialState;
+/** Creates a {@link Ref} with the given initial immutable value. */
+export const createRef = <T>(initialValue: T): Ref<T> => {
+  let currentValue = initialValue;
 
   return {
-    get: () => currentState,
+    get: () => currentValue,
+
+    set: (value) => {
+      currentValue = value;
+    },
+
+    getAndSet: (value) => {
+      const previousValue = currentValue;
+      currentValue = value;
+      return previousValue;
+    },
+
+    setAndGet: (value) => {
+      currentValue = value;
+      return currentValue;
+    },
+
+    update: (updater) => {
+      currentValue = updater(currentValue);
+    },
+
+    getAndUpdate: (updater) => {
+      const previousValue = currentValue;
+      currentValue = updater(currentValue);
+      return previousValue;
+    },
 
-    set: (state) => {
-      currentState = state;
+    updateAndGet: (updater) => {
+      currentValue = updater(currentValue);
+      return currentValue;
     },
 
     modify: (updater) => {
-      currentState = updater(currentState);
+      const [result, nextValue] = updater(currentValue);
+      currentValue = nextValue;
+      return result;
     },
   };
 };