@evolu/common 8.0.0-next.5 → 8.0.0

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, 

package/dist/src/Object.d.ts

@@ -20,15 +20,20 @@ export type ReadonlyRecord<K extends keyof any, V> = Readonly<Record<K, V>>;
  * Object.prototype` so it also works for plain objects coming from another
  * JavaScript realm.
  *
+ * TODO: deprecated Use `Object.is` from Type. Define a dedicated Type when
+ * another object domain is required.
+ *
  * ### Example
  *
  * ```ts
- * isPlainObject({}); // true
- * isPlainObject(Object.create(null)); // true
- * isPlainObject(new Date()); // false
- * isPlainObject(new (class Example {})()); // false
- * isPlainObject([]); // false
- * isPlainObject(null); // false
+ * import { isPlainObject } from "@evolu/common";
+ *
+ * expect(isPlainObject({})).toBe(true);
+ * expect(isPlainObject(Object.create(null))).toBe(true);
+ * expect(isPlainObject(new Date())).toBe(false);
+ * expect(isPlainObject(new (class Example {})())).toBe(false);
+ * expect(isPlainObject([])).toBe(false);
+ * expect(isPlainObject(null)).toBe(false);
  * ```
  */
 export declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
@@ -38,9 +43,11 @@ export declare const isPlainObject: (value: unknown) => value is Record<string,
  * ### Example
  *
  * ```ts
- * isFunction(() => {}); // true
- * isFunction(function () {}); // true
- * isFunction({}); // false
+ * import { isFunction } from "@evolu/common";
+ *
+ * expect(isFunction(() => {})).toBe(true);
+ * expect(isFunction(function () {})).toBe(true);
+ * expect(isFunction({})).toBe(false);
  * ```
  */
 export declare const isFunction: (value: unknown) => value is globalThis.Function;
@@ -50,9 +57,11 @@ export declare const isFunction: (value: unknown) => value is globalThis.Functio
  * ### Example
  *
  * ```ts
- * isIterable([1, 2, 3]); // true
- * isIterable("abc"); // true
- * isIterable({}); // false
+ * import { isIterable } from "@evolu/common";
+ *
+ * expect(isIterable([1, 2, 3])).toBe(true);
+ * expect(isIterable("abc")).toBe(true);
+ * expect(isIterable({})).toBe(false);
  * ```
  */
 export declare const isIterable: (value: unknown) => value is Iterable<unknown>;
@@ -62,9 +71,20 @@ export declare const isIterable: (value: unknown) => value is Iterable<unknown>;
  * ### Example
  *
  * ```ts
- * type UserId = string & { readonly __brand: "UserId" };
- * const users = createRecord<UserId, string>();
- * const entries = objectToEntries(users); // [UserId, string][]
+ * import {
+ *   objectToEntries,
+ *   type Brand,
+ *   type ReadonlyRecord,
+ * } from "@evolu/common";
+ *
+ * type UserId = string & Brand<"UserId">;
+ *
+ * const userId = "u1" as UserId;
+ * const users: ReadonlyRecord<UserId, string> = { [userId]: "Alice" };
+ * const entries = objectToEntries(users);
+ *
+ * expectTypeOf(entries).toEqualTypeOf<ReadonlyArray<[UserId, string]>>();
+ * expect(entries).toEqual([[userId, "Alice"]]);
  * ```
  */
 export declare const objectToEntries: <T extends Record<string, any>>(record: T) => ReadonlyArray<[StringKeyOf<T>, T[StringKeyOf<T>]]>;
@@ -78,11 +98,20 @@ type StringKeyOf<T> = Extract<keyof T, string>;
  * ### Example
  *
  * ```ts
- * type UserId = string & { readonly __brand: "UserId" };
+ * import {
+ *   objectFromEntries,
+ *   type Brand,
+ *   type ReadonlyRecord,
+ * } from "@evolu/common";
+ *
+ * type UserId = string & Brand<"UserId">;
  * const entries: ReadonlyArray<[UserId, string]> = [
  *   ["u1" as UserId, "Alice"],
  * ];
- * const users = objectFromEntries(entries); // ReadonlyRecord<UserId, string>
+ * const users = objectFromEntries(entries);
+ *
+ * expectTypeOf(users).toEqualTypeOf<ReadonlyRecord<UserId, string>>();
+ * expect(users).toEqual({ u1: "Alice" });
  * ```
  */
 export declare const objectFromEntries: <K extends string, V>(entries: Iterable<readonly [K, V]>) => ReadonlyRecord<K, V>;
@@ -95,11 +124,20 @@ export declare const objectFromEntries: <K extends string, V>(entries: Iterable<
  * ### Example
  *
  * ```ts
- * objectFrom(["en", "fr", "de"], loadTranslations);
- * // { en: Translations, fr: Translations, de: Translations }
+ * import { objectFrom, type ReadonlyRecord } from "@evolu/common";
  *
- * objectFrom(["trace", "debug", "log"], (level) => createHandler(level));
- * // { trace: Handler, debug: Handler, log: Handler }
+ * const translations = objectFrom(
+ *   ["en", "fr"] as const,
+ *   (locale): string => `Hello in ${locale}`,
+ * );
+ *
+ * expectTypeOf(translations).toEqualTypeOf<
+ *   ReadonlyRecord<"en" | "fr", string>
+ * >();
+ * expect(translations).toEqual({
+ *   en: "Hello in en",
+ *   fr: "Hello in fr",
+ * });
  * ```
  */
 export declare const objectFrom: <K extends string, V>(keys: ReadonlyArray<K>, getValue: (key: K) => V) => ReadonlyRecord<K, V>;
@@ -112,44 +150,123 @@ export declare const mapObject: <K extends string, V, U>(record: ReadonlyRecord<
 /** Conditionally excludes a property from an object. */
 export declare const excludeProp: <T extends object, K extends keyof T>(obj: T, prop: K, condition?: boolean) => typeof condition extends true ? T : Omit<T, K>;
 /**
- * Creates a prototype-less object typed as `Record<K, V>`.
+ * Creates a mutable Record.
+ *
+ * Use it to build a Record locally through mutation, avoiding repeated object
+ * spreads. Keep mutation scoped to the constructing function, and treat the
+ * completed Record as immutable after it leaves that scope. When a source is
+ * provided, its own enumerable properties are shallow-copied. Inherited and
+ * non-enumerable properties are not copied.
+ *
+ * The Record is created with `Object.create(null)`, so any string can be used
+ * as a key while it is being built. Missing keys such as `toString` and
+ * `constructor` do not resolve to inherited values, and assigning `__proto__`
+ * creates an own data property instead of changing the prototype.
+ *
+ * The null prototype makes dynamic construction safer, but it does not have to
+ * be preserved. Spreading the completed Record into an ordinary object is
+ * supported. Use {@link getOwnProp} when a lookup must read only own
+ * properties.
+ *
+ * For immutable empty application data, defaults, or placeholders, use
+ * {@link emptyRecord}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { createMutableRecord } from "@evolu/common";
  *
- * Use this function when you need a plain record without a prototype chain
- * (e.g. when keys are controlled by external sources) to avoid prototype
- * pollution and accidental collisions with properties like `__proto__`.
+ * const createValuesByKey = (
+ *   entries: ReadonlyArray<readonly [string, number]>,
+ * ): Readonly<Record<string, number>> => {
+ *   const valuesByKey = createMutableRecord<string, number>();
  *
- * Example:
+ *   for (const [key, value] of entries) {
+ *     valuesByKey[key] = value;
+ *   }
+ *
+ *   return valuesByKey;
+ * };
+ *
+ * expect(
+ *   createValuesByKey([
+ *     ["a", 1],
+ *     ["b", 2],
+ *   ]),
+ * ).toEqual({ a: 1, b: 2 });
+ * ```
+ *
+ * Note that TypeScript does not model an object's runtime prototype. A plain
+ * TypeScript Record exposes `Object.prototype` members even when the runtime
+ * object has a `null` prototype:
+ *
+ * ```ts
+ * const values = Object.create(null) as Record<string, number>;
+ *
+ * // TypeScript accepts the call, but `toString` is undefined at runtime.
+ * expect(() => values.toString()).toThrow(TypeError);
+ * ```
+ *
+ * `createMutableRecord` uses the same TypeScript Record representation.
  *
  * ```ts
- * const values = createRecord<string, SqliteValue>();
- * values["__proto__"] = someValue; // safe, no prototype pollution
+ * import { createMutableRecord } from "@evolu/common";
+ *
+ * const values = createMutableRecord<string, number>();
+ *
+ * // TypeScript accepts the call, but `toString` is undefined at runtime.
+ * expect(() => values.toString()).toThrow(TypeError);
  * ```
+ *
+ * In other words, treat the returned object as string-keyed data rather than
+ * calling inherited object methods through it.
  */
-export declare const createRecord: <K extends string = string, V = unknown>() => Record<K, V>;
+export declare function createMutableRecord<K extends string = string, V = unknown>(): Record<K, V>;
+export declare function createMutableRecord<T extends object>(source: T): {
+    -readonly [K in keyof T]: T[K];
+};
 /**
- * An empty readonly record.
+ * A shared frozen empty readonly Record.
  *
- * Use as a default or initial value to avoid allocating new empty records.
+ * Use it as an immutable empty value for defaults and placeholders instead of
+ * allocating a new empty object. Because the instance is shared, it is frozen
+ * to prevent accidental mutation.
+ *
+ * Use {@link createMutableRecord} to build a Record locally through mutation
+ * instead of repeated object spreads.
  *
  * @group Constants
  */
 export declare const emptyRecord: Readonly<Record<string, never>>;
 /**
- * Safely gets a property from a record, returning `undefined` if the key
- * doesn't exist.
+ * Gets an own property from a record, returning `undefined` if the key is
+ * missing or inherited.
  *
  * TypeScript's `Record<K, V>` type assumes all keys exist, but at runtime
- * accessing a non-existent key returns `undefined`. This helper provides proper
- * typing for that case without needing a type assertion.
+ * accessing a missing key returns `undefined`. This helper provides proper
+ * typing for that case without treating properties inherited from
+ * `Object.prototype` as record data.
  *
  * ### Example
  *
  * ```ts
- * const users: Record<string, User> = { alice: { name: "Alice" } };
- * const user = getProperty(users, "bob"); // User | undefined
+ * import { getOwnProp } from "@evolu/common";
+ *
+ * interface User {
+ *   readonly name: string;
+ * }
+ *
+ * const users: Readonly<Record<string, User>> = {
+ *   alice: { name: "Alice" },
+ * };
+ * const user = getOwnProp(users, "bob");
+ *
+ * expectTypeOf(user).toEqualTypeOf<User | undefined>();
+ * expect(user).toBeUndefined();
+ * expect(getOwnProp(users, "toString")).toBeUndefined();
  * ```
  */
-export declare const getProperty: <K extends string, V>(record: ReadonlyRecord<K, V>, key: K) => V | undefined;
+export declare const getOwnProp: <K extends string, V>(record: ReadonlyRecord<K, V>, key: NoInfer<K>) => V | undefined;
 /**
  * A disposable wrapper around `URL.createObjectURL` that automatically revokes
  * the URL when disposed. Use with the `using` declaration for automatic
@@ -158,10 +275,13 @@ export declare const getProperty: <K extends string, V>(record: ReadonlyRecord<K
  * ### Example
  *
  * ```ts
+ * import { createObjectURL } from "@evolu/common";
+ *
  * const blob = new Blob(["hello"], { type: "text/plain" });
  * using objectUrl = createObjectURL(blob);
- * console.log(objectUrl.url); // blob:...
- * // URL.revokeObjectURL is automatically called when the scope ends
+ *
+ * expect(objectUrl.url).toMatch(/^blob:/);
+ * // URL.revokeObjectURL is automatically called when the scope ends.
  * ```
  *
  * This ensures the URL is always revoked when the scope ends, even if an error

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

@@ -1 +1 @@
-{"version":3,"file":"Object.d.ts","sourceRoot":"","sources":["../../src/Object.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Object.d.ts","sourceRoot":"","sources":["../../src/Object.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,GAAG,EAAE,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,aAAa,UACjB,OAAO,KACb,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAOjC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU,UAAW,OAAO,KAAG,KAAK,IAAI,UAAU,CAAC,QACnC,CAAC;AAE9B;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU,UAAW,OAAO,KAAG,KAAK,IAAI,QAAQ,CAAC,OAAO,CAEA,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,UACnD,CAAC,KACR,aAAa,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CACkB,CAAC;AAGvE,KAAK,WAAW,CAAC,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,WAC1C,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KACjC,cAAc,CAAC,CAAC,EAAE,CAAC,CAAwD,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,QACtC,aAAa,CAAC,CAAC,CAAC,YACZ,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,KACtB,cAAc,CAAC,CAAC,EAAE,CAAC,CACyD,CAAC;AAEhF;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC,UACtC,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,MACxB,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,KAC1B,cAAc,CAAC,CAAC,EAAE,CAAC,CAQrB,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,OACxD,CAAC,QACA,CAAC,cACK,OAAO,KAClB,OAAO,SAAS,SAAS,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAM/C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,wBAAgB,mBAAmB,CACjC,CAAC,SAAS,MAAM,GAAG,MAAM,EACzB,CAAC,GAAG,OAAO,KACR,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAClB,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,EAClD,MAAM,EAAE,CAAC,GACR;IAAE,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC;AAMtC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAGrD,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,UACpC,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,OACvB,OAAO,CAAC,CAAC,CAAC,KACd,CAAC,GAAG,SAAmE,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,SAAU,SAAQ,UAAU;IAC3C,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,iEAAiE;AACjE,eAAO,MAAM,eAAe,SAAU,IAAI,KAAG,SAQ5C,CAAC"}