@evolu/common 8.7.0 → 8.9.0

package/src/Set.test.ts

@@ -0,0 +1,279 @@
+import { describe, it } from "node:test";
+import { assertEqual, assertFalse, assertTrue } from "./Assert.ts";
+
+import {
+  addToSet,
+  createSet,
+  deleteFromSet,
+  emptySet,
+  filterSet,
+  firstInSet,
+  isNonEmptySet,
+  mapSet,
+  type NonEmptyReadonlySet,
+} from "./Set.ts";
+import { assertType } from "./Type.ts";
+
+describe("Constants", () => {
+  describe("emptySet", () => {
+    it("is empty", () => {
+      assertEqual(emptySet.size, 0);
+    });
+
+    it("is assignable to any ReadonlySet<T>", () => {
+      const numbers: ReadonlySet<number> = emptySet;
+      const objects: ReadonlySet<{ id: number }> = emptySet;
+
+      assertType<typeof numbers, ReadonlySet<number>>();
+      assertType<typeof objects, ReadonlySet<{ id: number }>>();
+
+      assertEqual(numbers.size, 0);
+      assertEqual(objects.size, 0);
+    });
+
+    it("enables fast empty check via reference equality", () => {
+      const children: ReadonlySet<number> = emptySet;
+      assertTrue(children === emptySet);
+
+      const nonEmpty = addToSet(emptySet, 1);
+      assertFalse((nonEmpty as ReadonlySet<number>) === emptySet);
+    });
+  });
+});
+
+describe("Type guards", () => {
+  describe("isNonEmptySet", () => {
+    it("returns true for non-empty set", () => {
+      const set = new Set([1, 2, 3]);
+      assertTrue(isNonEmptySet(set));
+    });
+
+    it("returns false for empty set", () => {
+      const set = new Set<number>();
+      assertFalse(isNonEmptySet(set));
+    });
+
+    it("returns true for single element set", () => {
+      const set = new Set([1]);
+      assertTrue(isNonEmptySet(set));
+    });
+
+    it("narrows mutable set to NonEmptyReadonlySet", () => {
+      const set = new Set<number>([1, 2, 3]);
+      if (isNonEmptySet(set)) {
+        // Mutable set intersected with branded readonly type
+        assertType<
+          typeof set extends NonEmptyReadonlySet<number> ? true : false,
+          true
+        >();
+      }
+    });
+
+    it("narrows readonly set to NonEmptyReadonlySet", () => {
+      const set: ReadonlySet<number> = new Set([1, 2, 3]);
+      if (isNonEmptySet(set)) {
+        assertType<typeof set, NonEmptyReadonlySet<number>>();
+      }
+    });
+
+    it("returns false for empty readonly set", () => {
+      const set: ReadonlySet<number> = new Set();
+      assertFalse(isNonEmptySet(set));
+    });
+  });
+});
+
+describe("Transformations", () => {
+  describe("createSet", () => {
+    it("creates empty set from empty array", () => {
+      const result = createSet([] as ReadonlyArray<number>);
+      assertEqual(result, new Set());
+      assertType<
+        typeof result extends ReadonlySet<number> ? true : false,
+        true
+      >();
+    });
+
+    it("creates non-empty set from non-empty array", () => {
+      const result = createSet([1, 2, 3] as const);
+      assertEqual(result, new Set([1, 2, 3]));
+      assertType<typeof result, NonEmptyReadonlySet<1 | 2 | 3>>();
+    });
+
+    it("deduplicates duplicate values", () => {
+      const result = createSet([1, 1, 2, 2, 3]);
+      assertEqual(result, new Set([1, 2, 3]));
+    });
+
+    it("returns new set instance each call", () => {
+      const a = createSet([1, 2, 3]);
+      const b = createSet([1, 2, 3]);
+      assertFalse(Object.is(a, b));
+    });
+  });
+
+  describe("addToSet", () => {
+    it("adds item to empty set", () => {
+      const set: ReadonlySet<number> = new Set();
+      const result = addToSet(set, 1);
+      assertEqual(result, new Set([1]));
+      assertType<typeof result, NonEmptyReadonlySet<number>>();
+    });
+
+    it("adds item to non-empty set", () => {
+      const set: ReadonlySet<number> = new Set([1, 2]);
+      const result = addToSet(set, 3);
+      assertEqual(result, new Set([1, 2, 3]));
+    });
+
+    it("does not mutate original set", () => {
+      const set: ReadonlySet<number> = new Set([1, 2]);
+      addToSet(set, 3);
+      assertEqual(set, new Set([1, 2]));
+    });
+
+    it("returns new reference even when item already exists", () => {
+      const set: ReadonlySet<number> = new Set([1, 2]);
+      const result = addToSet(set, 2);
+      assertEqual(result, new Set([1, 2]));
+      assertFalse(Object.is(result, set));
+    });
+
+    it("accepts mutable set and returns readonly", () => {
+      const mutableSet = new Set<number>([1, 2]);
+      const result = addToSet(mutableSet, 3);
+      assertEqual(result, new Set([1, 2, 3]));
+      assertType<typeof result, NonEmptyReadonlySet<number>>();
+      assertEqual(mutableSet, new Set([1, 2]));
+    });
+  });
+
+  describe("deleteFromSet", () => {
+    it("removes item from set", () => {
+      const set: ReadonlySet<number> = new Set([1, 2, 3]);
+      const result = deleteFromSet(set, 2);
+      assertEqual(result, new Set([1, 3]));
+      assertType<typeof result, ReadonlySet<number>>();
+    });
+
+    it("does not mutate original set", () => {
+      const set: ReadonlySet<number> = new Set([1, 2, 3]);
+      deleteFromSet(set, 2);
+      assertEqual(set, new Set([1, 2, 3]));
+    });
+
+    it("returns new reference even when item does not exist", () => {
+      const set: ReadonlySet<number> = new Set([1, 2]);
+      const result = deleteFromSet(set, 5);
+      assertEqual(result, new Set([1, 2]));
+      assertFalse(Object.is(result, set));
+    });
+
+    it("can delete to empty set", () => {
+      const set: ReadonlySet<number> = new Set([1]);
+      const result = deleteFromSet(set, 1);
+      assertEqual(result.size, 0);
+    });
+
+    it("accepts mutable set and returns readonly", () => {
+      const mutableSet = new Set<number>([1, 2, 3]);
+      const result = deleteFromSet(mutableSet, 2);
+      assertEqual(result, new Set([1, 3]));
+      assertType<typeof result, ReadonlySet<number>>();
+      assertEqual(mutableSet, new Set([1, 2, 3]));
+    });
+  });
+
+  describe("mapSet", () => {
+    it("maps set values", () => {
+      const set: ReadonlySet<number> = new Set([1, 2, 3]);
+      const result = mapSet(set, (item) => item * 2);
+      assertEqual(result, new Set([2, 4, 6]));
+      assertType<typeof result, ReadonlySet<number>>();
+    });
+
+    it("deduplicates mapped duplicates", () => {
+      const set: ReadonlySet<number> = new Set([1, 2, 3]);
+      const result = mapSet(set, (item) => item % 2);
+      assertEqual(result, new Set([1, 0]));
+    });
+
+    it("preserves non-empty type for non-empty input", () => {
+      const set = addToSet(emptySet, 1);
+      const result = mapSet(set, (item) => item.toString());
+      assertType<typeof result, NonEmptyReadonlySet<string>>();
+      assertEqual(result, new Set(["1"]));
+    });
+
+    it("does not mutate original set", () => {
+      const set: ReadonlySet<number> = new Set([1, 2, 3]);
+      mapSet(set, (item) => item + 1);
+      assertEqual(set, new Set([1, 2, 3]));
+    });
+  });
+
+  describe("filterSet", () => {
+    it("filters set values with predicate", () => {
+      const set: ReadonlySet<number> = new Set([1, 2, 3, 4]);
+      const result = filterSet(set, (item) => item % 2 === 0);
+      assertEqual(result, new Set([2, 4]));
+      assertType<typeof result, ReadonlySet<number>>();
+    });
+
+    it("passes index to predicate", () => {
+      const set: ReadonlySet<number> = new Set([10, 20, 30]);
+      const result = filterSet(set, (_item, index) => index % 2 === 0);
+      assertEqual(result, new Set([10, 30]));
+    });
+
+    it("supports refinement predicates", () => {
+      const set: ReadonlySet<string | number> = new Set([1, "a", 2, "b"]);
+      const result = filterSet(
+        set,
+        (item): item is string => typeof item === "string",
+      );
+      assertEqual(result, new Set(["a", "b"]));
+      assertType<typeof result, ReadonlySet<string>>();
+    });
+
+    it("does not mutate original set", () => {
+      const set: ReadonlySet<number> = new Set([1, 2, 3]);
+      filterSet(set, (item) => item > 1);
+      assertEqual(set, new Set([1, 2, 3]));
+    });
+  });
+});
+
+describe("Accessors", () => {
+  describe("firstInSet", () => {
+    it("requires NonEmptyReadonlySet (branded type prevents unguarded access)", () => {
+      const set: ReadonlySet<number> = new Set([1, 2, 3]);
+      // @ts-expect-error - ReadonlySet is not assignable to NonEmptyReadonlySet
+      firstInSet(set);
+    });
+
+    it("returns first element by insertion order", () => {
+      const set: ReadonlySet<number> = new Set([1, 2, 3]);
+      if (isNonEmptySet(set)) {
+        const result = firstInSet(set);
+        assertEqual(result, 1);
+        assertType<typeof result, number>();
+      }
+    });
+
+    it("returns only element from single element set", () => {
+      const set: ReadonlySet<string> = new Set(["only"]);
+      if (isNonEmptySet(set)) {
+        assertEqual(firstInSet(set), "only");
+      }
+    });
+
+    it("does not mutate original set", () => {
+      const set: ReadonlySet<number> = new Set([1, 2, 3]);
+      if (isNonEmptySet(set)) {
+        firstInSet(set);
+        assertEqual(set, new Set([1, 2, 3]));
+      }
+    });
+  });
+});

package/src/Set.ts

@@ -69,8 +69,8 @@ export const emptySet: ReadonlySet<never> = /*#__PURE__*/ new Set();
  * const values = createSet([1, 2, 3]);
  * const empty = createSet([] as ReadonlyArray<number>);
  *
- * assertType<NonEmptyReadonlySet<number>, typeof values>();
- * assertType<ReadonlySet<number>, typeof empty>();
+ * assertType<typeof values, NonEmptyReadonlySet<number>>();
+ * assertType<typeof empty, ReadonlySet<number>>();
  * assertEqual(values, new Set([1, 2, 3]));
  * ```
  *
@@ -124,7 +124,7 @@ export type NonEmptyReadonlySet<T> = ReadonlySet<T> & Brand<"NonEmpty">;
  * const set: ReadonlySet<number> = new Set([1, 2, 3]);
  * if (!isNonEmptySet(set)) throw new Error("Expected a non-empty set");
  *
- * assertType<NonEmptyReadonlySet<number>, typeof set>();
+ * assertType<typeof set, NonEmptyReadonlySet<number>>();
  * assertEqual(set.size, 3);
  * ```
  *
@@ -155,7 +155,7 @@ export const isNonEmptySet = <T>(
  * const added = addToSet(original, 3);
  * const unchanged = addToSet(original, 2);
  *
- * assertType<NonEmptyReadonlySet<number>, typeof added>();
+ * assertType<typeof added, NonEmptyReadonlySet<number>>();
  * assertEqual(added, new Set([1, 2, 3]));
  * assertTrue(unchanged !== original);
  * ```
@@ -221,7 +221,7 @@ export const deleteFromSet = <T>(
  * const doubled = mapSet(original, (x) => x * 2);
  * const parity = mapSet(original, (x) => x % 2);
  *
- * assertType<NonEmptyReadonlySet<number>, typeof doubled>();
+ * assertType<typeof doubled, NonEmptyReadonlySet<number>>();
  * assertEqual(doubled, new Set([2, 4, 6]));
  * assertEqual(parity, new Set([1, 0]));
  * ```
@@ -268,7 +268,7 @@ export function mapSet<T, U>(
  *   mixed,
  *   (value): value is string => typeof value === "string",
  * );
- * assertType<ReadonlySet<string>, typeof strings>();
+ * assertType<typeof strings, ReadonlySet<string>>();
  * assertEqual(strings, new Set(["a", "b"]));
  * ```
  *

package/src/Sqlite.ts

@@ -5,7 +5,7 @@
  */
 
 import type { Brand } from "./Brand.ts";
-import { bytesToHex, hexToBytes } from "./Buffer.ts";
+import { bytesToHex, hexToBytes } from "./Binary.ts";
 import type { EncryptionKey } from "./Crypto.ts";
 import type { Eq } from "./Eq.ts";
 import { createEqObject, eqString, eqUint8Array } from "./Eq.ts";

package/src/Store.test.ts

@@ -0,0 +1,288 @@
+import { describe, it, mock } from "node:test";
+import { assertEqual } from "./Assert.ts";
+
+import { createStore } from "./Store.ts";
+
+describe("get", () => {
+  it("get returns initial state", () => {
+    const store = createStore(42);
+    assertEqual(store.get(), 42);
+  });
+});
+
+describe("set", () => {
+  it("updates state", () => {
+    const store = createStore(0);
+    store.set(1);
+    assertEqual(store.get(), 1);
+  });
+
+  it("notifies listeners when state changes", () => {
+    const store = createStore(0);
+    const listener = mock.fn<() => void>();
+    store.subscribe(listener);
+
+    store.set(1);
+
+    assertEqual(listener.mock.callCount(), 1);
+  });
+
+  it("does not notify listeners when state is equal", () => {
+    const store = createStore(1);
+    const listener = mock.fn<() => void>();
+    store.subscribe(listener);
+
+    store.set(1);
+
+    assertEqual(listener.mock.callCount(), 0);
+  });
+
+  it("does not notify listeners when repeated state is NaN", () => {
+    const store = createStore(NaN);
+    const listener = mock.fn<() => void>();
+    store.subscribe(listener);
+
+    store.set(NaN);
+
+    assertEqual(listener.mock.callCount(), 0);
+  });
+});
+
+describe("getAndSet", () => {
+  it("returns previous state and updates state", () => {
+    const store = createStore(1);
+
+    assertEqual(store.getAndSet(2), 1);
+    assertEqual(store.get(), 2);
+  });
+
+  it("notifies listeners when state changes", () => {
+    const store = createStore(1);
+    const listener = mock.fn<() => void>();
+    store.subscribe(listener);
+
+    assertEqual(store.getAndSet(2), 1);
+    assertEqual(listener.mock.callCount(), 1);
+  });
+
+  it("does not notify listeners when state is equal", () => {
+    const store = createStore(1);
+    const listener = mock.fn<() => void>();
+    store.subscribe(listener);
+
+    assertEqual(store.getAndSet(1), 1);
+    assertEqual(listener.mock.callCount(), 0);
+  });
+});
+
+describe("setAndGet", () => {
+  it("returns updated state", () => {
+    const store = createStore(1);
+
+    assertEqual(store.setAndGet(2), 2);
+    assertEqual(store.get(), 2);
+  });
+
+  it("does not notify listeners when state is equal", () => {
+    const store = createStore(1);
+    const listener = mock.fn<() => void>();
+    store.subscribe(listener);
+
+    assertEqual(store.setAndGet(1), 1);
+    assertEqual(listener.mock.callCount(), 0);
+  });
+});
+
+describe("update", () => {
+  it("updates state", () => {
+    const store = createStore(1);
+
+    store.update((n) => n + 1);
+
+    assertEqual(store.get(), 2);
+  });
+
+  it("notifies listeners when state changes", () => {
+    const store = createStore(1);
+    const listener = mock.fn<() => void>();
+    store.subscribe(listener);
+
+    store.update((n) => n + 1);
+
+    assertEqual(listener.mock.callCount(), 1);
+  });
+
+  it("does not notify listeners when state is equal", () => {
+    const store = createStore(1);
+    const listener = mock.fn<() => void>();
+    store.subscribe(listener);
+
+    store.update((n) => n);
+
+    assertEqual(listener.mock.callCount(), 0);
+  });
+});
+
+describe("getAndUpdate", () => {
+  it("returns previous state and updates state", () => {
+    const store = createStore(1);
+
+    assertEqual(
+      store.getAndUpdate((n: number) => n + 1),
+      1,
+    );
+    assertEqual(store.get(), 2);
+  });
+
+  it("notifies listeners when state changes", () => {
+    const store = createStore(1);
+    const listener = mock.fn<() => void>();
+    store.subscribe(listener);
+
+    assertEqual(
+      store.getAndUpdate((n: number) => n + 1),
+      1,
+    );
+    assertEqual(listener.mock.callCount(), 1);
+  });
+
+  it("does not notify listeners when state is equal", () => {
+    const store = createStore(1);
+    const listener = mock.fn<() => void>();
+    store.subscribe(listener);
+
+    assertEqual(
+      store.getAndUpdate((n) => n),
+      1,
+    );
+    assertEqual(listener.mock.callCount(), 0);
+  });
+});
+
+describe("updateAndGet", () => {
+  it("returns updated state", () => {
+    const store = createStore(1);
+
+    assertEqual(
+      store.updateAndGet((n: number) => n + 1),
+      2,
+    );
+    assertEqual(store.get(), 2);
+  });
+
+  it("does not notify listeners when state is equal", () => {
+    const store = createStore(1);
+    const listener = mock.fn<() => void>();
+    store.subscribe(listener);
+
+    assertEqual(
+      store.updateAndGet((n) => n),
+      1,
+    );
+    assertEqual(listener.mock.callCount(), 0);
+  });
+});
+
+describe("modify", () => {
+  it("returns a computed result and updates state", () => {
+    const store = createStore(0);
+    const result = store.modify((current) => [current, current + 1]);
+
+    assertEqual(result, 0);
+    assertEqual(store.get(), 1);
+  });
+
+  it("returns computed result and updates state", () => {
+    const store = createStore(1);
+
+    const result = store.modify((current: number) => [
+      `previous:${current}`,
+      current + 1,
+    ]);
+
+    assertEqual(result, "previous:1");
+    assertEqual(store.get(), 2);
+  });
+
+  it("notifies listeners when state changes", () => {
+    const store = createStore(0);
+    const listener = mock.fn<() => void>();
+    store.subscribe(listener);
+
+    const result = store.modify((current: number) => [current, current + 1]);
+
+    assertEqual(result, 0);
+    assertEqual(listener.mock.callCount(), 1);
+  });
+
+  it("does not notify listeners when next state is equal", () => {
+    const store = createStore(1);
+    const listener = mock.fn<() => void>();
+    store.subscribe(listener);
+
+    const result = store.modify((current) => [current, current]);
+
+    assertEqual(result, 1);
+    assertEqual(listener.mock.callCount(), 0);
+  });
+});
+
+describe("subscribe", () => {
+  it("returns unsubscribe function", () => {
+    const store = createStore(0);
+    const listener = mock.fn<() => void>();
+    const unsubscribe = store.subscribe(listener);
+
+    store.set(1);
+    assertEqual(listener.mock.callCount(), 1);
+
+    unsubscribe();
+    store.set(2);
+    assertEqual(listener.mock.callCount(), 1);
+  });
+
+  it("supports multiple listeners", () => {
+    const store = createStore(0);
+    const listener1 = mock.fn<() => void>();
+    const listener2 = mock.fn<() => void>();
+
+    store.subscribe(listener1);
+    store.subscribe(listener2);
+
+    store.set(1);
+
+    assertEqual(listener1.mock.callCount(), 1);
+    assertEqual(listener2.mock.callCount(), 1);
+  });
+});
+
+describe("dispose", () => {
+  it("clears all listeners", () => {
+    const store = createStore(0);
+    const listener = mock.fn<() => void>();
+    store.subscribe(listener);
+
+    store[Symbol.dispose]();
+    store.set(1);
+
+    assertEqual(listener.mock.callCount(), 0);
+  });
+});
+
+describe("custom eq", () => {
+  it("suppresses notifications for equal states under the provided equality", () => {
+    const eqModulo10 = (a: number, b: number) => a % 10 === b % 10;
+    const store = createStore<number>(5, eqModulo10);
+
+    const listener = mock.fn<() => void>();
+    store.subscribe(listener);
+
+    store.set(15);
+    assertEqual(store.get(), 15);
+    assertEqual(listener.mock.callCount(), 0);
+
+    store.set(16);
+    assertEqual(store.get(), 16);
+    assertEqual(listener.mock.callCount(), 1);
+  });
+});

package/src/String.test.ts

@@ -0,0 +1,54 @@
+import { test } from "node:test";
+import { assertEqual, assertSame, assertTrue } from "./Assert.ts";
+
+import { escapeRegExp, safelyStringifyUnknownValue } from "./String.ts";
+
+test("escapeRegExp", () => {
+  const value = "value.*+?^${}()|[]\\end";
+
+  assertEqual(
+    escapeRegExp(value),
+    "value\\.\\*\\+\\?\\^\\$\\{\\}\\(\\)\\|\\[\\]\\\\end",
+  );
+  assertTrue(new RegExp(`^${escapeRegExp(value)}$`, "u").test(value));
+});
+
+test("safelyStringifyUnknownValue", () => {
+  assertEqual(
+    safelyStringifyUnknownValue('line 1\n"line 2"'),
+    '"line 1\\n\\"line 2\\""',
+  );
+  assertEqual(safelyStringifyUnknownValue(undefined), "undefined");
+  assertEqual(safelyStringifyUnknownValue(null), "null");
+  assertEqual(safelyStringifyUnknownValue(true), "true");
+  assertEqual(safelyStringifyUnknownValue(NaN), "NaN");
+  assertEqual(safelyStringifyUnknownValue(Infinity), "Infinity");
+  assertEqual(safelyStringifyUnknownValue(42n), "42");
+  assertEqual(safelyStringifyUnknownValue(Symbol("id")), "Symbol(id)");
+
+  const fn = (): undefined => undefined;
+  assertSame(safelyStringifyUnknownValue(fn), String(fn));
+  assertEqual(safelyStringifyUnknownValue({ answer: 42 }), '{"answer":42}');
+  assertEqual(
+    safelyStringifyUnknownValue({ toJSON: () => undefined }),
+    "[object Object]",
+  );
+
+  const circularValue: { circular?: unknown } = {};
+  circularValue.circular = circularValue;
+  assertEqual(safelyStringifyUnknownValue(circularValue), "[object Object]");
+
+  const unserializableValue: {
+    self?: unknown;
+    readonly toString: () => never;
+  } = {
+    toString: () => {
+      throw new Error("Cannot stringify.");
+    },
+  };
+  unserializableValue.self = unserializableValue;
+  assertEqual(
+    safelyStringifyUnknownValue(unserializableValue),
+    "[Unserializable value]",
+  );
+});

package/src/String.ts

@@ -14,8 +14,7 @@ export const escapeRegExp = (value: string): string =>
 /** Converts an unknown value to a compact, human-readable diagnostic string. */
 export const safelyStringifyUnknownValue = (value: unknown): string => {
   if (typeof value === "string") return JSON.stringify(value);
-  if (value === null || typeof value !== "object")
-    return globalThis.String(value);
+  if (value === null || typeof value !== "object") return String(value);
 
   try {
     // `JSON.stringify` can return `undefined` when `toJSON` does.
@@ -26,7 +25,8 @@ export const safelyStringifyUnknownValue = (value: unknown): string => {
   }
 
   try {
-    return globalThis.String(value);
+    // oxlint-disable-next-line typescript/no-base-to-string -- This is the intentional last-resort representation.
+    return String(value);
   } catch {
     return "[Unserializable value]";
   }