@evolu/common 8.0.0-next.4 → 8.0.0

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

@@ -1 +1 @@
-{"version":3,"file":"Order.d.ts","sourceRoot":"","sources":["../../src/Order.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,QAAQ,CAAC;AAEnD;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAElC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,GACrB,CAAC,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,KAAG,KAAK,CAAC,CAAC,CAER,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,GACtB,CAAC,EAAE,OAAO,KAAK,CAAC,CAAC,CAAC,KAAG,KAAK,CAAC,CAAC,CAEhB,CAAC;AAEhB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,EAAE,KAAK,CAAC,MAAM,CAErC,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW,eAAqD,CAAC;AAE9E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,eAAqD,CAAC;AAE9E,uCAAuC;AACvC,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,UAAU,CAU7C,CAAC"}
+{"version":3,"file":"Order.d.ts","sourceRoot":"","sources":["../../src/Order.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,QAAQ,CAAC;AAEnD;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAElC;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW,GACrB,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,KAAG,KAAK,CAAC,CAAC,CAER,CAAC;AAE5C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,GACtB,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,KAAG,KAAK,CAAC,CAAC,CAEhB,CAAC;AAEhB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,EAAE,KAAK,CAAC,MAAM,CAErC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,eAAqD,CAAC;AAE9E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,eAAqD,CAAC;AAE9E,uCAAuC;AACvC,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,UAAU,CAU7C,CAAC"}

package/dist/src/Order.js

@@ -9,10 +9,12 @@
  * ### Example
  *
  * ```ts
+ * import { createOrder } from "@evolu/common";
+ *
  * const orderNumber = createOrder<number>((x, y) => x < y);
- * expect(orderNumber(1, 2)).toEqual(-1);
- * expect(orderNumber(2, 1)).toEqual(1);
- * expect(orderNumber(1, 1)).toEqual(0);
+ * expect(orderNumber(1, 2)).toBe(-1);
+ * expect(orderNumber(2, 1)).toBe(1);
+ * expect(orderNumber(1, 1)).toBe(0);
  * ```
  */
 export const createOrder = (isLessThan) => (x, y) => x === y ? 0 : isLessThan(x, y) ? -1 : 1;
@@ -22,9 +24,10 @@ export const createOrder = (isLessThan) => (x, y) => x === y ? 0 : isLessThan(x,
  * ### Example
  *
  * ```ts
- * reverseOrder(orderNumber)(1, 2); // 1
- * reverseOrder(orderNumber)(2, 1); // -1
- * reverseOrder(orderNumber)(1, 1); // 0
+ * import { orderNumber, reverseOrder } from "@evolu/common";
+ *
+ * const descendingOrderNumber = reverseOrder(orderNumber);
+ * expect([3, 1, 2].toSorted(descendingOrderNumber)).toEqual([3, 2, 1]);
  * ```
  */
 export const reverseOrder = (order) => (a, b) => order(b, a);
@@ -34,10 +37,9 @@ export const reverseOrder = (order) => (a, b) => order(b, a);
  * ### Example
  *
  * ```ts
- * orderString("a", "b"); // -1
- * orderString("b", "a"); // 1
- * orderString("a", "a"); // 0
- * ["c", "b", "a"].toSorted(orderString); // ["a", "b", "c"]
+ * import { orderString } from "@evolu/common";
+ *
+ * expect(["c", "b", "a"].toSorted(orderString)).toEqual(["a", "b", "c"]);
  * ```
  */
 export const orderString = /*#__PURE__*/ createOrder((a, b) => a < b);
@@ -47,13 +49,9 @@ export const orderString = /*#__PURE__*/ createOrder((a, b) => a < b);
  * ### Example
  *
  * ```ts
- * orderNumber(1, 2); // -1
- * orderNumber(2, 1); // 1
- * orderNumber(1, 1); // 0
- * [2, 1, 3].toSorted(orderNumber); // [1, 2, 3]
- * reverseOrder(orderNumber)(1, 2); // 1
- * reverseOrder(orderNumber)(2, 1); // -1
- * reverseOrder(orderNumber)(1, 1); // 0
+ * import { orderNumber } from "@evolu/common";
+ *
+ * expect([2, 1, 3].toSorted(orderNumber)).toEqual([1, 2, 3]);
  * ```
  */
 export const orderNumber = /*#__PURE__*/ createOrder((a, b) => a < b);
@@ -63,10 +61,9 @@ export const orderNumber = /*#__PURE__*/ createOrder((a, b) => a < b);
  * ### Example
  *
  * ```ts
- * orderBigInt(1n, 2n); // -1
- * orderBigInt(2n, 1n); // 1
- * orderBigInt(1n, 1n); // 0
- * [2n, 1n, 3n].toSorted(orderBigInt); // [1n, 2n, 3n]
+ * import { orderBigInt } from "@evolu/common";
+ *
+ * expect([2n, 1n, 3n].toSorted(orderBigInt)).toEqual([1n, 2n, 3n]);
  * ```
  */
 export const orderBigInt = /*#__PURE__*/ createOrder((a, b) => a < b);

package/dist/src/Platform.d.ts

@@ -7,6 +7,18 @@
 export declare const isHermes: boolean;
 /** Returns true if running in a server environment (no DOM). */
 export declare const isServer: boolean;
+/**
+ * True outside production builds.
+ *
+ * Bundlers (webpack, Vite, esbuild, Metro) replace the text
+ * `process.env.NODE_ENV` statically at build time, so in production bundles
+ * this expression folds to `false` and code behind it is dead-code-eliminated —
+ * the same mechanism React uses. The `typeof` guard makes the runtime read safe
+ * where no bundler ran, such as un-bundled browser ESM, where it fails closed
+ * to production behavior. Node.js reads it natively; React Native polyfills it.
+ * A missing `NODE_ENV` counts as development, matching React semantics.
+ */
+export declare const isDev: boolean;
 /**
  * Detects if Node.js Buffer is available and should be used.
  *
@@ -46,4 +58,23 @@ export type ReloadApp = (url?: string) => void;
 export interface ReloadAppDep {
     readonly reloadApp: ReloadApp;
 }
+export interface TestGlobalErrors extends Disposable {
+    readonly errors: ReadonlyArray<unknown>;
+    readonly next: () => Promise<unknown>;
+    /**
+     * Waits until every error already reported to the platform has been delivered
+     * to this recorder, then returns {@link TestGlobalErrors.errors}.
+     *
+     * Platforms deliver global errors asynchronously and provide no hook for
+     * "nothing was reported", so settle emits a sentinel of the same kind and
+     * resolves when it arrives. Platform delivery is ordered, so all earlier
+     * errors are recorded by then. Use it to assert absence: `expect(await
+     * unhandledRejections.settle()).toEqual([])`.
+     */
+    readonly settle: () => Promise<ReadonlyArray<unknown>>;
+}
+/** Records platform global uncaught-error reporting until disposed. */
+export declare const testGlobalUncaughtErrors: () => TestGlobalErrors;
+/** Records platform global unhandled-rejection reporting until disposed. */
+export declare const testGlobalUnhandledRejections: () => TestGlobalErrors;
 //# sourceMappingURL=Platform.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Platform.d.ts","sourceRoot":"","sources":["../../src/Platform.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,kEAAkE;AAClE,eAAO,MAAM,QAAQ,SAAiC,CAAC;AAEvD,gEAAgE;AAChE,eAAO,MAAM,QAAQ,SAAkC,CAAC;AAExD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,SAC6B,CAAC;AAExD;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;AAEvD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;AAE/C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B"}
+{"version":3,"file":"Platform.d.ts","sourceRoot":"","sources":["../../src/Platform.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,kEAAkE;AAClE,eAAO,MAAM,QAAQ,SAAiC,CAAC;AAEvD,gEAAgE;AAChE,eAAO,MAAM,QAAQ,SAAkC,CAAC;AAExD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,SAGyB,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,SAC6B,CAAC;AAExD;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;AAEvD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;AAE/C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtC;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;CACxD;AAED,uEAAuE;AACvE,eAAO,MAAM,wBAAwB,QAAO,gBACF,CAAC;AAE3C,4EAA4E;AAC5E,eAAO,MAAM,6BAA6B,QAAO,gBACH,CAAC"}

package/dist/src/Platform.js

@@ -7,6 +7,20 @@
 export const isHermes = "HermesInternal" in globalThis;
 /** Returns true if running in a server environment (no DOM). */
 export const isServer = typeof document === "undefined";
+/**
+ * True outside production builds.
+ *
+ * Bundlers (webpack, Vite, esbuild, Metro) replace the text
+ * `process.env.NODE_ENV` statically at build time, so in production bundles
+ * this expression folds to `false` and code behind it is dead-code-eliminated —
+ * the same mechanism React uses. The `typeof` guard makes the runtime read safe
+ * where no bundler ran, such as un-bundled browser ESM, where it fails closed
+ * to production behavior. Node.js reads it natively; React Native polyfills it.
+ * A missing `NODE_ENV` counts as development, matching React semantics.
+ */
+export const isDev = typeof process === "undefined"
+    ? false
+    : process.env.NODE_ENV !== "production";
 /**
  * Detects if Node.js Buffer is available and should be used.
  *
@@ -19,3 +33,87 @@ export const isServer = typeof document === "undefined";
  * @see https://github.com/craftzdog/react-native-quick-base64#installation
  */
 export const hasNodeBuffer = !isHermes && typeof globalThis.Buffer !== "undefined";
+/** Records platform global uncaught-error reporting until disposed. */
+export const testGlobalUncaughtErrors = () => createTestGlobalErrors("uncaughtErrors");
+/** Records platform global unhandled-rejection reporting until disposed. */
+export const testGlobalUnhandledRejections = () => createTestGlobalErrors("unhandledRejection");
+const settleSentinel = new Error("TestGlobalErrors.settle sentinel");
+const createTestGlobalErrors = (kind) => {
+    const nodeEvent = kind === "uncaughtErrors" ? "uncaughtException" : "unhandledRejection";
+    const webEvent = kind === "uncaughtErrors" ? "error" : "unhandledrejection";
+    const webErrorKey = kind === "uncaughtErrors" ? "error" : "reason";
+    const errorType = kind === "uncaughtErrors" ? "uncaught-error" : "unhandled-rejection";
+    const disposableStack = new DisposableStack();
+    const errors = [];
+    const nextWaiters = [];
+    const settleWaiters = [];
+    let nextIndex = 0;
+    const next = () => {
+        if (nextIndex < errors.length) {
+            const error = errors[nextIndex];
+            nextIndex += 1;
+            return Promise.resolve(error);
+        }
+        const next = Promise.withResolvers();
+        nextWaiters.push(next.resolve);
+        return next.promise;
+    };
+    const record = (error) => {
+        if (error === settleSentinel) {
+            settleWaiters.shift()?.();
+            return;
+        }
+        errors.push(error);
+        const resolveNext = nextWaiters.shift();
+        if (!resolveNext)
+            return;
+        nextIndex += 1;
+        resolveNext(error);
+    };
+    const settle = () => {
+        const settled = Promise.withResolvers();
+        settleWaiters.push(() => {
+            settled.resolve(errors);
+        });
+        if (kind === "unhandledRejection") {
+            void Promise.reject(settleSentinel);
+        }
+        else {
+            queueMicrotask(() => {
+                throw settleSentinel;
+            });
+        }
+        return settled.promise;
+    };
+    if (typeof process === "object" &&
+        typeof process.on === "function" &&
+        typeof process.off === "function") {
+        process.on(nodeEvent, record);
+        disposableStack.defer(() => {
+            process.off(nodeEvent, record);
+        });
+    }
+    else if (typeof globalThis.addEventListener === "function") {
+        const listener = (event) => {
+            event.preventDefault();
+            record(event[webErrorKey]);
+        };
+        globalThis.addEventListener(webEvent, listener);
+        disposableStack.defer(() => {
+            globalThis.removeEventListener(webEvent, listener);
+        });
+    }
+    else {
+        throw new Error(`Unsupported platform global ${errorType} reporting.`);
+    }
+    return {
+        errors,
+        next,
+        settle,
+        [Symbol.dispose]: () => {
+            nextWaiters.length = 0;
+            settleWaiters.length = 0;
+            disposableStack.dispose();
+        },
+    };
+};

package/dist/src/Random.d.ts

@@ -1,10 +1,10 @@
 /**
- * Seeded random number generation.
+ * Random number generation.
  *
  * @module
  */
 import { Random as RandomLib } from "random";
-import type { Brand } from "./Brand.js";
+import type { Brand } from "./Brand.ts";
 /**
  * A random floating point number in [0, 1).
  *
@@ -19,41 +19,56 @@ export type RandomNumber = number & Brand<"RandomNumber">;
  * ### Example
  *
  * ```ts
- * // For apps
+ * import {
+ *   createRandom,
+ *   testCreateRandom,
+ *   type RandomNumber,
+ * } from "@evolu/common";
+ *
+ * // For apps, use the Math.random-backed implementation.
  * const random = createRandom();
- * random.next();
+ * const value = random.next();
+ * expectTypeOf(value).toEqualTypeOf<RandomNumber>();
+ * expect(value).toBeGreaterThanOrEqual(0);
+ * expect(value).toBeLessThan(1);
  *
- * // For tests
- * const random = createRandomWithSeed("test");
- * random.next();
+ * // For tests, use a seed.
+ * const firstTestRandom = testCreateRandom("test");
+ * const secondTestRandom = testCreateRandom("test");
+ * expect(firstTestRandom.next()).toBe(secondTestRandom.next());
  * ```
  */
 export interface Random {
     /** Returns a floating point number in [0, 1). Just like Math.random(). */
-    next: () => RandomNumber;
+    readonly next: () => RandomNumber;
 }
 export interface RandomDep {
-    random: Random;
+    readonly 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.
+ * Creates a seeded {@link Random} for deterministic tests.
+ *
+ * Default seed "evolu".
  */
-export declare const createRandomWithSeed: (seed: string) => Random;
+export declare const testCreateRandom: (seed?: string) => Random;
 /**
- * A random number generator using the NPM `random` package dependency.
+ * Seedable random number generator supporting many common distributions,
+ * provided by the NPM `random` package.
  *
  * https://github.com/transitive-bullshit/random
  */
 export interface RandomLibDep {
     readonly randomLib: RandomLib;
 }
-/** Creates a `RandomLib` using the NPM `random` package. */
+/** Creates a random number generator from the NPM `random` package. */
 export declare const createRandomLib: () => RandomLib;
-/** Creates a seeded `RandomLib` for deterministic tests. Default seed "evolu". */
+/**
+ * Creates a seeded random number generator from the NPM `random` package 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;;;;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"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,MAAM;IACrB,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,YAAY,CAAC;CACnC;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,oDAAoD;AACpD,eAAO,MAAM,YAAY,QAAO,MAE9B,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,qBAAqB,MAKjD,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B;AAED,uEAAuE;AACvE,eAAO,MAAM,eAAe,QAAO,SAA4B,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,qBAAqB,SAChC,CAAC"}

package/dist/src/Random.js

@@ -1,5 +1,5 @@
 /**
- * Seeded random number generation.
+ * Random number generation.
  *
  * @module
  */
@@ -8,19 +8,23 @@ import { Random as RandomLib } from "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.
+ * Creates a seeded {@link Random} for deterministic tests.
+ *
+ * Default seed "evolu".
  */
-export const createRandomWithSeed = (seed) => {
+export const testCreateRandom = (seed = "evolu") => {
     const random = new RandomLib(seed);
     return {
         next: () => random.next(),
     };
 };
-/** Creates a `RandomLib` using the NPM `random` package. */
+/** Creates a random number generator from the NPM `random` package. */
 export const createRandomLib = () => new RandomLib();
-/** Creates a seeded `RandomLib` for deterministic tests. Default seed "evolu". */
+/**
+ * Creates a seeded random number generator from the NPM `random` package for
+ * deterministic tests.
+ *
+ * Default seed "evolu".
+ */
 export const testCreateRandomLib = (seed = "evolu") => new RandomLib(seed);

package/dist/src/Redacted.d.ts

@@ -3,8 +3,8 @@
  *
  * @module
  */
-import type { Brand } from "./Brand.js";
-import type { Eq } from "./Eq.js";
+import type { Brand } from "./Brand.ts";
+import type { Eq } from "./Eq.ts";
 /**
  * A wrapper type that prevents sensitive values from being accidentally exposed
  * through logging, serialization, or inspection.
@@ -26,35 +26,38 @@ import type { Eq } from "./Eq.js";
  * ### Example
  *
  * ```ts
- * // Define branded types for your secrets
+ * import {
+ *   createRedacted,
+ *   revealRedacted,
+ *   type Brand,
+ *   type Redacted,
+ * } from "@evolu/common";
+ *
  * type ApiKey = string & Brand<"ApiKey">;
  * type DbPassword = string & Brand<"DbPassword">;
- *
- * // Wrap them with Redacted for safe passing
  * type RedactedApiKey = Redacted<ApiKey>;
- * type RedactedDbPassword = Redacted<DbPassword>;
  *
- * // Create a redacted secret
+ * // Apply brands only after validation or at another trusted boundary.
  * const apiKey: ApiKey = "secret-123" as ApiKey;
- * const redactedKey: RedactedApiKey = createRedacted(apiKey);
- *
- * console.log(redactedKey); // <redacted>
- * console.log(revealRedacted(redactedKey)); // secret-123
- *
- * // Type safety: RedactedApiKey ≠ RedactedDbPassword
- * const fetchUser = (key: RedactedApiKey) => {
- *   const value: ApiKey = revealRedacted(key);
- *   // use value...
- * };
- *
- * fetchUser(redactedKey); // ok
- * // fetchUser(createRedacted("x" as DbPassword)); // type error
- *
- * // Automatic cleanup with `using`
- * {
- *   using secret = createRedacted("sensitive" as ApiKey);
- *   // ... use secret ...
- * } // automatically wiped from memory
+ * using redactedKey: RedactedApiKey = createRedacted(apiKey);
+ * const fetchUser = (key: RedactedApiKey): ApiKey => revealRedacted(key);
+ *
+ * expect(redactedKey.toString()).toBe("<redacted>");
+ * expect(JSON.stringify({ apiKey: redactedKey })).toBe(
+ *   '{"apiKey":"<redacted>"}',
+ * );
+ * expect(fetchUser(redactedKey)).toBe(apiKey);
+ *
+ * using password = createRedacted("password" as DbPassword);
+ * // @ts-expect-error Redacted secrets retain their distinct branded types.
+ * fetchUser(password);
+ *
+ * const disposedKey = (() => {
+ *   using key = createRedacted(apiKey);
+ *   return key;
+ * })();
+ * // Leaving the `using` scope removes the value from memory.
+ * expect(() => revealRedacted(disposedKey)).toThrow();
  * ```
  */
 export interface Redacted<A> extends Brand<"Redacted">, Disposable {
@@ -80,12 +83,23 @@ export declare const isRedacted: (value: unknown) => value is Redacted<unknown>;
  * ### Example
  *
  * ```ts
+ * import {
+ *   createEqRedacted,
+ *   createRedacted,
+ *   eqString,
+ *   type Brand,
+ * } from "@evolu/common";
+ *
  * type ApiKey = string & Brand<"ApiKey">;
  * const eqRedactedApiKey = createEqRedacted<ApiKey>(eqString);
  *
- * const a = createRedacted("x" as ApiKey);
- * const b = createRedacted("x" as ApiKey);
- * eqRedactedApiKey(a, b); // true
+ * // Apply brands only after validation or at another trusted boundary.
+ * using a = createRedacted("x" as ApiKey);
+ * using b = createRedacted("x" as ApiKey);
+ * using c = createRedacted("y" as ApiKey);
+ *
+ * expect(eqRedactedApiKey(a, b)).toBe(true);
+ * expect(eqRedactedApiKey(a, c)).toBe(false);
  * ```
  */
 export declare const createEqRedacted: <A>(eq: Eq<A>) => Eq<Redacted<A>>;

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

@@ -1 +1 @@
-{"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"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;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,SAAS,CAAC,KAAG,QAAQ,CAAC,CAAC,CAItD,CAAC;AAaF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,YAAY,QAAQ,CAAC,CAAC,CAAC,KAAG,CAGzD,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,UAAU,UAAW,OAAO,KAAG,KAAK,IAAI,QAAQ,CAAC,OAAO,CAG7B,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,gBAAgB,GAC1B,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,KAAG,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAEY,CAAC"}

package/dist/src/Redacted.js

@@ -42,12 +42,23 @@ export const isRedacted = (value) => typeof value === "object" &&
  * ### Example
  *
  * ```ts
+ * import {
+ *   createEqRedacted,
+ *   createRedacted,
+ *   eqString,
+ *   type Brand,
+ * } from "@evolu/common";
+ *
  * type ApiKey = string & Brand<"ApiKey">;
  * const eqRedactedApiKey = createEqRedacted<ApiKey>(eqString);
  *
- * const a = createRedacted("x" as ApiKey);
- * const b = createRedacted("x" as ApiKey);
- * eqRedactedApiKey(a, b); // true
+ * // Apply brands only after validation or at another trusted boundary.
+ * using a = createRedacted("x" as ApiKey);
+ * using b = createRedacted("x" as ApiKey);
+ * using c = createRedacted("y" as ApiKey);
+ *
+ * expect(eqRedactedApiKey(a, b)).toBe(true);
+ * expect(eqRedactedApiKey(a, c)).toBe(false);
  * ```
  */
 export const createEqRedacted = (eq) => (x, y) => eq(revealRedacted(x), revealRedacted(y));

package/dist/src/Ref.d.ts

@@ -18,18 +18,26 @@
  * ### Example
  *
  * ```ts
+ * import { createRef } from "@evolu/common";
+ *
  * const count = createRef(0);
  * count.set(1);
  * count.update((n) => n + 1);
- * console.log(count.get()); // 2
+ * expect(count.get()).toBe(2);
  * ```
  *
- * ### Example of using Ref as a dependency
+ * ### As a dependency
  *
  * ```ts
+ * import { createRef, type Ref } from "@evolu/common";
+ *
  * interface CounterRefDep {
  *   readonly counterRef: Ref<number>;
  * }
+ *
+ * const deps: CounterRefDep = { counterRef: createRef(0) };
+ * deps.counterRef.update((count) => count + 1);
+ * expect(deps.counterRef.get()).toBe(1);
  * ```
  */
 export interface Ref<T> {
@@ -48,7 +56,7 @@ export interface Ref<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;
+    readonly modify: <R>(modifier: (current: T) => readonly [result: R, nextValue: T]) => R;
 }
 /** Creates a {@link Ref} with the given initial immutable value. */
 export declare const createRef: <T>(initialValue: T) => Ref<T>;

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

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"Ref.d.ts","sourceRoot":"","sources":["../../src/Ref.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;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,QAAQ,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,KACzD,CAAC,CAAC;CACR;AAED,oEAAoE;AACpE,eAAO,MAAM,SAAS,GAAI,CAAC,gBAAgB,CAAC,KAAG,GAAG,CAAC,CAAC,CA0CnD,CAAC"}

package/dist/src/Ref.js

@@ -32,8 +32,8 @@ export const createRef = (initialValue) => {
             currentValue = updater(currentValue);
             return currentValue;
         },
-        modify: (updater) => {
-            const [result, nextValue] = updater(currentValue);
+        modify: (modifier) => {
+            const [result, nextValue] = modifier(currentValue);
             currentValue = nextValue;
             return result;
         },

package/dist/src/RefCount.d.ts

@@ -3,8 +3,8 @@
  *
  * @module
  */
-import { type LookupOption } from "./Lookup.js";
-import { NonNegativeInt, PositiveInt } from "./Type.js";
+import { type LookupOption } from "./Lookup.ts";
+import { NonNegativeInt, PositiveInt } from "./Type.ts";
 /**
  * Reference count for one retained value.
  *
@@ -21,8 +21,6 @@ export interface RefCount extends Disposable {
     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;
@@ -50,8 +48,6 @@ export interface RefCountByKey<TKey> extends Disposable {
     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> {

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

@@ -1 +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,QA4BjC,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"}
+{"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;CACzC;AAED,gCAAgC;AAChC,eAAO,MAAM,cAAc,QAAO,QAkBjC,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;CACxC;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"}