@evolu/common 7.4.1 → 8.0.0-next.0

package/dist/src/Number.js

@@ -1,6 +1,11 @@
+/**
+ * Number arithmetic, comparison, and branded numeric types.
+ *
+ * @module
+ */
 import { assertNonEmptyReadonlyArray } from "./Assert.js";
 import { err, ok } from "./Result.js";
-import { PositiveInt } from "./Type.js";
+import { brand, lessThanOrEqualTo, onePositiveInt, NonNegativeInt, PositiveInt, } from "./Type.js";
 export const increment = (n) => n + 1;
 export const decrement = (n) => n - 1;
 /** Clamps a number within a given range. */
@@ -54,3 +59,20 @@ minNumberOfItemsPerBucket = PositiveInt.orThrow(2)) => {
     assertNonEmptyReadonlyArray(indexes);
     return ok(indexes);
 };
+/**
+ * Valid index for {@link fibonacciAt}, constrained to 1-78.
+ *
+ * Limited to 78 because F(79) exceeds JavaScript's `MAX_SAFE_INTEGER`.
+ */
+export const FibonacciIndex = /*#__PURE__*/ brand("FibonacciIndex", 
+/*#__PURE__*/ lessThanOrEqualTo(78)(PositiveInt));
+/** Returns the Fibonacci number at the given index (1-indexed: 1,1,2,3,5,8,...). */
+export const fibonacciAt = (index) => {
+    if (index <= 2)
+        return onePositiveInt;
+    let a = 1;
+    let b = 1;
+    for (let i = 3; i <= index; i++)
+        [a, b] = [b, a + b];
+    return PositiveInt.orThrow(b);
+};

package/dist/src/Object.d.ts

@@ -1,22 +1,61 @@
+/**
+ * Object utilities.
+ *
+ * @module
+ */
+/**
+ * A read-only `Record<K, V>` with `K extends keyof any` to preserve branded key
+ * types (e.g., in {@link mapObject}).
+ */
+export type ReadonlyRecord<K extends keyof any, V> = Readonly<Record<K, V>>;
 /**
  * Checks if a value is a plain object (e.g., created with `{}` or `Object`).
  *
+ * Accepts objects with `Object.prototype` and objects with a `null` prototype
+ * created via `Object.create(null)`. Rejects class instances and other built-in
+ * objects because their prototype chain includes an application-specific or
+ * built-in prototype before `Object.prototype`.
+ *
+ * The prototype-chain check uses structure instead of `prototype ===
+ * Object.prototype` so it also works for plain objects coming from another
+ * JavaScript realm.
+ *
  * ### Example
  *
  * ```ts
  * isPlainObject({}); // true
+ * isPlainObject(Object.create(null)); // true
  * isPlainObject(new Date()); // false
+ * isPlainObject(new (class Example {})()); // false
  * isPlainObject([]); // false
  * isPlainObject(null); // false
  * ```
  */
 export declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
 /**
- * A read-only `Record<K, V>` with `K extends keyof any` to preserve branded key
- * types (e.g., in {@link mapObject}).
+ * Checks if a value is a function.
+ *
+ * ### Example
+ *
+ * ```ts
+ * isFunction(() => {}); // true
+ * isFunction(function () {}); // true
+ * isFunction({}); // false
+ * ```
  */
-export type ReadonlyRecord<K extends keyof any, V> = Readonly<Record<K, V>>;
-type StringKeyOf<T> = Extract<keyof T, string>;
+export declare const isFunction: (value: unknown) => value is globalThis.Function;
+/**
+ * Checks if a value is {@link Iterable}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * isIterable([1, 2, 3]); // true
+ * isIterable("abc"); // true
+ * isIterable({}); // false
+ * ```
+ */
+export declare const isIterable: (value: unknown) => value is Iterable<unknown>;
 /**
  * Like `Object.entries` but preserves branded keys.
  *
@@ -29,6 +68,41 @@ type StringKeyOf<T> = Extract<keyof T, string>;
  * ```
  */
 export declare const objectToEntries: <T extends Record<string, any>>(record: T) => ReadonlyArray<[StringKeyOf<T>, T[StringKeyOf<T>]]>;
+type StringKeyOf<T> = Extract<keyof T, string>;
+/**
+ * Creates an object from key-value pairs, preserving branded key types.
+ *
+ * The inverse of {@link objectToEntries}. Use when you need type-safe
+ * reconstruction of objects with branded keys.
+ *
+ * ### Example
+ *
+ * ```ts
+ * type UserId = string & { readonly __brand: "UserId" };
+ * const entries: ReadonlyArray<[UserId, string]> = [
+ *   ["u1" as UserId, "Alice"],
+ * ];
+ * const users = objectFromEntries(entries); // ReadonlyRecord<UserId, string>
+ * ```
+ */
+export declare const objectFromEntries: <K extends string, V>(entries: Iterable<readonly [K, V]>) => ReadonlyRecord<K, V>;
+/**
+ * Creates an object by mapping keys to values.
+ *
+ * The inverse of `Object.keys` — instead of extracting keys from an object,
+ * builds an object from keys with a mapper function.
+ *
+ * ### Example
+ *
+ * ```ts
+ * objectFrom(["en", "fr", "de"], loadTranslations);
+ * // { en: Translations, fr: Translations, de: Translations }
+ *
+ * objectFrom(["trace", "debug", "log"], (level) => createHandler(level));
+ * // { trace: Handler, debug: Handler, log: Handler }
+ * ```
+ */
+export declare const objectFrom: <K extends string, V>(keys: ReadonlyArray<K>, getValue: (key: K) => V) => ReadonlyRecord<K, V>;
 /**
  * Maps a `ReadonlyRecord<K, V>` to a new `ReadonlyRecord<K, U>`, preserving
  * branded key types (e.g., `type Id = 'id' & string`) lost by `Object.entries`.
@@ -52,6 +126,14 @@ export declare const excludeProp: <T extends object, K extends keyof T>(obj: T,
  * ```
  */
 export declare const createRecord: <K extends string = string, V = unknown>() => Record<K, V>;
+/**
+ * An empty readonly record.
+ *
+ * Use as a default or initial value to avoid allocating new empty records.
+ *
+ * @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.
@@ -67,6 +149,29 @@ export declare const createRecord: <K extends string = string, V = unknown>() =>
  * const user = getProperty(users, "bob"); // User | undefined
  * ```
  */
-export declare const getProperty: <K extends string, V>(record: ReadonlyRecord<K, V>, key: string) => V | undefined;
+export declare const getProperty: <K extends string, V>(record: ReadonlyRecord<K, V>, key: K) => V | undefined;
+/**
+ * A disposable wrapper around `URL.createObjectURL` that automatically revokes
+ * the URL when disposed. Use with the `using` declaration for automatic
+ * cleanup.
+ *
+ * ### Example
+ *
+ * ```ts
+ * 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
+ * ```
+ *
+ * This ensures the URL is always revoked when the scope ends, even if an error
+ * occurs, preventing memory leaks from unreleased blob URLs.
+ */
+export interface ObjectURL extends Disposable {
+    /** The object URL string created by `URL.createObjectURL`. */
+    readonly url: string;
+}
+/** Creates a disposable {@link ObjectURL} for the given blob. */
+export declare const createObjectURL: (blob: Blob) => ObjectURL;
 export {};
 //# sourceMappingURL=Object.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Object.d.ts","sourceRoot":"","sources":["../../src/Object.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GACxB,OAAO,OAAO,KACb,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAC2B,CAAC;AAE9D;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,GAAG,EAAE,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAG5E,KAAK,WAAW,CAAC,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;AAE/C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3D,QAAQ,CAAC,KACR,aAAa,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAGK,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC,EAC9C,QAAQ,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,EAC5B,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,KAC1B,cAAc,CAAC,CAAC,EAAE,CAAC,CAMK,CAAC;AAE5B,wDAAwD;AACxD,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,EAC7D,KAAK,CAAC,EACN,MAAM,CAAC,EACP,YAAY,OAAO,KAClB,OAAO,SAAS,SAAS,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAM/C,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,OAAO,OAAK,MAAM,CAC5E,CAAC,EACD,CAAC,CACqC,CAAC;AAEzC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,EAC7C,QAAQ,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,EAC5B,KAAK,MAAM,KACV,CAAC,GAAG,SAA2D,CAAC"}
+{"version":3,"file":"Object.d.ts","sourceRoot":"","sources":["../../src/Object.ts"],"names":[],"mappings":"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"}

package/dist/src/Object.js

@@ -1,16 +1,63 @@
+/**
+ * Object utilities.
+ *
+ * @module
+ */
 /**
  * Checks if a value is a plain object (e.g., created with `{}` or `Object`).
  *
+ * Accepts objects with `Object.prototype` and objects with a `null` prototype
+ * created via `Object.create(null)`. Rejects class instances and other built-in
+ * objects because their prototype chain includes an application-specific or
+ * built-in prototype before `Object.prototype`.
+ *
+ * The prototype-chain check uses structure instead of `prototype ===
+ * Object.prototype` so it also works for plain objects coming from another
+ * JavaScript realm.
+ *
  * ### Example
  *
  * ```ts
  * isPlainObject({}); // true
+ * isPlainObject(Object.create(null)); // true
  * isPlainObject(new Date()); // false
+ * isPlainObject(new (class Example {})()); // false
  * isPlainObject([]); // false
  * isPlainObject(null); // false
  * ```
  */
-export const isPlainObject = (value) => Object.prototype.toString.call(value) === "[object Object]";
+export const isPlainObject = (value) => {
+    if (Object.prototype.toString.call(value) !== "[object Object]") {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === null || Object.getPrototypeOf(prototype) === null;
+};
+/**
+ * Checks if a value is a function.
+ *
+ * ### Example
+ *
+ * ```ts
+ * isFunction(() => {}); // true
+ * isFunction(function () {}); // true
+ * isFunction({}); // false
+ * ```
+ */
+export const isFunction = (value) => typeof value === "function";
+/**
+ * Checks if a value is {@link Iterable}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * isIterable([1, 2, 3]); // true
+ * isIterable("abc"); // true
+ * isIterable({}); // false
+ * ```
+ */
+export const isIterable = (value) => value != null &&
+    typeof value[Symbol.iterator] === "function";
 /**
  * Like `Object.entries` but preserves branded keys.
  *
@@ -23,15 +70,52 @@ export const isPlainObject = (value) => Object.prototype.toString.call(value) ==
  * ```
  */
 export const objectToEntries = (record) => Object.entries(record);
+/**
+ * Creates an object from key-value pairs, preserving branded key types.
+ *
+ * The inverse of {@link objectToEntries}. Use when you need type-safe
+ * reconstruction of objects with branded keys.
+ *
+ * ### Example
+ *
+ * ```ts
+ * type UserId = string & { readonly __brand: "UserId" };
+ * const entries: ReadonlyArray<[UserId, string]> = [
+ *   ["u1" as UserId, "Alice"],
+ * ];
+ * const users = objectFromEntries(entries); // ReadonlyRecord<UserId, string>
+ * ```
+ */
+export const objectFromEntries = (entries) => Object.fromEntries(entries);
+/**
+ * Creates an object by mapping keys to values.
+ *
+ * The inverse of `Object.keys` — instead of extracting keys from an object,
+ * builds an object from keys with a mapper function.
+ *
+ * ### Example
+ *
+ * ```ts
+ * objectFrom(["en", "fr", "de"], loadTranslations);
+ * // { en: Translations, fr: Translations, de: Translations }
+ *
+ * objectFrom(["trace", "debug", "log"], (level) => createHandler(level));
+ * // { trace: Handler, debug: Handler, log: Handler }
+ * ```
+ */
+export const objectFrom = (keys, getValue) => Object.fromEntries(keys.map((k) => [k, getValue(k)]));
 /**
  * Maps a `ReadonlyRecord<K, V>` to a new `ReadonlyRecord<K, U>`, preserving
  * branded key types (e.g., `type Id = 'id' & string`) lost by `Object.entries`.
  * Uses `K extends string` for precision.
  */
-export const mapObject = (record, fn) => Object.fromEntries(Object.entries(record).map(([key, value]) => [
-    key,
-    fn(value, key),
-]));
+export const mapObject = (record, fn) => {
+    const out = Object.create(null);
+    for (const key in record) {
+        out[key] = fn(record[key], key);
+    }
+    return out;
+};
 /** Conditionally excludes a property from an object. */
 export const excludeProp = (obj, prop, condition) => {
     if (condition) {
@@ -55,6 +139,15 @@ export const excludeProp = (obj, prop, condition) => {
  * ```
  */
 export const createRecord = () => Object.create(null);
+/**
+ * An empty readonly record.
+ *
+ * Use as a default or initial value to avoid allocating new empty records.
+ *
+ * @group Constants
+ */
+export const emptyRecord = 
+/*#__PURE__*/ createRecord();
 /**
  * Safely gets a property from a record, returning `undefined` if the key
  * doesn't exist.
@@ -71,3 +164,13 @@ export const createRecord = () => Object.create(null);
  * ```
  */
 export const getProperty = (record, key) => (key in record ? record[key] : undefined);
+/** Creates a disposable {@link ObjectURL} for the given blob. */
+export const createObjectURL = (blob) => {
+    const url = URL.createObjectURL(blob);
+    return {
+        url,
+        [Symbol.dispose]: () => {
+            URL.revokeObjectURL(url);
+        },
+    };
+};

package/dist/src/Option.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Optional value container.
+ *
+ * Distinguishes absence from values like `null` or `undefined`.
+ *
+ * Use Option when the value itself can be `null` or `undefined`. For APIs where
+ * `null` means "not found", just use `T | null` directly.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // A cache that can store any value, including null and undefined
+ * const cache = new Map<string, Option<unknown>>();
+ *
+ * const get = (key: string): Option<unknown> => cache.get(key) ?? none;
+ *
+ * cache.set("a", some(null)); // Stored null
+ * cache.set("b", some(undefined)); // Stored undefined
+ *
+ * isSome(get("a")); // true — value is null
+ * isSome(get("b")); // true — value is undefined
+ * isNone(get("c")); // true — key doesn't exist
+ * ```
+ *
+ * @module
+ */
+/** Optional value. */
+import type { Typed } from "./Type.js";
+/** Optional value. */
+export type Option<T> = Some<T> | None;
+/** Present value in an {@link Option}. */
+export interface Some<out T> extends Typed<"Some"> {
+    readonly value: T;
+}
+/** Absent value in an {@link Option}. */
+export interface None extends Typed<"None"> {
+}
+/**
+ * Extracts the value type from an {@link Option} or {@link Some}.
+ *
+ * @group Utilities
+ */
+export type InferOption<O extends Option<any>> = O extends Some<infer T> ? T : never;
+/** Creates a {@link Some}. */
+export declare const some: <T>(value: T) => Option<T>;
+/** Shared {@link None} instance. */
+export declare const none: None;
+/** Type guard for {@link Some}. */
+export declare const isSome: <T>(option: Option<T>) => option is Some<T>;
+/** Type guard for {@link None}. */
+export declare const isNone: <T>(option: Option<T>) => option is None;
+/**
+ * Converts a nullable value to an {@link Option}.
+ *
+ * `null` and `undefined` become {@link none}.
+ */
+export declare const fromNullable: <T>(value: T | null | undefined) => Option<NonNullable<T>>;
+//# sourceMappingURL=Option.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Option.d.ts","sourceRoot":"","sources":["../../src/Option.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,sBAAsB;AACtB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAEvC,sBAAsB;AACtB,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;AAEvC,0CAA0C;AAC1C,MAAM,WAAW,IAAI,CAAC,GAAG,CAAC,CAAC,CAAE,SAAQ,KAAK,CAAC,MAAM,CAAC;IAChD,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED,yCAAyC;AACzC,MAAM,WAAW,IAAK,SAAQ,KAAK,CAAC,MAAM,CAAC;CAAG;AAE9C;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,CAAC,IAC3C,CAAC,SAAS,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEtC,8BAA8B;AAC9B,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,MAAM,CAAC,CAAC,CAGzC,CAAC;AAEH,oCAAoC;AACpC,eAAO,MAAM,IAAI,EAAE,IAAuB,CAAC;AAE3C,mCAAmC;AACnC,eAAO,MAAM,MAAM,GAAI,CAAC,EAAE,QAAQ,MAAM,CAAC,CAAC,CAAC,KAAG,MAAM,IAAI,IAAI,CAAC,CAAC,CACtC,CAAC;AAEzB,mCAAmC;AACnC,eAAO,MAAM,MAAM,GAAI,CAAC,EAAE,QAAQ,MAAM,CAAC,CAAC,CAAC,KAAG,MAAM,IAAI,IAChC,CAAC;AAEzB;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,EAC5B,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,KAC1B,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAyC,CAAC"}

package/dist/src/Option.js

@@ -0,0 +1,43 @@
+/**
+ * Optional value container.
+ *
+ * Distinguishes absence from values like `null` or `undefined`.
+ *
+ * Use Option when the value itself can be `null` or `undefined`. For APIs where
+ * `null` means "not found", just use `T | null` directly.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // A cache that can store any value, including null and undefined
+ * const cache = new Map<string, Option<unknown>>();
+ *
+ * const get = (key: string): Option<unknown> => cache.get(key) ?? none;
+ *
+ * cache.set("a", some(null)); // Stored null
+ * cache.set("b", some(undefined)); // Stored undefined
+ *
+ * isSome(get("a")); // true — value is null
+ * isSome(get("b")); // true — value is undefined
+ * isNone(get("c")); // true — key doesn't exist
+ * ```
+ *
+ * @module
+ */
+/** Creates a {@link Some}. */
+export const some = (value) => ({
+    type: "Some",
+    value,
+});
+/** Shared {@link None} instance. */
+export const none = { type: "None" };
+/** Type guard for {@link Some}. */
+export const isSome = (option) => option.type === "Some";
+/** Type guard for {@link None}. */
+export const isNone = (option) => option.type === "None";
+/**
+ * Converts a nullable value to an {@link Option}.
+ *
+ * `null` and `undefined` become {@link none}.
+ */
+export const fromNullable = (value) => (value == null ? none : some(value));

package/dist/src/Order.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Ordering and comparison utilities.
+ *
+ * @module
+ */
 /**
  * Compares two values of type `A` and returns their ordering.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"Order.d.ts","sourceRoot":"","sources":["../../src/Order.ts"],"names":[],"mappings":"AAAA;;;;;;;;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,CAAgC,CAAC;AAEvE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW,eAAuC,CAAC;AAEhE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,eAAuC,CAAC;AAEhE,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;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"}

package/dist/src/Order.js

@@ -1,3 +1,8 @@
+/**
+ * Ordering and comparison utilities.
+ *
+ * @module
+ */
 /**
  * Creates an ordering function from a "less than" comparator.
  *
@@ -35,7 +40,7 @@ export const reverseOrder = (order) => (a, b) => order(b, a);
  * ["c", "b", "a"].toSorted(orderString); // ["a", "b", "c"]
  * ```
  */
-export const orderString = createOrder((a, b) => a < b);
+export const orderString = /*#__PURE__*/ createOrder((a, b) => a < b);
 /**
  * An order for numbers in ascending order.
  *
@@ -51,7 +56,7 @@ export const orderString = createOrder((a, b) => a < b);
  * reverseOrder(orderNumber)(1, 1); // 0
  * ```
  */
-export const orderNumber = createOrder((a, b) => a < b);
+export const orderNumber = /*#__PURE__*/ createOrder((a, b) => a < b);
 /**
  * An order for bigints in ascending order.
  *
@@ -64,7 +69,7 @@ export const orderNumber = createOrder((a, b) => a < b);
  * [2n, 1n, 3n].toSorted(orderBigInt); // [1n, 2n, 3n]
  * ```
  */
-export const orderBigInt = createOrder((a, b) => a < b);
+export const orderBigInt = /*#__PURE__*/ createOrder((a, b) => a < b);
 /** An {@link Order} for Uint8Array. */
 export const orderUint8Array = (a, b) => {
     if (a.byteLength > b.byteLength)

package/dist/src/Platform.d.ts

@@ -1,5 +1,12 @@
-/** Detects if the code is running in React Native environment. */
-export declare const isReactNative: boolean;
+/**
+ * Platform runtime utilities and capability abstractions.
+ *
+ * @module
+ */
+/** Returns true if running in React Native with Hermes engine. */
+export declare const isHermes: boolean;
+/** Returns true if running in a server environment (no DOM). */
+export declare const isServer: boolean;
 /**
  * Detects if Node.js Buffer is available and should be used.
  *
@@ -12,4 +19,31 @@ export declare const isReactNative: boolean;
  * @see https://github.com/craftzdog/react-native-quick-base64#installation
  */
 export declare const hasNodeBuffer: boolean;
+/**
+ * FlushSync is for libraries like React to flush updates synchronously inside
+ * the provided callback to ensure the DOM is updated immediately.
+ *
+ * For example, with React, when we want to focus on an element rendered as a
+ * result of a mutation, Evolu ensures all DOM changes are flushed synchronously
+ * if an onComplete callback is used.
+ *
+ * https://react.dev/reference/react-dom/flushSync
+ */
+export type FlushSync = (callback: () => void) => void;
+export interface FlushSyncDep {
+    readonly flushSync: FlushSync;
+}
+/**
+ * Reload the app in a platform-specific way.
+ *
+ * Use this after purging persistent storage to clear in-memory state and ensure
+ * the app starts fresh. It does not purge storage itself.
+ *
+ * - Web: Redirects to the specified URL (defaults to `/`)
+ * - React Native: Restarts the app (URL ignored)
+ */
+export type ReloadApp = (url?: string) => void;
+export interface ReloadAppDep {
+    readonly reloadApp: ReloadApp;
+}
 //# 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,kEAAkE;AAClE,eAAO,MAAM,aAAa,SAIoB,CAAC;AAE/C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,SACkC,CAAC"}
+{"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"}

package/dist/src/Platform.js

@@ -1,8 +1,12 @@
-/** Detects if the code is running in React Native environment. */
-export const isReactNative = typeof navigator !== "undefined" &&
-    "product" in navigator &&
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-    navigator.product === "ReactNative";
+/**
+ * Platform runtime utilities and capability abstractions.
+ *
+ * @module
+ */
+/** Returns true if running in React Native with Hermes engine. */
+export const isHermes = "HermesInternal" in globalThis;
+/** Returns true if running in a server environment (no DOM). */
+export const isServer = typeof document === "undefined";
 /**
  * Detects if Node.js Buffer is available and should be used.
  *
@@ -14,4 +18,4 @@ export const isReactNative = typeof navigator !== "undefined" &&
  *
  * @see https://github.com/craftzdog/react-native-quick-base64#installation
  */
-export const hasNodeBuffer = !isReactNative && typeof globalThis.Buffer !== "undefined";
+export const hasNodeBuffer = !isHermes && typeof globalThis.Buffer !== "undefined";

package/dist/src/Polyfills.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 declare const installPolyfills: () => void;
+//# sourceMappingURL=Polyfills.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Polyfills.d.ts","sourceRoot":"","sources":["../../src/Polyfills.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,gBAAgB,QAAO,IAgBnC,CAAC"}