@evolu/common 8.10.0 → 8.11.0

package/src/Error.test.ts

@@ -1,7 +1,15 @@
 import { describe, it } from "node:test";
-import { assertEqual, assertFalse, assertSame, assertTrue } from "./Assert.ts";
-
-import { UnknownError, createUnknownError } from "./Error.ts";
+import { runInNewContext } from "node:vm";
+import {
+  assertEqual,
+  assertFalse,
+  assertInstanceOf,
+  assertSame,
+  assertTrue,
+} from "./Assert.ts";
+
+import { UnknownError, createUnknownError, defectToError } from "./Error.ts";
+import { createRun } from "./Task.ts";
 import { assertType, Object, String } from "./Type.ts";
 
 describe("createUnknownError", () => {
@@ -116,3 +124,68 @@ describe("createUnknownError", () => {
     assertSame(actual.self, actual);
   });
 });
+
+describe("defectToError", () => {
+  it("converts a panic to its Error defect", async () => {
+    const reported: Array<unknown> = [];
+    await using run = createRun({
+      reportDefect: (defect) => {
+        reported.push(defect);
+      },
+    });
+    const defect = new Error("boom");
+
+    run.panic(defect);
+
+    assertSame(defectToError(reported[0]), defect);
+  });
+
+  it("returns an Error from another realm as it is", () => {
+    const defect: unknown = runInNewContext(
+      'new TypeError("other realm failed")',
+    );
+    assertFalse(defect instanceof Error);
+
+    assertSame(defectToError(defect), defect);
+  });
+
+  it("describes a DOMException with its name and message", () => {
+    const defect = new DOMException("dom failed", "NotFoundError");
+
+    const error = defectToError(defect);
+
+    assertEqual(error.message, "NotFoundError: dom failed");
+    assertSame(error.cause, defect);
+  });
+
+  it("describes a panic's defect that is not an Error", async () => {
+    const reported: Array<unknown> = [];
+    await using run = createRun({
+      reportDefect: (defect) => {
+        reported.push(defect);
+      },
+    });
+
+    const abortError = run.panic({ type: "UnexpectedState", count: 1 });
+
+    const error = defectToError(reported[0]);
+    assertInstanceOf(error, Error);
+    assertEqual(error.message, 'Defect: {"type":"UnexpectedState","count":1}');
+    assertSame(error.cause, abortError);
+  });
+
+  it("describes an AbortError that is not a panic", () => {
+    const abortError = {
+      type: "AbortError",
+      reason: { type: "OtherAbortReason" },
+    } as const;
+
+    const error = defectToError(abortError);
+
+    assertEqual(
+      error.message,
+      'Defect: {"type":"AbortError","reason":{"type":"OtherAbortReason"}}',
+    );
+    assertSame(error.cause, abortError);
+  });
+});

package/src/Error.ts

@@ -4,6 +4,8 @@
  * @module
  */
 
+import { safelyStringifyUnknownValue } from "./String.ts";
+import { AbortError, type createRun, type ReportDefect } from "./Task.ts";
 import { type InferType, typed, type TypedType, Unknown } from "./Type.ts";
 
 /**
@@ -84,3 +86,72 @@ export const createUnknownError = (error: unknown): UnknownError => {
     }
   }
 };
+
+/**
+ * Converts a reported defect to an `Error` that a host error reporter shows
+ * readably.
+ *
+ * Hosts such as browsers and React Native show a reported value that is not an
+ * `Error` only as text such as "[object Object]", and a worker's error reaches
+ * its page, including an error tracker listening there, as that text alone. A
+ * panic reports a plain {@link AbortError}, so its defect is converted instead.
+ * An `Error` is returned as it is, including one from another realm, such as an
+ * iframe. A `DOMException` is described in an `Error` with its name and
+ * message, because Chromium reports one from a worker without them. Any other
+ * value is described in an `Error` whose cause is what was reported.
+ *
+ * Platform {@link createRun} adapters use it for their default reporting. A
+ * custom {@link ReportDefect} can use it too, such as before passing a defect to
+ * an error tracker.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   assertSame,
+ *   createRun,
+ *   defectToError,
+ * } from "@evolu/common";
+ *
+ * const errors: Array<Error> = [];
+ * await using run = createRun({
+ *   reportDefect: (reported) => {
+ *     errors.push(defectToError(reported));
+ *   },
+ * });
+ * const defect = new Error("boom");
+ *
+ * run.panic(defect);
+ *
+ * assertSame(errors[0], defect);
+ * assertEqual(
+ *   defectToError({ type: "UnexpectedState" }).message,
+ *   'Defect: {"type":"UnexpectedState"}',
+ * );
+ * ```
+ */
+export const defectToError = (reported: unknown): Error => {
+  const defect =
+    AbortError.is(reported) && reported.reason.type === "PanicAbortReason"
+      ? reported.reason.defect
+      : reported;
+  // The internal tag survives crossing realms, such as from an iframe, where
+  // instanceof fails.
+  const tag = Object.prototype.toString.call(defect);
+  // Chromium reports a DOMException from a worker without its name or message,
+  // so it is described in an Error.
+  if (tag === "[object DOMException]") {
+    const { name, message } = defect as Error;
+    return new Error(`${name}: ${message}`, { cause: defect });
+  }
+  if (defect instanceof Error || tag === "[object Error]") {
+    return defect as Error;
+  }
+  // A value with a cycle or a bigint falls back to String, often
+  // "[object Object]", and a nested Error shows as "{}". That is enough:
+  // Evolu's own defects are Errors, and the cause still holds the value.
+  return new Error(`Defect: ${safelyStringifyUnknownValue(defect)}`, {
+    cause: reported,
+  });
+};

package/src/Fs.ts

@@ -60,7 +60,11 @@ import type { ByteLength } from "./Bytes.ts";
 import type { createRun, Task } from "./Task.ts";
 import type { Typed } from "./Type.ts";
 
-/** Asynchronous file system operations. */
+/**
+ * Asynchronous file system operations.
+ *
+ * @group Core
+ */
 export interface Fs {
   /**
    * Reads a whole file, as bytes by default or as a string with an encoding. An
@@ -163,15 +167,27 @@ export interface Fs {
   ) => Task<FsTempDirectory, FsError>;
 }
 
-/** Dependency wrapper for {@link Fs}. */
+/**
+ * Dependency wrapper for {@link Fs}.
+ *
+ * @group Core
+ */
 export interface FsDep {
   readonly fs: Fs;
 }
 
-/** A file system path, or a `file:` URL. */
+/**
+ * A file system path, or a `file:` URL.
+ *
+ * @group Core
+ */
 export type FsPath = string | URL;
 
-/** Supported text encodings. */
+/**
+ * Supported text encodings.
+ *
+ * @group Core
+ */
 export type FsEncoding =
   | "ascii"
   | "utf8"
@@ -186,7 +202,11 @@ export type FsEncoding =
   | "binary"
   | "hex";
 
-/** Supported file opening modes for {@link Fs.writeFile}. */
+/**
+ * Supported file opening modes for {@link Fs.writeFile}.
+ *
+ * @group Core
+ */
 export type FsOpenFlag =
   | "a"
   | "ax"
@@ -202,7 +222,11 @@ export type FsOpenFlag =
   | "w+"
   | "wx+";
 
-/** Reads bytes by default, or text when an encoding is specified. */
+/**
+ * Reads bytes by default, or text when an encoding is specified.
+ *
+ * @group Core
+ */
 export interface FsReadFile {
   (path: FsPath): Task<Uint8Array, FsError>;
   (
@@ -211,7 +235,11 @@ export interface FsReadFile {
   ): Task<string, FsError>;
 }
 
-/** Options for {@link Fs.writeFile}. */
+/**
+ * Options for {@link Fs.writeFile}.
+ *
+ * @group Options
+ */
 export interface FsWriteFileOptions {
   /** Encoding of string data. Defaults to `utf8`. */
   readonly encoding?: FsEncoding;
@@ -221,13 +249,21 @@ export interface FsWriteFileOptions {
   readonly flag?: FsOpenFlag;
 }
 
-/** Options for {@link Fs.readDirectory}. */
+/**
+ * Options for {@link Fs.readDirectory}.
+ *
+ * @group Options
+ */
 export interface FsReadDirectoryOptions {
   /** Includes entries from nested directories. Defaults to `false`. */
   readonly recursive?: boolean;
 }
 
-/** Options for {@link Fs.createDirectory}. */
+/**
+ * Options for {@link Fs.createDirectory}.
+ *
+ * @group Options
+ */
 export interface FsCreateDirectoryOptions {
   /** Creates missing parents and accepts an existing directory. */
   readonly recursive?: boolean;
@@ -235,7 +271,11 @@ export interface FsCreateDirectoryOptions {
   readonly mode?: number;
 }
 
-/** Options for {@link Fs.copy}. */
+/**
+ * Options for {@link Fs.copy}.
+ *
+ * @group Options
+ */
 export interface FsCopyOptions {
   /**
    * Node's `force` option. Replaces existing files; `false` skips them unless
@@ -253,13 +293,21 @@ export interface FsCopyOptions {
   readonly preserveTimestamps?: boolean;
 }
 
-/** Options for {@link Fs.copyFile}. */
+/**
+ * Options for {@link Fs.copyFile}.
+ *
+ * @group Options
+ */
 export interface FsCopyFileOptions {
   /** Replaces an existing destination file. Defaults to `false`. */
   readonly overwrite?: boolean;
 }
 
-/** Options for {@link Fs.remove}. */
+/**
+ * Options for {@link Fs.remove}.
+ *
+ * @group Options
+ */
 export interface FsRemoveOptions {
   /** Removes directories and their contents. */
   readonly recursive?: boolean;
@@ -277,7 +325,11 @@ export interface FsRemoveOptions {
   readonly retryDelay?: number;
 }
 
-/** File metadata as data, with Node's numeric and timestamp field names. */
+/**
+ * File metadata as data, with Node's numeric and timestamp field names.
+ *
+ * @group Core
+ */
 export interface FsMetadata {
   readonly type: FsEntryType;
   readonly dev: number;
@@ -300,7 +352,11 @@ export interface FsMetadata {
   readonly birthtime: Date;
 }
 
-/** The kind of file system entry described by {@link FsMetadata}. */
+/**
+ * The kind of file system entry described by {@link FsMetadata}.
+ *
+ * @group Core
+ */
 export type FsEntryType =
   | "File"
   | "Directory"
@@ -311,7 +367,11 @@ export type FsEntryType =
   | "Socket"
   | "Unknown";
 
-/** Options for {@link Fs.createTempDirectory}. */
+/**
+ * Options for {@link Fs.createTempDirectory}.
+ *
+ * @group Options
+ */
 export interface FsCreateTempDirectoryOptions {
   /** Existing parent directory. Defaults to the system temporary directory. */
   readonly directory?: string;
@@ -319,12 +379,20 @@ export interface FsCreateTempDirectoryOptions {
   readonly prefix?: string;
 }
 
-/** A temporary directory removed, with its contents, on asynchronous disposal. */
+/**
+ * A temporary directory removed, with its contents, on asynchronous disposal.
+ *
+ * @group Core
+ */
 export interface FsTempDirectory extends AsyncDisposable {
   readonly path: string;
 }
 
-/** A failed file system operation. */
+/**
+ * A failed file system operation.
+ *
+ * @group Errors
+ */
 export interface FsError extends Typed<"FsError"> {
   readonly reason: FsErrorReason;
   /**
@@ -345,7 +413,11 @@ export interface FsError extends Typed<"FsError"> {
   readonly message: string;
 }
 
-/** Why a file system operation failed, mapped from the platform's error code. */
+/**
+ * Why a file system operation failed, mapped from the platform's error code.
+ *
+ * @group Errors
+ */
 export type FsErrorReason =
   | "NotFound"
   | "AlreadyExists"
@@ -392,6 +464,8 @@ export type FsErrorReason =
  *
  * assertOk(await run(saveMessage));
  * ```
+ *
+ * @group Testing
  */
 export const testCreateFs = (overrides: Partial<Fs> = {}): Fs => ({
   readFile: createUnexpectedFsOperation("readFile"),

package/src/Identicon.ts

@@ -37,6 +37,7 @@ export type IdenticonStyle = "github" | "quadrant" | "gradient" | "sutnar";
  *   assertTrue,
  *   createIdFromString,
  *   createIdenticon,
+ *   testTodoId,
  * } from "@evolu/common";
  *
  * const id = createIdFromString("identicon-example");
@@ -47,8 +48,7 @@ export type IdenticonStyle = "github" | "quadrant" | "gradient" | "sutnar";
  * );
  *
  * // Branded IDs work too.
- * const todoId = createIdFromString<"Todo">("todo-1");
- * const todoSvg = createIdenticon(todoId);
+ * const todoSvg = createIdenticon(testTodoId);
  *
  * assertTrue(svg.startsWith("<svg"));
  * assertEqual(new Set([svg, ...alternativeSvgs]).size, 4);

package/src/LeakDetector.ts

@@ -22,6 +22,8 @@ import { constVoid } from "./Function.ts";
  * a warning may come late or, in short-lived processes, never. It is a
  * development canary, not a guarantee. Production uses
  * {@link noopLeakDetector}.
+ *
+ * @group Core
  */
 export interface LeakDetector {
   /**
@@ -38,7 +40,11 @@ export interface LeakDetector {
   readonly untrack: (unregisterToken: object) => void;
 }
 
-/** Describes a tracked handle for {@link LeakDetector.track}. */
+/**
+ * Describes a tracked handle for {@link LeakDetector.track}.
+ *
+ * @group Core
+ */
 export interface Leak {
   /** Handle name used in the warning, for example `"Lease"`. */
   readonly name: string;
@@ -50,6 +56,7 @@ export interface Leak {
 /**
  * Dependency wrapper for {@link LeakDetector}.
  *
+ * @group Core
  * @see {@link LeakDetector}
  */
 export interface LeakDetectorDep {
@@ -61,6 +68,8 @@ export interface LeakDetectorDep {
  *
  * Capturing a stack per track call is too expensive for production; use
  * {@link noopLeakDetector} there.
+ *
+ * @group Core
  */
 export const createLeakDetector = (deps: ConsoleDep): LeakDetector => {
   if (typeof globalThis.FinalizationRegistry !== "function")
@@ -86,7 +95,11 @@ export const createLeakDetector = (deps: ConsoleDep): LeakDetector => {
   };
 };
 
-/** No-op {@link LeakDetector} for production. */
+/**
+ * No-op {@link LeakDetector} for production.
+ *
+ * @group Core
+ */
 export const noopLeakDetector: LeakDetector = {
   track: constVoid,
   untrack: constVoid,
@@ -118,6 +131,7 @@ const reportLeak =
 /**
  * Test {@link LeakDetector} with deterministic collection.
  *
+ * @group Testing
  * @see {@link testCreateLeakDetector}
  */
 export interface TestLeakDetector extends LeakDetector {
@@ -136,13 +150,18 @@ export interface TestLeakDetector extends LeakDetector {
 /**
  * Dependency wrapper for {@link TestLeakDetector}.
  *
+ * @group Testing
  * @see {@link TestLeakDetector}
  */
 export interface TestLeakDetectorDep extends LeakDetectorDep {
   readonly leakDetector: TestLeakDetector;
 }
 
-/** Creates {@link TestLeakDetector}. */
+/**
+ * Creates {@link TestLeakDetector}.
+ *
+ * @group Testing
+ */
 export const testCreateLeakDetector = (deps: ConsoleDep): TestLeakDetector => {
   const trackedLeaksByToken = new Map<object, ReadonlyArray<TrackedLeak>>();
   const report = reportLeak(deps);

package/src/LockManager.ts

@@ -47,6 +47,8 @@ import type { Callback } from "./Types.ts";
  * );
  * assertEqual(result, "example");
  * ```
+ *
+ * @group Core
  */
 
 export interface LockManagerDep {
@@ -65,6 +67,8 @@ export interface LockManagerDep {
  * via internal namespacing, so tests can reuse the same lock names without
  * contending through the global Web Locks. Query results are filtered to that
  * private namespace and returned with the original visible names.
+ *
+ * @group Testing
  */
 export const testCreateLockManager = (
   nativeLockManager: LockManager = navigator.locks,
@@ -119,6 +123,8 @@ export const testCreateLockManager = (
  * Leadership is held until the returned handle is disposed. Once released,
  * another waiting caller may become the next leader. Waiting for leadership is
  * abortable via the calling {@link Task}'s signal.
+ *
+ * @group Leader election
  */
 export const acquireLeaderLock =
   (name: string): Task<AsyncDisposable, never, LockManagerDep> =>
@@ -156,6 +162,8 @@ export const acquireLeaderLock =
  * Leadership is held until the returned handle is disposed. Once released,
  * another waiting caller may become the next leader. Waiting for leadership is
  * abortable by disposing the returned handle.
+ *
+ * @group Leader election
  */
 export const acquireLeaderLockCallback =
   (deps: LockManagerDep) =>

package/src/Object.test.ts

@@ -1,6 +1,12 @@
 import nodeAssert from "node:assert/strict";
 import { describe, it, test } from "node:test";
-import { assertEqual, assertFalse, assertSame, assertTrue } from "./Assert.ts";
+import {
+  assertEqual,
+  assertFalse,
+  assertNonNullable,
+  assertSame,
+  assertTrue,
+} from "./Assert.ts";
 
 import type { Brand } from "./Brand.ts";
 import type { ReadonlyRecord } from "./Object.ts";
@@ -105,6 +111,22 @@ test("isPlainObject", () => {
   assertFalse(isPlainObject(Object.create(partialObjectPrototype)));
 });
 
+test("isPlainObject checks the root markers of Object.prototype", () => {
+  for (const key of ["hasOwnProperty", "isPrototypeOf"]) {
+    const descriptor = Object.getOwnPropertyDescriptor(Object.prototype, key);
+    assertNonNullable(descriptor);
+    Reflect.deleteProperty(Object.prototype, key);
+    try {
+      assertFalse(isPlainObject({}));
+      assertTrue(isPlainObject(Object.create(null)));
+    } finally {
+      // oxlint-disable-next-line eslint/no-extend-native -- Restores the built-in property this test deleted.
+      Object.defineProperty(Object.prototype, key, descriptor);
+    }
+  }
+  assertTrue(isPlainObject({}));
+});
+
 test("isFunction", () => {
   assertTrue(isFunction(() => {}));
   assertTrue(isFunction(function () {}));
@@ -244,13 +266,12 @@ describe("filterObjectKeys", () => {
     >();
     assertEqual(selectedUsers, { u1: 1 });
 
-    const reject = () => {
+    void (() => {
       // @ts-expect-error filterObjectKeys requires an object source.
       filterObjectKeys("text", () => true);
       // @ts-expect-error Selected properties are readonly.
       selected.APP_PORT = "5000";
-    };
-    assertType<typeof reject, () => void>();
+    });
   });
 
   it("preserves descriptors without reading getters", () => {
@@ -360,16 +381,10 @@ test("createMutableRecord", () => {
   assertEqual(source, { name: "Ada" });
   assertSame(Object.getPrototypeOf(copy), null);
 
-  const compileTimeAssertions = () => {
+  void (() => {
     // @ts-expect-error createMutableRecord source must be an object.
     createMutableRecord("Ada");
-  };
-  assertType<
-    typeof compileTimeAssertions extends (...args: Array<never>) => unknown
-      ? true
-      : false,
-    true
-  >();
+  });
 });
 
 test("emptyRecord", () => {

package/src/Object.ts

@@ -87,6 +87,11 @@ export const isPlainObject = (
 
   const prototype = Object.getPrototypeOf(value) as object | null;
   if (prototype === null) return true;
+  // This realm's Object.prototype has an immutable null prototype, so `in`
+  // checks the same own properties as the structural test below, faster.
+  if (prototype === Object.prototype) {
+    return "hasOwnProperty" in prototype && "isPrototypeOf" in prototype;
+  }
   return (
     Object.getPrototypeOf(prototype) === null &&
     Object.hasOwn(prototype, "hasOwnProperty") &&