@evolu/common 8.9.0 → 8.11.0

package/src/Crypto.ts

@@ -24,6 +24,11 @@ import {
   zeroNonNegativeInt,
 } from "./Type.ts";
 
+/**
+ * Cryptographically secure random bytes with length-branded results.
+ *
+ * @group Random bytes
+ */
 export interface RandomBytes {
   /**
    * Creates cryptographically secure random bytes with type-safe length
@@ -77,6 +82,11 @@ export interface RandomBytes {
   create(bytesLength: number): Entropy;
 }
 
+/**
+ * Dependency wrapper for {@link RandomBytes}.
+ *
+ * @group Random bytes
+ */
 export interface RandomBytesDep {
   readonly randomBytes: RandomBytes;
 }
@@ -84,23 +94,53 @@ export interface RandomBytesDep {
 const Entropy = /*#__PURE__*/ brand("Entropy", Uint8Array);
 type Entropy = typeof Entropy.Output;
 
+/**
+ * Cryptographic entropy of exactly 16 bytes.
+ *
+ * @group Random bytes
+ */
 export const Entropy16 = /*#__PURE__*/ length(16)(Entropy);
 export type Entropy16 = typeof Entropy16.Output;
 
+/**
+ * Cryptographic entropy of exactly 24 bytes.
+ *
+ * @group Random bytes
+ */
 export const Entropy24 = /*#__PURE__*/ length(24)(Entropy);
 export type Entropy24 = typeof Entropy24.Output;
 
+/**
+ * Cryptographic entropy of exactly 32 bytes.
+ *
+ * @group Random bytes
+ */
 export const Entropy32 = /*#__PURE__*/ length(32)(Entropy);
 export type Entropy32 = typeof Entropy32.Output;
 
+/**
+ * Cryptographic entropy of exactly 64 bytes.
+ *
+ * @group Random bytes
+ */
 export const Entropy64 = /*#__PURE__*/ length(64)(Entropy);
 export type Entropy64 = typeof Entropy64.Output;
 
+/**
+ * Creates {@link RandomBytes} backed by the platform's secure random number
+ * generator.
+ *
+ * @group Random bytes
+ */
 export const createRandomBytes = (): RandomBytes => ({
   create: randomBytes as RandomBytes["create"],
 });
 
-/** Creates seeded random bytes for deterministic tests. */
+/**
+ * Creates seeded random bytes for deterministic tests.
+ *
+ * @group Testing
+ */
 export const testCreateRandomBytes = (deps: RandomLibDep): RandomBytes =>
   ({
     create: (bytesLength: number) =>
@@ -113,6 +153,8 @@ export const testCreateRandomBytes = (deps: RandomLibDep): RandomBytes =>
  * SLIP21.
  *
  * https://github.com/satoshilabs/slips/blob/master/slip-0021.md
+ *
+ * @group Key derivation
  */
 export const createSlip21 = (
   seed: Entropy16 | Entropy32 | Entropy64,
@@ -135,6 +177,7 @@ export const createSlip21 = (
 /**
  * Derives a single node in the SLIP-21 hierarchical key derivation.
  *
+ * @group Key derivation
  * @see {@link createSlip21}
  */
 export const deriveSlip21Node = (
@@ -148,16 +191,25 @@ export const deriveSlip21Node = (
   return hmac(sha512, parentNode.slice(0, 32), message) as Entropy64;
 };
 
-/** The encryption key for symmetric encryption. */
+/**
+ * The encryption key for symmetric encryption.
+ *
+ * @group Encryption
+ */
 export const EncryptionKey = /*#__PURE__*/ brand("EncryptionKey", Entropy32);
 export type EncryptionKey = typeof EncryptionKey.Output;
 
-/** The nonce length for XChaCha20-Poly1305 encryption. */
+/**
+ * The nonce length for XChaCha20-Poly1305 encryption.
+ *
+ * @group Encryption
+ */
 export const xChaCha20Poly1305NonceLength = 24;
 
 /**
  * Branded Uint8Array for XChaCha20-Poly1305 encryption.
  *
+ * @group Encryption
  * @see {@link encryptWithXChaCha20Poly1305}
  */
 export const XChaCha20Poly1305Ciphertext = /*#__PURE__*/ brand(
@@ -196,6 +248,7 @@ export type XChaCha20Poly1305Ciphertext =
  * assertEqual(nonce.length, 24);
  * ```
  *
+ * @group Encryption
  * @see https://github.com/paulmillr/noble-ciphers
  */
 export const encryptWithXChaCha20Poly1305 =
@@ -211,6 +264,11 @@ export const encryptWithXChaCha20Poly1305 =
     return [ciphertext, nonce];
   };
 
+/**
+ * Error returned by {@link decryptWithXChaCha20Poly1305} when decryption fails.
+ *
+ * @group Encryption
+ */
 export interface DecryptWithXChaCha20Poly1305Error extends Typed<"DecryptWithXChaCha20Poly1305Error"> {
   readonly error: unknown;
 }
@@ -254,6 +312,8 @@ export interface DecryptWithXChaCha20Poly1305Error extends Typed<"DecryptWithXCh
  *
  * assertOk(decryptMessage(), "secret message");
  * ```
+ *
+ * @group Encryption
  */
 export const decryptWithXChaCha20Poly1305 = (
   ciphertext: XChaCha20Poly1305Ciphertext,
@@ -275,6 +335,8 @@ export const decryptWithXChaCha20Poly1305 = (
  * wide range of encrypted data sizes.
  *
  * See the PURBs paper for details: https://bford.info/pub/sec/purb.pdf
+ *
+ * @group Padding
  */
 export const createPadmePaddedLength = (
   length: NonNegativeInt,
@@ -287,7 +349,11 @@ export const createPadmePaddedLength = (
   return NonNegativeInt.orThrow((length + mask) & ~mask);
 };
 
-/** Creates a PADMÉ padding array of zeros for the given input length. */
+/**
+ * Creates a PADMÉ padding array of zeros for the given input length.
+ *
+ * @group Padding
+ */
 export const createPadmePadding = (length: NonNegativeInt): Uint8Array => {
   const paddedLength = createPadmePaddedLength(length);
   const paddingLength = NonNegativeInt.orThrow(paddedLength - length);
@@ -299,10 +365,16 @@ export const createPadmePadding = (length: NonNegativeInt): Uint8Array => {
  * are equal, false otherwise. Takes constant time regardless of where the
  * arrays differ.
  *
+ * @group Comparison
  * @see https://nodejs.org/api/crypto.html#cryptotimingsafeequala-b
  */
 export type TimingSafeEqual = (a: Uint8Array, b: Uint8Array) => boolean;
 
+/**
+ * Dependency wrapper for {@link TimingSafeEqual}.
+ *
+ * @group Comparison
+ */
 export interface TimingSafeEqualDep {
   readonly timingSafeEqual: TimingSafeEqual;
 }

package/src/Eq.test.ts

@@ -293,13 +293,12 @@ test("eqData", () => {
   }
   const service: Service = { run: () => undefined };
   const broadObject: NonNullable<unknown> = new WeakMap();
-  const compileTimeAssertions = () => {
+  void (() => {
     // @ts-expect-error ⛔ eqData error: Actual and expected values must consist only of Data.
     eqData(service, service);
     // @ts-expect-error ⛔ eqData error: Actual and expected values must consist only of Data.
     eqData(broadObject, broadObject);
-  };
-  assertEqual(typeof compileTimeAssertions, "function");
+  });
 });
 
 test("eqData compares deeply nested Set and Map data", () => {

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.test.ts

@@ -0,0 +1,105 @@
+import { describe, it } from "node:test";
+import {
+  assert,
+  assertEqual,
+  assertErr,
+  assertInstanceOf,
+  assertOk,
+  assertSame,
+} from "./Assert.ts";
+import { testCreateFs, type Fs, type FsDep, type FsError } from "./Fs.ts";
+import { err, ok } from "./Result.ts";
+import { AbortError, testCreateRun, type Task } from "./Task.ts";
+import { assertType } from "./Type.ts";
+
+describe("testCreateFs", () => {
+  it("accepts native copy options and rejects the former overwrite option", () => {
+    const fs = testCreateFs();
+    const task = fs.copy("source", "destination", {
+      force: false,
+      errorOnExist: true,
+      preserveTimestamps: true,
+    });
+    assertType<typeof task, Task<void, FsError>>();
+
+    // @ts-expect-error: FsCopyOptions has no overwrite property; use Node's force and errorOnExist options.
+    fs.copy("source", "destination", { overwrite: false });
+  });
+
+  for (const [method, createTask] of [
+    ["readFile", (fs: Fs) => fs.readFile("file.txt")],
+    ["writeFile", (fs: Fs) => fs.writeFile("file.txt", "content")],
+    ["readDirectory", (fs: Fs) => fs.readDirectory("directory")],
+    ["createDirectory", (fs: Fs) => fs.createDirectory("directory")],
+    ["copy", (fs: Fs) => fs.copy("source", "destination")],
+    ["copyFile", (fs: Fs) => fs.copyFile("source", "destination")],
+    ["rename", (fs: Fs) => fs.rename("source", "destination")],
+    ["remove", (fs: Fs) => fs.remove("file.txt")],
+    ["getMetadata", (fs: Fs) => fs.getMetadata("file.txt")],
+    ["exists", (fs: Fs) => fs.exists("file.txt")],
+    ["createTempDirectory", (fs: Fs) => fs.createTempDirectory()],
+  ] as const) {
+    it(`panics when an unconfigured ${method} Task runs`, async () => {
+      const fs = testCreateFs();
+      const task = createTask(fs);
+      await using run = testCreateRun();
+
+      const result = await run.abortable<unknown, FsError>(task);
+
+      assertErr(result);
+      assert(AbortError.is(result.error), "Unexpected Fs calls must abort.");
+      assertEqual(result.error.reason.type, "PanicAbortReason");
+      const { defect } = result.error.reason;
+      assertInstanceOf(defect, Error);
+      assertEqual(defect.message, `Unexpected Fs.${method} call`);
+      assertEqual(run.deps.reportDefect.getDefects(), [result.error]);
+    });
+  }
+
+  it("uses an injected override with the original arguments", async () => {
+    const path = new URL("file:///message.txt");
+    const data = new TextEncoder().encode("hello");
+    const options = { flag: "a" } as const;
+    let calls = 0;
+    const writeFile: Fs["writeFile"] =
+      (receivedPath, receivedData, receivedOptions) => () => {
+        calls += 1;
+        assertSame(receivedPath, path);
+        assertSame(receivedData, data);
+        assertSame(receivedOptions, options);
+        return ok();
+      };
+    const fs = testCreateFs({ writeFile });
+    assertSame(fs.writeFile, writeFile);
+    await using run = testCreateRun({ fs });
+    const saveMessage: Task<void, FsError, FsDep> = (run) =>
+      run(run.deps.fs.writeFile(path, data, options));
+
+    assertEqual(calls, 0);
+    assertOk(await run(saveMessage));
+    assertEqual(calls, 1);
+  });
+
+  it("preserves readFile overloads and injected errors", async () => {
+    const error: FsError = {
+      type: "FsError",
+      reason: "PermissionDenied",
+      path: "protected.txt",
+      syscall: "open",
+      message: "Permission denied",
+    };
+    const fs = testCreateFs({ readFile: () => () => err(error) });
+    await using run = testCreateRun();
+    const bytes = fs.readFile("protected.txt");
+    const text = fs.readFile("protected.txt", "utf8");
+    const encoded = fs.readFile("protected.txt", { encoding: "utf8" });
+    assertType<typeof bytes, Task<Uint8Array, FsError>>();
+    assertType<typeof text, Task<string, FsError>>();
+    assertType<typeof encoded, Task<string, FsError>>();
+
+    assertErr(await run(bytes), error);
+    assertErr(await run(text), error);
+    assertErr(await run(encoded), error);
+    assertEqual(run.deps.reportDefect.getDefects(), []);
+  });
+});