@fragno-dev/db 0.2.2 → 0.3.0

package/src/naming/sql-naming.ts

@@ -0,0 +1,180 @@
+import { createHash } from "node:crypto";
+import type { AnySchema, AnyTable } from "../schema/create";
+
+export type NamespaceScope = "suffix" | "schema";
+
+export interface SqlNamingStrategy {
+  namespaceScope: NamespaceScope;
+  namespaceToSchema: (namespace: string) => string;
+
+  tableName: (logicalTable: string, namespace: string | null) => string;
+  columnName: (logicalColumn: string, logicalTable: string) => string;
+
+  indexName: (logicalIndex: string, logicalTable: string, namespace: string | null) => string;
+  uniqueIndexName: (logicalIndex: string, logicalTable: string, namespace: string | null) => string;
+  foreignKeyName: (params: {
+    logicalTable: string;
+    logicalReferencedTable: string;
+    referenceName: string;
+    namespace: string | null;
+  }) => string;
+}
+
+const normalizeNamespace = (namespace: string | null) =>
+  namespace && namespace.length > 0 ? namespace : null;
+
+const buildNamespaceSuffix = (namespace: string | null) => {
+  const sanitized = normalizeNamespace(namespace);
+  return sanitized ? `_${sanitized}` : "";
+};
+
+const MAX_IDENTIFIER_LENGTH = 63;
+const HASH_LENGTH = 8;
+
+const withHash = (value: string) => {
+  const hash = createHash("sha1").update(value).digest("hex").slice(0, 8);
+  return `${value}_${hash}`;
+};
+
+const truncateWithHash = (value: string) => {
+  if (value.length <= MAX_IDENTIFIER_LENGTH) {
+    return value;
+  }
+  const hash = createHash("sha1").update(value).digest("hex").slice(0, HASH_LENGTH);
+  return `${value.slice(0, MAX_IDENTIFIER_LENGTH - HASH_LENGTH)}${hash}`;
+};
+
+const buildIndexName = (
+  prefix: "idx" | "uidx",
+  logicalIndex: string,
+  logicalTable: string,
+  namespace: string | null,
+) => {
+  const base = `${logicalTable}_${logicalIndex}${buildNamespaceSuffix(namespace)}`;
+  return `${prefix}_${withHash(base)}`;
+};
+
+export const suffixNamingStrategy: SqlNamingStrategy = {
+  namespaceScope: "suffix",
+  namespaceToSchema: (namespace) => namespace,
+  tableName: (logicalTable, namespace) => {
+    const sanitized = normalizeNamespace(namespace);
+    return truncateWithHash(sanitized ? `${logicalTable}_${sanitized}` : logicalTable);
+  },
+  columnName: (logicalColumn) => logicalColumn,
+  indexName: (logicalIndex, logicalTable, namespace) =>
+    truncateWithHash(buildIndexName("idx", logicalIndex, logicalTable, namespace)),
+  uniqueIndexName: (logicalIndex, logicalTable, namespace) =>
+    truncateWithHash(buildIndexName("uidx", logicalIndex, logicalTable, namespace)),
+  foreignKeyName: ({ logicalTable, logicalReferencedTable, referenceName, namespace }) => {
+    const base = `${logicalTable}_${logicalReferencedTable}_${referenceName}${buildNamespaceSuffix(namespace)}`;
+    return truncateWithHash(`fk_${withHash(base)}`);
+  },
+};
+
+export const schemaNamingStrategy: SqlNamingStrategy = {
+  namespaceScope: "schema",
+  namespaceToSchema: (namespace) => namespace,
+  tableName: (logicalTable) => truncateWithHash(logicalTable),
+  columnName: (logicalColumn) => logicalColumn,
+  indexName: (logicalIndex) => truncateWithHash(logicalIndex),
+  uniqueIndexName: (logicalIndex) => truncateWithHash(logicalIndex),
+  foreignKeyName: ({ logicalTable, logicalReferencedTable, referenceName }) =>
+    truncateWithHash(`fk_${logicalTable}_${logicalReferencedTable}_${referenceName}`),
+};
+
+export class NamingResolver {
+  readonly #namespace: string | null;
+  readonly #strategy: SqlNamingStrategy;
+  readonly #tableNameMap: Record<string, string> = {};
+  readonly #columnNameMaps = new Map<string, Record<string, string>>();
+
+  constructor(schema: AnySchema, namespace: string | null, strategy: SqlNamingStrategy) {
+    this.#namespace = namespace;
+    this.#strategy = strategy;
+
+    for (const table of Object.values(schema.tables)) {
+      const physicalTable = this.getTableName(table.name);
+      this.#tableNameMap[physicalTable] = table.name;
+
+      const columnMap: Record<string, string> = {};
+      for (const column of Object.values(table.columns)) {
+        const physicalColumn = this.getColumnName(table.name, column.name);
+        columnMap[physicalColumn] = column.name;
+      }
+      this.#columnNameMaps.set(table.name, columnMap);
+    }
+  }
+
+  get namespace(): string | null {
+    return this.#namespace;
+  }
+
+  get strategy(): SqlNamingStrategy {
+    return this.#strategy;
+  }
+
+  getSchemaName(): string | null {
+    if (this.#strategy.namespaceScope !== "schema") {
+      return null;
+    }
+    if (!this.#namespace || this.#namespace.length === 0) {
+      return null;
+    }
+    return this.#strategy.namespaceToSchema(this.#namespace);
+  }
+
+  getTableName(logicalTable: string): string {
+    return this.#strategy.tableName(logicalTable, this.#namespace);
+  }
+
+  getColumnName(logicalTable: string, logicalColumn: string): string {
+    return this.#strategy.columnName(logicalColumn, logicalTable);
+  }
+
+  getIndexName(logicalIndex: string, logicalTable: string): string {
+    return this.#strategy.indexName(logicalIndex, logicalTable, this.#namespace);
+  }
+
+  getUniqueIndexName(logicalIndex: string, logicalTable: string): string {
+    return this.#strategy.uniqueIndexName(logicalIndex, logicalTable, this.#namespace);
+  }
+
+  getForeignKeyName(params: {
+    logicalTable: string;
+    logicalReferencedTable: string;
+    referenceName: string;
+  }): string {
+    return this.#strategy.foreignKeyName({
+      ...params,
+      namespace: this.#namespace,
+    });
+  }
+
+  getTableNameMap(): Record<string, string> {
+    return { ...this.#tableNameMap };
+  }
+
+  getColumnNameMap(table: AnyTable | string): Record<string, string> {
+    const tableName = typeof table === "string" ? table : table.name;
+    const map = this.#columnNameMaps.get(tableName);
+    return map ? { ...map } : {};
+  }
+}
+
+export const createNamingResolver = (
+  schema: AnySchema,
+  namespace: string | null,
+  strategy: SqlNamingStrategy,
+): NamingResolver => new NamingResolver(schema, namespace, strategy);
+
+/**
+ * Sanitizes a namespace for use in SQL identifiers and TypeScript exports.
+ * Converts dashes to underscores to ensure compatibility with SQL identifiers.
+ *
+ * @example
+ * sanitizeNamespace("my-fragment") // => "my_fragment"
+ */
+export function sanitizeNamespace(namespace: string): string {
+  return namespace.replace(/-/g, "_");
+}

package/src/outbox/outbox-builder.ts

@@ -0,0 +1,241 @@
+import type { MutationOperation } from "../query/unit-of-work/unit-of-work";
+import type { AnySchema, AnyTable } from "../schema/create";
+import { FragnoId, FragnoReference } from "../schema/create";
+import { internalSchema } from "../fragments/internal-fragment.schema";
+import type { OutboxRefLookup, OutboxPayload, OutboxMutation } from "./outbox";
+import { encodeVersionstamp, versionstampToHex } from "./outbox";
+
+const INTERNAL_TABLE_NAMES = new Set(Object.keys(internalSchema.tables));
+
+type OutboxMutationDraft = OutboxMutation extends infer T
+  ? T extends OutboxMutation
+    ? Omit<T, "versionstamp"> & { versionstamp?: string }
+    : never
+  : never;
+
+export type OutboxPlan = {
+  drafts: OutboxMutationDraft[];
+  lookups: OutboxRefLookup[];
+};
+
+export function buildOutboxPlan(operations: MutationOperation<AnySchema>[]): OutboxPlan {
+  const drafts: OutboxMutationDraft[] = [];
+  const lookups: OutboxRefLookup[] = [];
+
+  for (const op of operations) {
+    if (op.type === "check") {
+      continue;
+    }
+
+    if (isInternalMutation(op)) {
+      continue;
+    }
+
+    const table = getTable(op.schema, op.table);
+    const schemaName = op.namespace ?? "";
+    const namespace = op.namespace ? op.namespace : undefined;
+    const mutationIndex = drafts.length;
+
+    if (op.type === "create") {
+      drafts.push({
+        op: "create",
+        schema: schemaName,
+        namespace,
+        table: op.table,
+        externalId: op.generatedExternalId,
+        values: encodeOutboxValues({
+          table,
+          values: op.values,
+          mutationIndex,
+          namespace,
+          lookups,
+        }),
+      });
+      continue;
+    }
+
+    if (op.type === "update") {
+      drafts.push({
+        op: "update",
+        schema: schemaName,
+        namespace,
+        table: op.table,
+        externalId: getExternalId(op.id),
+        set: encodeOutboxValues({
+          table,
+          values: op.set,
+          mutationIndex,
+          namespace,
+          lookups,
+        }),
+        checkVersion: op.checkVersion && op.id instanceof FragnoId ? op.id.version : undefined,
+      });
+      continue;
+    }
+
+    if (op.type === "delete") {
+      drafts.push({
+        op: "delete",
+        schema: schemaName,
+        namespace,
+        table: op.table,
+        externalId: getExternalId(op.id),
+        checkVersion: op.checkVersion && op.id instanceof FragnoId ? op.id.version : undefined,
+      });
+    }
+  }
+
+  return { drafts, lookups };
+}
+
+export function finalizeOutboxPayload(plan: OutboxPlan, transactionVersion: bigint): OutboxPayload {
+  const mutations: OutboxMutation[] = plan.drafts.map((draft, index) => {
+    const versionstamp = versionstampToHex(encodeVersionstamp(transactionVersion, index));
+    return { ...draft, versionstamp } as OutboxMutation;
+  });
+
+  return {
+    version: 1,
+    mutations,
+  };
+}
+
+function encodeOutboxValues(options: {
+  table: AnyTable;
+  values: Record<string, unknown>;
+  mutationIndex: number;
+  namespace?: string;
+  lookups: OutboxRefLookup[];
+}): Record<string, unknown> {
+  const { table, values, mutationIndex, namespace, lookups } = options;
+  const output: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(values)) {
+    if (value === undefined) {
+      continue;
+    }
+
+    const column = table.columns[key];
+
+    if (column?.role === "reference") {
+      const resolved = resolveReferenceValue({
+        value,
+        mutationIndex,
+        columnName: key,
+        table,
+        namespace,
+        lookups,
+      });
+      output[key] = resolved;
+      continue;
+    }
+
+    if (value instanceof FragnoId) {
+      output[key] = value.externalId;
+      continue;
+    }
+
+    output[key] = value;
+  }
+
+  return output;
+}
+
+function resolveReferenceValue(options: {
+  value: unknown;
+  mutationIndex: number;
+  columnName: string;
+  table: AnyTable;
+  namespace?: string;
+  lookups: OutboxRefLookup[];
+}): unknown {
+  const { value, mutationIndex, columnName, table, namespace, lookups } = options;
+
+  if (value === null) {
+    return null;
+  }
+
+  if (value instanceof FragnoId) {
+    return value.externalId;
+  }
+
+  if (typeof value === "string") {
+    return value;
+  }
+
+  if (value instanceof FragnoReference) {
+    return createReferencePlaceholder({
+      internalId: value.internalId,
+      mutationIndex,
+      columnName,
+      table,
+      namespace,
+      lookups,
+    });
+  }
+
+  if (typeof value === "bigint" || typeof value === "number") {
+    return createReferencePlaceholder({
+      internalId: value,
+      mutationIndex,
+      columnName,
+      table,
+      namespace,
+      lookups,
+    });
+  }
+
+  return value;
+}
+
+function createReferencePlaceholder(options: {
+  internalId: bigint | number;
+  mutationIndex: number;
+  columnName: string;
+  table: AnyTable;
+  namespace?: string;
+  lookups: OutboxRefLookup[];
+}): { __fragno_ref: string } {
+  const { internalId, mutationIndex, columnName, table, namespace, lookups } = options;
+  const key = `${mutationIndex}.${columnName}`;
+  const referencedTable = resolveReferencedTable(table, columnName);
+
+  lookups.push({
+    key,
+    internalId,
+    table: referencedTable,
+    namespace,
+  });
+
+  return { __fragno_ref: key };
+}
+
+function resolveReferencedTable(table: AnyTable, columnName: string): AnyTable {
+  for (const relation of Object.values(table.relations)) {
+    if (relation.on.some(([localColumn]) => localColumn === columnName)) {
+      return relation.table;
+    }
+  }
+
+  throw new Error(`Reference column ${columnName} not found in table ${table.name}`);
+}
+
+function getExternalId(id: FragnoId | string): string {
+  return typeof id === "string" ? id : id.externalId;
+}
+
+function isInternalMutation(op: MutationOperation<AnySchema>): boolean {
+  if (op.schema === internalSchema) {
+    return true;
+  }
+
+  return op.namespace === "" && INTERNAL_TABLE_NAMES.has(op.table);
+}
+
+function getTable(schema: AnySchema, tableName: string): AnyTable {
+  const table = schema.tables[tableName];
+  if (!table) {
+    throw new Error(`Invalid table name ${tableName}.`);
+  }
+  return table;
+}

package/src/outbox/outbox.test.ts

@@ -0,0 +1,253 @@
+import { describe, expect, it } from "vitest";
+import { defineFragment, instantiate } from "@fragno-dev/core";
+import { SQLocalKysely } from "sqlocal/kysely";
+import { KyselyPGlite } from "kysely-pglite";
+import { PGlite } from "@electric-sql/pglite";
+import superjson, { type SuperJSONResult } from "superjson";
+import { SqlAdapter } from "../adapters/generic-sql/generic-sql-adapter";
+import { PGLiteDriverConfig, SQLocalDriverConfig } from "../adapters/generic-sql/driver-config";
+import type { SimpleQueryInterface } from "../query/simple-query-interface";
+import { withDatabase } from "../with-database";
+import { internalSchema, type InternalFragmentInstance } from "../fragments/internal-fragment";
+import { schema, idColumn, column, referenceColumn, FragnoReference } from "../schema/create";
+import type { OutboxConfig, OutboxEntry, OutboxPayload } from "./outbox";
+
+const outboxSchema = 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 outboxFragmentName = "outbox-test";
+const outboxFragmentDef = defineFragment(outboxFragmentName)
+  .extend(withDatabase(outboxSchema))
+  .build();
+
+type OutboxAdapterConfig =
+  | { type: "kysely-sqlite"; outbox?: OutboxConfig }
+  | { type: "kysely-pglite"; outbox?: OutboxConfig };
+
+type OutboxTestContext = {
+  db: SimpleQueryInterface<typeof outboxSchema>;
+  internalFragment: InternalFragmentInstance;
+  cleanup: () => Promise<void>;
+};
+
+async function migrateSchema(
+  adapter: SqlAdapter,
+  schemaToMigrate: typeof outboxSchema | typeof internalSchema,
+  namespace: string,
+): Promise<void> {
+  const migrations = adapter.prepareMigrations(schemaToMigrate, namespace);
+  await migrations.executeWithDriver(adapter.driver, 0);
+}
+
+async function createAdapter(config: OutboxAdapterConfig): Promise<{
+  adapter: SqlAdapter;
+  cleanup: () => Promise<void>;
+}> {
+  if (config.type === "kysely-sqlite") {
+    const { dialect } = new SQLocalKysely(":memory:");
+    const adapter = new SqlAdapter({
+      dialect,
+      driverConfig: new SQLocalDriverConfig(),
+      outbox: config.outbox,
+    });
+
+    await migrateSchema(adapter, internalSchema, "");
+    await migrateSchema(adapter, outboxSchema, outboxSchema.name);
+
+    return {
+      adapter,
+      cleanup: async () => {
+        await adapter.close();
+      },
+    };
+  }
+
+  const pgliteDatabase = new PGlite();
+  const { dialect } = new KyselyPGlite(pgliteDatabase);
+  const adapter = new SqlAdapter({
+    dialect,
+    driverConfig: new PGLiteDriverConfig(),
+    outbox: config.outbox,
+  });
+
+  await migrateSchema(adapter, internalSchema, "");
+  await migrateSchema(adapter, outboxSchema, outboxSchema.name);
+
+  return {
+    adapter,
+    cleanup: async () => {
+      await adapter.close();
+    },
+  };
+}
+
+async function buildOutboxTest(adapterConfig: OutboxAdapterConfig): Promise<OutboxTestContext> {
+  const { adapter, cleanup } = await createAdapter(adapterConfig);
+  const fragment = instantiate(outboxFragmentDef)
+    .withConfig({})
+    .withRoutes([])
+    .withOptions({ databaseAdapter: adapter })
+    .build();
+  const deps = fragment.$internal.deps as { db: SimpleQueryInterface<typeof outboxSchema> };
+
+  return {
+    db: deps.db,
+    internalFragment: fragment.$internal.linkedFragments._fragno_internal,
+    cleanup,
+  };
+}
+
+async function listOutbox(
+  internalFragment: InternalFragmentInstance,
+  options?: { afterVersionstamp?: string; limit?: number },
+): Promise<OutboxEntry[]> {
+  return internalFragment.inContext(async function () {
+    return (await this.handlerTx()
+      .withServiceCalls(() => [internalFragment.services.outboxService.list(options)] as const)
+      .transform(({ serviceResult: [result] }) => result)
+      .execute()) as OutboxEntry[];
+  });
+}
+
+const adapterConfigs = [{ type: "kysely-sqlite" as const }, { type: "kysely-pglite" as const }];
+
+describe("Fragno DB Outbox", () => {
+  it("does not write outbox entries when disabled", async () => {
+    const { db, internalFragment, cleanup } = await buildOutboxTest({
+      type: "kysely-sqlite",
+    });
+
+    await db.create("users", { email: "disabled@example.com" });
+
+    const entries = await listOutbox(internalFragment);
+    expect(entries).toHaveLength(0);
+
+    await cleanup();
+  });
+
+  it("stores refMap placeholders and lists entries in order", async () => {
+    const { db, internalFragment, cleanup } = await buildOutboxTest({
+      type: "kysely-sqlite",
+      outbox: { enabled: true },
+    });
+
+    await db.create("users", { email: "alpha@example.com" });
+    const user = await db.findFirst("users", (b) =>
+      b.whereIndex("idx_users_email", (eb) => eb("email", "=", "alpha@example.com")),
+    );
+    expect(user).not.toBeNull();
+    expect(user?.id.internalId).toBeDefined();
+
+    await db.create("posts", {
+      title: "Hello",
+      authorId: FragnoReference.fromInternal(user!.id.internalId!),
+    });
+
+    const entries = await listOutbox(internalFragment);
+    expect(entries).toHaveLength(2);
+    expect(entries[0].versionstamp < entries[1].versionstamp).toBe(true);
+
+    const filtered = await listOutbox(internalFragment, {
+      afterVersionstamp: entries[0].versionstamp,
+      limit: 1,
+    });
+    expect(filtered).toHaveLength(1);
+    expect(filtered[0].versionstamp).toBe(entries[1].versionstamp);
+
+    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": user!.id.externalId,
+    });
+
+    await internalFragment.inContext(async function () {
+      await this.handlerTx()
+        .withServiceCalls(() => [
+          internalFragment.services.settingsService.set("outbox-test", "noop", "1"),
+        ])
+        .execute();
+    });
+
+    const afterInternal = await listOutbox(internalFragment);
+    expect(afterInternal).toHaveLength(2);
+
+    await cleanup();
+  });
+
+  it("orders outbox entries by commit order across concurrent UOWs", async () => {
+    const { db, internalFragment, cleanup } = await buildOutboxTest({
+      type: "kysely-sqlite",
+      outbox: { enabled: true },
+    });
+
+    const uow1 = db.createUnitOfWork("uow-1");
+    const uow2 = db.createUnitOfWork("uow-2");
+    const uow1Id = uow1.idempotencyKey;
+    const uow2Id = uow2.idempotencyKey;
+
+    uow1.create("users", { email: "order-1@example.com" });
+    uow2.create("users", { email: "order-2@example.com" });
+
+    const completionOrder: string[] = [];
+    await Promise.all([
+      uow1.executeMutations().then(() => completionOrder.push(uow1Id)),
+      uow2.executeMutations().then(() => completionOrder.push(uow2Id)),
+    ]);
+
+    const entries = await listOutbox(internalFragment);
+    expect(entries.map((entry) => entry.uowId)).toEqual(completionOrder);
+    expect(entries[0].versionstamp < entries[1].versionstamp).toBe(true);
+
+    await cleanup();
+  });
+
+  describe.each(adapterConfigs)("adapter opt-in (%s)", (adapterConfig) => {
+    it("writes outbox rows only when enabled", async () => {
+      const { db, internalFragment, cleanup } = await buildOutboxTest(adapterConfig);
+
+      await db.create("users", { email: "disabled@example.com" });
+      const disabledEntries = await listOutbox(internalFragment);
+      expect(disabledEntries).toHaveLength(0);
+      await cleanup();
+
+      const {
+        db: enabledDb,
+        internalFragment: enabledInternal,
+        cleanup: enabledCleanup,
+      } = await buildOutboxTest({
+        ...adapterConfig,
+        outbox: { enabled: true },
+      });
+      await enabledDb.create("users", { email: "enabled@example.com" });
+      const enabledEntries = await listOutbox(enabledInternal);
+      expect(enabledEntries).toHaveLength(1);
+      await enabledCleanup();
+    }, 10_000);
+  });
+});