@evolu/common 8.6.2 → 8.8.0

package/src/Console.ts

@@ -466,19 +466,19 @@ export const createConsole = ({
  *
  * const output = createNativeConsoleOutput();
  *
- * assertType<ConsoleOutput, typeof output>();
+ * assertType<typeof output, ConsoleOutput>();
  * assertEqual(typeof output.write, "function");
  * ```
  */
 export const createNativeConsoleOutput = (): ConsoleOutput => ({
   write: (entry, formatter) => {
     const args = formatter ? formatter(entry) : entry.args;
-    (
-      globalThis.console as unknown as Record<
-        ConsoleMethod,
-        (...args: Array<unknown>) => void
-      >
-    )[entry.method](...args);
+    // oxlint-disable-next-line evolu/no-unnecessary-global-this -- Write to the global object console even if a realm lexical binding shadows it.
+    const nativeConsole = globalThis.console as unknown as Record<
+      ConsoleMethod,
+      (...args: Array<unknown>) => void
+    >;
+    nativeConsole[entry.method](...args);
   },
 });
 
@@ -522,15 +522,7 @@ export const createNativeConsoleOutput = (): ConsoleOutput => ({
  * assertType(Data, nested);
  * assertEqual(nested, ["+1.500s [relay] [db]", "opened"]);
  *
- * const localTimestamp = new globalThis.Date(
- *   2026,
- *   0,
- *   28,
- *   14,
- *   30,
- *   15,
- *   123,
- * ).getTime();
+ * const localTimestamp = new Date(2026, 0, 28, 14, 30, 15, 123).getTime();
  * const formatAbsolute = createConsoleFormatter({
  *   time: testCreateTime({ startAt: Millis.orThrow(localTimestamp) }),
  * })({ timestampFormat: "absolute" });
@@ -561,7 +553,7 @@ export const createConsoleFormatter =
           timestamp = formatMillisAsClockTime(now);
           break;
         case "iso":
-          timestamp = new globalThis.Date(now).toISOString();
+          timestamp = new Date(now).toISOString();
           break;
       }
 

package/src/Crypto.test.ts

@@ -0,0 +1,138 @@
+import { test } from "node:test";
+import { assertEqual, assertErr, assertSame } from "./Assert.ts";
+import { bytesToHex, utf8ToBytes } from "@noble/ciphers/utils.js";
+
+import {
+  createPadmePaddedLength,
+  createPadmePadding,
+  createRandomBytes,
+  createSlip21,
+  decryptWithXChaCha20Poly1305,
+  encryptWithXChaCha20Poly1305,
+  XChaCha20Poly1305Ciphertext,
+} from "./Crypto.ts";
+import { mnemonicToOwnerSecret } from "./index.ts";
+import { ok } from "./Result.ts";
+import { testCreateDeps } from "./Task.ts";
+import { Mnemonic, NonNegativeInt } from "./Type.ts";
+import { testAppOwner } from "./local-first/Owner.ts";
+
+test("encryptWithXChaCha20Poly1305 / decryptWithXChaCha20Poly1305", () => {
+  const deps = testCreateDeps();
+  const plaintext = utf8ToBytes("Hello, world!");
+  const encryptionKey = testAppOwner.encryptionKey;
+
+  const [ciphertext, nonce] = encryptWithXChaCha20Poly1305(deps)(
+    plaintext,
+    encryptionKey,
+  );
+
+  assertEqual(
+    decryptWithXChaCha20Poly1305(ciphertext, nonce, encryptionKey),
+    ok(plaintext),
+  );
+
+  const result = decryptWithXChaCha20Poly1305(
+    XChaCha20Poly1305Ciphertext.orThrow(new Uint8Array([1, 2, 3])),
+    nonce,
+    encryptionKey,
+  );
+  assertErr(result);
+  assertEqual(result.error.type, "DecryptWithXChaCha20Poly1305Error");
+});
+
+test("createPadmePaddedLength", () => {
+  [
+    [0, 0],
+    [1, 1],
+    [2, 2],
+    [3, 3],
+    [4, 4],
+    [8, 8],
+    [9, 10],
+    [15, 16],
+    [16, 16],
+    [17, 18],
+    [31, 32],
+    [32, 32],
+    [33, 36],
+    [64, 64],
+    [65, 72],
+    [100, 104],
+    [128, 128],
+    [129, 144],
+    [200, 208],
+    [256, 256],
+    [300, 304],
+    [512, 512],
+    [1000, 1024],
+    [1024, 1024],
+    [2048, 2048],
+    [4096, 4096],
+    [10000, 10240],
+    [65536, 65536],
+    [100000, 100352],
+    [1048576, 1048576],
+  ].forEach(([input, expected]) => {
+    assertSame(createPadmePaddedLength(input as NonNegativeInt), expected);
+    assertSame(
+      createPadmePadding(input as NonNegativeInt).length,
+      expected - input,
+    );
+  });
+});
+
+test("createSlip21", () => {
+  const mnemonic = Mnemonic.orThrow(
+    "all all all all all all all all all all all all",
+  );
+  const ownerSecret = mnemonicToOwnerSecret(mnemonic);
+
+  const ownerId = createSlip21(ownerSecret, ["Evolu", "Owner Id"]);
+  assertEqual(
+    bytesToHex(ownerId),
+    "bce9b26dad1a3364c105eb65e7aef032fdffd53816819ac4664442c4a915327f",
+  );
+
+  const encryptionKey = createSlip21(ownerSecret, ["Evolu", "Encryption Key"]);
+  assertEqual(
+    bytesToHex(encryptionKey),
+    "abf2095887bc74adda889a572e29a407a457a39bfdd4202d34ee6eac5c28effc",
+  );
+});
+
+test("createSlip21 normalizes numeric path elements", () => {
+  const mnemonic = Mnemonic.orThrow(
+    "all all all all all all all all all all all all",
+  );
+  const ownerSecret = mnemonicToOwnerSecret(mnemonic);
+
+  const withNumber = createSlip21(ownerSecret, ["Evolu", 0]);
+  const withString = createSlip21(ownerSecret, ["Evolu", "0"]);
+
+  assertSame(bytesToHex(withNumber), bytesToHex(withString));
+});
+
+/**
+ * This test demonstrates createRandomBytes performance, which is used for
+ * createId and is fast enough: ~0.0014ms per call on Apple M1.
+ */
+test.skip("createRandomBytes generates unique values", () => {
+  const randomBytes = createRandomBytes();
+  const values = new Set<string>();
+  const iterations = 10_000;
+
+  const start = performance.now();
+  for (let i = 0; i < iterations; i++) {
+    values.add(bytesToHex(randomBytes.create(16)));
+  }
+  const end = performance.now();
+
+  // ~14ms on Apple M1
+  // oxlint-disable-next-line eslint/no-console
+  console.log(
+    `createRandomBytes: ${iterations} in ${(end - start).toFixed(2)}ms`,
+  );
+
+  assertSame(values.size, iterations);
+});

package/src/Crypto.ts

@@ -63,10 +63,10 @@ export interface RandomBytes {
    * const seed = randomBytes.create(64);
    * const custom = randomBytes.create(48);
    *
-   * assertType<Entropy16, typeof nonce16>();
-   * assertType<Entropy24, typeof nonce24>();
-   * assertType<Entropy32, typeof key>();
-   * assertType<Entropy64, typeof seed>();
+   * assertType<typeof nonce16, Entropy16>();
+   * assertType<typeof nonce24, Entropy24>();
+   * assertType<typeof key, Entropy32>();
+   * assertType<typeof seed, Entropy64>();
    * assertEqual(custom.length, 48);
    * ```
    */
@@ -192,7 +192,7 @@ export type XChaCha20Poly1305Ciphertext =
  *   randomBytes: createRandomBytes(),
  * })(plaintext, encryptionKey);
  *
- * assertType<XChaCha20Poly1305Ciphertext, typeof ciphertext>();
+ * assertType<typeof ciphertext, XChaCha20Poly1305Ciphertext>();
  * assertEqual(nonce.length, 24);
  * ```
  *

package/src/Eq.test.ts

@@ -0,0 +1,333 @@
+import { test } from "node:test";
+import { assertEqual, assertFalse, assertSame, assertTrue } from "./Assert.ts";
+
+import {
+  createEqArrayLike,
+  createEqObject,
+  eqArrayNumber,
+  eqArraySameValue,
+  eqData,
+  eqFromOrder,
+  eqNumber,
+  eqSameValue,
+  eqSameValueZero,
+  eqUint8Array,
+  type Eq,
+} from "./Eq.ts";
+import { orderNumber } from "./Order.ts";
+import { assertType, type Data } from "./Type.ts";
+
+test("eqSameValue", () => {
+  assertTrue(eqSameValue(1, 1));
+  assertTrue(eqSameValue(NaN, NaN));
+  assertFalse(eqSameValue(0, -0));
+
+  const object = {};
+  assertTrue(eqSameValue(object, object));
+  assertFalse(eqSameValue({}, {}));
+});
+
+test("eqSameValueZero", () => {
+  assertTrue(eqSameValueZero(NaN, NaN));
+  assertTrue(eqSameValueZero(0, -0));
+  assertFalse(eqSameValueZero(1, 2));
+
+  const object = {};
+  assertTrue(eqSameValueZero(object, object));
+  assertFalse(eqSameValueZero({}, {}));
+});
+
+test("eqNumber", () => {
+  assertTrue(eqNumber(NaN, NaN));
+  assertFalse(eqNumber(0, -0));
+});
+
+test("eqFromOrder", () => {
+  const eqNumberFromOrder = eqFromOrder(orderNumber);
+  assertTrue(eqNumberFromOrder(1, 1));
+  assertFalse(eqNumberFromOrder(1, 2));
+});
+
+test("createEqArrayLike", () => {
+  const eqArrayNumberFromEq = createEqArrayLike(eqNumber);
+  const array = [1, 2, 3];
+  assertTrue(eqArrayNumberFromEq(array, array));
+  assertFalse(eqArrayNumberFromEq([1, 2, 3], [1, 2]));
+  assertTrue(eqArrayNumberFromEq([1, 2, 3], [1, 2, 3]));
+  assertFalse(eqArrayNumberFromEq([1, 2, 3], [1, 2, 4]));
+});
+
+test("eqArraySameValue", () => {
+  assertTrue(eqArraySameValue([NaN], [NaN]));
+  assertFalse(eqArraySameValue([0], [-0]));
+
+  const object = {};
+  assertTrue(eqArraySameValue([object], [object]));
+  assertFalse(eqArraySameValue([{}], [{}]));
+});
+
+test("eqUint8Array", () => {
+  assertType<typeof eqUint8Array, Eq<Uint8Array>>();
+  assertSame(eqUint8Array, eqArrayNumber);
+  assertTrue(eqUint8Array(new Uint8Array([1, 2]), new Uint8Array([1, 2])));
+  assertFalse(eqUint8Array(new Uint8Array([1, 2]), new Uint8Array([1, 3])));
+  assertFalse(eqUint8Array(new Uint8Array([1]), new Uint8Array([1, 2])));
+});
+
+test("createEqObject", () => {
+  const eqObjectNumber = createEqObject({ a: eqNumber });
+  const object = { a: 1 };
+  assertTrue(eqObjectNumber(object, object));
+  assertTrue(eqObjectNumber({ a: 1 }, { a: 1 }));
+  assertFalse(eqObjectNumber({ a: 1 }, { a: 2 }));
+});
+
+test("eqData", () => {
+  const unsafeEqData = eqData as unknown as (
+    actual: unknown,
+    expected: unknown,
+  ) => boolean;
+  const emptyData: Data = {};
+
+  assertTrue(eqData(NaN, NaN));
+  assertFalse(eqData(0, -0));
+  assertFalse(eqData({ value: 0 }, { value: -0 }));
+  assertFalse(eqData(1, 2));
+  assertFalse(eqData(1, "1"));
+  assertFalse(eqData(null, emptyData));
+  assertTrue(eqData(1n, 1n));
+
+  const sameReference = { value: 1 };
+  assertTrue(eqData(sameReference, sameReference));
+  assertTrue(eqData({ a: 1, b: 2 }, { b: 2, a: 1 }));
+  assertFalse(eqData({ a: 1 }, { a: 2 }));
+  assertFalse(eqData({ a: 1 }, { b: 1 }));
+  assertFalse(eqData(emptyData, { value: undefined }));
+
+  const nullPrototype = Object.assign(Object.create(null) as object, {
+    value: 1,
+  });
+  assertTrue(eqData({ value: 1 }, nullPrototype));
+
+  assertTrue(eqData([1, 2], [1, 2]));
+  assertFalse(eqData([1, 2], [2, 1]));
+  assertFalse(eqData([1], [1, 2]));
+  assertFalse(eqData([1], { 0: 1 }));
+
+  assertTrue(eqData(new Date(0), new Date(0)));
+  assertFalse(eqData(new Date(0), new Date(1)));
+  assertFalse(eqData(new Date(0), emptyData));
+
+  assertTrue(eqData(new Uint8Array([1, 2]), new Uint8Array([1, 2])));
+  assertFalse(eqData(new Uint8Array([1, 2]), new Uint8Array([1, 3])));
+  assertFalse(eqData(new Uint8Array([1]), new Uint8Array([1, 2])));
+
+  assertFalse(unsafeEqData(new ArrayBuffer(1), new ArrayBuffer(1)));
+
+  assertTrue(eqData(new Set([1, 2]), new Set([2, 1])));
+  assertTrue(
+    eqData(
+      new Set([{ value: 1 }, { value: 2 }]),
+      new Set([{ value: 2 }, { value: 1 }]),
+    ),
+  );
+  assertFalse(eqData(new Set([{ value: 1 }]), new Set([{ value: 2 }])));
+  assertFalse(eqData(new Set([1]), new Set([1, 2])));
+
+  assertFalse(
+    unsafeEqData(
+      Object.assign(new Set([1]), { metadata: true }),
+      Object.assign(new Set([1]), { metadata: true }),
+    ),
+  );
+
+  assertTrue(
+    eqData(
+      new Map<Data, Data>([[{ id: 1 }, { name: "Ada" }]]),
+      new Map<Data, Data>([[{ id: 1 }, { name: "Ada" }]]),
+    ),
+  );
+  assertTrue(
+    eqData(
+      new Map<Data, Data>([
+        [1, "one"],
+        [2, "two"],
+      ]),
+      new Map<Data, Data>([
+        [2, "two"],
+        [1, "one"],
+      ]),
+    ),
+  );
+  assertFalse(eqData(new Map([[1, "one"]]), new Map([[1, "two"]])));
+  assertFalse(eqData(new Map([[1, "one"]]), new Map([[2, "one"]])));
+  assertFalse(eqData(new Map([[1, "one"]]), new Map<number, string>()));
+  assertTrue(
+    eqData(
+      new Map<Data, Data>([
+        [{ id: 1 }, "one"],
+        [{ id: 1 }, "two"],
+      ]),
+      new Map<Data, Data>([
+        [{ id: 1 }, "two"],
+        [{ id: 1 }, "one"],
+      ]),
+    ),
+  );
+
+  assertFalse(
+    unsafeEqData(
+      Object.assign(new Map([[1, "one"]]), { metadata: true }),
+      Object.assign(new Map([[1, "one"]]), { metadata: true }),
+    ),
+  );
+
+  const sparse: Array<undefined> = [];
+  sparse.length = 1;
+  assertFalse(unsafeEqData(sparse, [undefined]));
+
+  const arrayAccessor: Array<number> = [];
+  Object.defineProperty(arrayAccessor, 0, {
+    enumerable: true,
+    get: () => 1,
+  });
+  arrayAccessor.length = 1;
+  assertFalse(unsafeEqData(arrayAccessor, [1]));
+
+  let reads = 0;
+  const accessor = Object.defineProperty({}, "value", {
+    enumerable: true,
+    get: () => {
+      reads++;
+      return 1;
+    },
+  });
+  assertFalse(unsafeEqData(accessor, { value: 1 }));
+  assertEqual(reads, 0);
+  assertFalse(
+    unsafeEqData(
+      Object.defineProperty({}, "hidden", { value: 1 }),
+      Object.defineProperty({}, "hidden", { value: 1 }),
+    ),
+  );
+  const symbolKey = Symbol("value");
+  assertFalse(unsafeEqData({ [symbolKey]: 1 }, { [symbolKey]: 1 }));
+  assertFalse(unsafeEqData([1], Object.assign([1], { extra: true })));
+
+  class Model {
+    readonly value = 1;
+  }
+  assertFalse(unsafeEqData(new Model(), new Model()));
+  class NullBase extends null {}
+  const nullBasePrototype = NullBase.prototype;
+  assertFalse(
+    unsafeEqData(
+      Object.create(nullBasePrototype),
+      Object.create(nullBasePrototype),
+    ),
+  );
+  assertFalse(unsafeEqData(/value/u, /value/u));
+
+  interface CircularData {
+    readonly value: number;
+    self?: CircularData;
+  }
+  const circularOne: CircularData = { value: 1 };
+  circularOne.self = circularOne;
+  const circularTwo: CircularData = { value: 1 };
+  circularTwo.self = circularTwo;
+  assertTrue(eqData(circularOne, circularTwo));
+
+  const circularDifferent: CircularData = { value: 2 };
+  circularDifferent.self = circularDifferent;
+  assertFalse(eqData(circularOne, circularDifferent));
+
+  const circularSetOne = new Set<Data>();
+  circularSetOne.add(circularSetOne);
+  const circularSetTwo = new Set<Data>();
+  circularSetTwo.add(circularSetTwo);
+  assertTrue(eqData(circularSetOne, circularSetTwo));
+
+  const backtrackingSetOne = new Set<Data>();
+  backtrackingSetOne.add(backtrackingSetOne);
+  backtrackingSetOne.add({ value: 1 });
+  const backtrackingSetTwo = new Set<Data>();
+  backtrackingSetTwo.add({ value: 1 });
+  backtrackingSetTwo.add(backtrackingSetTwo);
+  assertTrue(eqData(backtrackingSetOne, backtrackingSetTwo));
+
+  const circularMapOne = new Map<Data, Data>();
+  circularMapOne.set(circularMapOne, circularSetOne);
+  const circularMapTwo = new Map<Data, Data>();
+  circularMapTwo.set(circularMapTwo, circularSetTwo);
+  assertTrue(eqData(circularMapOne, circularMapTwo));
+
+  const shared: { readonly value?: number } = {};
+  const otherEmptyData: Data = {};
+  assertTrue(
+    eqData(
+      { first: shared, second: shared },
+      { first: emptyData, second: otherEmptyData },
+    ),
+  );
+
+  interface DeepData {
+    next?: DeepData;
+  }
+  const deepOne: DeepData = {};
+  const deepTwo: DeepData = {};
+  let currentOne = deepOne;
+  let currentTwo = deepTwo;
+  for (let index = 0; index < 10_000; index++) {
+    const nextOne: DeepData = {};
+    const nextTwo: DeepData = {};
+    currentOne.next = nextOne;
+    currentTwo.next = nextTwo;
+    currentOne = nextOne;
+    currentTwo = nextTwo;
+  }
+  assertTrue(eqData(deepOne, deepTwo));
+
+  interface Service {
+    readonly run: () => void;
+  }
+  const service: Service = { run: () => undefined };
+  const broadObject: NonNullable<unknown> = new WeakMap();
+  const compileTimeAssertions = () => {
+    // @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", () => {
+  type Shape = "Set" | "MapKey" | "MapValue" | "Mixed";
+
+  const setupNestedData = (shape: Shape, leaf: Data): Data => {
+    let value = leaf;
+
+    for (let index = 0; index < 10_000; index++) {
+      const currentShape =
+        shape === "Mixed" ? (index % 2 === 0 ? "Set" : "MapValue") : shape;
+
+      if (currentShape === "Set") {
+        value = new Set([value]);
+      } else if (currentShape === "MapKey") {
+        value = new Map([[value, null]]);
+      } else {
+        value = new Map([[null, value]]);
+      }
+    }
+
+    return value;
+  };
+
+  for (const shape of ["Set", "MapKey", "MapValue", "Mixed"] as const) {
+    const actual = setupNestedData(shape, 0);
+
+    assertTrue(eqData(actual, setupNestedData(shape, 0)));
+    assertFalse(eqData(actual, setupNestedData(shape, 1)));
+  }
+});