@fragno-dev/db 0.1.14 → 0.2.0

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

@@ -1,15 +1,16 @@
 import type { FragnoDatabase } from "../mod";
 import type { AnySchema } from "../schema/create";
-import type { PreparedMigration } from "./create";
-import {
-  settingsSchema,
-  SETTINGS_NAMESPACE,
-  createSettingsManager,
-} from "../shared/settings-schema";
 import {
   fragnoDatabaseAdapterNameFakeSymbol,
   fragnoDatabaseAdapterVersionFakeSymbol,
 } from "../adapters/adapters";
+import {
+  internalFragmentDef,
+  internalSchema,
+  SETTINGS_NAMESPACE,
+  getSchemaVersionFromDatabase,
+} from "../fragments/internal-fragment";
+import { instantiate } from "@fragno-dev/core";
 
 export interface GenerationEngineResult {
   schema: string;
@@ -23,7 +24,6 @@ export interface GenerationInternalResult {
   namespace: string;
   fromVersion: number;
   toVersion: number;
-  preparedMigration?: PreparedMigration;
 }
 
 export interface ExecuteMigrationResult {
@@ -59,12 +59,30 @@ export async function generateMigrationsOrSchema<
       );
     }
 
-    const fragments = databases.map((db) => ({
-      schema: db.schema,
-      namespace: db.namespace,
-    }));
+    // 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 }>();
+
+    // Include internal fragment first with empty namespace (settings table has no prefix)
+    fragmentsMap.set("", {
+      schema: internalSchema,
+      namespace: "",
+    });
+
+    // 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, {
+          schema: db.schema,
+          namespace: db.namespace,
+        });
+      }
+    }
 
-    const generator = adapter.createSchemaGenerator(fragments, {
+    const allFragments = Array.from(fragmentsMap.values());
+    const generator = adapter.createSchemaGenerator(allFragments, {
       path: options?.path,
     });
 
@@ -76,10 +94,10 @@ export async function generateMigrationsOrSchema<
     ];
   }
 
-  // Otherwise, use migration engine for individual generation (e.g., Kysely)
-  if (!adapter.createMigrationEngine) {
+  // Otherwise, use migration engine for individual generation (e.g., Kysely, GenericSQL)
+  if (!adapter.prepareMigrations) {
     throw new Error(
-      "Adapter does not support migration-based schema generation. Ensure your adapter implements createMigrationEngine.",
+      "Adapter does not support migration-based schema generation. Ensure your adapter implements prepareMigrations.",
     );
   }
 
@@ -89,49 +107,36 @@ export async function generateMigrationsOrSchema<
     );
   }
 
-  const settingsQueryEngine = adapter.createQueryEngine(settingsSchema, "");
-  const settingsManager = createSettingsManager(settingsQueryEngine, SETTINGS_NAMESPACE);
+  // Use the internal fragment for settings management
+  const internalFragment = instantiate(internalFragmentDef)
+    .withConfig({})
+    .withOptions({ databaseAdapter: adapter })
+    .build();
 
-  let settingsSourceVersion: number;
-  try {
-    const result = await settingsManager.get("version");
-
-    if (!result) {
-      settingsSourceVersion = 0;
-    } else {
-      settingsSourceVersion = parseInt(result.value);
-    }
-  } catch {
-    // We don't really have a way to verify this error happens because the key doesn't exist in the database
-    settingsSourceVersion = 0;
-  }
+  const settingsSourceVersion = await getSchemaVersionFromDatabase(
+    internalFragment,
+    SETTINGS_NAMESPACE,
+  );
 
   const generatedFiles: GenerationInternalResult[] = [];
 
-  const settingsMigrator = adapter.createMigrationEngine(settingsSchema, SETTINGS_NAMESPACE);
-  const settingsTargetVersion = settingsSchema.version;
+  // Use empty namespace for settings (SETTINGS_NAMESPACE is for prefixing keys, not the database namespace)
+  const settingsPreparedMigrations = adapter.prepareMigrations(internalSchema, "");
+  const settingsTargetVersion = internalSchema.version;
 
   // Generate settings table migration
-  const settingsMigration = await settingsMigrator.prepareMigrationTo(settingsTargetVersion, {
-    fromVersion: settingsSourceVersion,
-  });
-
-  if (!settingsMigration.getSQL) {
-    throw new Error(
-      "Migration engine does not support SQL generation. Ensure your adapter's migration engine provides getSQL().",
-    );
-  }
-
-  const settingsSql = settingsMigration.getSQL();
+  const settingsSql = settingsPreparedMigrations.getSQL(
+    settingsSourceVersion,
+    settingsTargetVersion,
+  );
 
   if (settingsSql.trim()) {
     generatedFiles.push({
       schema: settingsSql,
       path: "settings-migration.sql", // Placeholder, will be renamed in post-processing
-      namespace: SETTINGS_NAMESPACE,
+      namespace: "", // Empty namespace for settings table
       fromVersion: settingsSourceVersion,
       toVersion: settingsTargetVersion,
-      preparedMigration: settingsMigration,
     });
   }
 
@@ -140,29 +145,19 @@ export async function generateMigrationsOrSchema<
     const dbAdapter = db.adapter;
 
     // Use migration engine
-    if (!dbAdapter.createMigrationEngine) {
+    if (!dbAdapter.prepareMigrations) {
       throw new Error(
         `Adapter for ${db.namespace} does not support schema generation. ` +
-          `Ensure your adapter implements either createSchemaGenerator or createMigrationEngine.`,
+          `Ensure your adapter implements either createSchemaGenerator or prepareMigrations.`,
       );
     }
 
-    const migrator = dbAdapter.createMigrationEngine(db.schema, db.namespace);
+    const preparedMigrations = dbAdapter.prepareMigrations(db.schema, db.namespace);
     const targetVersion = options?.toVersion ?? db.schema.version;
     const sourceVersion = options?.fromVersion ?? 0;
 
     // Generate migration from source to target version
-    const preparedMigration = await migrator.prepareMigrationTo(targetVersion, {
-      fromVersion: sourceVersion,
-    });
-
-    if (!preparedMigration.getSQL) {
-      throw new Error(
-        "Migration engine does not support SQL generation. Ensure your adapter's migration engine provides getSQL().",
-      );
-    }
-
-    const sql = preparedMigration.getSQL();
+    const sql = preparedMigrations.getSQL(sourceVersion, targetVersion);
 
     // If no migrations needed, skip this fragment
     if (sql.trim()) {
@@ -172,7 +167,6 @@ export async function generateMigrationsOrSchema<
         namespace: db.namespace,
         fromVersion: sourceVersion,
         toVersion: targetVersion,
-        preparedMigration: preparedMigration,
       });
     }
   }
@@ -199,7 +193,7 @@ export async function executeMigrations<const TDatabases extends FragnoDatabase<
   const adapter = firstDb.adapter;
 
   // Validate adapter supports migrations
-  if (!adapter.createMigrationEngine) {
+  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.",
@@ -233,36 +227,41 @@ export async function executeMigrations<const TDatabases extends FragnoDatabase<
     namespace: string;
     fromVersion: number;
     toVersion: number;
-    preparedMigration: PreparedMigration;
+    execute: () => Promise<void>;
   }> = [];
 
   // 1. Prepare settings table migration
-  const settingsQueryEngine = adapter.createQueryEngine(settingsSchema, "");
-  const settingsManager = createSettingsManager(settingsQueryEngine, SETTINGS_NAMESPACE);
-
-  let settingsSourceVersion: number;
-  try {
-    const result = await settingsManager.get("version");
-    settingsSourceVersion = result ? parseInt(result.value) : 0;
-  } catch {
-    settingsSourceVersion = 0;
-  }
+  // Use the internal fragment for settings management
+  const internalFragment = instantiate(internalFragmentDef)
+    .withConfig({})
+    .withOptions({ databaseAdapter: adapter })
+    .build();
 
-  const settingsMigrator = adapter.createMigrationEngine(settingsSchema, SETTINGS_NAMESPACE);
-  const settingsTargetVersion = settingsSchema.version;
+  const settingsSourceVersion = await getSchemaVersionFromDatabase(
+    internalFragment,
+    SETTINGS_NAMESPACE,
+  );
+
+  // Use empty namespace for settings (SETTINGS_NAMESPACE is for prefixing keys, not the database namespace)
+  const settingsPreparedMigrations = adapter.prepareMigrations(internalSchema, "");
+  const settingsTargetVersion = internalSchema.version;
 
   if (settingsSourceVersion < settingsTargetVersion) {
-    const settingsMigration = await settingsMigrator.prepareMigrationTo(settingsTargetVersion, {
-      fromVersion: settingsSourceVersion,
-      updateSettings: true,
-    });
+    const compiledMigration = settingsPreparedMigrations.compile(
+      settingsSourceVersion,
+      settingsTargetVersion,
+      { updateVersionInMigration: true },
+    );
 
-    if (settingsMigration.operations.length > 0) {
+    if (compiledMigration.statements.length > 0) {
       migrationsToExecute.push({
-        namespace: SETTINGS_NAMESPACE,
+        namespace: "", // Empty namespace for settings table
         fromVersion: settingsSourceVersion,
         toVersion: settingsTargetVersion,
-        preparedMigration: settingsMigration,
+        execute: () =>
+          settingsPreparedMigrations.execute(settingsSourceVersion, settingsTargetVersion, {
+            updateVersionInMigration: true,
+          }),
       });
     }
   }
@@ -271,21 +270,24 @@ export async function executeMigrations<const TDatabases extends FragnoDatabase<
   const sortedDatabases = [...databases].sort((a, b) => a.namespace.localeCompare(b.namespace));
 
   for (const fragnoDb of sortedDatabases) {
-    const migrator = adapter.createMigrationEngine(fragnoDb.schema, fragnoDb.namespace);
-    const currentVersion = await migrator.getVersion();
+    const preparedMigrations = adapter.prepareMigrations(fragnoDb.schema, fragnoDb.namespace);
+    const currentVersion = await getSchemaVersionFromDatabase(internalFragment, fragnoDb.namespace);
     const targetVersion = fragnoDb.schema.version;
 
     if (currentVersion < targetVersion) {
-      const preparedMigration = await migrator.prepareMigrationTo(targetVersion, {
-        updateSettings: true,
+      const compiledMigration = preparedMigrations.compile(currentVersion, targetVersion, {
+        updateVersionInMigration: true,
       });
 
-      if (preparedMigration.operations.length > 0) {
+      if (compiledMigration.statements.length > 0) {
         migrationsToExecute.push({
           namespace: fragnoDb.namespace,
           fromVersion: currentVersion,
           toVersion: targetVersion,
-          preparedMigration: preparedMigration,
+          execute: () =>
+            preparedMigrations.execute(currentVersion, targetVersion, {
+              updateVersionInMigration: true,
+            }),
         });
       }
     }
@@ -293,7 +295,7 @@ export async function executeMigrations<const TDatabases extends FragnoDatabase<
 
   // 3. Execute all migrations in order
   for (const migration of migrationsToExecute) {
-    await migration.preparedMigration.execute();
+    await migration.execute();
     results.push({
       namespace: migration.namespace,
       didMigrate: true,
@@ -334,12 +336,13 @@ export function postProcessMigrationFilenames(
     return [];
   }
 
-  // Sort files: settings namespace first, then alphabetically by namespace
+  // Sort files: settings namespace first (empty string), then alphabetically by namespace
   const sortedFiles = [...files].sort((a, b) => {
-    if (a.namespace === SETTINGS_NAMESPACE) {
+    // Settings table has empty namespace - sort it first
+    if (a.namespace === "") {
       return -1;
     }
-    if (b.namespace === SETTINGS_NAMESPACE) {
+    if (b.namespace === "") {
       return 1;
     }
     return a.namespace.localeCompare(b.namespace);
@@ -357,7 +360,11 @@ export function postProcessMigrationFilenames(
     const orderNum = (index + 1).toString().padStart(3, "0");
     const fromPadded = fromVersion.toString().padStart(3, "0");
     const toPadded = toVersion.toString().padStart(3, "0");
-    const safeName = file.namespace.replace(/[^a-z0-9-]/gi, "_");
+
+    // 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 newPath = `${date}_${orderNum}_f${fromPadded}_t${toPadded}_${safeName}.sql`;
 
     return {

package/src/mod.ts

@@ -1,8 +1,16 @@
 import type { DatabaseAdapter } from "./adapters/adapters";
 import type { AnySchema } from "./schema/create";
-import type { AbstractQuery } from "./query/query";
 import type { CursorResult } from "./query/cursor";
 import { Cursor } from "./query/cursor";
+import type { FragnoInstantiatedFragment, AnyFragnoInstantiatedFragment } from "@fragno-dev/core";
+import type {
+  FragnoPublicConfigWithDatabase,
+  ImplicitDatabaseDependencies,
+} from "./db-fragment-definition-builder";
+import {
+  getSchemaVersionFromDatabase,
+  type InternalFragmentInstance,
+} from "./fragments/internal-fragment";
 
 export type { DatabaseAdapter, CursorResult };
 export { Cursor };
@@ -30,40 +38,6 @@ export function isFragnoDatabase(value: unknown): value is FragnoDatabase<AnySch
   );
 }
 
-/**
- * Definition of a Fragno database schema and namespace.
- * Created by library authors using defineFragnoDatabase().
- * Apps instantiate it by calling .create(adapter).
- */
-export class FragnoDatabaseDefinition<const T extends AnySchema> {
-  #namespace: string;
-  #schema: T;
-
-  constructor(options: CreateFragnoDatabaseDefinitionOptions<T>) {
-    this.#namespace = options.namespace;
-    this.#schema = options.schema;
-  }
-
-  get namespace() {
-    return this.#namespace;
-  }
-
-  get schema() {
-    return this.#schema;
-  }
-
-  /**
-   * Creates a FragnoDatabase instance by binding an adapter to this definition.
-   */
-  create<TUOWConfig = void>(adapter: DatabaseAdapter<TUOWConfig>): FragnoDatabase<T, TUOWConfig> {
-    return new FragnoDatabase({
-      namespace: this.#namespace,
-      schema: this.#schema,
-      adapter,
-    });
-  }
-}
-
 /**
  * A Fragno database instance with a bound adapter.
  * Created from a FragnoDatabaseDefinition by calling .create(adapter).
@@ -83,30 +57,6 @@ export class FragnoDatabase<const T extends AnySchema, TUOWConfig = void> {
     return fragnoDatabaseFakeSymbol;
   }
 
-  async createClient(): Promise<AbstractQuery<T, TUOWConfig>> {
-    const dbVersion = await this.#adapter.getSchemaVersion(this.#namespace);
-    if (dbVersion !== this.#schema.version.toString()) {
-      throw new Error(
-        `Database is not at expected version. Did you forget to run migrations?` +
-          ` Current version: ${dbVersion}, Expected version: ${this.#schema.version}`,
-      );
-    }
-
-    return this.#adapter.createQueryEngine(this.#schema, this.#namespace);
-  }
-
-  async runMigrations(): Promise<boolean> {
-    if (!this.#adapter.createMigrationEngine) {
-      throw new Error("Migration engine not supported for this adapter.");
-    }
-
-    const migrator = this.#adapter.createMigrationEngine(this.#schema, this.#namespace);
-    const preparedMigration = await migrator.prepareMigration();
-    await preparedMigration.execute();
-
-    return preparedMigration.operations.length > 0;
-  }
-
   get namespace() {
     return this.#namespace;
   }
@@ -120,36 +70,147 @@ export class FragnoDatabase<const T extends AnySchema, TUOWConfig = void> {
   }
 }
 
-export function defineFragnoDatabase<const TSchema extends AnySchema>(
-  options: CreateFragnoDatabaseDefinitionOptions<TSchema>,
-): FragnoDatabaseDefinition<TSchema> {
-  return new FragnoDatabaseDefinition(options);
-}
-
 export {
-  defineFragmentWithDatabase,
-  DatabaseFragmentBuilder,
+  DatabaseFragmentDefinitionBuilder,
   type FragnoPublicConfigWithDatabase,
   type DatabaseFragmentContext,
-  type DatabaseRouteHandler,
-} from "./fragment";
+  type DatabaseHandlerContext as DatabaseRequestContext,
+  type ImplicitDatabaseDependencies,
+} from "./db-fragment-definition-builder";
+
+export { withDatabase } from "./with-database";
 
 export { decodeCursor, type CursorData } from "./query/cursor";
 
 export {
   createUnitOfWork,
   UnitOfWork,
-  UnitOfWorkSchemaView,
-  type IUnitOfWorkBase,
+  TypedUnitOfWork,
+  type IUnitOfWork,
+  type IUnitOfWorkRestricted,
   type UOWCompiler,
   type UOWExecutor,
   type UOWDecoder,
-} from "./query/unit-of-work";
+} from "./query/unit-of-work/unit-of-work";
+
+export {
+  type RetryPolicy,
+  NoRetryPolicy,
+  ExponentialBackoffRetryPolicy,
+  LinearBackoffRetryPolicy,
+} from "./query/unit-of-work/retry-policy";
 
 export {
-  withUnitOfWork,
-  serviceContext,
-  uowStorage,
-  type DatabaseRequestThisContext,
-} from "./fragment";
-export { type BoundServices } from "./bind-services";
+  executeUnitOfWork,
+  type ExecuteUnitOfWorkResult,
+  type ExecuteUnitOfWorkCallbacks,
+  type ExecuteUnitOfWorkOptions,
+} from "./query/unit-of-work/execute-unit-of-work";
+
+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>
+>;
+
+/**
+ * Helper function to run migrations for a database fragment.
+ * Extracts the database adapter, schema, and namespace from the fragment and runs migrations.
+ * This function:
+ * 1. Ensures the internal settings fragment is migrated first
+ * 2. Retrieves the current database version from the internal fragment
+ * 3. Runs migration from current version to target version
+ *
+ * @param fragment - The instantiated fragment to run migrations for
+ * @throws Error if the fragment doesn't have database support or the adapter doesn't support migrations
+ *
+ * @example
+ * ```typescript
+ * const fragment = instantiate(myFragmentDef)
+ *   .withConfig({})
+ *   .withRoutes([])
+ *   .withOptions({ databaseAdapter: myAdapter })
+ *   .build();
+ *
+ * await migrate(fragment);
+ * ```
+ */
+export async function migrate(fragment: AnyFragnoInstantiatedDatabaseFragment): Promise<void> {
+  const { options, deps, linkedFragments } = fragment.$internal;
+  const adapter = options.databaseAdapter;
+
+  // Check if adapter supports prepareMigrations
+  if (!adapter.prepareMigrations) {
+    throw new Error(
+      "Database adapter does not support prepareMigrations. Please use an adapter that implements this method.",
+    );
+  }
+
+  const schema = deps.schema;
+  const namespace = deps.namespace;
+
+  // Step 1: Ensure the internal fragment (settings table) is migrated first
+  const internalFragment = linkedFragments._fragno_internal;
+
+  if (!internalFragment) {
+    throw new Error("Internal fragment not found. Please ensure the internal fragment is linked.");
+  }
+
+  if (!(await adapter.isConnectionHealthy())) {
+    throw new Error(
+      "Database connection is not healthy. Please check your database connection and try again.",
+    );
+  }
+
+  const internalDeps = internalFragment.$internal.deps;
+  const internalSchema = internalDeps.schema;
+  const internalNamespace = internalDeps.namespace;
+
+  const internalCurrentVersion = await getSchemaVersionFromDatabase(
+    internalFragment,
+    internalNamespace,
+  );
+
+  // Migrate internal fragment if needed
+  if (internalCurrentVersion < internalSchema.version) {
+    const internalMigrations = adapter.prepareMigrations(internalSchema, internalNamespace);
+    await internalMigrations.execute(internalCurrentVersion, internalSchema.version);
+  }
+
+  // Step 2: Get current database version for this fragment's namespace
+  const currentVersion = await getSchemaVersionFromDatabase(internalFragment, namespace);
+
+  // Step 3: Run the migration from current version to target version
+  const targetVersion = schema.version;
+
+  if (currentVersion === targetVersion) {
+    return;
+  }
+
+  if (currentVersion > targetVersion) {
+    throw new Error(
+      `Cannot migrate backwards: current version (${currentVersion}) > target version (${targetVersion})`,
+    );
+  }
+
+  const migrations = adapter.prepareMigrations(schema, namespace);
+  await migrations.execute(currentVersion, targetVersion);
+}

package/src/query/column-defaults.ts

@@ -0,0 +1,49 @@
+import type { AnyColumn } from "../schema/create";
+import { createId } from "../id";
+
+/**
+ * Generate a runtime default value for a column that has defaultTo$()
+ *
+ * Only generates values for runtime defaults (defaultTo$), NOT static defaults (defaultTo).
+ * Static defaults should be handled by the database via DEFAULT constraints.
+ *
+ * @param column - The column with a default value configuration
+ * @returns The generated default value, or undefined if the column has no runtime default
+ *
+ * @internal
+ */
+export function generateRuntimeDefault(column: AnyColumn): unknown {
+  // Check if column has a default value configuration
+  if (!column.default) {
+    return undefined;
+  }
+
+  // If it's a static default value (defaultTo), return undefined
+  // as the database should handle this via DEFAULT constraint
+  if ("value" in column.default) {
+    return undefined;
+  }
+
+  // If it's a database-level special function (defaultTo(b => b.now())), return undefined
+  // as the database should handle this via DEFAULT NOW() or equivalent
+  if ("dbSpecial" in column.default) {
+    return undefined;
+  }
+
+  // Handle runtime defaults (defaultTo$)
+  const runtime = column.default.runtime;
+
+  if (runtime === "cuid") {
+    return createId();
+  }
+
+  if (runtime === "now") {
+    return new Date();
+  }
+
+  if (typeof runtime === "function") {
+    return runtime();
+  }
+
+  return undefined;
+}