@fragno-dev/db 0.2.2 → 0.4.1

package/src/internal/adapter-registry.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest";
+
+import SQLite from "better-sqlite3";
+import { SqliteDialect } from "kysely";
+
+import { BetterSQLite3DriverConfig } from "../adapters/generic-sql/driver-config";
+import { SqlAdapter } from "../adapters/generic-sql/generic-sql-adapter";
+import { getRegistryForAdapterSync } from "./adapter-registry";
+import { getOutboxConfigForAdapter } from "./outbox-state";
+
+describe("adapter registry", () => {
+  it("returns the same registry for the same adapter instance", async () => {
+    const sqlite = new SQLite(":memory:");
+    const adapter = new SqlAdapter({
+      dialect: new SqliteDialect({ database: sqlite }),
+      driverConfig: new BetterSQLite3DriverConfig(),
+    });
+
+    const registryA = getRegistryForAdapterSync(adapter);
+    const registryB = getRegistryForAdapterSync(adapter);
+
+    expect(registryA).toBe(registryB);
+    expect(registryA.internalFragment).toBeTruthy();
+
+    await adapter.close();
+    sqlite.close();
+  });
+
+  it("keeps registries isolated across adapter instances", async () => {
+    const sqliteA = new SQLite(":memory:");
+    const adapterA = new SqlAdapter({
+      dialect: new SqliteDialect({ database: sqliteA }),
+      driverConfig: new BetterSQLite3DriverConfig(),
+    });
+
+    const sqliteB = new SQLite(":memory:");
+    const adapterB = new SqlAdapter({
+      dialect: new SqliteDialect({ database: sqliteB }),
+      driverConfig: new BetterSQLite3DriverConfig(),
+    });
+
+    const registryA = getRegistryForAdapterSync(adapterA);
+    const registryB = getRegistryForAdapterSync(adapterB);
+
+    registryA.registerSchema(
+      {
+        name: "alpha",
+        namespace: "alpha",
+        version: 1,
+        tables: ["alpha_items"],
+      },
+      { name: "alpha-fragment", mountRoute: "/alpha" },
+      { outboxEnabled: true },
+    );
+
+    expect(registryA.listSchemas()).toHaveLength(1);
+    expect(registryB.listSchemas()).toHaveLength(0);
+
+    await adapterA.close();
+    await adapterB.close();
+    sqliteA.close();
+    sqliteB.close();
+  });
+
+  it("enables adapter outbox config when a fragment opts in", async () => {
+    const sqlite = new SQLite(":memory:");
+    const adapter = new SqlAdapter({
+      dialect: new SqliteDialect({ database: sqlite }),
+      driverConfig: new BetterSQLite3DriverConfig(),
+    });
+
+    const outboxConfig = getOutboxConfigForAdapter(adapter);
+    expect(outboxConfig.enabled).toBe(false);
+
+    const registry = getRegistryForAdapterSync(adapter);
+    registry.registerSchema(
+      {
+        name: "alpha",
+        namespace: "alpha",
+        version: 1,
+        tables: ["alpha_items"],
+      },
+      { name: "alpha-fragment", mountRoute: "/alpha" },
+      { outboxEnabled: true },
+    );
+
+    expect(outboxConfig.enabled).toBe(true);
+    expect(registry.isOutboxEnabled()).toBe(true);
+
+    await adapter.close();
+    sqlite.close();
+  });
+});

package/src/internal/adapter-registry.ts

@@ -0,0 +1,239 @@
+import { instantiate } from "@fragno-dev/core";
+
+import type { DatabaseAdapter } from "../adapters/adapters";
+import {
+  SchemaRegistryCollisionError,
+  internalFragmentDef,
+  type InternalFragmentInstance,
+} from "../fragments/internal-fragment";
+import {
+  createInternalFragmentDescribeRoutes,
+  createInternalFragmentOutboxRoutes,
+  createInternalFragmentSyncRoutes,
+} from "../fragments/internal-fragment.routes";
+import type { SyncCommandDefinition, SyncCommandTargetRegistration } from "../sync/types";
+import { getOutboxStateForAdapter, type OutboxState } from "./outbox-state";
+
+export type SchemaInfo = {
+  name: string;
+  namespace: string | null;
+  version: number;
+  tables: string[];
+};
+
+export type FragmentMeta = {
+  name: string;
+  mountRoute: string;
+};
+
+export type SyncCommandTarget = {
+  fragmentName: string;
+  schemaName: string;
+  namespace: string | null;
+  commands: Map<string, SyncCommandDefinition>;
+};
+
+export type AdapterRegistry = {
+  internalFragment: InternalFragmentInstance;
+  schemas: Map<string, SchemaInfo>;
+  fragments: Map<string, FragmentMeta>;
+  outboxState: OutboxState;
+  syncCommandTargets: Map<string, SyncCommandTarget>;
+  registerSchema: (
+    schema: SchemaInfo,
+    fragment: FragmentMeta,
+    options?: { outboxEnabled?: boolean },
+  ) => void;
+  registerSyncCommands: (registration: SyncCommandTargetRegistration) => void;
+  resolveSyncTarget: (fragmentName: string, schemaName: string) => SyncCommandTarget | undefined;
+  resolveSyncCommand: (
+    fragmentName: string,
+    schemaName: string,
+    commandName: string,
+  ) => { command: SyncCommandDefinition; namespace: string | null } | undefined;
+  listSchemas: () => SchemaInfo[];
+  listFragments: () => FragmentMeta[];
+  listOutboxFragments: () => FragmentMeta[];
+  isOutboxEnabled: () => boolean;
+};
+
+type AdapterKey = DatabaseAdapter<unknown>;
+
+const registryByAdapter = new WeakMap<AdapterKey, AdapterRegistry>();
+
+const toAdapterKey = <TUOWConfig>(adapter: DatabaseAdapter<TUOWConfig>): AdapterKey =>
+  adapter as AdapterKey;
+
+const isDryRun = (): boolean => process.env["FRAGNO_INIT_DRY_RUN"] === "true";
+
+const getNamespaceKey = (schema: SchemaInfo): string => schema.namespace ?? schema.name;
+const getSyncTargetKey = (fragmentName: string, schemaName: string): string =>
+  `${fragmentName}::${schemaName}`;
+
+const sortSchemas = (schemas: SchemaInfo[]): SchemaInfo[] =>
+  schemas.sort((a, b) => {
+    const namespaceA = a.namespace ?? "";
+    const namespaceB = b.namespace ?? "";
+    if (namespaceA !== namespaceB) {
+      return namespaceA.localeCompare(namespaceB);
+    }
+    if (a.name !== b.name) {
+      return a.name.localeCompare(b.name);
+    }
+    return a.version - b.version;
+  });
+
+const sortFragments = (fragments: FragmentMeta[]): FragmentMeta[] =>
+  fragments.sort((a, b) => a.name.localeCompare(b.name));
+
+const buildInternalFragment = (
+  adapter: DatabaseAdapter<unknown>,
+  registry: AdapterRegistry,
+): InternalFragmentInstance => {
+  const routes = [
+    createInternalFragmentDescribeRoutes(),
+    createInternalFragmentOutboxRoutes(),
+    createInternalFragmentSyncRoutes(),
+  ];
+
+  return instantiate(internalFragmentDef)
+    .withConfig({ registry })
+    .withOptions({ databaseAdapter: adapter, databaseNamespace: null })
+    .withRoutes(routes)
+    .build();
+};
+
+const createRegistry = (adapter: DatabaseAdapter<unknown>): AdapterRegistry => {
+  const schemas = new Map<string, SchemaInfo>();
+  const fragments = new Map<string, FragmentMeta>();
+  const outboxState = getOutboxStateForAdapter(adapter);
+  const syncCommandTargets = new Map<string, SyncCommandTarget>();
+  let registry: AdapterRegistry;
+
+  registry = {
+    internalFragment: undefined as unknown as InternalFragmentInstance,
+    schemas,
+    fragments,
+    outboxState,
+    syncCommandTargets,
+    registerSchema: (schema, fragment, options) => {
+      const namespaceKey = getNamespaceKey(schema);
+      const existing = schemas.get(namespaceKey);
+      if (existing && (existing.name !== schema.name || existing.namespace !== schema.namespace)) {
+        throw new SchemaRegistryCollisionError({
+          namespaceKey,
+          existing: { name: existing.name, namespace: existing.namespace },
+          attempted: { name: schema.name, namespace: schema.namespace },
+        });
+      }
+      const schemaCopy = { ...schema, tables: [...schema.tables] };
+      if (
+        existing &&
+        existing.name === schemaCopy.name &&
+        existing.namespace === schemaCopy.namespace &&
+        existing.version === schemaCopy.version &&
+        existing.tables.length === schemaCopy.tables.length &&
+        existing.tables.every((table, index) => table === schemaCopy.tables[index])
+      ) {
+        fragments.set(fragment.name, { ...fragment });
+        if (options?.outboxEnabled) {
+          outboxState.enabledSchemaKeys.add(namespaceKey);
+          outboxState.enabledFragments.add(fragment.name);
+          outboxState.config.enabled = true;
+        }
+        return;
+      }
+      schemas.set(namespaceKey, schemaCopy);
+      fragments.set(fragment.name, { ...fragment });
+      if (options?.outboxEnabled) {
+        outboxState.enabledSchemaKeys.add(namespaceKey);
+        outboxState.enabledFragments.add(fragment.name);
+        outboxState.config.enabled = true;
+      }
+    },
+    registerSyncCommands: (registration) => {
+      const key = getSyncTargetKey(registration.fragmentName, registration.schemaName);
+      const existing = syncCommandTargets.get(key);
+      if (existing) {
+        const commandsMatch =
+          existing.commands.size === registration.commands.size &&
+          [...existing.commands.entries()].every(
+            ([name, command]) => registration.commands.get(name) === command,
+          );
+        if (
+          existing.namespace !== registration.namespace ||
+          existing.fragmentName !== registration.fragmentName ||
+          existing.schemaName !== registration.schemaName ||
+          !commandsMatch
+        ) {
+          throw new Error(
+            `Sync commands for ${registration.fragmentName}/${registration.schemaName} are already registered.`,
+          );
+        }
+        return;
+      }
+      syncCommandTargets.set(key, {
+        fragmentName: registration.fragmentName,
+        schemaName: registration.schemaName,
+        namespace: registration.namespace,
+        commands: new Map(registration.commands),
+      });
+    },
+    resolveSyncTarget: (fragmentName, schemaName) => {
+      const key = getSyncTargetKey(fragmentName, schemaName);
+      return syncCommandTargets.get(key);
+    },
+    resolveSyncCommand: (fragmentName, schemaName, commandName) => {
+      const target = registry.resolveSyncTarget(fragmentName, schemaName);
+      if (!target) {
+        return undefined;
+      }
+      const command = target.commands.get(commandName);
+      if (!command) {
+        return undefined;
+      }
+      return { command, namespace: target.namespace };
+    },
+    listSchemas: () => sortSchemas([...schemas.values()]),
+    listFragments: () => sortFragments([...fragments.values()]),
+    listOutboxFragments: () =>
+      sortFragments(
+        [...fragments.values()].filter((fragment) =>
+          outboxState.enabledFragments.has(fragment.name),
+        ),
+      ),
+    isOutboxEnabled: () => outboxState.config.enabled,
+  };
+
+  registry.internalFragment = buildInternalFragment(adapter, registry);
+  return registry;
+};
+
+export const getRegistryForAdapterSync = <TUOWConfig>(
+  adapter: DatabaseAdapter<TUOWConfig>,
+): AdapterRegistry => {
+  const adapterKey = toAdapterKey(adapter);
+  const existing = registryByAdapter.get(adapterKey);
+  if (existing) {
+    return existing;
+  }
+  if (isDryRun()) {
+    throw new Error("Adapter registry is unavailable during dry-run initialization.");
+  }
+
+  const registry = createRegistry(adapterKey);
+  registryByAdapter.set(adapterKey, registry);
+  return registry;
+};
+
+export const getInternalFragment = <TUOWConfig>(
+  adapter: DatabaseAdapter<TUOWConfig>,
+): InternalFragmentInstance => {
+  const adapterKey = toAdapterKey(adapter);
+  if (isDryRun()) {
+    return instantiate(internalFragmentDef)
+      .withOptions({ databaseAdapter: adapterKey, databaseNamespace: null })
+      .build();
+  }
+  return getRegistryForAdapterSync(adapterKey).internalFragment;
+};

package/src/internal/outbox-state.ts

@@ -0,0 +1,43 @@
+import type { DatabaseAdapter } from "../adapters/adapters";
+import type { OutboxConfig } from "../outbox/outbox";
+import type { MutationOperation } from "../query/unit-of-work/unit-of-work";
+import type { AnySchema } from "../schema/create";
+
+export type OutboxState = {
+  config: OutboxConfig;
+  enabledSchemaKeys: Set<string>;
+  enabledFragments: Set<string>;
+};
+
+type AdapterKey = DatabaseAdapter<unknown>;
+
+const outboxStateByAdapter = new WeakMap<AdapterKey, OutboxState>();
+
+const getOperationNamespaceKey = (operation: MutationOperation<AnySchema>): string =>
+  operation.namespace ?? operation.schema.name;
+
+const createOutboxState = (): OutboxState => {
+  const enabledSchemaKeys = new Set<string>();
+  const enabledFragments = new Set<string>();
+  const config: OutboxConfig = {
+    enabled: false,
+    shouldInclude: (operation) => enabledSchemaKeys.has(getOperationNamespaceKey(operation)),
+  };
+
+  return { config, enabledSchemaKeys, enabledFragments };
+};
+
+export const getOutboxStateForAdapter = (adapter: AdapterKey): OutboxState => {
+  const existing = outboxStateByAdapter.get(adapter);
+  if (existing) {
+    return existing;
+  }
+
+  const state = createOutboxState();
+  outboxStateByAdapter.set(adapter, state);
+  return state;
+};
+
+export const getOutboxConfigForAdapter = <TUOWConfig>(
+  adapter: DatabaseAdapter<TUOWConfig>,
+): OutboxConfig => getOutboxStateForAdapter(adapter as AdapterKey).config;

package/src/migration-engine/auto-from-schema.test.ts

@@ -1,10 +1,11 @@
 import { describe, expect, it } from "vitest";
+
 import { column, idColumn, referenceColumn, schema } from "../schema/create";
 import { generateMigrationFromSchema } from "./auto-from-schema";
 
 describe("generateMigrationFromSchema", () => {
   it("should generate create-table operation for new tables", () => {
-    const mySchema = schema((s) => {
+    const mySchema = schema("my", (s) => {
       return s
         .addTable("users", (t) => {
           return t.addColumn("id", idColumn()).addColumn("name", column("string"));
@@ -35,7 +36,7 @@ describe("generateMigrationFromSchema", () => {
   });
 
   it("should generate multiple table operations in sequence", () => {
-    const mySchema = schema((s) => {
+    const mySchema = schema("my", (s) => {
       return s
         .addTable("users", (t) => {
           return t.addColumn("id", idColumn()).addColumn("name", column("string"));
@@ -79,7 +80,7 @@ describe("generateMigrationFromSchema", () => {
   });
 
   it("should generate add-foreign-key operation for new foreign keys", () => {
-    const mySchema = schema((s) => {
+    const mySchema = schema("my", (s) => {
       return s
         .addTable("users", (t) => {
           return t.addColumn("id", idColumn());
@@ -108,7 +109,7 @@ describe("generateMigrationFromSchema", () => {
     const fkOp = operations[0];
     if (fkOp.type === "add-foreign-key") {
       expect(fkOp.value).toMatchObject({
-        name: "posts_users_author_fk",
+        name: "author",
         referencedTable: "users",
         columns: ["authorId"],
         referencedColumns: ["_internalId"],
@@ -116,8 +117,39 @@ describe("generateMigrationFromSchema", () => {
     }
   });
 
+  it("should skip add-foreign-key operation for join-only references", () => {
+    const mySchema = schema("my", (s) => {
+      return s
+        .addTable("users", (t) => {
+          return t
+            .addColumn("id", idColumn())
+            .addColumn("email", column("string"))
+            .createIndex("idx_users_email", ["email"]);
+        })
+        .addTable("invitations", (t) => {
+          return t
+            .addColumn("id", idColumn())
+            .addColumn("email", column("string"))
+            .createIndex("idx_inv_email", ["email"]);
+        })
+        .addReference("invitedUser", {
+          type: "one",
+          from: { table: "invitations", column: "email" },
+          to: { table: "users", column: "email" },
+          foreignKey: false,
+        });
+    });
+
+    // Version 0 -> 1: users table
+    // Version 1 -> 2: invitations table
+    // Version 2 -> 3: join-only relation (no FK)
+    const operations = generateMigrationFromSchema(mySchema, 2, 3);
+
+    expect(operations).toHaveLength(0);
+  });
+
   it("should generate add-index operation for indexes added via alterTable", () => {
-    const mySchema = schema((s) => {
+    const mySchema = schema("my", (s) => {
       return s
         .addTable("users", (t) => {
           return t.addColumn("id", idColumn()).addColumn("email", column("string"));
@@ -140,8 +172,69 @@ describe("generateMigrationFromSchema", () => {
     });
   });
 
+  it("should generate update-column operation when column becomes nullable", () => {
+    const mySchema = schema("my", (s) => {
+      return s
+        .addTable("users", (t) => {
+          return t.addColumn("id", idColumn()).addColumn("name", column("string"));
+        })
+        .alterTable("users", (t) => {
+          return t.alterColumn("name").nullable();
+        });
+    });
+
+    const operations = generateMigrationFromSchema(mySchema, 1, 2);
+
+    expect(operations).toHaveLength(1);
+    expect(operations[0].type).toBe("alter-table");
+
+    const op = operations[0] as Extract<(typeof operations)[number], { type: "alter-table" }>;
+    expect(op.value).toHaveLength(1);
+    expect(op.value[0]).toMatchObject({
+      type: "update-column",
+      name: "name",
+      updateNullable: true,
+      updateDefault: false,
+      updateDataType: false,
+      value: expect.objectContaining({ isNullable: true }),
+    });
+  });
+
+  it("should not mutate historical operations when altering nullable", () => {
+    const mySchema = schema("my", (s) => {
+      return s
+        .addTable("users", (t) => {
+          return t.addColumn("id", idColumn()).addColumn("name", column("string"));
+        })
+        .alterTable("users", (t) => {
+          return t.alterColumn("name").nullable();
+        });
+    });
+
+    const operationsV1 = generateMigrationFromSchema(mySchema, 0, 1);
+    expect(operationsV1).toHaveLength(1);
+    expect(operationsV1[0].type).toBe("create-table");
+    const createOp = operationsV1[0] as Extract<
+      (typeof operationsV1)[number],
+      { type: "create-table" }
+    >;
+    const nameColumn = createOp.columns.find((col) => col.name === "name");
+    expect(nameColumn).toBeDefined();
+    expect(nameColumn?.isNullable).toBe(false);
+
+    const operationsV2 = generateMigrationFromSchema(mySchema, 0, 2);
+    expect(operationsV2).toHaveLength(2);
+    const createOpV2 = operationsV2[0] as Extract<
+      (typeof operationsV2)[number],
+      { type: "create-table" }
+    >;
+    const nameColumnV2 = createOpV2.columns.find((col) => col.name === "name");
+    expect(nameColumnV2).toBeDefined();
+    expect(nameColumnV2?.isNullable).toBe(false);
+  });
+
   it("should generate mixed operations for tables and foreign keys", () => {
-    const mySchema = schema((s) => {
+    const mySchema = schema("my", (s) => {
       return s
         .addTable("users", (t) => {
           return t.addColumn("id", idColumn()).addColumn("name", column("string"));
@@ -166,7 +259,7 @@ describe("generateMigrationFromSchema", () => {
   });
 
   it("should generate mixed operations for tables, indexes, and foreign keys", () => {
-    const mySchema = schema((s) => {
+    const mySchema = schema("my", (s) => {
       return s
         .addTable("users", (t) => {
           return t.addColumn("id", idColumn()).addColumn("email", column("string"));
@@ -195,7 +288,7 @@ describe("generateMigrationFromSchema", () => {
   });
 
   it("should generate no operations when version range is empty", () => {
-    const mySchema = schema((s) => {
+    const mySchema = schema("my", (s) => {
       return s.addTable("users", (t) => {
         return t.addColumn("id", idColumn()).addColumn("name", column("string"));
       });
@@ -207,7 +300,7 @@ describe("generateMigrationFromSchema", () => {
   });
 
   it("should throw error when fromVersion exceeds schema version", () => {
-    const mySchema = schema((s) => s.addTable("users", (t) => t.addColumn("id", idColumn())));
+    const mySchema = schema("my", (s) => s.addTable("users", (t) => t.addColumn("id", idColumn())));
 
     expect(() => {
       generateMigrationFromSchema(mySchema, 999, 1000);
@@ -215,7 +308,7 @@ describe("generateMigrationFromSchema", () => {
   });
 
   it("should throw error when toVersion exceeds schema version", () => {
-    const mySchema = schema((s) => s.addTable("users", (t) => t.addColumn("id", idColumn())));
+    const mySchema = schema("my", (s) => s.addTable("users", (t) => t.addColumn("id", idColumn())));
 
     expect(() => {
       generateMigrationFromSchema(mySchema, 0, 999);
@@ -223,7 +316,7 @@ describe("generateMigrationFromSchema", () => {
   });
 
   it("should throw error when trying to migrate backwards", () => {
-    const mySchema = schema((s) => s.addTable("users", (t) => t.addColumn("id", idColumn())));
+    const mySchema = schema("my", (s) => s.addTable("users", (t) => t.addColumn("id", idColumn())));
 
     expect(() => {
       generateMigrationFromSchema(mySchema, 1, 0);
@@ -231,7 +324,7 @@ describe("generateMigrationFromSchema", () => {
   });
 
   it("should throw error for negative fromVersion", () => {
-    const mySchema = schema((s) => s.addTable("users", (t) => t.addColumn("id", idColumn())));
+    const mySchema = schema("my", (s) => s.addTable("users", (t) => t.addColumn("id", idColumn())));
 
     expect(() => {
       generateMigrationFromSchema(mySchema, -1, 1);
@@ -239,7 +332,7 @@ describe("generateMigrationFromSchema", () => {
   });
 
   it("should only create constraints for references, not for referenceColumns", () => {
-    const mySchema = schema((s) => {
+    const mySchema = schema("my", (s) => {
       return s
         .addTable("posts", (t) => {
           return t
@@ -276,7 +369,7 @@ describe("generateMigrationFromSchema", () => {
   });
 
   it("should not create duplicate foreign key constraints", () => {
-    const mySchema = schema((s) => {
+    const mySchema = schema("my", (s) => {
       return s
         .addTable("users", (t) => t.addColumn("id", idColumn()))
         .addTable("posts", (t) =>