@evolu/common 8.7.0 → 8.9.0

package/src/Option.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, test } from "node:test";
+import { assertEqual, assertSame, assertTrue } from "./Assert.ts";
+
+import {
+  fromNullable,
+  type InferOption,
+  isNone,
+  isSome,
+  none,
+  type None,
+  type Option,
+  some,
+  type Some,
+} from "./Option.ts";
+import { assertType } from "./Type.ts";
+
+test("some creates Some", () => {
+  assertEqual(some(42), { type: "Some", value: 42 });
+});
+
+test("none is None", () => {
+  assertEqual(none, { type: "None" });
+});
+
+test("isSome narrows type", () => {
+  const option: Option<string> = some("test");
+  if (isSome(option)) {
+    assertType<typeof option, Some<string>>();
+    assertType<typeof option.value, string>();
+  }
+});
+
+test("isNone narrows type", () => {
+  const option: Option<string> = none;
+  if (isNone(option)) {
+    assertType<typeof option, None>();
+  }
+});
+
+test("fromNullable maps null and undefined to none", () => {
+  assertTrue(isNone(fromNullable(null)));
+  assertTrue(isNone(fromNullable(undefined)));
+  {
+    const actual = fromNullable(null);
+    assertType<typeof actual, Option<never>>();
+  }
+});
+
+test("fromNullable maps values to some", () => {
+  const option = fromNullable("value");
+
+  assertEqual(option, some("value"));
+});
+
+test("fromNullable strips null and undefined from type", () => {
+  const value: string | null | undefined = "test";
+  const option = fromNullable(value);
+  assertType<typeof option, Option<string>>();
+});
+
+describe("InferOption", () => {
+  it("extracts value type from Option", () => {
+    type MyOption = Option<string>;
+    assertType<InferOption<MyOption>, string>();
+  });
+
+  it("extracts value type from Some", () => {
+    type MySome = Some<number>;
+    assertType<InferOption<MySome>, number>();
+  });
+
+  it("returns never for None", () => {
+    assertType<InferOption<None>, never>();
+  });
+
+  it("works at runtime", () => {
+    type MyOption = Option<string>;
+    const value: InferOption<MyOption> = "hello";
+    assertEqual(value, "hello");
+  });
+});
+
+describe("examples", () => {
+  it("cache that can store null and undefined", () => {
+    const cache = new Map<string, Option<unknown>>();
+
+    const get = (key: string): Option<unknown> => cache.get(key) ?? none;
+
+    cache.set("a", some(null));
+    cache.set("b", some(undefined));
+
+    assertTrue(isSome(get("a")));
+    assertTrue(isSome(get("b")));
+    assertTrue(isNone(get("c")));
+
+    const a = get("a");
+    assertTrue(isSome(a));
+    assertSame(a.value, null);
+
+    const b = get("b");
+    assertTrue(isSome(b));
+    assertSame(b.value, undefined);
+  });
+});

package/src/Option.ts

@@ -10,7 +10,6 @@
  *
  * ```ts
  * import {
- *   assert,
  *   assertSame,
  *   assertTrue,
  *   isNone,
@@ -28,7 +27,7 @@
  * cache.set("b", some(undefined));
  *
  * const a = get("a");
- * assert(isSome(a), "Expected Some.");
+ * assertTrue(isSome(a));
  * assertSame(a.value, null);
  * assertTrue(isSome(get("b")));
  * assertTrue(isNone(get("c")));

package/src/Order.test.ts

@@ -0,0 +1,56 @@
+import { test } from "node:test";
+import { assertEqual } from "./Assert.ts";
+
+import {
+  createOrder,
+  orderBigInt,
+  orderNumber,
+  orderString,
+  orderUint8Array,
+  reverseOrder,
+} from "./Order.ts";
+
+test("createOrder", () => {
+  const orderNumber = createOrder<number>((x, y) => x < y);
+  assertEqual(orderNumber(1, 2), -1);
+  assertEqual(orderNumber(2, 1), 1);
+  assertEqual(orderNumber(1, 1), 0);
+
+  const orderString = createOrder<string>((x, y) => x.localeCompare(y) < 0);
+  assertEqual(orderString("a", "b"), -1);
+  assertEqual(orderString("b", "a"), 1);
+  assertEqual(orderString("a", "a"), 0);
+});
+
+test("reverseOrder", () => {
+  const orderNumberDesc = reverseOrder(orderNumber);
+  assertEqual([2, 1, 3].toSorted(orderNumberDesc), [3, 2, 1]);
+});
+
+test("orderString", () => {
+  assertEqual(["b", "a", "c"].toSorted(orderString), ["a", "b", "c"]);
+});
+
+test("orderNumber", () => {
+  assertEqual([2, 1, 3].toSorted(orderNumber), [1, 2, 3]);
+});
+
+test("orderBigInt", () => {
+  assertEqual([2n, 1n, 3n].toSorted(orderBigInt), [1n, 2n, 3n]);
+});
+
+test("orderUint8Array", () => {
+  const a = new Uint8Array([0x01, 0x02, 0x03]);
+  const b = new Uint8Array([0x01, 0x02, 0x04]);
+  const c = new Uint8Array([0x01, 0x02, 0x03]);
+  // shorter
+  const d = new Uint8Array([0x01, 0x02]);
+  // longer
+  const e = new Uint8Array([0x01, 0x02, 0x03, 0x00]);
+
+  assertEqual(orderUint8Array(a, b), -1);
+  assertEqual(orderUint8Array(b, a), 1);
+  assertEqual(orderUint8Array(a, c), 0);
+  assertEqual(orderUint8Array(a, d), 1);
+  assertEqual(orderUint8Array(a, e), -1);
+});

package/src/Platform.ts

@@ -171,8 +171,10 @@ const createTestGlobalErrors = (
       record((event as Record<typeof webErrorKey, unknown>)[webErrorKey]);
     };
 
+    // oxlint-disable-next-line evolu/no-unnecessary-global-this -- Call the same global object event API verified by the feature check.
     globalThis.addEventListener(webEvent, listener);
     disposableStack.defer(() => {
+      // oxlint-disable-next-line evolu/no-unnecessary-global-this -- Remove the listener through the same global object event API used to add it.
       globalThis.removeEventListener(webEvent, listener);
     });
   } else {

package/src/Polyfills.ts

@@ -16,6 +16,12 @@
  *   `Map.prototype.getOrInsertComputed`, `WeakMap.prototype.getOrInsert`, and
  *   `WeakMap.prototype.getOrInsertComputed`) for Node 24 and React Native
  *
+ * The polyfills are implemented directly in the Evolu Library instead of being
+ * third-party runtime dependencies. We audit their behavior against
+ * specifications, conformance tests, and native implementations, and fix issues
+ * when necessary. This lets Evolu understand and control every line of this
+ * runtime code.
+ *
  * `@evolu/react-native` has its own `Polyfills` module and its
  * `installPolyfills` calls this function first, then installs React Native
  * specific polyfills.
@@ -125,6 +131,7 @@ const appendDisposeError = (
   currentError: unknown,
   previousError: unknown,
 ): unknown =>
+  // oxlint-disable-next-line evolu/no-unnecessary-global-this -- Use the constructor installed on the global object even if a realm lexical binding shadows it.
   new globalThis.SuppressedError(
     currentError,
     previousError,
@@ -158,6 +165,7 @@ const getOrInstallSymbol = (
   key: "dispose" | "asyncDispose",
   description: string,
 ): symbol => {
+  // oxlint-disable-next-line evolu/no-unnecessary-global-this -- Patch the global object constructor even if a realm lexical binding shadows it.
   const SymbolCtor = globalThis.Symbol as SymbolWithDisposable;
   const installedValue = Object.getOwnPropertyDescriptor(SymbolCtor, key)
     ?.value as unknown;
@@ -178,10 +186,7 @@ const getOrInstallSymbol = (
 const installSuppressedError = (): void => {
   if (typeof globalThis.SuppressedError === "function") return;
 
-  class SuppressedErrorPolyfill
-    extends Error
-    implements globalThis.SuppressedError
-  {
+  class SuppressedErrorPolyfill extends Error implements SuppressedError {
     readonly error: unknown;
     readonly suppressed: unknown;
 

package/src/Random.test.ts

@@ -0,0 +1,89 @@
+import { afterEach, describe, it, mock } from "node:test";
+import { assertEqual } from "./Assert.ts";
+
+const randomLibConstructor = mock.fn<(seed?: string) => void>();
+const randomLibNext = mock.fn<() => number>();
+
+mock.module("random", {
+  // @ts-expect-error -- Node.js 24.20 replaces the deprecated namedExports option with exports, which @types/node 24.13 does not declare yet.
+  exports: {
+    Random: class {
+      next = randomLibNext;
+
+      constructor(seed?: string) {
+        if (seed === undefined) randomLibConstructor();
+        else randomLibConstructor(seed);
+      }
+    },
+  },
+});
+
+const { createRandom, createRandomLib, testCreateRandom, testCreateRandomLib } =
+  await import("./Random.ts");
+
+describe("Random", () => {
+  afterEach(() => {
+    mock.restoreAll();
+    randomLibConstructor.mock.resetCalls();
+    randomLibNext.mock.resetCalls();
+  });
+
+  it("createRandom delegates to Math.random", () => {
+    const mathRandom = mock.method(Math, "random", () => 0.25);
+
+    assertEqual(createRandom().next(), 0.25);
+    assertEqual(mathRandom.mock.callCount(), 1);
+  });
+
+  it("testCreateRandom constructs RandomLib with the default seed", () => {
+    testCreateRandom();
+
+    assertEqual(
+      randomLibConstructor.mock.calls.map(({ arguments: args }) => args),
+      [["evolu"]],
+    );
+  });
+
+  it("testCreateRandom constructs RandomLib with a custom seed", () => {
+    testCreateRandom("test");
+
+    assertEqual(
+      randomLibConstructor.mock.calls.map(({ arguments: args }) => args),
+      [["test"]],
+    );
+  });
+
+  it("testCreateRandom delegates next to RandomLib", () => {
+    randomLibNext.mock.mockImplementation(() => 0.25);
+
+    assertEqual(testCreateRandom().next(), 0.25);
+    assertEqual(randomLibNext.mock.callCount(), 1);
+  });
+
+  it("createRandomLib constructs RandomLib without a seed", () => {
+    createRandomLib();
+
+    assertEqual(
+      randomLibConstructor.mock.calls.map(({ arguments: args }) => args),
+      [[]],
+    );
+  });
+
+  it("testCreateRandomLib constructs RandomLib with the default seed", () => {
+    testCreateRandomLib();
+
+    assertEqual(
+      randomLibConstructor.mock.calls.map(({ arguments: args }) => args),
+      [["evolu"]],
+    );
+  });
+
+  it("testCreateRandomLib constructs RandomLib with a custom seed", () => {
+    testCreateRandomLib("test");
+
+    assertEqual(
+      randomLibConstructor.mock.calls.map(({ arguments: args }) => args),
+      [["test"]],
+    );
+  });
+});

package/src/Random.ts

@@ -34,7 +34,7 @@ export type RandomNumber = number & Brand<"RandomNumber">;
  * // For apps, use the Math.random-backed implementation.
  * const random = createRandom();
  * const value = random.next();
- * assertType<RandomNumber, typeof value>();
+ * assertType<typeof value, RandomNumber>();
  * assertTrue(value >= 0);
  * assertTrue(value < 1);
  *

package/src/Ref.test.ts

@@ -0,0 +1,139 @@
+import { describe, it } from "node:test";
+import { assertEqual } from "./Assert.ts";
+
+import { createRef } from "./Ref.ts";
+
+describe("Ref", () => {
+  describe("get", () => {
+    it("returns initial value", () => {
+      const ref = createRef(42);
+      assertEqual(ref.get(), 42);
+    });
+  });
+
+  describe("set", () => {
+    it("updates value", () => {
+      const ref = createRef(0);
+      ref.set(1);
+      assertEqual(ref.get(), 1);
+    });
+
+    it("accepts a value equal to the current value", () => {
+      const ref = createRef(1);
+      ref.set(1);
+      assertEqual(ref.get(), 1);
+    });
+  });
+
+  describe("getAndSet", () => {
+    it("returns previous value and updates value", () => {
+      const ref = createRef(1);
+
+      assertEqual(ref.getAndSet(2), 1);
+      assertEqual(ref.get(), 2);
+    });
+
+    it("accepts a value equal to the current value", () => {
+      const ref = createRef(1);
+
+      assertEqual(ref.getAndSet(1), 1);
+      assertEqual(ref.get(), 1);
+    });
+  });
+
+  describe("setAndGet", () => {
+    it("returns updated value", () => {
+      const ref = createRef(1);
+
+      assertEqual(ref.setAndGet(2), 2);
+      assertEqual(ref.get(), 2);
+    });
+
+    it("accepts a value equal to the current value", () => {
+      const ref = createRef(1);
+
+      assertEqual(ref.setAndGet(1), 1);
+      assertEqual(ref.get(), 1);
+    });
+  });
+
+  describe("update", () => {
+    it("updates value", () => {
+      const ref = createRef(1);
+
+      ref.update((n) => n + 1);
+
+      assertEqual(ref.get(), 2);
+    });
+
+    it("can keep the same value", () => {
+      const ref = createRef(1);
+
+      ref.update((n) => n);
+
+      assertEqual(ref.get(), 1);
+    });
+  });
+
+  describe("getAndUpdate", () => {
+    it("returns previous value and updates value", () => {
+      const ref = createRef(1);
+
+      assertEqual(
+        ref.getAndUpdate((n) => n + 1),
+        1,
+      );
+      assertEqual(ref.get(), 2);
+    });
+
+    it("accepts an identity updater", () => {
+      const ref = createRef(1);
+
+      assertEqual(
+        ref.getAndUpdate((n) => n),
+        1,
+      );
+      assertEqual(ref.get(), 1);
+    });
+  });
+
+  describe("updateAndGet", () => {
+    it("returns updated value", () => {
+      const ref = createRef(1);
+
+      assertEqual(
+        ref.updateAndGet((n) => n + 1),
+        2,
+      );
+      assertEqual(ref.get(), 2);
+    });
+
+    it("accepts an identity updater", () => {
+      const ref = createRef(1);
+
+      assertEqual(
+        ref.updateAndGet((n) => n),
+        1,
+      );
+      assertEqual(ref.get(), 1);
+    });
+  });
+
+  describe("modify", () => {
+    it("returns a computed result and updates value", () => {
+      const ref = createRef(0);
+      const result = ref.modify((current) => [current, current + 1]);
+
+      assertEqual(result, 0);
+      assertEqual(ref.get(), 1);
+    });
+
+    it("can keep the same value while returning a result", () => {
+      const ref = createRef(1);
+      const result = ref.modify((current) => [`current:${current}`, current]);
+
+      assertEqual(result, "current:1");
+      assertEqual(ref.get(), 1);
+    });
+  });
+});

package/src/RefCount.test.ts

@@ -0,0 +1,184 @@
+import { describe, it } from "node:test";
+import {
+  assertEqual,
+  assertFalse,
+  assertThrowsInstanceOf,
+  assertTrue,
+} from "./Assert.ts";
+
+import { installPolyfills } from "./Polyfills.ts";
+import { createRefCount, createRefCountByKey } from "./RefCount.ts";
+
+installPolyfills();
+
+describe("createRefCount", () => {
+  it("increments and decrements the count", () => {
+    const refCount = createRefCount();
+
+    assertEqual(refCount.getCount(), 0);
+    assertEqual(refCount.increment(), 1);
+    assertEqual(refCount.increment(), 2);
+    assertEqual(refCount.getCount(), 2);
+    assertEqual(refCount.decrement(), 1);
+    assertEqual(refCount.decrement(), 0);
+    assertEqual(refCount.getCount(), 0);
+  });
+
+  it("decrement throws on underflow", () => {
+    const refCount = createRefCount();
+
+    const error = assertThrowsInstanceOf(() => refCount.decrement(), Error);
+    assertTrue(
+      error.message.includes("RefCount must not be decremented below zero."),
+    );
+  });
+
+  it("dispose invalidates the helper", () => {
+    const refCount = createRefCount();
+
+    refCount.increment();
+    refCount.increment();
+    refCount[Symbol.dispose]();
+
+    const incrementError = assertThrowsInstanceOf(
+      () => refCount.increment(),
+      Error,
+    );
+    assertTrue(
+      incrementError.message.includes("Cannot use a disposed object."),
+    );
+    const decrementError = assertThrowsInstanceOf(
+      () => refCount.decrement(),
+      Error,
+    );
+    assertTrue(
+      decrementError.message.includes("Cannot use a disposed object."),
+    );
+    const getCountError = assertThrowsInstanceOf(
+      () => refCount.getCount(),
+      Error,
+    );
+    assertTrue(getCountError.message.includes("Cannot use a disposed object."));
+  });
+});
+
+describe("createRefCountByKey", () => {
+  it("tracks counts per key", () => {
+    const refCount = createRefCountByKey<string>();
+
+    assertEqual(refCount.increment("a"), 1);
+    assertEqual(refCount.increment("a"), 2);
+    assertEqual(refCount.increment("b"), 1);
+    assertEqual(refCount.getCount("a"), 2);
+    assertEqual(refCount.getCount("b"), 1);
+    assertEqual(refCount.keys(), new Set(["a", "b"]));
+  });
+
+  it("decrement removes key at zero", () => {
+    const refCount = createRefCountByKey<string>();
+
+    refCount.increment("a");
+
+    assertEqual(refCount.decrement("a"), 0);
+    assertEqual(refCount.getCount("a"), 0);
+    assertFalse(refCount.has("a"));
+    assertEqual(refCount.keys(), new Set());
+  });
+
+  it("decrement throws on missing key", () => {
+    const refCount = createRefCountByKey<string>();
+
+    const error = assertThrowsInstanceOf(
+      () => refCount.decrement("missing"),
+      Error,
+    );
+    assertTrue(
+      error.message.includes(
+        "RefCount must not be decremented for an untracked key.",
+      ),
+    );
+    assertFalse(refCount.has("missing"));
+    assertEqual(refCount.keys(), new Set());
+  });
+
+  it("decrement keeps key while count stays positive", () => {
+    const refCount = createRefCountByKey<string>();
+
+    refCount.increment("a");
+    refCount.increment("a");
+
+    assertEqual(refCount.decrement("a"), 1);
+    assertEqual(refCount.getCount("a"), 1);
+    assertTrue(refCount.has("a"));
+  });
+
+  it("keys returns a snapshot set", () => {
+    const refCount = createRefCountByKey<string>();
+    refCount.increment("a");
+
+    const keys = refCount.keys();
+    refCount.increment("b");
+
+    assertEqual(keys, new Set(["a"]));
+  });
+
+  it("dispose invalidates the helper", () => {
+    const refCount = createRefCountByKey<string>();
+
+    refCount.increment("a");
+    refCount.increment("b");
+    refCount[Symbol.dispose]();
+
+    const incrementError = assertThrowsInstanceOf(
+      () => refCount.increment("c"),
+      Error,
+    );
+    assertTrue(
+      incrementError.message.includes("Cannot use a disposed object."),
+    );
+    const decrementError = assertThrowsInstanceOf(
+      () => refCount.decrement("a"),
+      Error,
+    );
+    assertTrue(
+      decrementError.message.includes("Cannot use a disposed object."),
+    );
+    const getCountError = assertThrowsInstanceOf(
+      () => refCount.getCount("a"),
+      Error,
+    );
+    assertTrue(getCountError.message.includes("Cannot use a disposed object."));
+    const hasError = assertThrowsInstanceOf(() => refCount.has("a"), Error);
+    assertTrue(hasError.message.includes("Cannot use a disposed object."));
+    const keysError = assertThrowsInstanceOf(() => refCount.keys(), Error);
+    assertTrue(keysError.message.includes("Cannot use a disposed object."));
+  });
+
+  it("uses reference identity for object keys", () => {
+    const refCount = createRefCountByKey<{ readonly id: string }>();
+    const keyA = { id: "same" };
+    const keyB = { id: "same" };
+
+    refCount.increment(keyA);
+    refCount.increment(keyB);
+
+    assertEqual(refCount.getCount(keyA), 1);
+    assertEqual(refCount.getCount(keyB), 1);
+    assertEqual(refCount.keys().size, 2);
+  });
+
+  it("uses lookup for logical key equality", () => {
+    const refCount = createRefCountByKey<{ readonly id: string }, string>({
+      lookup: (key) => key.id,
+    });
+
+    assertEqual(refCount.increment({ id: "same" }), 1);
+    assertEqual(refCount.increment({ id: "same" }), 2);
+    assertEqual(refCount.getCount({ id: "same" }), 2);
+    assertEqual(refCount.keys().size, 1);
+
+    assertEqual(refCount.decrement({ id: "same" }), 1);
+    assertEqual(refCount.decrement({ id: "same" }), 0);
+    assertFalse(refCount.has({ id: "same" }));
+  });
+});