@fragno-dev/db 0.2.2 → 0.4.1

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,42 @@
+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,91 @@
+import { createId, init } from "@fragno-dev/core";
+
+import type { SqlNamingStrategy } from "../../naming/sql-naming";
+import type { OutboxConfig } from "../../outbox/outbox";
+
+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;
+  outbox?: OutboxConfig;
+};
+
+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,
+    outbox: undefined,
+  };
+};

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

@@ -0,0 +1,361 @@
+import { describe, expect, it } from "vitest";
+
+import superjson, { type SuperJSONResult } from "superjson";
+
+import { defineFragment, instantiate } from "@fragno-dev/core";
+
+import type { InternalFragmentInstance } from "../../fragments/internal-fragment";
+import { internalSchema } from "../../fragments/internal-fragment";
+import { getInternalFragment } from "../../internal/adapter-registry";
+import type { AnyFragnoInstantiatedDatabaseFragment, DatabaseRequestContext } from "../../mod";
+import type { OutboxEntry, OutboxPayload } from "../../outbox/outbox";
+import { schema, idColumn, column, referenceColumn, FragnoReference } from "../../schema/create";
+import { withDatabase } from "../../with-database";
+import { InMemoryAdapter } from "./in-memory-adapter";
+
+const buildOutboxSchema = () =>
+  schema("outbox", (s) => {
+    return s
+      .addTable("users", (t) => {
+        return t
+          .addColumn("id", idColumn())
+          .addColumn("email", column("string"))
+          .createIndex("idx_users_email", ["email"], { unique: true });
+      })
+      .addTable("posts", (t) => {
+        return t
+          .addColumn("id", idColumn())
+          .addColumn("authorId", referenceColumn())
+          .addColumn("title", column("string"));
+      })
+      .addReference("author", {
+        type: "one",
+        from: { table: "posts", column: "authorId" },
+        to: { table: "users", column: "id" },
+      });
+  });
+
+const outboxSchema = buildOutboxSchema();
+
+const outboxFragmentName = "outbox-in-memory-test";
+const outboxFragmentDef = defineFragment(outboxFragmentName)
+  .extend(withDatabase(outboxSchema))
+  .build();
+
+type OutboxTestContext = {
+  fragment: AnyFragnoInstantiatedDatabaseFragment<typeof outboxSchema>;
+  internalFragment: InternalFragmentInstance;
+  cleanup: () => Promise<void>;
+};
+
+async function buildOutboxTest(options: { outboxEnabled?: boolean }): Promise<OutboxTestContext> {
+  const adapter = new InMemoryAdapter({
+    idSeed: "outbox-seed",
+  });
+
+  const fragment = instantiate(outboxFragmentDef)
+    .withConfig({})
+    .withRoutes([])
+    .withOptions({
+      databaseAdapter: adapter,
+      outbox: options.outboxEnabled ? { enabled: true } : undefined,
+    })
+    .build();
+
+  return {
+    fragment,
+    internalFragment: getInternalFragment(adapter),
+    cleanup: async () => {
+      await adapter.close();
+    },
+  };
+}
+
+async function listOutbox(
+  internalFragment: InternalFragmentInstance,
+  options?: { afterVersionstamp?: string; limit?: number },
+): Promise<OutboxEntry[]> {
+  return internalFragment.inContext(async function (this: DatabaseRequestContext) {
+    return (await this.handlerTx()
+      .withServiceCalls(() => [internalFragment.services.outboxService.list(options)] as const)
+      .transform(({ serviceResult: [result] }) => result)
+      .execute()) as OutboxEntry[];
+  });
+}
+
+async function listOutboxMutations(internalFragment: InternalFragmentInstance): Promise<
+  Array<{
+    entryVersionstamp: string;
+    mutationVersionstamp: string;
+    uowId: string;
+    schema: string;
+    table: string;
+    externalId: string;
+    op: string;
+  }>
+> {
+  return internalFragment.inContext(async function (this: DatabaseRequestContext) {
+    return await this.handlerTx()
+      .retrieve(({ forSchema }) =>
+        forSchema(internalSchema).find("fragno_db_outbox_mutations", (b) =>
+          b
+            .whereIndex("idx_outbox_mutations_entry")
+            .orderByIndex("idx_outbox_mutations_entry", "asc"),
+        ),
+      )
+      .transformRetrieve(([result]) => result)
+      .execute();
+  });
+}
+
+async function createUser(
+  fragment: AnyFragnoInstantiatedDatabaseFragment<typeof outboxSchema>,
+  email: string,
+) {
+  return fragment.inContext(async function (this: DatabaseRequestContext) {
+    await this.handlerTx()
+      .mutate(({ forSchema }) => forSchema(outboxSchema).create("users", { email }))
+      .execute();
+
+    const user = await this.handlerTx()
+      .retrieve(({ forSchema }) =>
+        forSchema(outboxSchema).findFirst("users", (b) =>
+          b.whereIndex("idx_users_email", (eb) => eb("email", "=", email)),
+        ),
+      )
+      .transformRetrieve(([result]) => result)
+      .execute();
+
+    if (!user) {
+      throw new Error("Expected user to be created.");
+    }
+
+    return user.id;
+  });
+}
+
+async function createPost(
+  fragment: AnyFragnoInstantiatedDatabaseFragment<typeof outboxSchema>,
+  title: string,
+  authorId: FragnoReference,
+) {
+  return fragment.inContext(async function (this: DatabaseRequestContext) {
+    return await this.handlerTx()
+      .mutate(({ forSchema }) => forSchema(outboxSchema).create("posts", { title, authorId }))
+      .transform(({ mutateResult }) => mutateResult)
+      .execute();
+  });
+}
+
+describe("in-memory outbox", () => {
+  it("does not write outbox entries when disabled", async () => {
+    const { fragment, internalFragment, cleanup } = await buildOutboxTest({
+      outboxEnabled: false,
+    });
+
+    await createUser(fragment, "disabled@example.com");
+
+    const entries = await listOutbox(internalFragment);
+    expect(entries).toHaveLength(0);
+    const mutations = await listOutboxMutations(internalFragment);
+    expect(mutations).toHaveLength(0);
+
+    await cleanup();
+  });
+
+  it("stores refMap placeholders and lists entries in order", async () => {
+    const { fragment, internalFragment, cleanup } = await buildOutboxTest({ outboxEnabled: true });
+
+    const userId = await createUser(fragment, "alpha@example.com");
+    expect(userId.internalId).toBeDefined();
+
+    await createPost(fragment, "Hello", FragnoReference.fromInternal(userId.internalId!));
+
+    const entries = await listOutbox(internalFragment);
+    expect(entries).toHaveLength(2);
+    expect(entries[0].versionstamp < entries[1].versionstamp).toBe(true);
+
+    const payload = superjson.deserialize(entries[1].payload as SuperJSONResult) as OutboxPayload;
+    expect(payload.version).toBe(1);
+    expect(payload.mutations).toHaveLength(1);
+    const [mutation] = payload.mutations;
+    if (mutation.op !== "create") {
+      throw new Error("Expected create mutation in outbox payload.");
+    }
+    expect(mutation.values).toMatchObject({
+      authorId: { __fragno_ref: "0.authorId" },
+    });
+    expect(entries[1].refMap).toEqual({
+      "0.authorId": userId.externalId,
+    });
+
+    await cleanup();
+  });
+
+  it("writes mutation log rows for each outbox entry", async () => {
+    const { fragment, internalFragment, cleanup } = await buildOutboxTest({
+      outboxEnabled: true,
+    });
+
+    const userId = await createUser(fragment, "log-alpha@example.com");
+    expect(userId.internalId).toBeDefined();
+
+    await createPost(fragment, "Log", FragnoReference.fromInternal(userId.internalId!));
+
+    const entries = await listOutbox(internalFragment);
+    const mutations = await listOutboxMutations(internalFragment);
+
+    expect(entries).toHaveLength(2);
+    expect(mutations).toHaveLength(2);
+
+    const entryByVersion = new Map(entries.map((entry) => [entry.versionstamp, entry]));
+
+    for (const entry of entries) {
+      const payload = superjson.deserialize(entry.payload as SuperJSONResult) as OutboxPayload;
+      expect(payload.mutations).toHaveLength(1);
+    }
+
+    for (const mutationRow of mutations) {
+      const entry = entryByVersion.get(mutationRow.entryVersionstamp);
+      expect(entry).toBeDefined();
+      const payload = superjson.deserialize(entry!.payload as SuperJSONResult) as OutboxPayload;
+      const mutation = payload.mutations[0];
+      expect(mutationRow.mutationVersionstamp).toBe(mutation.versionstamp);
+      expect(mutationRow.uowId).toBe(entry!.uowId);
+      expect(mutationRow.schema).toBe(mutation.schema);
+      expect(mutationRow.table).toBe(mutation.table);
+      expect(mutationRow.externalId).toBe(mutation.externalId);
+      expect(mutationRow.op).toBe(mutation.op);
+    }
+
+    await cleanup();
+  });
+
+  it("resolves refMap lookups within the correct namespace", async () => {
+    const adapter = new InMemoryAdapter({
+      idSeed: "outbox-seed",
+    });
+
+    try {
+      const schemaA = buildOutboxSchema();
+      const schemaB = buildOutboxSchema();
+
+      const fragmentDefA = defineFragment(`${outboxFragmentName}-a`)
+        .extend(withDatabase(schemaA))
+        .build();
+      const fragmentDefB = defineFragment(`${outboxFragmentName}-b`)
+        .extend(withDatabase(schemaB))
+        .build();
+
+      const fragmentA = instantiate(fragmentDefA)
+        .withConfig({})
+        .withRoutes([])
+        .withOptions({
+          databaseAdapter: adapter,
+          databaseNamespace: "tenant-a",
+          outbox: { enabled: true },
+        })
+        .build();
+      const fragmentB = instantiate(fragmentDefB)
+        .withConfig({})
+        .withRoutes([])
+        .withOptions({
+          databaseAdapter: adapter,
+          databaseNamespace: "tenant-b",
+          outbox: { enabled: true },
+        })
+        .build();
+
+      const userA = await fragmentA.inContext(async function (this: DatabaseRequestContext) {
+        await this.handlerTx()
+          .mutate(({ forSchema }) =>
+            forSchema(schemaA).create("users", { email: "tenant-a@example.com" }),
+          )
+          .execute();
+
+        const user = await this.handlerTx()
+          .retrieve(({ forSchema }) =>
+            forSchema(schemaA).findFirst("users", (b) =>
+              b.whereIndex("idx_users_email", (eb) => eb("email", "=", "tenant-a@example.com")),
+            ),
+          )
+          .transformRetrieve(([result]) => result)
+          .execute();
+
+        if (!user) {
+          throw new Error("Expected user to be created.");
+        }
+
+        return user.id;
+      });
+
+      const userB = await fragmentB.inContext(async function (this: DatabaseRequestContext) {
+        await this.handlerTx()
+          .mutate(({ forSchema }) =>
+            forSchema(schemaB).create("users", { email: "tenant-b@example.com" }),
+          )
+          .execute();
+
+        const user = await this.handlerTx()
+          .retrieve(({ forSchema }) =>
+            forSchema(schemaB).findFirst("users", (b) =>
+              b.whereIndex("idx_users_email", (eb) => eb("email", "=", "tenant-b@example.com")),
+            ),
+          )
+          .transformRetrieve(([result]) => result)
+          .execute();
+
+        if (!user) {
+          throw new Error("Expected user to be created.");
+        }
+
+        return user.id;
+      });
+
+      expect(userA.internalId).toBeDefined();
+      expect(userB.internalId).toBeDefined();
+      expect(userA.internalId).toBe(userB.internalId);
+
+      await fragmentB.inContext(async function (this: DatabaseRequestContext) {
+        await this.handlerTx()
+          .mutate(({ forSchema }) =>
+            forSchema(schemaB).create("posts", {
+              title: "Hello",
+              authorId: FragnoReference.fromInternal(userB.internalId!),
+            }),
+          )
+          .execute();
+      });
+
+      const entries = await listOutbox(getInternalFragment(adapter));
+      let postEntry: OutboxEntry | undefined;
+      let postPayload: OutboxPayload | undefined;
+
+      for (const entry of entries) {
+        const payload = superjson.deserialize(entry.payload as SuperJSONResult) as OutboxPayload;
+        if (
+          payload.mutations.some(
+            (mutation) =>
+              mutation.op === "create" &&
+              mutation.table === "posts" &&
+              mutation.namespace === "tenant-b",
+          )
+        ) {
+          postEntry = entry;
+          postPayload = payload;
+          break;
+        }
+      }
+
+      if (!postEntry || !postPayload) {
+        throw new Error("Expected outbox entry for tenant-b posts.");
+      }
+
+      expect(postEntry.refMap).toEqual({
+        "0.authorId": userB.externalId,
+      });
+    } finally {
+      await adapter.close();
+    }
+  });
+});

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

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+
+import { ReferenceSubquery } from "../../query/value-encoding";
+import { column, idColumn, referenceColumn, schema } from "../../schema/create";
+import { resolveReferenceSubqueries } from "./reference-resolution";
+import { createInMemoryStore, ensureNamespaceStore } from "./store";
+
+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 { NamingResolver } from "../../naming/sql-naming";
+import { ReferenceSubquery } from "../../query/value-encoding";
+import type { AnyTable } from "../../schema/create";
+import type { InMemoryNamespaceStore, InMemoryTableStore } from "./store";
+
+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;
+};