@fragno-dev/db 0.1.15 → 0.2.0

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 };
@@ -49,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;
   }
@@ -107,22 +91,126 @@ export {
   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/retry-policy";
+} from "./query/unit-of-work/retry-policy";
 
 export {
   executeUnitOfWork,
   type ExecuteUnitOfWorkResult,
   type ExecuteUnitOfWorkCallbacks,
   type ExecuteUnitOfWorkOptions,
-} from "./query/execute-unit-of-work";
+} from "./query/unit-of-work/execute-unit-of-work";
 
-export { type BoundServices } from "@fragno-dev/core";
+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;
+}

package/src/query/cursor.test.ts

@@ -1,6 +1,11 @@
 import { describe, it, expect } from "vitest";
 import { decodeCursor, createCursorFromRecord, serializeCursorValues, Cursor } from "./cursor";
 import { column, idColumn, schema } from "../schema/create";
+import {
+  BetterSQLite3DriverConfig,
+  MySQL2DriverConfig,
+  NodePostgresDriverConfig,
+} from "../adapters/generic-sql/driver-config";
 
 describe("Cursor utilities", () => {
   describe("Cursor class encode and decode", () => {
@@ -245,7 +250,11 @@ describe("Cursor utilities", () => {
       });
 
       const indexColumns = [table.columns.id, table.columns.age];
-      const serialized = serializeCursorValues(cursor, indexColumns, "postgresql");
+      const serialized = serializeCursorValues(
+        cursor,
+        indexColumns,
+        new NodePostgresDriverConfig(),
+      );
 
       expect(serialized).toHaveProperty("id", "user123");
       expect(serialized).toHaveProperty("age", 25);
@@ -267,7 +276,11 @@ describe("Cursor utilities", () => {
       });
 
       const indexColumns = [table.columns.id, table.columns.name];
-      const serialized = serializeCursorValues(cursor, indexColumns, "postgresql");
+      const serialized = serializeCursorValues(
+        cursor,
+        indexColumns,
+        new NodePostgresDriverConfig(),
+      );
 
       expect(serialized).toHaveProperty("id", "user123");
       expect(serialized).not.toHaveProperty("name");
@@ -307,7 +320,11 @@ describe("Cursor utilities", () => {
       const decoded = decodeCursor(cursor.encode());
 
       // Serialize the values
-      const serialized = serializeCursorValues(decoded, indexColumns, "postgresql");
+      const serialized = serializeCursorValues(
+        decoded,
+        indexColumns,
+        new NodePostgresDriverConfig(),
+      );
 
       // Should preserve the values
       expect(serialized["score"]).toBe(42);
@@ -350,7 +367,11 @@ describe("Cursor utilities", () => {
       expect(decoded.indexValues["createdAt"]).toBe("2025-11-07T09:36:57.959Z");
 
       // Serialize should convert it back to Date for the database
-      const serialized = serializeCursorValues(decoded, indexColumns, "postgresql");
+      const serialized = serializeCursorValues(
+        decoded,
+        indexColumns,
+        new NodePostgresDriverConfig(),
+      );
 
       // For PostgreSQL, Date objects should be passed through as-is
       expect(serialized["createdAt"]).toBeInstanceOf(Date);
@@ -388,7 +409,11 @@ describe("Cursor utilities", () => {
       const decoded = decodeCursor(cursor.encode());
 
       // Serialize should convert string back to Date, then to timestamp number for SQLite
-      const serialized = serializeCursorValues(decoded, indexColumns, "sqlite");
+      const serialized = serializeCursorValues(
+        decoded,
+        indexColumns,
+        new BetterSQLite3DriverConfig(),
+      );
 
       // For SQLite, Date should be converted to timestamp number
       expect(typeof serialized["createdAt"]).toBe("number");
@@ -426,7 +451,7 @@ describe("Cursor utilities", () => {
       const decoded = decodeCursor(cursor.encode());
 
       // Serialize for MySQL
-      const serialized = serializeCursorValues(decoded, indexColumns, "mysql");
+      const serialized = serializeCursorValues(decoded, indexColumns, new MySQL2DriverConfig());
 
       // For MySQL, Date objects should be passed through as-is
       expect(serialized["createdAt"]).toBeInstanceOf(Date);

package/src/query/cursor.ts

@@ -1,6 +1,7 @@
 import type { AnyColumn } from "../schema/create";
-import { deserialize, serialize } from "../schema/serialize";
-import type { SQLProvider } from "../shared/providers";
+import { createSQLSerializer } from "./serialize/create-sql-serializer";
+import { resolveFragnoIdValue } from "./value-encoding";
+import type { DriverConfig } from "../adapters/generic-sql/driver-config";
 
 /**
  * Cursor object containing all information needed for pagination
@@ -216,7 +217,7 @@ export function createCursorFromRecord(
  *
  * @param cursor - The cursor object
  * @param indexColumns - The columns that make up the index
- * @param provider - The SQL provider
+ * @param driverConfig - The driver configuration
  * @returns Serialized values ready for database queries
  *
  * @example
@@ -224,15 +225,16 @@ export function createCursorFromRecord(
  * const serialized = serializeCursorValues(
  *   cursor,
  *   [table.columns.createdAt],
- *   "postgresql"
+ *   driverConfig
  * );
  * ```
  */
 export function serializeCursorValues(
   cursor: Cursor,
   indexColumns: AnyColumn[],
-  provider: SQLProvider,
+  driverConfig: DriverConfig,
 ): Record<string, unknown> {
+  const serializer = createSQLSerializer(driverConfig);
   const serialized: Record<string, unknown> = {};
 
   for (const col of indexColumns) {
@@ -240,10 +242,12 @@ export function serializeCursorValues(
     if (value !== undefined) {
       // First deserialize from JSON format to application format
       // (e.g., "2025-11-07T09:36:57.959Z" string → Date object)
-      const deserialized = deserialize(value, col, provider);
+      const deserialized = serializer.deserialize(value, col);
+      // Resolve FragnoId/FragnoReference to primitive values (if present)
+      const resolved = resolveFragnoIdValue(deserialized, col);
       // Then serialize to database format
       // (e.g., Date → database driver format)
-      serialized[col.ormName] = serialize(deserialized, col, provider);
+      serialized[col.ormName] = serializer.serialize(resolved, col);
     }
   }
 

package/src/query/orm/orm.ts

@@ -4,7 +4,7 @@ import type {
   FindManyOptions,
   JoinBuilder,
   OrderBy,
-} from "../query";
+} from "../simple-query-interface";
 import { buildCondition, type Condition } from "../condition-builder";
 import type { AnyColumn, AnyRelation, AnyTable } from "../../schema/create";
 

package/src/query/query-type.test.ts

@@ -1,14 +1,14 @@
 import { describe, expectTypeOf, it } from "vitest";
 import { column, FragnoId, idColumn, referenceColumn, schema } from "../schema/create";
 import type {
-  AbstractQuery,
+  SimpleQueryInterface,
   FindFirstOptions,
   FindManyOptions,
   JoinBuilder,
   OrderBy,
   SelectClause,
   TableToInsertValues,
-} from "./query";
+} from "./simple-query-interface";
 import type { ConditionBuilder } from "./condition-builder";
 
 describe("query type tests", () => {
@@ -91,8 +91,8 @@ describe("query type tests", () => {
     });
   });
 
-  describe("AbstractQuery methods", () => {
-    type Query = AbstractQuery<TestSchema>;
+  describe("SimpleQueryInterface methods", () => {
+    type Query = SimpleQueryInterface<TestSchema>;
 
     describe("findFirst", () => {
       it("should return all columns when select is true or undefined", () => {
@@ -257,7 +257,7 @@ describe("query type tests", () => {
 
   describe("table name type checking", () => {
     it("should only allow valid table names", () => {
-      const _query = {} as AbstractQuery<TestSchema>;
+      const _query = {} as SimpleQueryInterface<TestSchema>;
 
       // Valid table names
       type UsersParam = Parameters<typeof _query.find<"users">>;
@@ -272,7 +272,7 @@ describe("query type tests", () => {
 
   describe("column type inference", () => {
     it("should correctly infer column types for users table", () => {
-      const _query = {} as AbstractQuery<TestSchema>;
+      const _query = {} as SimpleQueryInterface<TestSchema>;
       type Result = Awaited<ReturnType<typeof _query.findFirst<"users">>>;
       type User = Exclude<Result, null>;
 
@@ -284,7 +284,7 @@ describe("query type tests", () => {
     });
 
     it("should correctly infer column types for posts table", () => {
-      const _query = {} as AbstractQuery<TestSchema>;
+      const _query = {} as SimpleQueryInterface<TestSchema>;
       type Result = Awaited<ReturnType<typeof _query.findFirst<"posts">>>;
       type Post = Exclude<Result, null>;
 
@@ -297,7 +297,7 @@ describe("query type tests", () => {
     });
 
     it("should correctly infer column types for comments table", () => {
-      const _query = {} as AbstractQuery<TestSchema>;
+      const _query = {} as SimpleQueryInterface<TestSchema>;
       type Result = Awaited<ReturnType<typeof _query.findFirst<"comments">>>;
       type Comment = Exclude<Result, null>;
 
@@ -311,7 +311,7 @@ describe("query type tests", () => {
 
   describe("complex scenarios", () => {
     it("should handle multiple table operations with correct types", () => {
-      const _query = {} as AbstractQuery<TestSchema>;
+      const _query = {} as SimpleQueryInterface<TestSchema>;
 
       // Create user return type
       type UserResult = Awaited<ReturnType<typeof _query.create<"users">>>;

package/src/query/serialize/create-sql-serializer.ts

@@ -0,0 +1,34 @@
+import type { DriverConfig } from "../../adapters/generic-sql/driver-config";
+import { SQLSerializer } from "./sql-serializer";
+import { SQLiteSerializer } from "./dialect/sqlite-serializer";
+import { PostgreSQLSerializer } from "./dialect/postgres-serializer";
+import { MySQLSerializer } from "./dialect/mysql-serializer";
+
+// Re-export SQLSerializer for convenience
+export { SQLSerializer } from "./sql-serializer";
+
+/**
+ * Factory function to create a dialect-specific SQL serializer from a DriverConfig.
+ *
+ * Based on the database type, returns the appropriate serializer implementation
+ * (PostgreSQL, MySQL, or SQLite).
+ *
+ * @param driverConfig - The driver configuration
+ * @returns Dialect-specific SQLSerializer instance
+ */
+export function createSQLSerializer(driverConfig: DriverConfig): SQLSerializer {
+  // TODO: The serializers are pretty lenient in what they accept (lost of typeof checks), it may
+  //       be beneficial to implement serializers per DriverConfig, and be less lenient.
+  switch (driverConfig.databaseType) {
+    case "postgresql":
+      return new PostgreSQLSerializer(driverConfig);
+    case "mysql":
+      return new MySQLSerializer(driverConfig);
+    case "sqlite":
+      return new SQLiteSerializer(driverConfig);
+    default: {
+      const exhaustiveCheck: never = driverConfig.databaseType;
+      throw new Error(`Unsupported database type: ${exhaustiveCheck}`);
+    }
+  }
+}

package/src/query/serialize/dialect/mysql-serializer.ts

@@ -0,0 +1,142 @@
+import type { AnyColumn } from "../../../schema/create";
+import { SQLSerializer } from "../sql-serializer";
+import type { DriverConfig } from "../../../adapters/generic-sql/driver-config";
+
+/**
+ * MySQL-specific serializer.
+ *
+ * MySQL has good native type support:
+ * - Native JSON support (MySQL 5.7+)
+ * - Native boolean type (TINYINT(1))
+ * - Native timestamp/datetime/date types
+ * - Native bigint support
+ *
+ * Similar to PostgreSQL, most values pass through without conversion.
+ * Timestamps/dates are returned as strings and need to be parsed.
+ */
+export class MySQLSerializer extends SQLSerializer {
+  constructor(driverConfig: DriverConfig) {
+    super(driverConfig);
+  }
+
+  protected serializeDate(value: Date): Date {
+    // MySQL handles Date objects natively
+    return value;
+  }
+
+  protected serializeBoolean(value: boolean): boolean {
+    // MySQL handles boolean natively (as TINYINT(1))
+    return value;
+  }
+
+  protected serializeBigInt(value: bigint, _col: AnyColumn): bigint {
+    // MySQL handles bigint natively
+    return value;
+  }
+
+  protected deserializeDate(value: unknown): Date {
+    if (value instanceof Date) {
+      return value;
+    }
+    // MySQL returns timestamps/dates as strings
+    if (typeof value === "string") {
+      return new Date(value);
+    }
+    throw new Error(`Cannot deserialize date from value: ${value}`);
+  }
+
+  protected deserializeBoolean(value: unknown): boolean {
+    if (typeof value === "boolean") {
+      return value;
+    }
+    // MySQL may return booleans as numbers (0/1)
+    if (typeof value === "number") {
+      return value === 1;
+    }
+    throw new Error(`Cannot deserialize boolean from value: ${value}`);
+  }
+
+  protected deserializeBigInt(value: unknown): bigint {
+    if (typeof value === "bigint") {
+      return value;
+    }
+    // MySQL may return bigints as strings
+    if (typeof value === "string") {
+      return BigInt(value);
+    }
+    if (typeof value === "number") {
+      return BigInt(value);
+    }
+    throw new Error(`Cannot deserialize bigint from value: ${value}`);
+  }
+
+  protected serializeJson(value: unknown): unknown {
+    // MySQL supports native JSON, pass through as-is
+    return value;
+  }
+
+  protected deserializeJson(value: unknown): unknown {
+    // MySQL returns parsed JSON objects, pass through as-is
+    return value;
+  }
+
+  protected deserializeBinary(value: unknown): Uint8Array {
+    // MySQL can return Buffer or Uint8Array for BLOB columns
+    if (value instanceof Buffer) {
+      return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+    }
+    if (value instanceof Uint8Array) {
+      return value;
+    }
+    if (value instanceof ArrayBuffer) {
+      return new Uint8Array(value);
+    }
+    throw new Error(`Cannot deserialize binary from value: ${typeof value}`);
+  }
+
+  protected deserializeInteger(value: unknown): number {
+    if (typeof value === "number") {
+      return value;
+    }
+    // MySQL may return integers as strings
+    if (typeof value === "string") {
+      const num = Number(value);
+      if (isNaN(num)) {
+        throw new Error(`Cannot deserialize integer from invalid string: ${value}`);
+      }
+      return num;
+    }
+    // MySQL may return bigint for large integers
+    if (typeof value === "bigint") {
+      if (value > Number.MAX_SAFE_INTEGER || value < Number.MIN_SAFE_INTEGER) {
+        throw new RangeError(
+          `Cannot deserialize integer value ${value}: exceeds safe integer range`,
+        );
+      }
+      return Number(value);
+    }
+    throw new Error(`Cannot deserialize integer from value: ${typeof value}`);
+  }
+
+  protected deserializeDecimal(value: unknown): number {
+    // MySQL can return decimals as numbers or strings
+    if (typeof value === "number") {
+      return value;
+    }
+    if (typeof value === "string") {
+      const num = parseFloat(value);
+      if (isNaN(num)) {
+        throw new Error(`Cannot deserialize decimal from invalid string: ${value}`);
+      }
+      return num;
+    }
+    throw new Error(`Cannot deserialize decimal from value: ${typeof value}`);
+  }
+
+  protected deserializeString(value: unknown): string {
+    if (typeof value === "string") {
+      return value;
+    }
+    throw new Error(`Cannot deserialize string from value: ${typeof value}`);
+  }
+}