@evolu/common 8.0.0-next.5 → 8.0.0

package/dist/src/Object.js

@@ -15,15 +15,20 @@
  * 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 const isPlainObject = (value) => {
@@ -39,9 +44,11 @@ export const isPlainObject = (value) => {
  * ### 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 const isFunction = (value) => typeof value === "function";
@@ -51,9 +58,11 @@ export const isFunction = (value) => typeof value === "function";
  * ### 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 const isIterable = (value) => value != null &&
@@ -64,9 +73,20 @@ export const isIterable = (value) => value != null &&
  * ### 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 const objectToEntries = (record) => Object.entries(record);
@@ -79,11 +99,20 @@ export const objectToEntries = (record) => Object.entries(record);
  * ### 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 const objectFromEntries = (entries) => Object.fromEntries(entries);
@@ -96,11 +125,20 @@ export const objectFromEntries = (entries) => Object.fromEntries(entries);
  * ### 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 }
+ * import { objectFrom, type ReadonlyRecord } from "@evolu/common";
+ *
+ * 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 const objectFrom = (keys, getValue) => Object.fromEntries(keys.map((k) => [k, getValue(k)]));
@@ -124,46 +162,54 @@ export const excludeProp = (obj, prop, condition) => {
     const { [prop]: _, ...rest } = obj;
     return rest;
 };
+export function createMutableRecord(source) {
+    const record = Object.create(null);
+    return source === undefined ? record : Object.assign(record, source);
+}
 /**
- * Creates a prototype-less object typed as `Record<K, V>`.
+ * A shared frozen empty readonly Record.
  *
- * 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__`.
+ * 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.
  *
- * Example:
- *
- * ```ts
- * const values = createRecord<string, SqliteValue>();
- * values["__proto__"] = someValue; // safe, no prototype pollution
- * ```
- */
-export const createRecord = () => Object.create(null);
-/**
- * An empty readonly record.
- *
- * Use as a default or initial value to avoid allocating new empty records.
+ * Use {@link createMutableRecord} to build a Record locally through mutation
+ * instead of repeated object spreads.
  *
  * @group Constants
  */
 export const emptyRecord = 
-/*#__PURE__*/ createRecord();
+/*#__PURE__*/ Object.freeze(
+/*#__PURE__*/ createMutableRecord());
 /**
- * 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 const getProperty = (record, key) => (key in record ? record[key] : undefined);
+export const getOwnProp = (record, key) => (Object.hasOwn(record, key) ? record[key] : undefined);
 /** Creates a disposable {@link ObjectURL} for the given blob. */
 export const createObjectURL = (blob) => {
     const url = URL.createObjectURL(blob);

package/dist/src/Option.d.ts

@@ -9,23 +9,26 @@
  * ### Example
  *
  * ```ts
- * // A cache that can store any value, including null and undefined
+ * import { isNone, isSome, none, type Option, some } from "@evolu/common";
+ *
  * 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
+ * cache.set("a", some(null));
+ * cache.set("b", some(undefined));
  *
- * isSome(get("a")); // true — value is null
- * isSome(get("b")); // true — value is undefined
- * isNone(get("c")); // true — key doesn't exist
+ * const a = get("a");
+ * assert(isSome(a));
+ * expect(a.value).toBeNull();
+ * expect(isSome(get("b"))).toBe(true);
+ * expect(isNone(get("c"))).toBe(true);
  * ```
  *
  * @module
  */
 /** Optional value. */
-import type { Typed } from "./Type.js";
+import type { Typed } from "./Type.ts";
 /** Optional value. */
 export type Option<T> = Some<T> | None;
 /** Present value in an {@link Option}. */

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

@@ -1 +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"}
+{"version":3,"file":"Option.d.ts","sourceRoot":"","sources":["../../src/Option.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;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,SAAS,CAAC,KAAG,MAAM,CAAC,CAAC,CAGzC,CAAC;AAEH,oCAAoC;AACpC,eAAO,MAAM,IAAI,EAAE,IAAuB,CAAC;AAE3C,mCAAmC;AACnC,eAAO,MAAM,MAAM,GAAI,CAAC,UAAU,MAAM,CAAC,CAAC,CAAC,KAAG,MAAM,IAAI,IAAI,CAAC,CAAC,CACtC,CAAC;AAEzB,mCAAmC;AACnC,eAAO,MAAM,MAAM,GAAI,CAAC,UAAU,MAAM,CAAC,CAAC,CAAC,KAAG,MAAM,IAAI,IAChC,CAAC;AAEzB;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,SACrB,CAAC,GAAG,IAAI,GAAG,SAAS,KAC1B,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAyC,CAAC"}

package/dist/src/Option.js

@@ -9,17 +9,20 @@
  * ### Example
  *
  * ```ts
- * // A cache that can store any value, including null and undefined
+ * import { isNone, isSome, none, type Option, some } from "@evolu/common";
+ *
  * 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
+ * cache.set("a", some(null));
+ * cache.set("b", some(undefined));
  *
- * isSome(get("a")); // true — value is null
- * isSome(get("b")); // true — value is undefined
- * isNone(get("c")); // true — key doesn't exist
+ * const a = get("a");
+ * assert(isSome(a));
+ * expect(a.value).toBeNull();
+ * expect(isSome(get("b"))).toBe(true);
+ * expect(isNone(get("c"))).toBe(true);
  * ```
  *
  * @module

package/dist/src/Order.d.ts

@@ -11,6 +11,9 @@
  * - Returns `-1` if `x` is less than `y`.
  * - Returns `0` if `x` is equal to `y`.
  * - Returns `1` if `x` is greater than `y`.
+ *
+ * An `Order` also defines equality. Use {@link eqFromOrder} to derive an
+ * {@link Eq}.
  */
 export type Order<in A> = (x: A, y: A) => Ordering;
 /**
@@ -25,10 +28,12 @@ export type Ordering = -1 | 0 | 1;
  * ### 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 declare const createOrder: <A>(isLessThan: (x: A, y: A) => boolean) => Order<A>;
@@ -38,9 +43,10 @@ export declare const createOrder: <A>(isLessThan: (x: A, y: A) => boolean) => Or
  * ### 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 declare const reverseOrder: <A>(order: Order<A>) => Order<A>;
@@ -50,10 +56,9 @@ export declare const reverseOrder: <A>(order: Order<A>) => Order<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 declare const orderString: Order<string>;
@@ -63,13 +68,9 @@ export declare const orderString: Order<string>;
  * ### 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 declare const orderNumber: Order<number>;
@@ -79,10 +80,9 @@ export declare const orderNumber: Order<number>;
  * ### 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 declare const orderBigInt: Order<bigint>;

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();
+        },
+    };
+};