@evolu/common 8.0.0-next.4 → 8.0.0

package/src/Object.ts

@@ -22,15 +22,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 const isPlainObject = (
@@ -50,9 +55,11 @@ export const isPlainObject = (
  * ### 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: unknown): value is globalThis.Function =>
@@ -64,9 +71,11 @@ export const isFunction = (value: unknown): value is globalThis.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: unknown): value is Iterable<unknown> =>
@@ -79,17 +88,26 @@ export 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 const objectToEntries = <T extends Record<string, any>>(
   record: T,
 ): ReadonlyArray<[StringKeyOf<T>, T[StringKeyOf<T>]]> =>
-  Object.entries(record) as Array<
-    [StringKeyOf<T>, T[StringKeyOf<T>]]
-  >;
+  Object.entries(record) as Array<[StringKeyOf<T>, T[StringKeyOf<T>]]>;
 
 // A helper type to remove symbol keys (e.g for branded objects).
 type StringKeyOf<T> = Extract<keyof T, string>;
@@ -103,11 +121,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 const objectFromEntries = <K extends string, V>(
@@ -123,11 +150,20 @@ export const objectFromEntries = <K extends string, V>(
  * ### Example
  *
  * ```ts
- * objectFrom(["en", "fr", "de"], loadTranslations);
- * // { en: Translations, fr: Translations, de: Translations }
+ * import { objectFrom, type ReadonlyRecord } from "@evolu/common";
+ *
+ * const translations = objectFrom(
+ *   ["en", "fr"] as const,
+ *   (locale): string => `Hello in ${locale}`,
+ * );
  *
- * objectFrom(["trace", "debug", "log"], (level) => createHandler(level));
- * // { trace: Handler, debug: Handler, log: Handler }
+ * expectTypeOf(translations).toEqualTypeOf<
+ *   ReadonlyRecord<"en" | "fr", string>
+ * >();
+ * expect(translations).toEqual({
+ *   en: "Hello in en",
+ *   fr: "Hello in fr",
+ * });
  * ```
  */
 export const objectFrom = <K extends string, V>(
@@ -168,53 +204,138 @@ export const excludeProp = <T extends object, K extends keyof T>(
 };
 
 /**
- * Creates a prototype-less object typed as `Record<K, V>`.
+ * Creates a mutable 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 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.
  *
- * Example:
+ * 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
- * const values = createRecord<string, SqliteValue>();
- * values["__proto__"] = someValue; // safe, no prototype pollution
+ * import { createMutableRecord } from "@evolu/common";
+ *
+ * const createValuesByKey = (
+ *   entries: ReadonlyArray<readonly [string, number]>,
+ * ): Readonly<Record<string, number>> => {
+ *   const valuesByKey = createMutableRecord<string, number>();
+ *
+ *   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
+ * 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 const createRecord = <K extends string = string, V = unknown>(): Record<
-  K,
-  V
-> => Object.create(null) as Record<K, V>;
+export function createMutableRecord<
+  K extends string = string,
+  V = unknown,
+>(): Record<K, V>;
+export function createMutableRecord<T extends object>(
+  source: T,
+): { -readonly [K in keyof T]: T[K] };
+export function createMutableRecord(source?: object): Record<string, unknown> {
+  const record = Object.create(null) as Record<string, unknown>;
+  return source === undefined ? record : Object.assign(record, source);
+}
 
 /**
- * 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 const emptyRecord: Readonly<Record<string, never>> =
-  /*#__PURE__*/ createRecord();
+  /*#__PURE__*/ Object.freeze(
+    /*#__PURE__*/ createMutableRecord<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 const getProperty = <K extends string, V>(
+export const getOwnProp = <K extends string, V>(
   record: ReadonlyRecord<K, V>,
-  key: K,
-): V | undefined => (key in record ? record[key] : undefined);
+  key: NoInfer<K>,
+): V | undefined => (Object.hasOwn(record, key) ? record[key] : undefined);
 
 /**
  * A disposable wrapper around `URL.createObjectURL` that automatically revokes
@@ -224,10 +345,13 @@ export const getProperty = <K extends string, V>(
  * ### 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/src/Option.ts

@@ -9,24 +9,27 @@
  * ### 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;

package/src/Order.ts

@@ -4,6 +4,8 @@
  * @module
  */
 
+import type { Eq, eqFromOrder } from "./Eq.ts";
+
 /**
  * Compares two values of type `A` and returns their ordering.
  *
@@ -12,6 +14,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;
 
@@ -28,10 +33,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 const createOrder =
@@ -45,9 +52,10 @@ export const createOrder =
  * ### 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 =
@@ -61,10 +69,9 @@ export const reverseOrder =
  * ### 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: Order<string> = /*#__PURE__*/ createOrder(
@@ -77,13 +84,9 @@ export const orderString: Order<string> = /*#__PURE__*/ createOrder(
  * ### 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<number>((a, b) => a < b);
@@ -94,10 +97,9 @@ export const orderNumber = /*#__PURE__*/ createOrder<number>((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<bigint>((a, b) => a < b);

package/src/Platform.ts

@@ -10,6 +10,22 @@ 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.
  *
@@ -54,3 +70,123 @@ 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 const testGlobalUncaughtErrors = (): TestGlobalErrors =>
+  createTestGlobalErrors("uncaughtErrors");
+
+/** Records platform global unhandled-rejection reporting until disposed. */
+export const testGlobalUnhandledRejections = (): TestGlobalErrors =>
+  createTestGlobalErrors("unhandledRejection");
+
+const settleSentinel = new Error("TestGlobalErrors.settle sentinel");
+
+const createTestGlobalErrors = (
+  kind: "uncaughtErrors" | "unhandledRejection",
+): TestGlobalErrors => {
+  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: Array<unknown> = [];
+  const nextWaiters: Array<(error: unknown) => void> = [];
+  const settleWaiters: Array<() => void> = [];
+  let nextIndex = 0;
+
+  const next = (): Promise<unknown> => {
+    if (nextIndex < errors.length) {
+      const error = errors[nextIndex];
+      nextIndex += 1;
+      return Promise.resolve(error);
+    }
+
+    const next = Promise.withResolvers<unknown>();
+    nextWaiters.push(next.resolve);
+    return next.promise;
+  };
+
+  const record = (error: unknown): void => {
+    if (error === settleSentinel) {
+      settleWaiters.shift()?.();
+      return;
+    }
+
+    errors.push(error);
+    const resolveNext = nextWaiters.shift();
+    if (!resolveNext) return;
+
+    nextIndex += 1;
+    resolveNext(error);
+  };
+
+  const settle = (): Promise<ReadonlyArray<unknown>> => {
+    const settled = Promise.withResolvers<ReadonlyArray<unknown>>();
+    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: unknown): void => {
+      (event as Event).preventDefault();
+      record((event as Record<typeof webErrorKey, unknown>)[webErrorKey]);
+    };
+
+    globalThis.addEventListener(webEvent, listener);
+    disposableStack.defer(() => {
+      globalThis.removeEventListener(webEvent, listener);
+    });
+  } else {
+    throw new Error(`Unsupported platform global ${errorType} reporting.`);
+  }
+
+  return {
+    errors,
+    next,
+    settle,
+    [Symbol.dispose]: () => {
+      nextWaiters.length = 0;
+      settleWaiters.length = 0;
+      disposableStack.dispose();
+    },
+  };
+};

package/src/Polyfills.ts

@@ -199,13 +199,10 @@ const installSuppressedError = (): void => {
 const createDisposableStackPolyfill = (
   symbolDispose: symbol,
 ): new () => DisposableStack => {
-  class DisposableStackPolyfill implements DisposableStack {
+  class DisposableStackPolyfill {
     #disposed = false;
     #resources: Array<DisposableResource> = [];
 
-    declare readonly [Symbol.toStringTag]: "DisposableStack";
-    declare [Symbol.dispose]: () => void;
-
     get disposed(): boolean {
       return this.#disposed;
     }
@@ -278,7 +275,7 @@ const createDisposableStackPolyfill = (
       this.#resources = [];
       this.#disposed = true;
 
-      return moved;
+      return moved as unknown as DisposableStack;
     }
 
     dispose(): void {
@@ -321,20 +318,17 @@ const createDisposableStackPolyfill = (
     value: "DisposableStack",
   });
 
-  return DisposableStackPolyfill;
+  return DisposableStackPolyfill as unknown as new () => DisposableStack;
 };
 
 const createAsyncDisposableStackPolyfill = (
   symbolDispose: symbol,
   symbolAsyncDispose: symbol,
 ): new () => AsyncDisposableStack => {
-  class AsyncDisposableStackPolyfill implements AsyncDisposableStack {
+  class AsyncDisposableStackPolyfill {
     #disposed = false;
     #resources: Array<AsyncDisposableResource> = [];
 
-    declare readonly [Symbol.toStringTag]: "AsyncDisposableStack";
-    declare [Symbol.asyncDispose]: () => Promise<void>;
-
     get disposed(): boolean {
       return this.#disposed;
     }
@@ -417,7 +411,7 @@ const createAsyncDisposableStackPolyfill = (
       this.#resources = [];
       this.#disposed = true;
 
-      return moved;
+      return moved as unknown as AsyncDisposableStack;
     }
 
     async disposeAsync(): Promise<void> {
@@ -464,7 +458,7 @@ const createAsyncDisposableStackPolyfill = (
     },
   );
 
-  return AsyncDisposableStackPolyfill;
+  return AsyncDisposableStackPolyfill as unknown as new () => AsyncDisposableStack;
 };
 
 /** Installs `Map` and `WeakMap` upsert polyfills missing from the runtime. */