@evolu/common 8.4.0 → 8.6.0

package/src/Object.ts

@@ -10,43 +10,88 @@
  */
 export type ReadonlyRecord<K extends keyof any, V> = Readonly<Record<K, V>>;
 
+/** An Object representation recognized by {@link getObjectKind}. */
+export type ObjectKind =
+  "Array" | "Date" | "Map" | "Object" | "Set" | "Uint8Array" | "Unsupported";
+
 /**
- * Checks if a value is a plain object (e.g., created with `{}` or `Object`).
+ * Classifies Object representations supported by Evolu's structural data APIs.
+ *
+ * Plain Objects are classified from their prototype without reading their
+ * properties, including `Symbol.toStringTag`.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertEqual, getObjectKind } from "@evolu/common";
  *
- * 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`.
+ * assertEqual(getObjectKind({}), "Object");
+ * assertEqual(getObjectKind(new Map()), "Map");
+ * assertEqual(getObjectKind(/value/u), "Unsupported");
+ * ```
+ */
+export const getObjectKind = (value: object): ObjectKind => {
+  if (Array.isArray(value)) return "Array";
+  if (isPlainObject(value)) return "Object";
+
+  switch (Object.prototype.toString.call(value)) {
+    case "[object Date]":
+      return "Date";
+    case "[object Map]":
+      return "Map";
+    case "[object Set]":
+      return "Set";
+    case "[object Uint8Array]":
+      return "Uint8Array";
+    default:
+      return "Unsupported";
+  }
+};
+
+/**
+ * Checks if a value is a plain object (e.g., created with `{}` or `Object`).
  *
- * The prototype-chain check uses structure instead of `prototype ===
- * Object.prototype` so it also works for plain objects coming from another
- * JavaScript realm.
+ * Accepts objects with a `null` prototype. Otherwise, it uses a realm-neutral
+ * structural heuristic: the immediate prototype must be a root object with own
+ * `hasOwnProperty` and `isPrototypeOf` properties. This recognizes ordinary
+ * Objects from another JavaScript realm without relying on prototype identity.
  *
- * TODO: deprecated Use `Object.is` from Type. Define a dedicated Type when
- * another object domain is required.
+ * A custom root prototype with the same shape can therefore be classified as
+ * plain. This function assumes trusted JavaScript and is not a prototype
+ * authentication or security boundary. Other custom prototypes, class
+ * instances, and built-in objects are rejected.
  *
  * ### Example
  *
  * ```ts
- * 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);
+ * import { assertFalse, assertTrue, isPlainObject } from "@evolu/common";
+ *
+ * class Example {
+ *   readonly value = "example";
+ * }
+ *
+ * assertTrue(isPlainObject({}));
+ * assertTrue(isPlainObject(Object.create(null)));
+ * assertFalse(isPlainObject(new Date()));
+ * assertFalse(isPlainObject(new Example()));
+ * assertFalse(isPlainObject([]));
+ * assertFalse(isPlainObject(null));
  * ```
  */
 export const isPlainObject = (
   value: unknown,
 ): value is Record<string, unknown> => {
-  if (Object.prototype.toString.call(value) !== "[object Object]") {
+  if (value === null || typeof value !== "object") {
     return false;
   }
 
   const prototype = Object.getPrototypeOf(value) as object | null;
-  return prototype === null || Object.getPrototypeOf(prototype) === null;
+  if (prototype === null) return true;
+  return (
+    Object.getPrototypeOf(prototype) === null &&
+    Object.hasOwn(prototype, "hasOwnProperty") &&
+    Object.hasOwn(prototype, "isPrototypeOf")
+  );
 };
 
 /**
@@ -55,11 +100,11 @@ export const isPlainObject = (
  * ### Example
  *
  * ```ts
- * import { isFunction } from "@evolu/common";
+ * import { assertFalse, assertTrue, isFunction } from "@evolu/common";
  *
- * expect(isFunction(() => {})).toBe(true);
- * expect(isFunction(function () {})).toBe(true);
- * expect(isFunction({})).toBe(false);
+ * assertTrue(isFunction(() => {}));
+ * assertTrue(isFunction(function () {}));
+ * assertFalse(isFunction({}));
  * ```
  */
 export const isFunction = (value: unknown): value is globalThis.Function =>
@@ -71,11 +116,11 @@ export const isFunction = (value: unknown): value is globalThis.Function =>
  * ### Example
  *
  * ```ts
- * import { isIterable } from "@evolu/common";
+ * import { assertFalse, assertTrue, isIterable } from "@evolu/common";
  *
- * expect(isIterable([1, 2, 3])).toBe(true);
- * expect(isIterable("abc")).toBe(true);
- * expect(isIterable({})).toBe(false);
+ * assertTrue(isIterable([1, 2, 3]));
+ * assertTrue(isIterable("abc"));
+ * assertFalse(isIterable({}));
  * ```
  */
 export const isIterable = (value: unknown): value is Iterable<unknown> =>
@@ -89,6 +134,8 @@ export const isIterable = (value: unknown): value is Iterable<unknown> =>
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertType,
  *   objectToEntries,
  *   type Brand,
  *   type ReadonlyRecord,
@@ -100,8 +147,8 @@ export const isIterable = (value: unknown): value is Iterable<unknown> =>
  * const users: ReadonlyRecord<UserId, string> = { [userId]: "Alice" };
  * const entries = objectToEntries(users);
  *
- * expectTypeOf(entries).toEqualTypeOf<ReadonlyArray<[UserId, string]>>();
- * expect(entries).toEqual([[userId, "Alice"]]);
+ * assertType<ReadonlyArray<[UserId, string]>, typeof entries>();
+ * assertEqual(entries, [[userId, "Alice"]]);
  * ```
  */
 export const objectToEntries = <T extends Record<string, any>>(
@@ -122,6 +169,8 @@ type StringKeyOf<T> = Extract<keyof T, string>;
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertType,
  *   objectFromEntries,
  *   type Brand,
  *   type ReadonlyRecord,
@@ -133,8 +182,8 @@ type StringKeyOf<T> = Extract<keyof T, string>;
  * ];
  * const users = objectFromEntries(entries);
  *
- * expectTypeOf(users).toEqualTypeOf<ReadonlyRecord<UserId, string>>();
- * expect(users).toEqual({ u1: "Alice" });
+ * assertType<ReadonlyRecord<UserId, string>, typeof users>();
+ * assertEqual(users, { u1: "Alice" });
  * ```
  */
 export const objectFromEntries = <K extends string, V>(
@@ -150,17 +199,20 @@ export const objectFromEntries = <K extends string, V>(
  * ### Example
  *
  * ```ts
- * import { objectFrom, type ReadonlyRecord } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   assertType,
+ *   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({
+ * assertType<ReadonlyRecord<"en" | "fr", string>, typeof translations>();
+ * assertEqual(translations, {
  *   en: "Hello in en",
  *   fr: "Hello in fr",
  * });
@@ -228,7 +280,7 @@ export const excludeProp = <T extends object, K extends keyof T>(
  * ### Example
  *
  * ```ts
- * import { createMutableRecord } from "@evolu/common";
+ * import { assertEqual, createMutableRecord } from "@evolu/common";
  *
  * const createValuesByKey = (
  *   entries: ReadonlyArray<readonly [string, number]>,
@@ -242,12 +294,13 @@ export const excludeProp = <T extends object, K extends keyof T>(
  *   return valuesByKey;
  * };
  *
- * expect(
+ * assertEqual(
  *   createValuesByKey([
  *     ["a", 1],
  *     ["b", 2],
  *   ]),
- * ).toEqual({ a: 1, b: 2 });
+ *   { a: 1, b: 2 },
+ * );
  * ```
  *
  * Note that TypeScript does not model an object's runtime prototype. A plain
@@ -255,21 +308,34 @@ export const excludeProp = <T extends object, K extends keyof T>(
  * object has a `null` prototype:
  *
  * ```ts
+ * import { assertErr, assertTrue, trySync } from "@evolu/common";
+ *
  * const values = Object.create(null) as Record<string, number>;
  *
  * // TypeScript accepts the call, but `toString` is undefined at runtime.
- * expect(() => values.toString()).toThrow(TypeError);
+ * // oxlint-disable-next-line typescript/no-base-to-string -- Intentionally calls a method missing from the null-prototype value.
+ * const result = trySync(() => values.toString());
+ * assertErr(result);
+ * assertTrue(result.error instanceof TypeError);
  * ```
  *
  * `createMutableRecord` uses the same TypeScript Record representation.
  *
  * ```ts
- * import { createMutableRecord } from "@evolu/common";
+ * import {
+ *   assertErr,
+ *   assertTrue,
+ *   createMutableRecord,
+ *   trySync,
+ * } from "@evolu/common";
  *
  * const values = createMutableRecord<string, number>();
  *
  * // TypeScript accepts the call, but `toString` is undefined at runtime.
- * expect(() => values.toString()).toThrow(TypeError);
+ * // oxlint-disable-next-line typescript/no-base-to-string -- Intentionally calls a method missing from the null-prototype value.
+ * const result = trySync(() => values.toString());
+ * assertErr(result);
+ * assertTrue(result.error instanceof TypeError);
  * ```
  *
  * In other words, treat the returned object as string-keyed data rather than
@@ -318,7 +384,7 @@ export const emptyRecord: Readonly<Record<string, never>> =
  * ### Example
  *
  * ```ts
- * import { getOwnProp } from "@evolu/common";
+ * import { assertEqual, assertType, getOwnProp } from "@evolu/common";
  *
  * interface User {
  *   readonly name: string;
@@ -329,9 +395,9 @@ export const emptyRecord: Readonly<Record<string, never>> =
  * };
  * const user = getOwnProp(users, "bob");
  *
- * expectTypeOf(user).toEqualTypeOf<User | undefined>();
- * expect(user).toBeUndefined();
- * expect(getOwnProp(users, "toString")).toBeUndefined();
+ * assertType<User | undefined, typeof user>();
+ * assertEqual(user, undefined);
+ * assertEqual(getOwnProp(users, "toString"), undefined);
  * ```
  */
 export const getOwnProp = <K extends string, V>(
@@ -347,12 +413,12 @@ export const getOwnProp = <K extends string, V>(
  * ### Example
  *
  * ```ts
- * import { createObjectURL } from "@evolu/common";
+ * import { assertTrue, createObjectURL } from "@evolu/common";
  *
  * const blob = new Blob(["hello"], { type: "text/plain" });
  * using objectUrl = createObjectURL(blob);
  *
- * expect(objectUrl.url).toMatch(/^blob:/);
+ * assertTrue(objectUrl.url.startsWith("blob:"));
  * // URL.revokeObjectURL is automatically called when the scope ends.
  * ```
  *

package/src/Option.ts

@@ -9,7 +9,16 @@
  * ### Example
  *
  * ```ts
- * import { isNone, isSome, none, type Option, some } from "@evolu/common";
+ * import {
+ *   assert,
+ *   assertSame,
+ *   assertTrue,
+ *   isNone,
+ *   isSome,
+ *   none,
+ *   type Option,
+ *   some,
+ * } from "@evolu/common";
  *
  * const cache = new Map<string, Option<unknown>>();
  *
@@ -19,10 +28,10 @@
  * cache.set("b", some(undefined));
  *
  * const a = get("a");
- * assert(isSome(a));
- * expect(a.value).toBeNull();
- * expect(isSome(get("b"))).toBe(true);
- * expect(isNone(get("c"))).toBe(true);
+ * assert(isSome(a), "Expected Some.");
+ * assertSame(a.value, null);
+ * assertTrue(isSome(get("b")));
+ * assertTrue(isNone(get("c")));
  * ```
  *
  * @module

package/src/Order.ts

@@ -33,12 +33,12 @@ export type Ordering = -1 | 0 | 1;
  * ### Example
  *
  * ```ts
- * import { createOrder } from "@evolu/common";
+ * import { assertEqual, createOrder } from "@evolu/common";
  *
  * const orderNumber = createOrder<number>((x, y) => x < y);
- * expect(orderNumber(1, 2)).toBe(-1);
- * expect(orderNumber(2, 1)).toBe(1);
- * expect(orderNumber(1, 1)).toBe(0);
+ * assertEqual(orderNumber(1, 2), -1);
+ * assertEqual(orderNumber(2, 1), 1);
+ * assertEqual(orderNumber(1, 1), 0);
  * ```
  */
 export const createOrder =
@@ -52,10 +52,10 @@ export const createOrder =
  * ### Example
  *
  * ```ts
- * import { orderNumber, reverseOrder } from "@evolu/common";
+ * import { assertEqual, orderNumber, reverseOrder } from "@evolu/common";
  *
  * const descendingOrderNumber = reverseOrder(orderNumber);
- * expect([3, 1, 2].toSorted(descendingOrderNumber)).toEqual([3, 2, 1]);
+ * assertEqual([3, 1, 2].toSorted(descendingOrderNumber), [3, 2, 1]);
  * ```
  */
 export const reverseOrder =
@@ -69,9 +69,9 @@ export const reverseOrder =
  * ### Example
  *
  * ```ts
- * import { orderString } from "@evolu/common";
+ * import { assertEqual, orderString } from "@evolu/common";
  *
- * expect(["c", "b", "a"].toSorted(orderString)).toEqual(["a", "b", "c"]);
+ * assertEqual(["c", "b", "a"].toSorted(orderString), ["a", "b", "c"]);
  * ```
  */
 export const orderString: Order<string> = /*#__PURE__*/ createOrder(
@@ -84,9 +84,9 @@ export const orderString: Order<string> = /*#__PURE__*/ createOrder(
  * ### Example
  *
  * ```ts
- * import { orderNumber } from "@evolu/common";
+ * import { assertEqual, orderNumber } from "@evolu/common";
  *
- * expect([2, 1, 3].toSorted(orderNumber)).toEqual([1, 2, 3]);
+ * assertEqual([2, 1, 3].toSorted(orderNumber), [1, 2, 3]);
  * ```
  */
 export const orderNumber = /*#__PURE__*/ createOrder<number>((a, b) => a < b);
@@ -97,9 +97,9 @@ export const orderNumber = /*#__PURE__*/ createOrder<number>((a, b) => a < b);
  * ### Example
  *
  * ```ts
- * import { orderBigInt } from "@evolu/common";
+ * import { assertEqual, orderBigInt } from "@evolu/common";
  *
- * expect([2n, 1n, 3n].toSorted(orderBigInt)).toEqual([1n, 2n, 3n]);
+ * assertEqual([2n, 1n, 3n].toSorted(orderBigInt), [1n, 2n, 3n]);
  * ```
  */
 export const orderBigInt = /*#__PURE__*/ createOrder<bigint>((a, b) => a < b);

package/src/Platform.ts

@@ -82,8 +82,8 @@ export interface TestGlobalErrors extends Disposable {
    * 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([])`.
+   * errors are recorded by then. Assert absence with `assertEqual(await
+   * unhandledRejections.settle(), [])`.
    */
   readonly settle: () => Promise<ReadonlyArray<unknown>>;
 }
@@ -176,6 +176,7 @@ const createTestGlobalErrors = (
       globalThis.removeEventListener(webEvent, listener);
     });
   } else {
+    // oxlint-disable-next-line unicorn/prefer-type-error -- An unsupported runtime environment is not an invalid argument type.
     throw new Error(`Unsupported platform global ${errorType} reporting.`);
   }
 

package/src/Random.ts

@@ -23,6 +23,9 @@ export type RandomNumber = number & Brand<"RandomNumber">;
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertTrue,
+ *   assertType,
  *   createRandom,
  *   testCreateRandom,
  *   type RandomNumber,
@@ -31,14 +34,14 @@ export type RandomNumber = number & Brand<"RandomNumber">;
  * // For apps, use the Math.random-backed implementation.
  * const random = createRandom();
  * const value = random.next();
- * expectTypeOf(value).toEqualTypeOf<RandomNumber>();
- * expect(value).toBeGreaterThanOrEqual(0);
- * expect(value).toBeLessThan(1);
+ * assertType<RandomNumber, typeof value>();
+ * assertTrue(value >= 0);
+ * assertTrue(value < 1);
  *
  * // For tests, use a seed.
  * const firstTestRandom = testCreateRandom("test");
  * const secondTestRandom = testCreateRandom("test");
- * expect(firstTestRandom.next()).toBe(secondTestRandom.next());
+ * assertEqual(firstTestRandom.next(), secondTestRandom.next());
  * ```
  */
 export interface Random {

package/src/Redacted.ts

@@ -30,8 +30,11 @@ import type { Eq } from "./Eq.ts";
  *
  * ```ts
  * import {
+ *   assertErr,
+ *   assertEqual,
  *   createRedacted,
  *   revealRedacted,
+ *   trySync,
  *   type Brand,
  *   type Redacted,
  * } from "@evolu/common";
@@ -45,11 +48,13 @@ import type { Eq } from "./Eq.ts";
  * using redactedKey: RedactedApiKey = createRedacted(apiKey);
  * const fetchUser = (key: RedactedApiKey): ApiKey => revealRedacted(key);
  *
- * expect(redactedKey.toString()).toBe("<redacted>");
- * expect(JSON.stringify({ apiKey: redactedKey })).toBe(
+ * // oxlint-disable-next-line typescript/no-base-to-string -- Redacted intentionally implements a safe custom toString.
+ * assertEqual(redactedKey.toString(), "<redacted>");
+ * assertEqual(
+ *   JSON.stringify({ apiKey: redactedKey }),
  *   '{"apiKey":"<redacted>"}',
  * );
- * expect(fetchUser(redactedKey)).toBe(apiKey);
+ * assertEqual(fetchUser(redactedKey), apiKey);
  *
  * using password = createRedacted("password" as DbPassword);
  * // @ts-expect-error Redacted secrets retain their distinct branded types.
@@ -60,7 +65,7 @@ import type { Eq } from "./Eq.ts";
  *   return key;
  * })();
  * // Leaving the `using` scope removes the value from memory.
- * expect(() => revealRedacted(disposedKey)).toThrow();
+ * assertErr(trySync(() => revealRedacted(disposedKey)));
  * ```
  */
 export interface Redacted<A> extends Brand<"Redacted">, Disposable {
@@ -112,6 +117,8 @@ export const isRedacted = (value: unknown): value is Redacted<unknown> =>
  *
  * ```ts
  * import {
+ *   assertFalse,
+ *   assertTrue,
  *   createEqRedacted,
  *   createRedacted,
  *   eqString,
@@ -126,8 +133,8 @@ export const isRedacted = (value: unknown): value is Redacted<unknown> =>
  * using b = createRedacted("x" as ApiKey);
  * using c = createRedacted("y" as ApiKey);
  *
- * expect(eqRedactedApiKey(a, b)).toBe(true);
- * expect(eqRedactedApiKey(a, c)).toBe(false);
+ * assertTrue(eqRedactedApiKey(a, b));
+ * assertFalse(eqRedactedApiKey(a, c));
  * ```
  */
 export const createEqRedacted =

package/src/Ref.ts

@@ -21,18 +21,18 @@ import type { Store } from "./Store.ts";
  * ### Example
  *
  * ```ts
- * import { createRef } from "@evolu/common";
+ * import { assertEqual, createRef } from "@evolu/common";
  *
  * const count = createRef(0);
  * count.set(1);
  * count.update((n) => n + 1);
- * expect(count.get()).toBe(2);
+ * assertEqual(count.get(), 2);
  * ```
  *
  * ### As a dependency
  *
  * ```ts
- * import { createRef, type Ref } from "@evolu/common";
+ * import { assertEqual, createRef, type Ref } from "@evolu/common";
  *
  * interface CounterRefDep {
  *   readonly counterRef: Ref<number>;
@@ -40,7 +40,7 @@ import type { Store } from "./Store.ts";
  *
  * const deps: CounterRefDep = { counterRef: createRef(0) };
  * deps.counterRef.update((count) => count + 1);
- * expect(deps.counterRef.get()).toBe(1);
+ * assertEqual(deps.counterRef.get(), 1);
  * ```
  */
 export interface Ref<T> {

package/src/Relation.ts

@@ -56,7 +56,7 @@ import {
  * Use the default identity semantics.
  *
  * ```ts
- * import { createRelation } from "@evolu/common";
+ * import { assertFalse, assertTrue, createRelation } from "@evolu/common";
  *
  * interface Socket {
  *   readonly id: string;
@@ -67,8 +67,8 @@ import {
  *
  * relation.add(socket, "owner-1");
  *
- * expect(relation.has(socket, "owner-1")).toBe(true);
- * expect(relation.has({ id: "socket-1" }, "owner-1")).toBe(false);
+ * assertTrue(relation.has(socket, "owner-1"));
+ * assertFalse(relation.has({ id: "socket-1" }, "owner-1"));
  * ```
  *
  * ### Lookup-derived equality
@@ -76,7 +76,7 @@ import {
  * Use lookup-derived equality.
  *
  * ```ts
- * import { createRelation } from "@evolu/common";
+ * import { assertTrue, createRelation } from "@evolu/common";
  *
  * interface Person {
  *   readonly id: string;
@@ -90,9 +90,7 @@ import {
  *
  * relation.add({ id: "1", name: "Ada" }, { id: "admins" });
  *
- * expect(relation.has({ id: "1", name: "Grace" }, { id: "admins" })).toBe(
- *   true,
- * );
+ * assertTrue(relation.has({ id: "1", name: "Grace" }, { id: "admins" }));
  * ```
  *
  * @see {@link createRelation}
@@ -250,14 +248,14 @@ export function createRelation<A, B, LA = A, LB = B>({
     removeByA: (a) => {
       const relatedB = bByA.get(a);
       if (!relatedB) return false;
-      for (const b of [...relatedB.keys()]) removePair(a, b);
+      for (const b of relatedB.keys()) removePair(a, b);
       return true;
     },
 
     removeByB: (b) => {
       const relatedA = aByB.get(b);
       if (!relatedA) return false;
-      for (const a of [...relatedA.keys()]) removePair(a, b);
+      for (const a of relatedA.keys()) removePair(a, b);
       return true;
     },
 
@@ -306,7 +304,7 @@ export function createRelation<A, B, LA = A, LB = B>({
 const assertRelationMappingConsistency: (
   condition: unknown,
 ) => asserts condition = (condition) => {
-  assert(condition, "Relation mapping inconsistency");
+  assert(Boolean(condition), "Relation mapping inconsistency");
 };
 
 /**