@fragno-dev/db 0.2.2 → 0.3.0

package/src/adapters/in-memory/index.ts

@@ -0,0 +1,3 @@
+export { InMemoryAdapter, type InMemoryUowConfig } from "./in-memory-adapter";
+export type { InMemoryAdapterOptions, ResolvedInMemoryAdapterOptions } from "./options";
+export { UniqueConstraintError, ForeignKeyConstraintError, NotFoundError } from "./errors";

package/src/adapters/in-memory/options.test.ts

@@ -0,0 +1,41 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { resolveInMemoryAdapterOptions } from "./options";
+
+describe("resolveInMemoryAdapterOptions", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("creates deterministic ids when seeded", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2020-01-01T00:00:00.000Z"));
+
+    const first = resolveInMemoryAdapterOptions({ idSeed: "seed" }).idGenerator;
+    const second = resolveInMemoryAdapterOptions({ idSeed: "seed" }).idGenerator;
+
+    const firstIds = [first(), first(), first()];
+    const secondIds = [second(), second(), second()];
+
+    expect(firstIds).toEqual(secondIds);
+  });
+
+  it("provides a monotonic internal id generator", () => {
+    const generator = resolveInMemoryAdapterOptions({ idSeed: "seed" }).internalIdGenerator;
+
+    expect(generator()).toBe(1n);
+    expect(generator()).toBe(2n);
+  });
+
+  it("defaults enforceConstraints and btreeOrder", () => {
+    const options = resolveInMemoryAdapterOptions({ idSeed: "seed" });
+
+    expect(options.enforceConstraints).toBe(true);
+    expect(options.btreeOrder).toBe(32);
+  });
+
+  it("defaults to a clock that returns dates", () => {
+    const options = resolveInMemoryAdapterOptions({ idSeed: "seed" });
+
+    expect(options.clock.now()).toBeInstanceOf(Date);
+  });
+});

package/src/adapters/in-memory/options.ts

@@ -0,0 +1,87 @@
+import { createId, init } from "@paralleldrive/cuid2";
+import type { SqlNamingStrategy } from "../../naming/sql-naming";
+
+export type InMemoryAdapterOptions = {
+  clock?: { now: () => Date };
+  idGenerator?: () => string;
+  idSeed?: string;
+  internalIdGenerator?: () => bigint;
+  enforceConstraints?: boolean;
+  btreeOrder?: number;
+  namingStrategy?: SqlNamingStrategy;
+};
+
+export type ResolvedInMemoryAdapterOptions = {
+  clock: { now: () => Date };
+  idGenerator: () => string;
+  idSeed: string;
+  internalIdGenerator: () => bigint;
+  internalIdGeneratorProvided: boolean;
+  enforceConstraints: boolean;
+  btreeOrder: number;
+};
+
+const defaultClock = {
+  now: () => new Date(),
+};
+
+const defaultBtreeOrder = 32;
+const defaultEnforceConstraints = true;
+const initialCountMax = 476782367;
+const seededRandomStep = 1831565813;
+
+const createCounter = (start: number) => {
+  let value = start;
+  return () => value++;
+};
+
+const hashSeed = (seed: string): number => {
+  let hash = 2166136261;
+  for (let i = 0; i < seed.length; i += 1) {
+    hash ^= seed.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+};
+
+const createSeededRandom = (seed: string) => {
+  let state = hashSeed(seed);
+  return () => {
+    state |= 0;
+    state = (state + seededRandomStep) | 0;
+    let t = Math.imul(state ^ (state >>> 15), 1 | state);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+};
+
+const createSeededIdGenerator = (seed: string): (() => string) => {
+  const random = createSeededRandom(seed);
+  const counter = createCounter(Math.floor(random() * initialCountMax));
+  return init({ random, counter });
+};
+
+const createInternalIdGenerator = (): (() => bigint) => {
+  let current = 0n;
+  return () => {
+    current += 1n;
+    return current;
+  };
+};
+
+export const resolveInMemoryAdapterOptions = (
+  options: InMemoryAdapterOptions = {},
+): ResolvedInMemoryAdapterOptions => {
+  const idSeed = options.idSeed ?? createId();
+  const internalIdGeneratorProvided = options.internalIdGenerator !== undefined;
+
+  return {
+    clock: options.clock ?? defaultClock,
+    idGenerator: options.idGenerator ?? createSeededIdGenerator(idSeed),
+    idSeed,
+    internalIdGenerator: options.internalIdGenerator ?? createInternalIdGenerator(),
+    internalIdGeneratorProvided,
+    enforceConstraints: options.enforceConstraints ?? defaultEnforceConstraints,
+    btreeOrder: options.btreeOrder ?? defaultBtreeOrder,
+  };
+};

package/src/adapters/in-memory/reference-resolution.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { column, idColumn, referenceColumn, schema } from "../../schema/create";
+import { ReferenceSubquery } from "../../query/value-encoding";
+import { createInMemoryStore, ensureNamespaceStore } from "./store";
+import { resolveReferenceSubqueries } from "./reference-resolution";
+
+const testSchema = schema("test", (s) =>
+  s
+    .addTable("users", (t) => t.addColumn("id", idColumn()).addColumn("name", column("string")))
+    .addTable("posts", (t) => t.addColumn("id", idColumn()).addColumn("userId", referenceColumn()))
+    .addReference("author", {
+      type: "one",
+      from: { table: "posts", column: "userId" },
+      to: { table: "users", column: "id" },
+    }),
+);
+
+describe("in-memory reference resolution", () => {
+  it("resolves reference subqueries to internal IDs", () => {
+    const store = createInMemoryStore();
+    const namespaceStore = ensureNamespaceStore(store, "test", testSchema);
+    const usersStore = namespaceStore.tables.get("users");
+    if (!usersStore) {
+      throw new Error("Missing users table store.");
+    }
+
+    usersStore.rows.set(1n, { id: "user-1", name: "Ada", _internalId: 1n, _version: 0 });
+
+    const values = {
+      userId: new ReferenceSubquery(testSchema.tables.users, "user-1"),
+    };
+
+    const resolved = resolveReferenceSubqueries(namespaceStore, values);
+
+    expect(resolved).toEqual({ userId: 1n });
+  });
+
+  it("returns null when the referenced row is missing", () => {
+    const store = createInMemoryStore();
+    const namespaceStore = ensureNamespaceStore(store, "test", testSchema);
+
+    const values = {
+      userId: new ReferenceSubquery(testSchema.tables.users, "missing-user"),
+    };
+
+    const resolved = resolveReferenceSubqueries(namespaceStore, values);
+
+    expect(resolved).toEqual({ userId: null });
+  });
+});

package/src/adapters/in-memory/reference-resolution.ts

@@ -0,0 +1,67 @@
+import type { AnyTable } from "../../schema/create";
+import { ReferenceSubquery } from "../../query/value-encoding";
+import type { InMemoryNamespaceStore, InMemoryTableStore } from "./store";
+import type { NamingResolver } from "../../naming/sql-naming";
+
+const getTableStore = (
+  namespaceStore: InMemoryNamespaceStore,
+  table: AnyTable,
+  resolver?: NamingResolver,
+): InMemoryTableStore => {
+  const tableName = resolver ? resolver.getTableName(table.name) : table.name;
+  const store = namespaceStore.tables.get(tableName);
+  if (!store) {
+    throw new Error(`Missing in-memory table store for "${tableName}".`);
+  }
+  return store;
+};
+
+const resolveExternalIdToInternalId = (
+  tableStore: InMemoryTableStore,
+  table: AnyTable,
+  externalId: string,
+  resolver?: NamingResolver,
+): bigint | undefined => {
+  const idColumnName = table.getIdColumn().name;
+  const physicalIdColumnName = resolver
+    ? resolver.getColumnName(table.name, idColumnName)
+    : idColumnName;
+  for (const [internalId, row] of tableStore.rows) {
+    if (row[physicalIdColumnName] === externalId) {
+      return internalId;
+    }
+  }
+  return undefined;
+};
+
+export const resolveReferenceSubquery = (
+  namespaceStore: InMemoryNamespaceStore,
+  reference: ReferenceSubquery,
+  resolver?: NamingResolver,
+): bigint | null => {
+  const tableStore = getTableStore(namespaceStore, reference.referencedTable, resolver);
+  const resolved = resolveExternalIdToInternalId(
+    tableStore,
+    reference.referencedTable,
+    reference.externalIdValue,
+    resolver,
+  );
+  return resolved ?? null;
+};
+
+export const resolveReferenceSubqueries = (
+  namespaceStore: InMemoryNamespaceStore,
+  values: Record<string, unknown>,
+  resolver?: NamingResolver,
+): Record<string, unknown> => {
+  const resolved: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(values)) {
+    resolved[key] =
+      value instanceof ReferenceSubquery
+        ? resolveReferenceSubquery(namespaceStore, value, resolver)
+        : value;
+  }
+
+  return resolved;
+};

package/src/adapters/in-memory/sorted-array-index.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it } from "vitest";
+import { UniqueConstraintError } from "./errors";
+import { SortedArrayIndex } from "./sorted-array-index";
+
+const compareValue = (left: unknown, right: unknown): number => {
+  if (left === right) {
+    return 0;
+  }
+
+  if (left === null || left === undefined) {
+    return -1;
+  }
+
+  if (right === null || right === undefined) {
+    return 1;
+  }
+
+  if (typeof left === "number" && typeof right === "number") {
+    return left < right ? -1 : 1;
+  }
+
+  if (typeof left === "string" && typeof right === "string") {
+    return left < right ? -1 : 1;
+  }
+
+  if (typeof left === "bigint" && typeof right === "bigint") {
+    return left < right ? -1 : 1;
+  }
+
+  throw new Error("Unsupported comparison in test helper.");
+};
+
+const valuesFromScan = (
+  index: SortedArrayIndex<string>,
+  options?: { direction?: "asc" | "desc" },
+) => index.scan(options).map((entry) => entry.value);
+
+describe("sorted-array index", () => {
+  it("keeps entries sorted by key and supports duplicates", () => {
+    const index = new SortedArrayIndex<string>(compareValue);
+
+    index.insert([2], "b");
+    index.insert([1], "a");
+    index.insert([2], "c");
+    index.insert([3], "d");
+
+    expect(valuesFromScan(index)).toEqual(["a", "b", "c", "d"]);
+  });
+
+  it("removes entries by key and value when duplicates exist", () => {
+    const index = new SortedArrayIndex<string>(compareValue);
+
+    index.insert([1], "a");
+    index.insert([1], "b");
+    index.insert([2], "c");
+
+    expect(index.remove([1], "b")).toBe(true);
+    expect(valuesFromScan(index)).toEqual(["a", "c"]);
+    expect(index.remove([3])).toBe(false);
+  });
+
+  it("updates entries by removing and re-inserting", () => {
+    const index = new SortedArrayIndex<string>(compareValue);
+
+    index.insert([1], "a");
+    index.insert([2], "b");
+
+    index.update([1], [3], "a");
+
+    expect(valuesFromScan(index)).toEqual(["b", "a"]);
+  });
+
+  it("scans ranges with inclusive/exclusive bounds and direction", () => {
+    const index = new SortedArrayIndex<string>(compareValue);
+
+    index.insert([1], "a");
+    index.insert([2], "b");
+    index.insert([3], "c");
+    index.insert([4], "d");
+
+    const inclusive = index
+      .scan({ start: [2], startInclusive: true, end: [3], endInclusive: true })
+      .map((entry) => entry.value);
+    expect(inclusive).toEqual(["b", "c"]);
+
+    const exclusive = index
+      .scan({ start: [2], startInclusive: false, end: [4], endInclusive: false })
+      .map((entry) => entry.value);
+    expect(exclusive).toEqual(["c"]);
+
+    const descending = index
+      .scan({ start: [2], end: [4], direction: "desc", endInclusive: true })
+      .map((entry) => entry.value);
+    expect(descending).toEqual(["d", "c", "b"]);
+  });
+
+  it("respects scan limits", () => {
+    const index = new SortedArrayIndex<string>(compareValue);
+
+    index.insert([1], "a");
+    index.insert([2], "b");
+    index.insert([3], "c");
+
+    expect(index.scan({ limit: 2 }).map((entry) => entry.value)).toEqual(["a", "b"]);
+  });
+
+  it("throws on duplicate keys when unique", () => {
+    const index = new SortedArrayIndex<string>(compareValue, { unique: true });
+
+    index.insert([1], "a");
+
+    expect(() => index.insert([1], "b")).toThrow(UniqueConstraintError);
+  });
+
+  it("allows duplicate keys when unique enforcement is disabled", () => {
+    const index = new SortedArrayIndex<string>(compareValue, { unique: true });
+
+    index.insert([1], "a", { enforceUnique: false });
+    index.insert([1], "b", { enforceUnique: false });
+
+    expect(valuesFromScan(index)).toEqual(["a", "b"]);
+  });
+});

package/src/adapters/in-memory/sorted-array-index.ts

@@ -0,0 +1,228 @@
+export type IndexKey = readonly unknown[];
+
+export type SortedArrayIndexEntry<T> = {
+  key: IndexKey;
+  value: T;
+};
+
+import { UniqueConstraintError } from "./errors";
+
+export type CompareValue = (left: unknown, right: unknown) => number;
+
+export type SortedArrayIndexOptions = {
+  unique?: boolean;
+};
+
+export type UniqueEnforcementOptions = {
+  enforceUnique?: boolean;
+};
+
+export type IndexScanOptions = {
+  start?: IndexKey;
+  startInclusive?: boolean;
+  end?: IndexKey;
+  endInclusive?: boolean;
+  direction?: "asc" | "desc";
+  limit?: number;
+};
+
+const compareKeys = (left: IndexKey, right: IndexKey, compareValue: CompareValue): number => {
+  const length = Math.min(left.length, right.length);
+  for (let i = 0; i < length; i += 1) {
+    const result = compareValue(left[i], right[i]);
+    if (result !== 0) {
+      return result;
+    }
+  }
+
+  return left.length - right.length;
+};
+
+export class SortedArrayIndex<T> {
+  #entries: SortedArrayIndexEntry<T>[] = [];
+  #compareValue: CompareValue;
+  #unique: boolean;
+
+  constructor(compareValue: CompareValue, options: SortedArrayIndexOptions = {}) {
+    this.#compareValue = compareValue;
+    this.#unique = options.unique ?? false;
+  }
+
+  get size(): number {
+    return this.#entries.length;
+  }
+
+  entries(): SortedArrayIndexEntry<T>[] {
+    return this.#entries.slice();
+  }
+
+  insert(key: IndexKey, value: T, options: UniqueEnforcementOptions = {}): void {
+    const enforceUnique = options.enforceUnique ?? true;
+    if (this.#unique && enforceUnique) {
+      this.#assertUnique(key);
+    }
+    const entry = { key, value };
+    const index = this.#upperBound(key);
+    this.#entries.splice(index, 0, entry);
+  }
+
+  remove(key: IndexKey, value?: T): boolean {
+    const start = this.#lowerBound(key);
+    const end = this.#upperBound(key);
+    if (start === end) {
+      return false;
+    }
+
+    if (value === undefined) {
+      this.#entries.splice(start, 1);
+      return true;
+    }
+
+    for (let i = start; i < end; i += 1) {
+      if (this.#entries[i]?.value === value) {
+        this.#entries.splice(i, 1);
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  update(
+    oldKey: IndexKey,
+    newKey: IndexKey,
+    value: T,
+    options: UniqueEnforcementOptions = {},
+  ): void {
+    const enforceUnique = options.enforceUnique ?? true;
+    if (this.#unique && enforceUnique) {
+      const range = this.#rangeForKey(newKey);
+      if (range.start !== range.end) {
+        const sameKey = compareKeys(oldKey, newKey, this.#compareValue) === 0;
+        const singleEntry = range.end - range.start === 1;
+        const entry = this.#entries[range.start];
+        const isSameEntry = sameKey && singleEntry && entry?.value === value;
+        if (!isSameEntry) {
+          throw new UniqueConstraintError(this.#uniqueErrorMessage(newKey));
+        }
+        if (sameKey) {
+          return;
+        }
+      }
+    }
+    const removed = this.remove(oldKey, value);
+    if (!removed) {
+      throw new Error("SortedArrayIndex update failed to locate existing entry.");
+    }
+    this.insert(newKey, value, { enforceUnique });
+  }
+
+  scan(options: IndexScanOptions = {}): SortedArrayIndexEntry<T>[] {
+    const direction = options.direction ?? "asc";
+    const limit = options.limit ?? Number.POSITIVE_INFINITY;
+
+    const start = options.start
+      ? options.startInclusive === false
+        ? this.#upperBound(options.start)
+        : this.#lowerBound(options.start)
+      : 0;
+
+    const end = options.end
+      ? options.endInclusive === true
+        ? this.#upperBound(options.end)
+        : this.#lowerBound(options.end)
+      : this.#entries.length;
+
+    if (start >= end || limit <= 0) {
+      return [];
+    }
+
+    const results: SortedArrayIndexEntry<T>[] = [];
+
+    if (direction === "desc") {
+      for (let i = end - 1; i >= start && results.length < limit; i -= 1) {
+        results.push(this.#entries[i]);
+      }
+      return results;
+    }
+
+    for (let i = start; i < end && results.length < limit; i += 1) {
+      results.push(this.#entries[i]);
+    }
+
+    return results;
+  }
+
+  #compareEntryWithKey(entry: SortedArrayIndexEntry<T>, key: IndexKey): number {
+    return compareKeys(entry.key, key, this.#compareValue);
+  }
+
+  #rangeForKey(key: IndexKey): { start: number; end: number } {
+    return {
+      start: this.#lowerBound(key),
+      end: this.#upperBound(key),
+    };
+  }
+
+  #assertUnique(key: IndexKey): void {
+    const range = this.#rangeForKey(key);
+    if (range.start !== range.end) {
+      throw new UniqueConstraintError(this.#uniqueErrorMessage(key));
+    }
+  }
+
+  #uniqueErrorMessage(key: IndexKey): string {
+    return `Unique constraint violation for key ${this.#formatKey(key)}.`;
+  }
+
+  #formatKey(key: IndexKey): string {
+    const parts = key.map((value) => this.#formatKeyValue(value));
+    return `[${parts.join(", ")}]`;
+  }
+
+  #formatKeyValue(value: unknown): string {
+    if (value instanceof Date) {
+      return value.toISOString();
+    }
+    if (typeof value === "bigint") {
+      return `${value}n`;
+    }
+    return String(value);
+  }
+
+  #lowerBound(key: IndexKey): number {
+    let low = 0;
+    let high = this.#entries.length;
+
+    while (low < high) {
+      const mid = (low + high) >>> 1;
+      const entry = this.#entries[mid];
+      const comparison = entry ? this.#compareEntryWithKey(entry, key) : 0;
+      if (comparison < 0) {
+        low = mid + 1;
+      } else {
+        high = mid;
+      }
+    }
+
+    return low;
+  }
+
+  #upperBound(key: IndexKey): number {
+    let low = 0;
+    let high = this.#entries.length;
+
+    while (low < high) {
+      const mid = (low + high) >>> 1;
+      const entry = this.#entries[mid];
+      const comparison = entry ? this.#compareEntryWithKey(entry, key) : 0;
+      if (comparison <= 0) {
+        low = mid + 1;
+      } else {
+        high = mid;
+      }
+    }
+
+    return low;
+  }
+}

package/src/adapters/in-memory/store.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import { column, idColumn, schema } from "../../schema/create";
+import { createInMemoryStore, ensureNamespaceStore } from "./store";
+
+const testSchema = schema("test", (s) =>
+  s
+    .addTable("users", (t) =>
+      t
+        .addColumn("id", idColumn())
+        .addColumn("name", column("string"))
+        .createIndex("name_idx", ["name"]),
+    )
+    .addTable("posts", (t) =>
+      t
+        .addColumn("id", idColumn())
+        .addColumn("userId", column("string"))
+        .createIndex("user_idx", ["userId"], { unique: true }),
+    ),
+);
+
+describe("in-memory store", () => {
+  it("creates namespace tables with empty row maps and counters", () => {
+    const store = createInMemoryStore();
+    const namespaceStore = ensureNamespaceStore(store, "test", testSchema);
+
+    expect(namespaceStore.tables.size).toBe(2);
+    expect(namespaceStore.tables.has("users")).toBe(true);
+    expect(namespaceStore.tables.has("posts")).toBe(true);
+
+    const usersTable = namespaceStore.tables.get("users");
+    const postsTable = namespaceStore.tables.get("posts");
+
+    expect(usersTable?.rows.size).toBe(0);
+    expect(postsTable?.rows.size).toBe(0);
+    expect(usersTable?.nextInternalId).toBe(1n);
+    expect(postsTable?.nextInternalId).toBe(1n);
+    expect(usersTable?.indexes.size).toBe(2);
+    expect(postsTable?.indexes.size).toBe(2);
+    expect(usersTable?.indexes.has("_primary")).toBe(true);
+    expect(postsTable?.indexes.has("_primary")).toBe(true);
+
+    const usersPrimary = usersTable?.indexes.get("_primary");
+    const usersNameIdx = usersTable?.indexes.get("name_idx");
+    const postsUserIdx = postsTable?.indexes.get("user_idx");
+
+    expect(usersPrimary?.definition.columnNames).toEqual(["id"]);
+    expect(usersPrimary?.definition.unique).toBe(true);
+    expect(usersNameIdx?.definition.columnNames).toEqual(["name"]);
+    expect(usersNameIdx?.definition.unique).toBe(false);
+    expect(postsUserIdx?.definition.columnNames).toEqual(["userId"]);
+    expect(postsUserIdx?.definition.unique).toBe(true);
+  });
+
+  it("reuses existing namespace stores", () => {
+    const store = createInMemoryStore();
+    const first = ensureNamespaceStore(store, "test", testSchema);
+    const usersTable = first.tables.get("users");
+    if (usersTable) {
+      usersTable.nextInternalId = 42n;
+    }
+
+    const second = ensureNamespaceStore(store, "test", testSchema);
+    const usersTableAgain = second.tables.get("users");
+
+    expect(second).toBe(first);
+    expect(usersTableAgain?.nextInternalId).toBe(42n);
+  });
+});