@fragno-dev/db 0.2.2 → 0.3.0

package/src/migration-engine/generation-engine.ts

@@ -4,77 +4,93 @@ import {
   fragnoDatabaseAdapterNameFakeSymbol,
   fragnoDatabaseAdapterVersionFakeSymbol,
 } from "../adapters/adapters";
-import {
-  internalFragmentDef,
-  internalSchema,
-  SETTINGS_NAMESPACE,
-  getSchemaVersionFromDatabase,
-} from "../fragments/internal-fragment";
+import { generateDrizzleSchema } from "../schema-output/drizzle";
+import { generatePrismaSchema } from "../schema-output/prisma";
+import { internalFragmentDef, getSchemaVersionFromDatabase } from "../fragments/internal-fragment";
+import { internalSchema, SETTINGS_TABLE_NAME } from "../fragments/internal-fragment.schema";
 import { instantiate } from "@fragno-dev/core";
+import { supportedDatabases, type SupportedDatabase } from "../adapters/generic-sql/driver-config";
 
 export interface GenerationEngineResult {
   schema: string;
   path: string;
-  namespace: string;
+  namespace: string | null;
+}
+
+export type SchemaOutputFormat = "sql" | "drizzle" | "prisma";
+
+export interface GenerateSchemaOptions {
+  format?: SchemaOutputFormat;
+  path?: string;
+  toVersion?: number;
+  fromVersion?: number;
 }
 
 export interface GenerationInternalResult {
   schema: string;
   path: string;
-  namespace: string;
+  namespace: string | null;
+  namespaceKey: string;
+  schemaName: string;
+  isSettings: boolean;
   fromVersion: number;
   toVersion: number;
 }
 
 export interface ExecuteMigrationResult {
-  namespace: string;
+  namespace: string | null;
   didMigrate: boolean;
   fromVersion: number;
   toVersion: number;
 }
 
-export async function generateMigrationsOrSchema<
+const DEFAULT_DRIZZLE_PATH = "fragno-schema.ts";
+const DEFAULT_PRISMA_PATH = "fragno.prisma";
+
+const isSupportedDatabase = (value: string): value is SupportedDatabase =>
+  supportedDatabases.includes(value as SupportedDatabase);
+
+export async function generateSchemaArtifacts<
   // oxlint-disable-next-line no-explicit-any
   const TDatabases extends FragnoDatabase<AnySchema, any>[],
->(
-  databases: TDatabases,
-  options?: {
-    path?: string;
-    toVersion?: number;
-    fromVersion?: number;
-  },
-): Promise<GenerationEngineResult[]> {
+>(databases: TDatabases, options?: GenerateSchemaOptions): Promise<GenerationEngineResult[]> {
   if (databases.length === 0) {
     throw new Error("No databases provided for schema generation");
   }
 
   const firstDb = databases[0];
   const adapter = firstDb.adapter;
+  const format = options?.format ?? "sql";
 
-  // If adapter has createSchemaGenerator, use it for combined generation (e.g., Drizzle)
-  if (adapter.createSchemaGenerator) {
+  if (format !== "sql") {
     if (options?.toVersion !== undefined || options?.fromVersion !== undefined) {
-      console.warn(
-        "⚠️ Warning: --from and --to version options are not supported when generating schemas for multiple fragments and will be ignored.",
+      throw new Error("--from and --to are only supported when generating SQL migrations.");
+    }
+
+    const databaseType = adapter.adapterMetadata?.databaseType;
+    if (!databaseType || !isSupportedDatabase(databaseType)) {
+      throw new Error(
+        "Adapter does not expose databaseType metadata required for schema output generation.",
       );
     }
 
     // Collect all schemas, de-duplicating by namespace.
     // The internal fragment (settings schema) is always included first since all database
     // fragments automatically link to it via withDatabase().
-    const fragmentsMap = new Map<string, { schema: AnySchema; namespace: string }>();
+    const fragmentsMap = new Map<string, { schema: AnySchema; namespace: string | null }>();
 
     // Include internal fragment first with empty namespace (settings table has no prefix)
-    fragmentsMap.set("", {
+    fragmentsMap.set(internalSchema.name, {
       schema: internalSchema,
-      namespace: "",
+      namespace: null,
     });
 
     // Add user fragments, de-duplicating by namespace
     // Each FragnoDatabase has a unique namespace, so this prevents duplicate schema generation
     for (const db of databases) {
-      if (!fragmentsMap.has(db.namespace)) {
-        fragmentsMap.set(db.namespace, {
+      const namespaceKey = db.namespace ?? db.schema.name;
+      if (!fragmentsMap.has(namespaceKey)) {
+        fragmentsMap.set(namespaceKey, {
           schema: db.schema,
           namespace: db.namespace,
         });
@@ -82,22 +98,30 @@ export async function generateMigrationsOrSchema<
     }
 
     const allFragments = Array.from(fragmentsMap.values());
-    const generator = adapter.createSchemaGenerator(allFragments, {
-      path: options?.path,
-    });
+    const defaultPath = format === "drizzle" ? DEFAULT_DRIZZLE_PATH : DEFAULT_PRISMA_PATH;
+    const schema =
+      format === "drizzle"
+        ? generateDrizzleSchema(allFragments, databaseType, {
+            namingStrategy: adapter.namingStrategy,
+          })
+        : generatePrismaSchema(allFragments, databaseType, {
+            sqliteStorageMode: adapter.adapterMetadata?.sqliteStorageMode,
+            namingStrategy: adapter.namingStrategy,
+          });
 
     return [
       {
-        ...generator.generateSchema(),
+        schema,
+        path: options?.path ?? defaultPath,
         namespace: firstDb.namespace,
       },
     ];
   }
 
-  // Otherwise, use migration engine for individual generation (e.g., Kysely, GenericSQL)
+  // Otherwise, use migration engine for SQL migration generation.
   if (!adapter.prepareMigrations) {
     throw new Error(
-      "Adapter does not support migration-based schema generation. Ensure your adapter implements prepareMigrations.",
+      "Adapter does not support migration generation. Ensure your adapter implements prepareMigrations.",
     );
   }
 
@@ -110,17 +134,14 @@ export async function generateMigrationsOrSchema<
   // Use the internal fragment for settings management
   const internalFragment = instantiate(internalFragmentDef)
     .withConfig({})
-    .withOptions({ databaseAdapter: adapter })
+    .withOptions({ databaseAdapter: adapter, databaseNamespace: null })
     .build();
 
-  const settingsSourceVersion = await getSchemaVersionFromDatabase(
-    internalFragment,
-    SETTINGS_NAMESPACE,
-  );
+  const settingsSourceVersion = await getSchemaVersionFromDatabase(internalFragment, "");
 
   const generatedFiles: GenerationInternalResult[] = [];
 
-  // Use empty namespace for settings (SETTINGS_NAMESPACE is for prefixing keys, not the database namespace)
+  // Internal fragment uses empty-string namespace: no table suffix, version key is ".schema_version"
   const settingsPreparedMigrations = adapter.prepareMigrations(internalSchema, "");
   const settingsTargetVersion = internalSchema.version;
 
@@ -134,7 +155,10 @@ export async function generateMigrationsOrSchema<
     generatedFiles.push({
       schema: settingsSql,
       path: "settings-migration.sql", // Placeholder, will be renamed in post-processing
-      namespace: "", // Empty namespace for settings table
+      namespace: null,
+      namespaceKey: SETTINGS_TABLE_NAME,
+      schemaName: internalSchema.name,
+      isSettings: true,
       fromVersion: settingsSourceVersion,
       toVersion: settingsTargetVersion,
     });
@@ -147,8 +171,8 @@ export async function generateMigrationsOrSchema<
     // Use migration engine
     if (!dbAdapter.prepareMigrations) {
       throw new Error(
-        `Adapter for ${db.namespace} does not support schema generation. ` +
-          `Ensure your adapter implements either createSchemaGenerator or prepareMigrations.`,
+        `Adapter for ${db.namespace ?? db.schema.name} does not support migration generation. ` +
+          `Ensure your adapter implements prepareMigrations.`,
       );
     }
 
@@ -165,6 +189,9 @@ export async function generateMigrationsOrSchema<
         schema: sql,
         path: "schema.sql", // Placeholder, will be renamed in post-processing
         namespace: db.namespace,
+        namespaceKey: db.namespace ?? db.schema.name,
+        schemaName: db.schema.name,
+        isSettings: false,
         fromVersion: sourceVersion,
         toVersion: targetVersion,
       });
@@ -196,7 +223,7 @@ export async function executeMigrations<const TDatabases extends FragnoDatabase<
   if (!adapter.prepareMigrations) {
     throw new Error(
       "Adapter does not support running migrations. The adapter only supports schema generation.\n" +
-        "Try using 'generateMigrationsOrSchema' instead to generate schema files.",
+        "Try using 'generateSchemaArtifacts' instead to generate schema files.",
     );
   }
 
@@ -224,7 +251,8 @@ export async function executeMigrations<const TDatabases extends FragnoDatabase<
 
   const results: ExecuteMigrationResult[] = [];
   const migrationsToExecute: Array<{
-    namespace: string;
+    namespace: string | null;
+    namespaceKey: string;
     fromVersion: number;
     toVersion: number;
     execute: () => Promise<void>;
@@ -234,15 +262,12 @@ export async function executeMigrations<const TDatabases extends FragnoDatabase<
   // Use the internal fragment for settings management
   const internalFragment = instantiate(internalFragmentDef)
     .withConfig({})
-    .withOptions({ databaseAdapter: adapter })
+    .withOptions({ databaseAdapter: adapter, databaseNamespace: null })
     .build();
 
-  const settingsSourceVersion = await getSchemaVersionFromDatabase(
-    internalFragment,
-    SETTINGS_NAMESPACE,
-  );
+  const settingsSourceVersion = await getSchemaVersionFromDatabase(internalFragment, "");
 
-  // Use empty namespace for settings (SETTINGS_NAMESPACE is for prefixing keys, not the database namespace)
+  // Internal fragment uses empty-string namespace: no table suffix, version key is ".schema_version"
   const settingsPreparedMigrations = adapter.prepareMigrations(internalSchema, "");
   const settingsTargetVersion = internalSchema.version;
 
@@ -255,7 +280,8 @@ export async function executeMigrations<const TDatabases extends FragnoDatabase<
 
     if (compiledMigration.statements.length > 0) {
       migrationsToExecute.push({
-        namespace: "", // Empty namespace for settings table
+        namespace: null,
+        namespaceKey: SETTINGS_TABLE_NAME,
         fromVersion: settingsSourceVersion,
         toVersion: settingsTargetVersion,
         execute: () =>
@@ -267,11 +293,15 @@ export async function executeMigrations<const TDatabases extends FragnoDatabase<
   }
 
   // 2. Prepare fragment migrations (sorted alphabetically)
-  const sortedDatabases = [...databases].sort((a, b) => a.namespace.localeCompare(b.namespace));
+  const getNamespaceKey = (db: FragnoDatabase<AnySchema>) => db.namespace ?? db.schema.name;
+  const sortedDatabases = [...databases].sort((a, b) =>
+    getNamespaceKey(a).localeCompare(getNamespaceKey(b)),
+  );
 
   for (const fragnoDb of sortedDatabases) {
+    const namespaceKey = getNamespaceKey(fragnoDb);
     const preparedMigrations = adapter.prepareMigrations(fragnoDb.schema, fragnoDb.namespace);
-    const currentVersion = await getSchemaVersionFromDatabase(internalFragment, fragnoDb.namespace);
+    const currentVersion = await getSchemaVersionFromDatabase(internalFragment, namespaceKey);
     const targetVersion = fragnoDb.schema.version;
 
     if (currentVersion < targetVersion) {
@@ -282,6 +312,7 @@ export async function executeMigrations<const TDatabases extends FragnoDatabase<
       if (compiledMigration.statements.length > 0) {
         migrationsToExecute.push({
           namespace: fragnoDb.namespace,
+          namespaceKey,
           fromVersion: currentVersion,
           toVersion: targetVersion,
           execute: () =>
@@ -294,6 +325,7 @@ export async function executeMigrations<const TDatabases extends FragnoDatabase<
   }
 
   // 3. Execute all migrations in order
+  const executedNamespaceKeys = new Set<string>();
   for (const migration of migrationsToExecute) {
     await migration.execute();
     results.push({
@@ -302,11 +334,13 @@ export async function executeMigrations<const TDatabases extends FragnoDatabase<
       fromVersion: migration.fromVersion,
       toVersion: migration.toVersion,
     });
+    executedNamespaceKeys.add(migration.namespaceKey);
   }
 
   // 4. Add skipped migrations (already up-to-date)
   for (const fragnoDb of databases) {
-    if (!results.find((r) => r.namespace === fragnoDb.namespace)) {
+    const namespaceKey = getNamespaceKey(fragnoDb);
+    if (!executedNamespaceKeys.has(namespaceKey)) {
       results.push({
         namespace: fragnoDb.namespace,
         didMigrate: false,
@@ -322,7 +356,7 @@ export async function executeMigrations<const TDatabases extends FragnoDatabase<
 /**
  * Post-processes migration files to add ordering and standardize naming.
  *
- * Sorts files with settings namespace first, then alphabetically by namespace,
+ * Sorts files with settings namespace first, then alphabetically by namespace key,
  * and assigns ordering numbers. Transforms filenames to format:
  * `<date>_<n>_f<from>_t<to>_<namespace>.sql`
  *
@@ -336,16 +370,15 @@ export function postProcessMigrationFilenames(
     return [];
   }
 
-  // Sort files: settings namespace first (empty string), then alphabetically by namespace
+  // Sort files: settings first, then alphabetically by namespace key
   const sortedFiles = [...files].sort((a, b) => {
-    // Settings table has empty namespace - sort it first
-    if (a.namespace === "") {
+    if (a.isSettings) {
       return -1;
     }
-    if (b.namespace === "") {
+    if (b.isSettings) {
       return 1;
     }
-    return a.namespace.localeCompare(b.namespace);
+    return a.namespaceKey.localeCompare(b.namespaceKey);
   });
 
   // Generate date prefix for filenames
@@ -361,10 +394,7 @@ export function postProcessMigrationFilenames(
     const fromPadded = fromVersion.toString().padStart(3, "0");
     const toPadded = toVersion.toString().padStart(3, "0");
 
-    // For settings table (empty namespace), use "fragno_db_settings" in the filename
-    // For other tables, use their namespace
-    const safeName =
-      file.namespace === "" ? "fragno_db_settings" : file.namespace.replace(/[^a-z0-9-]/gi, "_");
+    const safeName = file.namespaceKey.replace(/[^a-z0-9-]/gi, "_");
     const newPath = `${date}_${orderNum}_f${fromPadded}_t${toPadded}_${safeName}.sql`;
 
     return {

package/src/migration-engine/shared.ts

@@ -54,6 +54,7 @@ export type MigrationOperation<
       type: "drop-foreign-key";
       table: string;
       name: string;
+      referencedTable: string;
     } & { metadata?: TMeta })
   | ({
       type: "drop-index";

package/src/mod.ts

@@ -2,6 +2,7 @@ import type { DatabaseAdapter } from "./adapters/adapters";
 import type { AnySchema } from "./schema/create";
 import type { CursorResult } from "./query/cursor";
 import { Cursor } from "./query/cursor";
+import { dbNow, type DbNow } from "./query/db-now";
 import type { FragnoInstantiatedFragment, AnyFragnoInstantiatedFragment } from "@fragno-dev/core";
 import type {
   FragnoPublicConfigWithDatabase,
@@ -11,15 +12,20 @@ import {
   getSchemaVersionFromDatabase,
   type InternalFragmentInstance,
 } from "./fragments/internal-fragment";
+import { resolveDatabaseAdapter } from "./util/default-database-adapter";
 
 export type { DatabaseAdapter, CursorResult };
 export { Cursor };
+export { dbNow };
+export type { DbNow };
+export { InMemoryAdapter, type InMemoryAdapterOptions } from "./adapters/in-memory";
+export { internalSchema } from "./fragments/internal-fragment";
 
 export const fragnoDatabaseFakeSymbol = "$fragno-database" as const;
 export const fragnoDatabaseLibraryVersion = "0.1" as const;
 
 export interface CreateFragnoDatabaseDefinitionOptions<T extends AnySchema> {
-  namespace: string;
+  namespace: string | null;
   schema: T;
 }
 
@@ -43,11 +49,15 @@ export function isFragnoDatabase(value: unknown): value is FragnoDatabase<AnySch
  * Created from a FragnoDatabaseDefinition by calling .create(adapter).
  */
 export class FragnoDatabase<const T extends AnySchema, TUOWConfig = void> {
-  #namespace: string;
+  #namespace: string | null;
   #schema: T;
   #adapter: DatabaseAdapter<TUOWConfig>;
 
-  constructor(options: { namespace: string; schema: T; adapter: DatabaseAdapter<TUOWConfig> }) {
+  constructor(options: {
+    namespace: string | null;
+    schema: T;
+    adapter: DatabaseAdapter<TUOWConfig>;
+  }) {
     this.#namespace = options.namespace;
     this.#schema = options.schema;
     this.#adapter = options.adapter;
@@ -74,6 +84,7 @@ export {
   DatabaseFragmentDefinitionBuilder,
   type FragnoPublicConfigWithDatabase,
   type DatabaseFragmentContext,
+  type DatabaseServiceContext,
   type DatabaseHandlerContext as DatabaseRequestContext,
   type ImplicitDatabaseDependencies,
 } from "./db-fragment-definition-builder";
@@ -121,25 +132,47 @@ export type { BoundServices } from "@fragno-dev/core";
 
 export { internalFragmentDef } from "./fragments/internal-fragment";
 export type { InternalFragmentInstance } from "./fragments/internal-fragment";
-
-export type { HookContext, HooksMap, HookFn, HookPayload, TriggerHookOptions } from "./hooks/hooks";
-
-export type AnyFragnoInstantiatedDatabaseFragment = FragnoInstantiatedFragment<
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  any,
-  ImplicitDatabaseDependencies<AnySchema>,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  any,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  any,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  any,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  any,
-  FragnoPublicConfigWithDatabase,
-  // Ensure the fragment has the internal fragment linked
-  { _fragno_internal: InternalFragmentInstance } & Record<string, AnyFragnoInstantiatedFragment>
->;
+export type {
+  OutboxConfig,
+  OutboxEntry,
+  OutboxPayload,
+  OutboxMutation,
+  OutboxRefMap,
+} from "./outbox/outbox";
+
+export type {
+  HookContext,
+  HooksMap,
+  HookFn,
+  HookPayload,
+  TriggerHookOptions,
+  DurableHooksProcessingOptions,
+  StuckHookProcessingInfo,
+  StuckHookProcessingEvent,
+  StuckHookProcessingTimeoutMinutes,
+} from "./hooks/hooks";
+export {
+  createDurableHooksProcessor,
+  type DurableHooksProcessor,
+} from "./hooks/durable-hooks-processor";
+
+export type AnyFragnoInstantiatedDatabaseFragment<TSchema extends AnySchema = AnySchema> =
+  FragnoInstantiatedFragment<
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    any,
+    ImplicitDatabaseDependencies<TSchema>,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    any,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    any,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    any,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    any,
+    FragnoPublicConfigWithDatabase,
+    // Ensure the fragment has the internal fragment linked
+    { _fragno_internal: InternalFragmentInstance } & Record<string, AnyFragnoInstantiatedFragment>
+  >;
 
 /**
  * Helper function to run migrations for a database fragment.
@@ -163,9 +196,11 @@ export type AnyFragnoInstantiatedDatabaseFragment = FragnoInstantiatedFragment<
  * await migrate(fragment);
  * ```
  */
-export async function migrate(fragment: AnyFragnoInstantiatedDatabaseFragment): Promise<void> {
+export async function migrate<TSchema extends AnySchema>(
+  fragment: AnyFragnoInstantiatedDatabaseFragment<TSchema>,
+): Promise<void> {
   const { options, deps, linkedFragments } = fragment.$internal;
-  const adapter = options.databaseAdapter;
+  const adapter = resolveDatabaseAdapter(options, deps.schema);
 
   // Check if adapter supports prepareMigrations
   if (!adapter.prepareMigrations) {
@@ -175,7 +210,7 @@ export async function migrate(fragment: AnyFragnoInstantiatedDatabaseFragment):
   }
 
   const schema = deps.schema;
-  const namespace = deps.namespace;
+  const namespace = deps.namespace ?? schema.name;
 
   // Step 1: Ensure the internal fragment (settings table) is migrated first
   const internalFragment = linkedFragments._fragno_internal;
@@ -192,7 +227,10 @@ export async function migrate(fragment: AnyFragnoInstantiatedDatabaseFragment):
 
   const internalDeps = internalFragment.$internal.deps;
   const internalSchema = internalDeps.schema;
-  const internalNamespace = internalDeps.namespace;
+  // Internal fragment uses databaseNamespace: null (no table suffix).
+  // Version tracking uses empty string so the key is ".schema_version",
+  // which matches both the legacy format and how the internal fragment was designed.
+  const internalNamespace = internalDeps.namespace ?? "";
 
   const internalCurrentVersion = await getSchemaVersionFromDatabase(
     internalFragment,