@fragno-dev/db 0.2.2 → 0.4.1

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

@@ -0,0 +1,124 @@
+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,69 @@
+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);
+  });
+});

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

@@ -0,0 +1,145 @@
+import type { NamingResolver } from "../../naming/sql-naming";
+import { createSQLSerializer } from "../../query/serialize/create-sql-serializer";
+import type { AnyColumn, AnySchema, AnyTable } from "../../schema/create";
+import { SQLocalDriverConfig } from "../generic-sql/driver-config";
+import { SortedArrayIndex } from "./sorted-array-index";
+import { compareNormalizedValues } from "./value-comparison";
+
+export type InMemoryRow = Record<string, unknown>;
+
+export type InMemoryIndexDefinition = {
+  name: string;
+  columnNames: string[];
+  unique: boolean;
+};
+
+export type InMemoryIndexStore = {
+  definition: InMemoryIndexDefinition;
+  index: SortedArrayIndex<bigint>;
+};
+
+export type InMemoryTableStore = {
+  rows: Map<bigint, InMemoryRow>;
+  nextInternalId: bigint;
+  indexes: Map<string, InMemoryIndexStore>;
+};
+
+export type InMemoryNamespaceStore = {
+  tables: Map<string, InMemoryTableStore>;
+};
+
+export type InMemoryStore = {
+  namespaces: Map<string, InMemoryNamespaceStore>;
+};
+
+const sqliteSerializer = createSQLSerializer(new SQLocalDriverConfig());
+
+export const normalizeIndexValue = (value: unknown, column: AnyColumn): unknown => {
+  if (value === undefined) {
+    return undefined;
+  }
+  return sqliteSerializer.serialize(value, column);
+};
+
+export const buildIndexKey = (
+  table: AnyTable,
+  index: InMemoryIndexDefinition,
+  row: InMemoryRow,
+  resolver?: NamingResolver,
+): readonly unknown[] => {
+  const columnMap = resolver ? resolver.getColumnNameMap(table) : undefined;
+  return index.columnNames.map((columnName) => {
+    const logicalName = columnMap?.[columnName] ?? columnName;
+    const column = table.columns[logicalName];
+    if (!column) {
+      throw new Error(
+        `Column "${columnName}" not found in table "${table.name}" for index "${index.name}".`,
+      );
+    }
+    return normalizeIndexValue(row[columnName], column);
+  });
+};
+
+const createTableIndexes = (
+  table: AnyTable,
+  resolver?: NamingResolver,
+): Map<string, InMemoryIndexStore> => {
+  const indexes = new Map<string, InMemoryIndexStore>();
+  const primaryIndex = table.indexes["_primary"];
+  const primaryColumnNames = primaryIndex
+    ? primaryIndex.columnNames.map((columnName) =>
+        resolver ? resolver.getColumnName(table.name, columnName) : columnName,
+      )
+    : [
+        resolver
+          ? resolver.getColumnName(table.name, table.getIdColumn().name)
+          : table.getIdColumn().name,
+      ];
+  const primaryDefinition: InMemoryIndexDefinition = {
+    name: "_primary",
+    columnNames: primaryColumnNames,
+    unique: primaryIndex?.unique ?? true,
+  };
+  indexes.set("_primary", {
+    definition: primaryDefinition,
+    index: new SortedArrayIndex(compareNormalizedValues, { unique: primaryDefinition.unique }),
+  });
+
+  for (const [name, index] of Object.entries(table.indexes)) {
+    if (name === "_primary") {
+      continue;
+    }
+    indexes.set(name, {
+      definition: {
+        name,
+        columnNames: index.columnNames.map((columnName) =>
+          resolver ? resolver.getColumnName(table.name, columnName) : columnName,
+        ),
+        unique: index.unique,
+      },
+      index: new SortedArrayIndex(compareNormalizedValues, { unique: index.unique }),
+    });
+  }
+
+  return indexes;
+};
+
+const createTableStore = (table: AnyTable, resolver?: NamingResolver): InMemoryTableStore => ({
+  rows: new Map(),
+  nextInternalId: 1n,
+  indexes: createTableIndexes(table, resolver),
+});
+
+export const createNamespaceStore = (
+  schema: AnySchema,
+  resolver?: NamingResolver,
+): InMemoryNamespaceStore => {
+  const tables = new Map<string, InMemoryTableStore>();
+  for (const tableName of Object.keys(schema.tables)) {
+    const table = schema.tables[tableName];
+    const storeKey = resolver ? resolver.getTableName(table.name) : table.name;
+    tables.set(storeKey, createTableStore(table, resolver));
+  }
+
+  return { tables };
+};
+
+export const createInMemoryStore = (): InMemoryStore => ({
+  namespaces: new Map(),
+});
+
+export const ensureNamespaceStore = (
+  store: InMemoryStore,
+  namespace: string,
+  schema: AnySchema,
+  resolver?: NamingResolver,
+): InMemoryNamespaceStore => {
+  const existing = store.namespaces.get(namespace);
+  if (existing) {
+    return existing;
+  }
+
+  const created = createNamespaceStore(schema, resolver);
+  store.namespaces.set(namespace, created);
+  return created;
+};

package/src/adapters/in-memory/value-comparison.ts

@@ -0,0 +1,53 @@
+const asBuffer = (value: unknown): Buffer | undefined => {
+  if (value instanceof Buffer) {
+    return value;
+  }
+  if (value instanceof Uint8Array) {
+    return Buffer.from(value);
+  }
+  if (value instanceof ArrayBuffer) {
+    return Buffer.from(value);
+  }
+  return undefined;
+};
+
+export const compareNormalizedValues = (left: unknown, right: unknown): number => {
+  if (left === right) {
+    return 0;
+  }
+  if (left === undefined) {
+    return -1;
+  }
+  if (right === undefined) {
+    return 1;
+  }
+  if (left === null) {
+    return -1;
+  }
+  if (right === null) {
+    return 1;
+  }
+  const leftBuffer = asBuffer(left);
+  const rightBuffer = asBuffer(right);
+  if (leftBuffer && rightBuffer) {
+    return Buffer.compare(leftBuffer, rightBuffer);
+  }
+  if (left instanceof Date && right instanceof Date) {
+    return left.getTime() - right.getTime();
+  }
+  if (typeof left === "number" && typeof right === "number") {
+    return left - right;
+  }
+  if (typeof left === "bigint" && typeof right === "bigint") {
+    return left < right ? -1 : 1;
+  }
+  if (typeof left === "string" && typeof right === "string") {
+    return left < right ? -1 : 1;
+  }
+  if (typeof left === "boolean" && typeof right === "boolean") {
+    return left === right ? 0 : left ? 1 : -1;
+  }
+  const leftString = String(left);
+  const rightString = String(right);
+  return leftString < rightString ? -1 : leftString > rightString ? 1 : 0;
+};

package/src/adapters/in-memory/value-normalization.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+
+import { column, idColumn, referenceColumn, schema } from "../../schema/create";
+import { buildIndexKey } from "./store";
+
+const testSchema = schema("test", (s) =>
+  s.addTable("events", (t) =>
+    t
+      .addColumn("id", idColumn())
+      .addColumn("createdAt", column("timestamp"))
+      .addColumn("isActive", column("bool"))
+      .addColumn("payload", column("json"))
+      .addColumn("size", column("bigint"))
+      .addColumn("userId", referenceColumn())
+      .createIndex("compound_idx", ["createdAt", "isActive", "payload", "size", "userId"]),
+  ),
+);
+
+describe("in-memory index normalization", () => {
+  it("normalizes index keys using SQLite serializer semantics", () => {
+    const table = testSchema.tables.events;
+    const index = table.indexes["compound_idx"];
+    if (!index) {
+      throw new Error("compound_idx missing from schema");
+    }
+
+    const createdAt = new Date("2024-01-01T00:00:00.000Z");
+    const payload = { ok: true, count: 2 };
+    const size = 9n;
+    const userId = 12n;
+
+    const row = {
+      id: "evt_1",
+      createdAt,
+      isActive: true,
+      payload,
+      size,
+      userId,
+    };
+
+    const key = buildIndexKey(
+      table,
+      { name: index.name, columnNames: [...index.columnNames], unique: index.unique },
+      row,
+    );
+
+    const expectedBigint = Buffer.alloc(8);
+    expectedBigint.writeBigInt64BE(size);
+
+    expect(key).toEqual([
+      createdAt.getTime(),
+      1,
+      JSON.stringify(payload),
+      expectedBigint,
+      Number(userId),
+    ]);
+  });
+});