@evolu/common 7.4.0 → 8.0.0-next.0

package/dist/src/Polyfills.js

@@ -0,0 +1,299 @@
+/**
+ * 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 = () => {
+    /**
+     * 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();
+};
+/** Installs `DisposableStack`-related polyfills missing from the runtime. */
+const installDisposableStack = () => {
+    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));
+    }
+};
+const suppressedErrorMessage = "An error was suppressed during disposal.";
+const disposedMessage = (className, method) => `Cannot call ${className}.prototype.${method} on an already-disposed DisposableStack`;
+const defineGlobalValue = (target, key, value) => {
+    Object.defineProperty(target, key, {
+        configurable: true,
+        enumerable: false,
+        writable: true,
+        value,
+    });
+};
+const defineMethodAlias = (target, alias, methodName) => {
+    defineGlobalValue(target, alias, Object.getOwnPropertyDescriptor(target, methodName)?.value);
+};
+const throwIfDisposed = (disposed, message) => {
+    if (disposed) {
+        throw new ReferenceError(message);
+    }
+};
+const appendDisposeError = (currentError, previousError) => new globalThis.SuppressedError(currentError, previousError, suppressedErrorMessage);
+const assertObjectOrFunction = (value) => {
+    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, key) => {
+    const method = value[key];
+    if (method === undefined)
+        return undefined;
+    if (typeof method !== "function") {
+        throw new TypeError("Disposable method must be a function.");
+    }
+    return method;
+};
+const getOrInstallSymbol = (key, description) => {
+    const SymbolCtor = globalThis.Symbol;
+    const installedValue = Object.getOwnPropertyDescriptor(SymbolCtor, key)
+        ?.value;
+    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 = () => {
+    if (typeof globalThis.SuppressedError === "function")
+        return;
+    class SuppressedErrorPolyfill extends Error {
+        error;
+        suppressed;
+        constructor(error, suppressed, message) {
+            super(message ?? suppressedErrorMessage);
+            this.name = "SuppressedError";
+            this.error = error;
+            this.suppressed = suppressed;
+        }
+    }
+    defineGlobalValue(globalThis, "SuppressedError", SuppressedErrorPolyfill);
+};
+const createDisposableStackPolyfill = (symbolDispose) => {
+    class DisposableStackPolyfill {
+        #disposed = false;
+        #resources = [];
+        get disposed() {
+            return this.#disposed;
+        }
+        use(value) {
+            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(value, onDispose) {
+            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) {
+            throwIfDisposed(this.#disposed, disposedMessage("DisposableStack", "defer"));
+            if (typeof onDispose !== "function") {
+                throw new TypeError("onDispose must be a function.");
+            }
+            this.#resources.push({
+                dispose: () => {
+                    onDispose();
+                },
+            });
+        }
+        move() {
+            throwIfDisposed(this.#disposed, disposedMessage("DisposableStack", "move"));
+            const moved = new DisposableStackPolyfill();
+            moved.#resources = this.#resources;
+            this.#resources = [];
+            this.#disposed = true;
+            return moved;
+        }
+        dispose() {
+            if (this.#disposed)
+                return;
+            this.#disposed = true;
+            const resources = this.#resources;
+            this.#resources = [];
+            let completionError = 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, symbolAsyncDispose) => {
+    class AsyncDisposableStackPolyfill {
+        #disposed = false;
+        #resources = [];
+        get disposed() {
+            return this.#disposed;
+        }
+        use(value) {
+            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(value, onDisposeAsync) {
+            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) {
+            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() {
+            throwIfDisposed(this.#disposed, disposedMessage("AsyncDisposableStack", "move"));
+            const moved = new AsyncDisposableStackPolyfill();
+            moved.#resources = this.#resources;
+            this.#resources = [];
+            this.#disposed = true;
+            return moved;
+        }
+        async disposeAsync() {
+            if (this.#disposed)
+                return;
+            this.#disposed = true;
+            const resources = this.#resources;
+            this.#resources = [];
+            let completionError = 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/dist/src/Random.d.ts

@@ -1,4 +1,16 @@
+/**
+ * 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().
  *
@@ -18,13 +30,15 @@ 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 {
     random: Random;
 }
 /** Creates a {@link Random} using Math.random(). */
 export declare const createRandom: () => Random;
+/** Creates a seeded {@link Random} for deterministic tests. Default seed "evolu". */
+export declare const testCreateRandom: (seed?: string) => Random;
 /**
  * Creates {@link Random} using {@link RandomLibDep} with a seed which is useful
  * for tests.
@@ -36,13 +50,10 @@ export declare 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 declare const createRandomLib: () => RandomLib;
-/**
- * Creates {@link RandomLibDep} using the NPM `random` package with a seed which
- * is useful for tests.
- */
-export declare const createRandomLibWithSeed: (seed: string) => RandomLibDep;
+/** Creates a seeded `RandomLib` for deterministic tests. Default seed "evolu". */
+export declare const testCreateRandomLib: (seed?: string) => RandomLib;
 //# sourceMappingURL=Random.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Random.d.ts","sourceRoot":"","sources":["../../src/Random.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,QAAQ,CAAC;AAE7C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,MAAM;IACrB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,oDAAoD;AACpD,eAAO,MAAM,YAAY,QAAO,MAE9B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,MAKnD,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,SAAS,CAAC;CACnB;AAED,4DAA4D;AAC5D,eAAO,MAAM,eAAe,QAAO,SAA4B,CAAC;AAEhE;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GAAI,MAAM,MAAM,KAAG,YAErD,CAAC"}
+{"version":3,"file":"Random.d.ts","sourceRoot":"","sources":["../../src/Random.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,KAAK,CAAC,cAAc,CAAC,CAAC;AAE1D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,MAAM;IACrB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,YAAY,CAAC;CAC1B;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,oDAAoD;AACpD,eAAO,MAAM,YAAY,QAAO,MAE9B,CAAC;AAEH,qFAAqF;AACrF,eAAO,MAAM,gBAAgB,GAAI,aAAc,KAAG,MACtB,CAAC;AAE7B;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,MAKnD,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B;AAED,4DAA4D;AAC5D,eAAO,MAAM,eAAe,QAAO,SAA4B,CAAC;AAEhE,kFAAkF;AAClF,eAAO,MAAM,mBAAmB,GAAI,aAAc,KAAG,SAChC,CAAC"}

package/dist/src/Random.js

@@ -1,8 +1,15 @@
+/**
+ * Seeded random number generation.
+ *
+ * @module
+ */
 import { Random as RandomLib } from "random";
 /** Creates a {@link Random} using Math.random(). */
 export const createRandom = () => ({
     next: () => Math.random(),
 });
+/** Creates a seeded {@link Random} for deterministic tests. Default seed "evolu". */
+export const testCreateRandom = (seed = "evolu") => createRandomWithSeed(seed);
 /**
  * Creates {@link Random} using {@link RandomLibDep} with a seed which is useful
  * for tests.
@@ -15,10 +22,5 @@ export const createRandomWithSeed = (seed) => {
 };
 /** Creates a `RandomLib` using the NPM `random` package. */
 export const createRandomLib = () => new RandomLib();
-/**
- * Creates {@link RandomLibDep} using the NPM `random` package with a seed which
- * is useful for tests.
- */
-export const createRandomLibWithSeed = (seed) => ({
-    random: new RandomLib(seed),
-});
+/** Creates a seeded `RandomLib` for deterministic tests. Default seed "evolu". */
+export const testCreateRandomLib = (seed = "evolu") => new RandomLib(seed);

package/dist/src/Redacted.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Sensitive value protection against accidental exposure.
+ *
+ * @module
+ */
 import type { Brand } from "./Brand.js";
 import type { Eq } from "./Eq.js";
 /**
@@ -42,8 +47,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`
  * {
@@ -51,8 +56,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/dist/src/Redacted.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Redacted.d.ts","sourceRoot":"","sources":["../../src/Redacted.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,CAAE,SAAQ,KAAK,CAAC,UAAU,CAAC,EAAE,UAAU;IAChE,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;CAClB;AAED,gEAAgE;AAChE,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,QAAQ,CAAC,CAAC,CAItD,CAAC;AAaF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,UAAU,QAAQ,CAAC,CAAC,CAAC,KAAG,CAGzD,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,UAAU,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,QAAQ,CAAC,OAAO,CAG7B,CAAC;AAEzC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,GAC1B,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,KAAG,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAEY,CAAC"}
+{"version":3,"file":"Redacted.d.ts","sourceRoot":"","sources":["../../src/Redacted.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,CAAE,SAAQ,KAAK,CAAC,UAAU,CAAC,EAAE,UAAU;IAChE,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;CAClB;AAED,gEAAgE;AAChE,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,QAAQ,CAAC,CAAC,CAItD,CAAC;AAaF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,UAAU,QAAQ,CAAC,CAAC,CAAC,KAAG,CAGzD,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,UAAU,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,QAAQ,CAAC,OAAO,CAG7B,CAAC;AAEzC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,GAC1B,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,KAAG,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAEY,CAAC"}

package/dist/src/Redacted.js

@@ -1,3 +1,8 @@
+/**
+ * Sensitive value protection against accidental exposure.
+ *
+ * @module
+ */
 import { assert } from "./Assert.js";
 /** Creates a {@link Redacted} wrapper for a sensitive value. */
 export const createRedacted = (value) => {

package/dist/src/Ref.d.ts

@@ -1,21 +1,26 @@
 /**
- * `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}.
+ * @module
+ */
+/**
+ * Mutable reference to an immutable value.
+ *
+ * `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
  * ```
  *
@@ -28,13 +33,23 @@
  * ```
  */
 export interface Ref<T> {
-    /** Returns the current state. */
+    /** Returns the current value. */
     readonly get: () => T;
-    /** Sets the state. */
-    readonly set: (state: T) => void;
-    /** Modifies the state using an updater function. */
-    readonly modify: (updater: (current: T) => 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;
+    /** 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 declare const createRef: <T>(initialState: T) => Ref<T>;
+/** Creates a {@link Ref} with the given initial immutable value. */
+export declare const createRef: <T>(initialValue: T) => Ref<T>;
 //# sourceMappingURL=Ref.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Ref.d.ts","sourceRoot":"","sources":["../../src/Ref.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,GAAG,CAAC,CAAC;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAEtB,sBAAsB;IACtB,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAEjC,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;CACvD;AAED,0DAA0D;AAC1D,eAAO,MAAM,SAAS,GAAI,CAAC,EAAE,cAAc,CAAC,KAAG,GAAG,CAAC,CAAC,CAcnD,CAAC"}
+{"version":3,"file":"Ref.d.ts","sourceRoot":"","sources":["../../src/Ref.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,GAAG,CAAC,CAAC;IACpB,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAEtB,8BAA8B;IAC9B,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAEjC,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;IAEpC,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;IAEpC,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;IAEtD,gEAAgE;IAChE,QAAQ,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAEzD,gDAAgD;IAChD,QAAQ,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAEzD,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,EACjB,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,KACxD,CAAC,CAAC;CACR;AAED,oEAAoE;AACpE,eAAO,MAAM,SAAS,GAAI,CAAC,EAAE,cAAc,CAAC,KAAG,GAAG,CAAC,CAAC,CA0CnD,CAAC"}

package/dist/src/Ref.js

@@ -1,13 +1,41 @@
-/** Creates a {@link Ref} with the given initial state. */
-export const createRef = (initialState) => {
-    let currentState = initialState;
+/**
+ * Mutable reference to an immutable value.
+ *
+ * @module
+ */
+/** Creates a {@link Ref} with the given initial immutable value. */
+export const createRef = (initialValue) => {
+    let currentValue = initialValue;
     return {
-        get: () => currentState,
-        set: (state) => {
-            currentState = state;
+        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;
+        },
+        updateAndGet: (updater) => {
+            currentValue = updater(currentValue);
+            return currentValue;
         },
         modify: (updater) => {
-            currentState = updater(currentState);
+            const [result, nextValue] = updater(currentValue);
+            currentValue = nextValue;
+            return result;
         },
     };
 };

package/dist/src/RefCount.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Reference counting helpers.
+ *
+ * @module
+ */
+import { type LookupOption } from "./Lookup.js";
+import { NonNegativeInt, PositiveInt } from "./Type.js";
+/**
+ * Reference count for one retained value.
+ *
+ * Decrementing below zero is a programmer error checked with {@link assert}.
+ */
+export interface RefCount extends Disposable {
+    /** Increments the count and returns the new count. */
+    readonly increment: () => PositiveInt;
+    /**
+     * Decrements the count and returns the new count.
+     *
+     * Decrementing below zero is a programmer error checked with {@link assert}.
+     */
+    readonly decrement: () => NonNegativeInt;
+    /** Returns the current count. */
+    readonly getCount: () => NonNegativeInt;
+    /** Disposes and invalidates the helper. Further method calls throw. */
+    readonly [Symbol.dispose]: () => void;
+}
+/** Creates {@link RefCount}. */
+export declare const createRefCount: () => RefCount;
+/**
+ * Reference counts keyed by logical identity.
+ *
+ * By default, {@link createRefCountByKey} uses reference identity, the same as
+ * `Map` keys. Callers may instead provide a {@link Lookup lookup} so logical
+ * equality is based on a derived stable key. Decrementing a missing key is a
+ * programmer error checked with {@link assert}.
+ */
+export interface RefCountByKey<TKey> extends Disposable {
+    /** Increments key count and returns the new count. */
+    readonly increment: (key: TKey) => PositiveInt;
+    /**
+     * Decrements key count and returns the new count.
+     *
+     * Decrementing a missing key is a programmer error checked with
+     * {@link assert}.
+     */
+    readonly decrement: (key: TKey) => NonNegativeInt;
+    /** Gets current count for key. Returns `0` when the key is not tracked. */
+    readonly getCount: (key: TKey) => NonNegativeInt;
+    /** Returns `true` when the key is tracked with count greater than zero. */
+    readonly has: (key: TKey) => boolean;
+    /** Returns all currently tracked keys. */
+    readonly keys: () => ReadonlySet<TKey>;
+    /** Disposes and invalidates the helper. Further method calls throw. */
+    readonly [Symbol.dispose]: () => void;
+}
+/** Options for {@link createRefCountByKey}. */
+export interface CreateRefCountByKeyOptions<TKey, L = TKey> extends LookupOption<TKey, L> {
+}
+/** Creates {@link RefCountByKey}. */
+export declare function createRefCountByKey<TKey = unknown>(): RefCountByKey<TKey>;
+export declare function createRefCountByKey<TKey, L>(options: CreateRefCountByKeyOptions<TKey, L>): RefCountByKey<TKey>;
+//# sourceMappingURL=RefCount.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RefCount.d.ts","sourceRoot":"","sources":["../../src/RefCount.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAgC,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,WAAW,EAAsB,MAAM,WAAW,CAAC;AAE5E;;;;GAIG;AACH,MAAM,WAAW,QAAS,SAAQ,UAAU;IAC1C,sDAAsD;IACtD,QAAQ,CAAC,SAAS,EAAE,MAAM,WAAW,CAAC;IAEtC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,cAAc,CAAC;IAEzC,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,cAAc,CAAC;IAExC,uEAAuE;IACvE,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACvC;AAED,gCAAgC;AAChC,eAAO,MAAM,cAAc,QAAO,QA8BjC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa,CAAC,IAAI,CAAE,SAAQ,UAAU;IACrD,sDAAsD;IACtD,QAAQ,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,WAAW,CAAC;IAE/C;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,cAAc,CAAC;IAElD,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,cAAc,CAAC;IAEjD,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,OAAO,CAAC;IAErC,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC;IAEvC,uEAAuE;IACvE,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACvC;AAED,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B,CACzC,IAAI,EACJ,CAAC,GAAG,IAAI,CACR,SAAQ,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC;CAAG;AAElC,qCAAqC;AACrC,wBAAgB,mBAAmB,CAAC,IAAI,GAAG,OAAO,KAAK,aAAa,CAAC,IAAI,CAAC,CAAC;AAC3E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,CAAC,EACzC,OAAO,EAAE,0BAA0B,CAAC,IAAI,EAAE,CAAC,CAAC,GAC3C,aAAa,CAAC,IAAI,CAAC,CAAC"}