@evolu/common 8.0.0-next.4 → 8.0.0

package/dist/src/LeakDetector.js

@@ -0,0 +1,86 @@
+/**
+ * Development-time detection of leaked handles via garbage collection.
+ *
+ * @module
+ */
+import {} from "./Console.js";
+import { constVoid } from "./Function.js";
+/**
+ * Creates {@link LeakDetector} backed by `FinalizationRegistry`.
+ *
+ * Capturing a stack per track call is too expensive for production; use
+ * {@link noopLeakDetector} there.
+ */
+export const createLeakDetector = (deps) => {
+    if (typeof globalThis.FinalizationRegistry !== "function")
+        return noopLeakDetector;
+    const registry = new globalThis.FinalizationRegistry(reportLeak(deps));
+    return {
+        track: (target, leak, unregisterToken) => {
+            registry.register(target, { ...leak, stack: new Error().stack }, unregisterToken);
+        },
+        untrack: (unregisterToken) => {
+            registry.unregister(unregisterToken);
+        },
+    };
+};
+/** No-op {@link LeakDetector} for production. */
+export const noopLeakDetector = {
+    track: constVoid,
+    untrack: constVoid,
+};
+/**
+ * Reports a collected handle that was still held.
+ *
+ * Shared by {@link createLeakDetector} as the `FinalizationRegistry` callback
+ * and by {@link testCreateLeakDetector.collect | collect}, so tests cover the
+ * same reporting path without forcing garbage collection. Returns whether the
+ * leak was reported.
+ */
+const reportLeak = (deps) => (leak) => {
+    if (!leak.isLeaked())
+        return false;
+    deps.console.warn(`${leak.name} was garbage-collected without cleanup. Tracked at:`, leak.stack);
+    return true;
+};
+/** Creates {@link TestLeakDetector}. */
+export const testCreateLeakDetector = (deps) => {
+    const trackedLeaksByToken = new Map();
+    const report = reportLeak(deps);
+    return {
+        track: (_target, leak, unregisterToken) => {
+            const trackedLeaks = trackedLeaksByToken.get(unregisterToken) ?? [];
+            trackedLeaksByToken.set(unregisterToken, [
+                ...trackedLeaks,
+                {
+                    ...leak,
+                    stack: new Error().stack,
+                },
+            ]);
+        },
+        untrack: (unregisterToken) => {
+            trackedLeaksByToken.delete(unregisterToken);
+        },
+        collect: () => {
+            let leakCount = 0;
+            for (const trackedLeaks of trackedLeaksByToken.values()) {
+                for (const leak of trackedLeaks) {
+                    if (report(leak))
+                        leakCount++;
+                }
+            }
+            trackedLeaksByToken.clear();
+            return leakCount;
+        },
+        getTrackedCount: ({ name } = {}) => {
+            let count = 0;
+            for (const trackedLeaks of trackedLeaksByToken.values()) {
+                for (const leak of trackedLeaks) {
+                    if (name === undefined || leak.name === name)
+                        count++;
+                }
+            }
+            return count;
+        },
+    };
+};

package/dist/src/LockManager.d.ts

@@ -3,32 +3,41 @@
  *
  * @module
  */
-import { AbortError, type Task } from "./Task.js";
-import type { Callback } from "./Types.js";
+import type { Task } from "./Task.ts";
+import type { Callback } from "./Types.ts";
 /**
  * Dependency wrapper for {@link LockManager}.
  *
  * For React Native, use the `lockManager` ponyfill from `@evolu/react-native`.
  * For tests, use {@link testCreateLockManager}.
  *
- * ### Example
+ * ### Web and Node.js 24+
  *
  * ```ts
- * // Web or Node.js 24+
- * import { testCreateLockManager } from "@evolu/common";
+ * import type { LockManagerDep } from "@evolu/common";
  *
  * const deps: LockManagerDep = {
- *   lockManager: testCreateLockManager(),
+ *   lockManager: globalThis.navigator.locks,
  * };
+ *
+ * const result = await deps.lockManager.request("example", (lock) => {
+ *   return lock?.name;
+ * });
+ * expect(result).toBe("example");
  * ```
  *
- * ### Example
+ * ### React Native
  *
  * ```ts
- * // React Native
+ * import type { LockManagerDep } from "@evolu/common";
  * import { lockManager } from "@evolu/react-native";
  *
  * const deps: LockManagerDep = { lockManager };
+ *
+ * const result = await deps.lockManager.request("example", (lock) => {
+ *   return lock?.name;
+ * });
+ * expect(result).toBe("example");
  * ```
  */
 export interface LockManagerDep {
@@ -58,7 +67,7 @@ export declare const testCreateLockManager: (nativeLockManager?: LockManager) =>
  * another waiting caller may become the next leader. Waiting for leadership is
  * abortable via the calling {@link Task}'s signal.
  */
-export declare const acquireLeaderLock: (name: string) => Task<AsyncDisposable, AbortError, LockManagerDep>;
+export declare const acquireLeaderLock: (name: string) => Task<AsyncDisposable, never, LockManagerDep>;
 /**
  * Competes to become the current leader for `name` using {@link LockManager}.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"LockManager.d.ts","sourceRoot":"","sources":["../../src/LockManager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAE,UAAU,EAAE,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAElD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACnC;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,GAChC,oBAAmB,WAAwC,KAC1D,WAwCF,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAC3B,MAAM,MAAM,KAAG,IAAI,CAAC,eAAe,EAAE,UAAU,EAAE,cAAc,CA4B7D,CAAC;AAEN;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,GACnC,MAAM,cAAc,MACpB,MAAM,MAAM,EAAE,UAAU,QAAQ,CAAC,IAAI,CAAC,KAAG,UAsBzC,CAAC"}
+{"version":3,"file":"LockManager.d.ts","sourceRoot":"","sources":["../../src/LockManager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACnC;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,uBACb,WAAW,KAC7B,WAwCF,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,SACrB,MAAM,KAAG,IAAI,CAAC,eAAe,EAAE,KAAK,EAAE,cAAc,CAuB1D,CAAC;AAEJ;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,SAC7B,cAAc,YACd,MAAM,YAAY,QAAQ,CAAC,IAAI,CAAC,KAAG,UAsBzC,CAAC"}

package/dist/src/LockManager.js

@@ -4,9 +4,8 @@
  * @module
  */
 import { createRandomBytes } from "./Crypto.js";
-import { lazyVoid } from "./Function.js";
-import { tryAsync } from "./Result.js";
-import { AbortError } from "./Task.js";
+import { constVoid } from "./Function.js";
+import { ok } from "./Result.js";
 import { createId } from "./Type.js";
 /**
  * Creates a test {@link LockManager} backed by the native platform
@@ -56,7 +55,7 @@ export const testCreateLockManager = (nativeLockManager = globalThis.navigator.l
  * another waiting caller may become the next leader. Waiting for leadership is
  * abortable via the calling {@link Task}'s signal.
  */
-export const acquireLeaderLock = (name) => (run) => tryAsync(async () => {
+export const acquireLeaderLock = (name) => async (run) => {
     const acquisition = Promise.withResolvers();
     const released = Promise.withResolvers();
     const request = run.deps.lockManager.request(createLeaderLockName(name), { mode: "exclusive", signal: run.signal }, async () => {
@@ -65,13 +64,13 @@ export const acquireLeaderLock = (name) => (run) => tryAsync(async () => {
     });
     void request.catch(acquisition.reject);
     await acquisition.promise;
-    return {
+    return ok({
         [Symbol.asyncDispose]: async () => {
             released.resolve();
             await request;
         },
-    };
-}, (error) => AbortError.is(error) ? error : { type: "AbortError", reason: error });
+    });
+};
 /**
  * Competes to become the current leader for `name` using {@link LockManager}.
  *
@@ -92,7 +91,7 @@ export const acquireLeaderLockCallback = (deps) => (name, callback) => {
         callback();
         await released.promise;
     });
-    void request.catch(lazyVoid);
+    void request.catch(constVoid);
     return {
         [Symbol.dispose]: () => {
             abortController.abort();

package/dist/src/Lookup.d.ts

@@ -3,7 +3,7 @@
  *
  * @module
  */
-import type { Brand } from "./Brand.js";
+import type { Brand } from "./Brand.ts";
 /**
  * Derives the native lookup key used by lookup-based collections.
  *
@@ -18,6 +18,16 @@ import type { Brand } from "./Brand.js";
  * Use this when callers provide keys in one form but logical identity should be
  * based on another stable key, such as a natural id or {@link StructuralKey}.
  *
+ * Lookup functions must be pure and stable. The same logical key must derive
+ * the same native `Map` key while an entry is stored, so use lookup-based
+ * collections with immutable key data, preferably readonly values. Mutating key
+ * data after insertion can make later `get`, `has`, and `delete` calls disagree
+ * with the inserted entry.
+ *
+ * The returned lookup key uses native `Map` equality. Return primitives or
+ * stable object references; returning a new object for each call prevents equal
+ * logical keys from matching.
+ *
  * @see {@link createLookupMap}
  * @see {@link createLookupSet}
  */
@@ -113,17 +123,19 @@ export type StructuralKey = StructuralScalar | ReadonlyArray<StructuralKey> | {
  *
  * `Structural<T>` checks a concrete type recursively at compile time instead:
  * scalars pass through, arrays recurse, object properties recurse, and
- * function-valued properties are rejected. This keeps public structural APIs
- * ergonomic for interface-based inputs while preserving the same runtime
+ * function-valued and symbol-keyed properties are rejected. Symbol-keyed
+ * properties are rejected because runtime serialization reads only enumerable
+ * string keys, so they would be silently ignored. This keeps public structural
+ * APIs ergonomic for interface-based inputs while preserving the same runtime
  * constraints as structural lookup serialization.
  *
  * @see {@link StructuralKey}
  * @see {@link structuralLookup}
  */
 export type Structural<T> = T extends StructuralScalar ? T : T extends ReadonlyArray<infer Item> ? ReadonlyArray<Structural<Item>> : T extends StructuralFunction ? never : T extends object ? {
-    readonly [K in keyof T as Extract<T[K], StructuralFunction> extends never ? K : never]: Structural<Exclude<T[K], StructuralFunction>>;
+    readonly [K in keyof T as K extends symbol ? never : Extract<T[K], StructuralFunction> extends never ? K : never]: Structural<Exclude<T[K], StructuralFunction>>;
 } & {
-    readonly [K in keyof T as Extract<T[K], StructuralFunction> extends never ? never : K]?: never;
+    readonly [K in keyof T as K extends symbol ? K : Extract<T[K], StructuralFunction> extends never ? never : K]?: never;
 } : never;
 /** Function branch excluded by {@link Structural}. */
 export type StructuralFunction = (...args: ReadonlyArray<unknown>) => unknown;
@@ -132,7 +144,8 @@ export type StructuralFunction = (...args: ReadonlyArray<unknown>) => unknown;
  *
  * Structural lookup keys are derived from JSON-like values plus `Uint8Array`.
  * Equal structures produce the same lookup key even when they are different
- * JavaScript instances.
+ * JavaScript instances. `undefined` values and sparse array holes are rejected
+ * rather than skipped.
  *
  * The derived key is memoized by non-null object identity in a module-scoped
  * `WeakMap` shared by all callers, so keys must be immutable.
@@ -143,16 +156,33 @@ export type StructuralFunction = (...args: ReadonlyArray<unknown>) => unknown;
  * ### Example
  *
  * ```ts
- * const byFilter = createLookupMap<
- *   { readonly table: string; readonly where: readonly [string, string] },
- *   string,
- *   StructuralLookupKey
- * >({
+ * import {
+ *   createLookupMap,
+ *   structuralLookup,
+ *   type StructuralLookupKey,
+ * } from "@evolu/common";
+ *
+ * interface Filter {
+ *   readonly table: string;
+ *   readonly where: readonly [string, string];
+ * }
+ *
+ * const byFilter = createLookupMap<Filter, string, StructuralLookupKey>({
  *   lookup: structuralLookup,
  * });
  *
- * byFilter.set({ table: "todo", where: ["owner", "ada"] }, "cached");
- * byFilter.get({ table: "todo", where: ["owner", "ada"] }); // "cached"
+ * const cachedFilter: Filter = {
+ *   table: "todo",
+ *   where: ["owner", "ada"],
+ * };
+ * const equivalentFilter: Filter = {
+ *   where: ["owner", "ada"],
+ *   table: "todo",
+ * };
+ * byFilter.set(cachedFilter, "cached");
+ *
+ * expect(byFilter.get(equivalentFilter)).toBe("cached");
+ * expect(byFilter.getKey(equivalentFilter)).toBe(cachedFilter);
  * ```
  *
  * @see {@link StructuralKey}

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

@@ -1 +1 @@
-{"version":3,"file":"Lookup.d.ts","sourceRoot":"","sources":["../../src/Lookup.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Lookup.d.ts","sourceRoot":"","sources":["../../src/Lookup.ts"],"names":[],"mappings":"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"}

package/dist/src/Lookup.js

@@ -113,7 +113,8 @@ export const createLookupSet = ({ lookup, values, }) => {
  *
  * Structural lookup keys are derived from JSON-like values plus `Uint8Array`.
  * Equal structures produce the same lookup key even when they are different
- * JavaScript instances.
+ * JavaScript instances. `undefined` values and sparse array holes are rejected
+ * rather than skipped.
  *
  * The derived key is memoized by non-null object identity in a module-scoped
  * `WeakMap` shared by all callers, so keys must be immutable.
@@ -124,16 +125,33 @@ export const createLookupSet = ({ lookup, values, }) => {
  * ### Example
  *
  * ```ts
- * const byFilter = createLookupMap<
- *   { readonly table: string; readonly where: readonly [string, string] },
- *   string,
- *   StructuralLookupKey
- * >({
+ * import {
+ *   createLookupMap,
+ *   structuralLookup,
+ *   type StructuralLookupKey,
+ * } from "@evolu/common";
+ *
+ * interface Filter {
+ *   readonly table: string;
+ *   readonly where: readonly [string, string];
+ * }
+ *
+ * const byFilter = createLookupMap<Filter, string, StructuralLookupKey>({
  *   lookup: structuralLookup,
  * });
  *
- * byFilter.set({ table: "todo", where: ["owner", "ada"] }, "cached");
- * byFilter.get({ table: "todo", where: ["owner", "ada"] }); // "cached"
+ * const cachedFilter: Filter = {
+ *   table: "todo",
+ *   where: ["owner", "ada"],
+ * };
+ * const equivalentFilter: Filter = {
+ *   where: ["owner", "ada"],
+ *   table: "todo",
+ * };
+ * byFilter.set(cachedFilter, "cached");
+ *
+ * expect(byFilter.get(equivalentFilter)).toBe("cached");
+ * expect(byFilter.getKey(equivalentFilter)).toBe(cachedFilter);
  * ```
  *
  * @see {@link StructuralKey}
@@ -180,6 +198,8 @@ const structuralLookupInternal = (value, path = new Set()) => {
             else {
                 assert(false, "Structural lookup keys must be JSON-like values or Uint8Array.");
             }
+            // Cache only after traversal succeeds so cyclic values never leave a
+            // partial lookup key in the memo.
             structuralLookupKeyByValue.set(value, lookupKey);
             return lookupKey;
         }

package/dist/src/Microtask.d.ts

@@ -3,7 +3,7 @@
  *
  * @module
  */
-import { type NonEmptyReadonlyArray } from "./Array.js";
+import { type NonEmptyReadonlyArray } from "./Array.ts";
 /**
  * Batches values and flushes them in a single microtask.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"Microtask.d.ts","sourceRoot":"","sources":["../../src/Microtask.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAiB,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGvE;;;;;GAKG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,CAAE,SAAQ,UAAU;IACnD,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;IAEjC,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC;CAC/B;AAED,sCAAsC;AACtC,eAAO,MAAM,oBAAoB,GAAI,CAAC,EACpC,SAAS,CAAC,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,KAAK,IAAI,KACjD,cAAc,CAAC,CAAC,CAqClB,CAAC"}
+{"version":3,"file":"Microtask.d.ts","sourceRoot":"","sources":["../../src/Microtask.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAiB,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGvE;;;;;GAKG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,CAAE,SAAQ,UAAU;IACnD,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;IAEjC,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC;CAC/B;AAED,sCAAsC;AACtC,eAAO,MAAM,oBAAoB,GAAI,CAAC,WAC3B,CAAC,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,KAAK,IAAI,KACjD,cAAc,CAAC,CAAC,CAiClB,CAAC"}

package/dist/src/Microtask.js

@@ -56,7 +56,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
 import { appendToArray } from "./Array.js";
-import { assertNotDisposed } from "./Assert.js";
+import { disposable } from "./Function.js";
 /** Creates {@link MicrotaskBatch}. */
 export const createMicrotaskBatch = (onFlush) => {
     const env_1 = { stack: [], error: void 0, hasError: false };
@@ -66,7 +66,6 @@ export const createMicrotaskBatch = (onFlush) => {
         disposer.defer(() => {
             queue = null;
         });
-        const disposables = disposer.move();
         const flushQueuedItems = () => {
             if (queue == null)
                 return;
@@ -74,9 +73,8 @@ export const createMicrotaskBatch = (onFlush) => {
             queue = null;
             onFlush(queuedItems);
         };
-        return {
+        return disposable({
             push: (item) => {
-                assertNotDisposed(disposables);
                 if (queue == null) {
                     queue = [item];
                     queueMicrotask(flushQueuedItems);
@@ -85,11 +83,9 @@ export const createMicrotaskBatch = (onFlush) => {
                 queue = appendToArray(queue, item);
             },
             flushNow: () => {
-                assertNotDisposed(disposables);
                 flushQueuedItems();
             },
-            [Symbol.dispose]: () => disposables.dispose(),
-        };
+        }, disposer);
     }
     catch (e_1) {
         env_1.error = e_1;

package/dist/src/Number.d.ts

@@ -3,12 +3,25 @@
  *
  * @module
  */
-import type { NonEmptyReadonlyArray } from "./Array.js";
-import type { IsBranded } from "./Brand.js";
-import type { Result } from "./Result.js";
-import { NonNegativeInt, PositiveInt } from "./Type.js";
-import type { Predicate, WidenLiteral } from "./Types.js";
+import type { NonEmptyReadonlyArray } from "./Array.ts";
+import type { IsBranded } from "./Brand.ts";
+import type { Result } from "./Result.ts";
+import { NonNegativeInt, PositiveInt, Ratio } from "./Type.ts";
+import type { Digit, Digit1To9, Digit1To99, Predicate, WidenLiteral } from "./Types.ts";
+/** Percentage represented as a readable literal or a validated ratio. */
+export type Percentage = PercentageLiteral | Ratio;
+/**
+ * Percentage literal from `"0%"` to `"100%"`.
+ *
+ * Decimal literals support one decimal place. Use {@link Ratio} for computed
+ * values or greater precision.
+ */
+export type PercentageLiteral = "0%" | "100%" | `${Digit1To99}%` | `${Digit | Digit1To99}.${Digit1To9}%`;
+/** Converts a {@link Percentage} to its numeric {@link Ratio}. */
+export declare const percentageToRatio: (percentage: Percentage) => Ratio;
 export declare const increment: (n: number) => number;
+/** Increments a positive integer, saturating at the maximum safe integer. */
+export declare const incrementPositiveInt: (n: PositiveInt) => PositiveInt;
 export declare const decrement: (n: number) => number;
 /** Clamps a number within a given range. */
 export declare const clamp: (min: number, max: number) => (n: number) => number;
@@ -18,9 +31,12 @@ export declare const clamp: (min: number, max: number) => (n: number) => number;
  * ### Example
  *
  * ```ts
+ * import { isBetween } from "@evolu/common";
+ *
  * const isBetween10And20 = isBetween(10, 20);
- * console.log(isBetween10And20(15)); // true
- * console.log(isBetween10And20(25)); // false
+ *
+ * expect(isBetween10And20(20)).toBe(true);
+ * expect(isBetween10And20(25)).toBe(false);
  * ```
  */
 export declare const isBetween: (min: number, max: number) => Predicate<number>;
@@ -36,22 +52,42 @@ export declare const max: <T extends number>(...values: [T, ...ReadonlyArray<T>]
  * ### Example
  *
  * ```ts
- * computeBalancedBuckets(10, 3, 2); // Returns ok([4, 7, 10])
- * computeBalancedBuckets(5, 3, 2); // Returns err(6)
+ * import {
+ *   computeBalancedBuckets,
+ *   NonNegativeInt,
+ *   PositiveInt,
+ * } from "@evolu/common";
+ *
+ * expectOk(
+ *   computeBalancedBuckets(
+ *     NonNegativeInt.orThrow(10),
+ *     PositiveInt.orThrow(3),
+ *     PositiveInt.orThrow(2),
+ *   ),
+ *   [4, 7, 10],
+ * );
+ * expectErr(
+ *   computeBalancedBuckets(
+ *     NonNegativeInt.orThrow(5),
+ *     PositiveInt.orThrow(3),
+ *     PositiveInt.orThrow(2),
+ *   ),
+ *   6,
+ * );
  * ```
  */
 export declare const computeBalancedBuckets: (numberOfItems: NonNegativeInt, 
 /** Default: 16 */
-numberOfBuckets?: number & import("./Brand.js").Brand<"Int"> & import("./Brand.js").Brand<"NonNegative"> & import("./Brand.js").Brand<"Positive">, 
+numberOfBuckets?: number & import("./Brand.ts").Brand<"NonNaN"> & import("./Brand.ts").Brand<"Finite"> & import("./Brand.ts").Brand<"Int"> & import("./Brand.ts").Brand<"NonNegative"> & import("./Brand.ts").Brand<"Positive">, 
 /** Default: 2 */
-minNumberOfItemsPerBucket?: number & import("./Brand.js").Brand<"Int"> & import("./Brand.js").Brand<"NonNegative"> & import("./Brand.js").Brand<"Positive">) => Result<NonEmptyReadonlyArray<PositiveInt>, PositiveInt>;
+minNumberOfItemsPerBucket?: number & import("./Brand.ts").Brand<"NonNaN"> & import("./Brand.ts").Brand<"Finite"> & import("./Brand.ts").Brand<"Int"> & import("./Brand.ts").Brand<"NonNegative"> & import("./Brand.ts").Brand<"Positive">) => Result<NonEmptyReadonlyArray<PositiveInt>, PositiveInt>;
 /**
  * Valid index for {@link fibonacciAt}, constrained to 1-78.
  *
  * Limited to 78 because F(79) exceeds JavaScript's `MAX_SAFE_INTEGER`.
  */
-export declare const FibonacciIndex: import("./Type.js").BrandType<import("./Type.js").BrandType<import("./Type.js").Type<"Brand", number & import("./Brand.js").Brand<"Int"> & import("./Brand.js").Brand<"NonNegative"> & import("./Brand.js").Brand<"Positive">, number, import("./Type.js").PositiveError, number & import("./Brand.js").Brand<"Int"> & import("./Brand.js").Brand<"NonNegative">, import("./Type.js").NumberError | import("./Type.js").NonNegativeError | import("./Type.js").IntError>, "LessThanOrEqualTo78", import("./Type.js").LessThanOrEqualToError<78>, import("./Type.js").NumberError | import("./Type.js").NonNegativeError | import("./Type.js").IntError | import("./Type.js").PositiveError>, "FibonacciIndex", import("./Type.js").BrandWithoutRefineError<"FibonacciIndex", import("./Type.js").NumberError | import("./Type.js").NonNegativeError | import("./Type.js").IntError | import("./Type.js").PositiveError | import("./Type.js").LessThanOrEqualToError<78>>, never>;
-export type FibonacciIndex = typeof FibonacciIndex.Type;
+export declare const FibonacciIndex: import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").Type<"Number", number, number, import("./Type.ts").TypeOfError<"Number">, null, import("./Type.ts").TypeOfError<"Number">, never, number, true>, "NonNaN", import("./Type.ts").NonNaNError>, "Finite", import("./Type.ts").FiniteError>, "Int", import("./Type.ts").IntError>, "NonNegative", import("./Type.ts").NonNegativeError>, "Positive", import("./Type.ts").PositiveError>, "LessThanOrEqualTo78", import("./Type.ts").LessThanOrEqualToError<78>>, "FibonacciIndex", never>;
+export type FibonacciIndex = typeof FibonacciIndex.Output;
 /** Returns the Fibonacci number at the given index (1-indexed: 1,1,2,3,5,8,...). */
 export declare const fibonacciAt: (index: FibonacciIndex) => PositiveInt;
 //# sourceMappingURL=Number.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Number.d.ts","sourceRoot":"","sources":["../../src/Number.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EAIL,cAAc,EACd,WAAW,EACZ,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1D,eAAO,MAAM,SAAS,GAAI,GAAG,MAAM,KAAG,MAAe,CAAC;AAEtD,eAAO,MAAM,SAAS,GAAI,GAAG,MAAM,KAAG,MAAe,CAAC;AAEtD,4CAA4C;AAC5C,eAAO,MAAM,KAAK,GACf,KAAK,MAAM,EAAE,KAAK,MAAM,MACxB,GAAG,MAAM,KAAG,MACoB,CAAC;AAEpC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,GACnB,KAAK,MAAM,EAAE,KAAK,MAAM,KAAG,SAAS,CAAC,MAAM,CAEd,CAAC;AAEjC,wEAAwE;AACxE,eAAO,MAAM,GAAG,GAAI,CAAC,SAAS,MAAM,EAClC,GAAG,QAAQ,CAAC,CAAC,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,KAClC,SAAS,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC,CACE,CAAC;AAEpD,wEAAwE;AACxE,eAAO,MAAM,GAAG,GAAI,CAAC,SAAS,MAAM,EAClC,GAAG,QAAQ,CAAC,CAAC,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,KAClC,SAAS,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC,CACE,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,GACjC,eAAe,cAAc;AAE7B,kBAAkB;AAClB,iJAAyC;AAEzC,iBAAiB;AACjB,2JAAkD,KACjD,MAAM,CAAC,qBAAqB,CAAC,WAAW,CAAC,EAAE,WAAW,CAoBxD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,k7BAG1B,CAAC;AACF,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAC;AAExD,oFAAoF;AACpF,eAAO,MAAM,WAAW,GAAI,OAAO,cAAc,KAAG,WAMnD,CAAC"}
+{"version":3,"file":"Number.d.ts","sourceRoot":"","sources":["../../src/Number.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EAIL,cAAc,EACd,WAAW,EACX,KAAK,EACN,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EACV,KAAK,EACL,SAAS,EACT,UAAU,EACV,SAAS,EACT,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,yEAAyE;AACzE,MAAM,MAAM,UAAU,GAAG,iBAAiB,GAAG,KAAK,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAC3B,IAAI,GAAG,MAAM,GAAG,GAAG,UAAU,GAAG,GAAG,GAAG,KAAK,GAAG,UAAU,IAAI,SAAS,GAAG,CAAC;AAE3E,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,eAAgB,UAAU,KAAG,KAGQ,CAAC;AAEpE,eAAO,MAAM,SAAS,MAAO,MAAM,KAAG,MAAe,CAAC;AAEtD,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB,MAAO,WAAW,KAAG,WACf,CAAC;AAExC,eAAO,MAAM,SAAS,MAAO,MAAM,KAAG,MAAe,CAAC;AAEtD,4CAA4C;AAC5C,eAAO,MAAM,KAAK,QACV,MAAM,OAAO,MAAM,SACrB,MAAM,KAAG,MACoB,CAAC;AAEpC;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,SAAS,QACd,MAAM,OAAO,MAAM,KAAG,SAAS,CAAC,MAAM,CAEd,CAAC;AAEjC,wEAAwE;AACxE,eAAO,MAAM,GAAG,GAAI,CAAC,SAAS,MAAM,aACvB,CAAC,CAAC,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,KAClC,SAAS,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC,CACE,CAAC;AAEpD,wEAAwE;AACxE,eAAO,MAAM,GAAG,GAAI,CAAC,SAAS,MAAM,aACvB,CAAC,CAAC,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,KAClC,SAAS,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC,CACE,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,sBAAsB,kBAClB,cAAc;AAE7B,kBAAkB;;AAGlB,iBAAiB;8OAEhB,MAAM,CAAC,qBAAqB,CAAC,WAAW,CAAC,EAAE,WAAW,CAoBxD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,6rBAG1B,CAAC;AACF,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,MAAM,CAAC;AAE1D,oFAAoF;AACpF,eAAO,MAAM,WAAW,UAAW,cAAc,KAAG,WAMnD,CAAC"}

package/dist/src/Number.js

@@ -5,8 +5,14 @@
  */
 import { assertNonEmptyReadonlyArray } from "./Assert.js";
 import { err, ok } from "./Result.js";
-import { brand, lessThanOrEqualTo, onePositiveInt, NonNegativeInt, PositiveInt, } from "./Type.js";
+import { brand, lessThanOrEqualTo, onePositiveInt, NonNegativeInt, PositiveInt, Ratio, } from "./Type.js";
+/** Converts a {@link Percentage} to its numeric {@link Ratio}. */
+export const percentageToRatio = (percentage) => typeof percentage === "number"
+    ? percentage
+    : Ratio.orThrow(globalThis.Number.parseFloat(percentage) / 100);
 export const increment = (n) => n + 1;
+/** Increments a positive integer, saturating at the maximum safe integer. */
+export const incrementPositiveInt = (n) => PositiveInt.orNull(increment(n)) ?? n;
 export const decrement = (n) => n - 1;
 /** Clamps a number within a given range. */
 export const clamp = (min, max) => (n) => Math.min(Math.max(n, min), max);
@@ -16,9 +22,12 @@ export const clamp = (min, max) => (n) => Math.min(Math.max(n, min), max);
  * ### Example
  *
  * ```ts
+ * import { isBetween } from "@evolu/common";
+ *
  * const isBetween10And20 = isBetween(10, 20);
- * console.log(isBetween10And20(15)); // true
- * console.log(isBetween10And20(25)); // false
+ *
+ * expect(isBetween10And20(20)).toBe(true);
+ * expect(isBetween10And20(25)).toBe(false);
  * ```
  */
 export const isBetween = (min, max) => (value) => value >= min && value <= max;
@@ -34,8 +43,28 @@ export const max = (...values) => values.reduce((a, b) => (a > b ? a : b));
  * ### Example
  *
  * ```ts
- * computeBalancedBuckets(10, 3, 2); // Returns ok([4, 7, 10])
- * computeBalancedBuckets(5, 3, 2); // Returns err(6)
+ * import {
+ *   computeBalancedBuckets,
+ *   NonNegativeInt,
+ *   PositiveInt,
+ * } from "@evolu/common";
+ *
+ * expectOk(
+ *   computeBalancedBuckets(
+ *     NonNegativeInt.orThrow(10),
+ *     PositiveInt.orThrow(3),
+ *     PositiveInt.orThrow(2),
+ *   ),
+ *   [4, 7, 10],
+ * );
+ * expectErr(
+ *   computeBalancedBuckets(
+ *     NonNegativeInt.orThrow(5),
+ *     PositiveInt.orThrow(3),
+ *     PositiveInt.orThrow(2),
+ *   ),
+ *   6,
+ * );
  * ```
  */
 export const computeBalancedBuckets = (numberOfItems,