@fragno-dev/db 0.1.15 → 0.2.0

package/src/adapters/kysely/kysely-adapter.ts

@@ -1,23 +1,12 @@
-import { sql, type Kysely } from "kysely";
+import { type Kysely } from "kysely";
 import type { SQLProvider } from "../../shared/providers";
+import { type DatabaseAdapter } from "../adapters";
+import { createTableNameMapper } from "../shared/table-name-mapper";
 import {
-  fragnoDatabaseAdapterNameFakeSymbol,
-  fragnoDatabaseAdapterVersionFakeSymbol,
-  type DatabaseAdapter,
-  type DatabaseContextStorage,
-} from "../adapters";
-import { createMigrator, type Migrator } from "../../migration-engine/create";
-import type { AnySchema } from "../../schema/create";
-import type { CustomOperation, MigrationOperation } from "../../migration-engine/shared";
-import { execute, preprocessOperations } from "./migration/execute";
-import type { AbstractQuery } from "../../query/query";
-import { fromKysely, type KyselyUOWConfig } from "./kysely-query";
-import { createTableNameMapper } from "./kysely-shared";
-import { createHash } from "node:crypto";
-import { SETTINGS_TABLE_NAME } from "../../fragments/internal-fragment";
-import type { ConnectionPool } from "../../shared/connection-pool";
-import { createKyselyConnectionPool } from "./kysely-connection-pool";
-import { RequestContextStorage } from "@fragno-dev/core/internal/request-context-storage";
+  GenericSQLAdapter,
+  type GenericSQLOptions,
+  type UnitOfWorkConfig,
+} from "../generic-sql/generic-sql-adapter";
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type KyselyAny = Kysely<any>;
@@ -27,241 +16,12 @@ export interface KyselyConfig {
   provider: SQLProvider;
 }
 
-export class KyselyAdapter implements DatabaseAdapter<KyselyUOWConfig> {
-  #connectionPool: ConnectionPool<KyselyAny>;
-  #provider: SQLProvider;
-  #schemaNamespaceMap = new WeakMap<AnySchema, string>();
-  #contextStorage: RequestContextStorage<DatabaseContextStorage>;
-
-  constructor(config: KyselyConfig) {
-    this.#connectionPool = createKyselyConnectionPool(config.db);
-    this.#provider = config.provider;
-    this.#contextStorage = new RequestContextStorage();
-  }
-
-  get [fragnoDatabaseAdapterNameFakeSymbol](): string {
-    return "kysely";
-  }
-
-  get [fragnoDatabaseAdapterVersionFakeSymbol](): number {
-    return 0;
-  }
-
-  get contextStorage(): RequestContextStorage<DatabaseContextStorage> {
-    return this.#contextStorage;
-  }
-
-  async close(): Promise<void> {
-    await this.#connectionPool.close();
+export class KyselyAdapter extends GenericSQLAdapter implements DatabaseAdapter<UnitOfWorkConfig> {
+  constructor(options: GenericSQLOptions) {
+    super(options);
   }
 
   createTableNameMapper(namespace: string) {
     return createTableNameMapper(namespace);
   }
-
-  createQueryEngine<T extends AnySchema>(
-    schema: T,
-    namespace: string,
-  ): AbstractQuery<T, KyselyUOWConfig> {
-    // Register schema-namespace mapping
-    this.#schemaNamespaceMap.set(schema, namespace);
-
-    // Only create mapper if namespace is non-empty
-    const mapper = namespace ? createTableNameMapper(namespace) : undefined;
-    return fromKysely(
-      schema,
-      this.#connectionPool,
-      this.#provider,
-      mapper,
-      undefined,
-      this.#schemaNamespaceMap,
-    );
-  }
-
-  async isConnectionHealthy(): Promise<boolean> {
-    const conn = await this.#connectionPool.connect();
-    try {
-      const result = await conn.db.executeQuery(sql`SELECT 1 as healthy`.compile(conn.db));
-      return (result.rows[0] as Record<string, unknown>)["healthy"] === 1;
-    } catch {
-      return false;
-    } finally {
-      await conn.release();
-    }
-  }
-
-  createMigrationEngine(schema: AnySchema, namespace: string): Migrator {
-    const mapper = namespace ? createTableNameMapper(namespace) : undefined;
-
-    const preprocessMigrationOperations = (operations: MigrationOperation[], db: KyselyAny) => {
-      // Preprocess operations using the provided db instance
-      const config: KyselyConfig = {
-        db,
-        provider: this.#provider,
-      };
-      let preprocessed = preprocessOperations(operations, config);
-
-      if (this.#provider === "mysql") {
-        preprocessed.unshift({ type: "custom", sql: "SET FOREIGN_KEY_CHECKS = 0" });
-        preprocessed.push({ type: "custom", sql: "SET FOREIGN_KEY_CHECKS = 1" });
-      }
-
-      return preprocessed;
-    };
-
-    // Convert operations to executable nodes bound to specific db instance
-    const toExecutableNodes = (operations: MigrationOperation[], db: KyselyAny) => {
-      const onCustomNode = (node: CustomOperation, db: KyselyAny) => {
-        const statement = sql.raw(node["sql"] as string);
-
-        return {
-          compile() {
-            return statement.compile(db);
-          },
-          execute() {
-            return statement.execute(db);
-          },
-        };
-      };
-
-      const config: KyselyConfig = { db, provider: this.#provider };
-      return operations.flatMap((op) =>
-        execute(op, config, (node) => onCustomNode(node, db), mapper),
-      );
-    };
-
-    const migrator = createMigrator({
-      schema,
-      executor: async (operations) => {
-        const conn = await this.#connectionPool.connect();
-        try {
-          // For SQLite, execute PRAGMA defer_foreign_keys BEFORE transaction
-          if (this.#provider === "sqlite") {
-            await sql.raw("PRAGMA defer_foreign_keys = ON").execute(conn.db);
-          }
-
-          await conn.db.transaction().execute(async (tx) => {
-            // Use the transaction instance for both preprocessing and execution
-            const preprocessed = preprocessMigrationOperations(operations, tx);
-            const nodes = toExecutableNodes(preprocessed, tx);
-            for (const node of nodes) {
-              try {
-                await node.execute();
-              } catch (e) {
-                console.error("failed at", node.compile(), e);
-                throw e;
-              }
-            }
-          });
-        } finally {
-          await conn.release();
-        }
-      },
-      sql: {
-        toSql: (operations) => {
-          const parts: string[] = [];
-
-          // Add SQLite PRAGMA at the beginning
-          if (this.#provider === "sqlite") {
-            parts.push("PRAGMA defer_foreign_keys = ON;");
-          }
-
-          // Use getDatabaseSync for SQL generation (doesn't execute, just builds SQL strings)
-          const db = this.#connectionPool.getDatabaseSync();
-          const preprocessed = preprocessMigrationOperations(operations, db);
-          const nodes = toExecutableNodes(preprocessed, db);
-          const compiled = nodes.map((node) => `${node.compile().sql};`);
-
-          parts.push(...compiled);
-
-          return parts.join("\n\n");
-        },
-      },
-
-      settings: {
-        getVersion: async () => {
-          const conn = await this.#connectionPool.connect();
-          try {
-            const manager = createSettingsManager(conn.db, namespace);
-            const v = await manager.get(`schema_version`);
-            return v ? parseInt(v) : 0;
-          } finally {
-            await conn.release();
-          }
-        },
-        updateSettingsInMigration: async (fromVersion, toVersion) => {
-          const conn = await this.#connectionPool.connect();
-          try {
-            const manager = createSettingsManager(conn.db, namespace);
-            return [
-              {
-                type: "custom",
-                sql:
-                  fromVersion === 0
-                    ? manager.insert(`schema_version`, toVersion.toString())
-                    : manager.update(`schema_version`, toVersion.toString()),
-              },
-            ];
-          } finally {
-            await conn.release();
-          }
-        },
-      },
-    });
-
-    return migrator;
-  }
-
-  async getSchemaVersion(namespace: string): Promise<string | undefined> {
-    const conn = await this.#connectionPool.connect();
-    try {
-      const manager = createSettingsManager(conn.db, namespace);
-      return await manager.get(`schema_version`);
-    } finally {
-      await conn.release();
-    }
-  }
-}
-
-function createSettingsManager(db: KyselyAny, namespace: string) {
-  // Settings table is never namespaced, but keys include namespace prefix
-  const tableName = SETTINGS_TABLE_NAME;
-
-  return {
-    async get(key: string): Promise<string | undefined> {
-      try {
-        const result = await db
-          .selectFrom(tableName)
-          .where("key", "=", sql.lit(`${namespace}.${key}`))
-          .select(["value"])
-          .executeTakeFirstOrThrow();
-        return result.value as string;
-      } catch {
-        return;
-      }
-    },
-
-    insert(key: string, value: string) {
-      return db
-        .insertInto(tableName)
-        .values({
-          id: sql.lit(
-            createHash("md5").update(`${namespace}.${key}`).digest("base64url").replace(/=/g, ""),
-          ),
-          key: sql.lit(`${namespace}.${key}`),
-          value: sql.lit(value),
-        })
-        .compile().sql;
-    },
-
-    update(key: string, value: string) {
-      return db
-        .updateTable(tableName)
-        .set({
-          value: sql.lit(value),
-        })
-        .where("key", "=", sql.lit(`${namespace}.${key}`))
-        .compile().sql;
-    },
-  };
 }

package/src/adapters/{drizzle/drizzle-query.ts → shared/from-unit-of-work-compiler.ts}

@@ -1,24 +1,25 @@
-import type { AbstractQuery } from "../../query/query";
-import type { AnySchema, AnyTable } from "../../schema/create";
-import type { CompiledMutation, UOWExecutor, ValidIndexName } from "../../query/unit-of-work";
-import { createDrizzleUOWCompiler, type DrizzleCompiledQuery } from "./drizzle-uow-compiler";
-import { executeDrizzleRetrievalPhase, executeDrizzleMutationPhase } from "./drizzle-uow-executor";
-import { UnitOfWork } from "../../query/unit-of-work";
-import { parseDrizzle, type DrizzleResult, type TableNameMapper, type DBType } from "./shared";
-import { createDrizzleUOWDecoder } from "./drizzle-uow-decoder";
-import type { ConnectionPool } from "../../shared/connection-pool";
-import type { TableToUpdateValues } from "../../query/query";
+import type { SimpleQueryInterface, TableToUpdateValues } from "../../query/simple-query-interface";
+import type { AnySchema, AnyTable, FragnoId } from "../../schema/create";
+import type {
+  CompiledMutation,
+  UOWCompiler,
+  UOWDecoder,
+  UOWExecutor,
+  ValidIndexName,
+} from "../../query/unit-of-work/unit-of-work";
+import { UnitOfWork } from "../../query/unit-of-work/unit-of-work";
 import type { CursorResult } from "../../query/cursor";
+import type { CompiledQuery } from "../../sql-driver/sql-driver";
 
 /**
- * Configuration options for creating a Drizzle Unit of Work
+ * Configuration options for creating a Unit of Work with generic SQL
  */
-export interface DrizzleUOWConfig {
+export interface UnitOfWorkConfig {
   /**
    * Optional callback to receive compiled SQL queries for logging/debugging
    * This callback is invoked for each query as it's compiled
    */
-  onQuery?: (query: DrizzleCompiledQuery) => void;
+  onQuery?: (query: CompiledQuery) => void;
   /**
    * If true, the query will not be executed and the query will be returned. Not respected for UOWs
    * since those have to be manually executed.
@@ -27,10 +28,52 @@ export interface DrizzleUOWConfig {
 }
 
 /**
- * Special builder for updateMany operations that captures configuration
+ * Factory interface for creating Unit of Work instances
  */
+export interface UnitOfWorkFactory {
+  /**
+   * UOW compiler for compiling operations to SQL
+   */
+  compiler: UOWCompiler<CompiledQuery>;
+  /**
+   * UOW executor for running compiled queries
+   */
+  executor: UOWExecutor<CompiledQuery, unknown>;
+  /**
+   * UOW decoder for transforming raw results
+   */
+  decoder: UOWDecoder<unknown>;
+  /**
+   * Optional UOW configuration
+   */
+  uowConfig?: UnitOfWorkConfig;
+  /**
+   * Optional WeakMap for schema-to-namespace lookups
+   */
+  schemaNamespaceMap?: WeakMap<AnySchema, string>;
+}
+
+/**
+ * Type guard to check if a query is a CompiledMutation
+ */
+function isCompiledMutation(query: unknown): query is CompiledMutation<CompiledQuery> {
+  return (
+    query !== null &&
+    typeof query === "object" &&
+    "expectedAffectedRows" in query &&
+    "query" in query
+  );
+}
+
+/**
+ * Type guard to check if a record has an id field
+ */
+function hasIdField(record: unknown): record is { id: string | FragnoId } {
+  return record !== null && typeof record === "object" && "id" in record;
+}
+
 class UpdateManySpecialBuilder<TTable extends AnyTable> {
-  #indexName?: string;
+  #indexName?: ValidIndexName<TTable>;
   #condition?: unknown;
   #setValues?: TableToUpdateValues<TTable>;
 
@@ -38,7 +81,7 @@ class UpdateManySpecialBuilder<TTable extends AnyTable> {
     indexName: TIndexName,
     condition?: unknown,
   ): this {
-    this.#indexName = indexName as string;
+    this.#indexName = indexName;
     this.#condition = condition;
     return this;
   }
@@ -58,98 +101,56 @@ class UpdateManySpecialBuilder<TTable extends AnyTable> {
 }
 
 /**
- * Creates a Drizzle-based query engine for the given schema.
+ * Creates a generic SQL-based query engine for the given schema using a UnitOfWorkFactory.
  *
- * This is the main entry point for creating a database query interface using Drizzle.
+ * This is the main entry point for creating a database query interface using a Unit of Work compiler.
  * It uses a compiler-based architecture where queries are compiled to SQL and then executed,
  * enabling features like SQL snapshot testing.
  *
  * @param schema - The database schema definition
- * @param pool - Connection pool for acquiring database connections
- * @param provider - SQL provider (sqlite, mysql, postgresql)
- * @param mapper - Optional table name mapper for namespace prefixing
- * @param uowConfig - Optional UOW configuration
- * @param schemaNamespaceMap - Optional WeakMap for schema-to-namespace lookups
- * @returns An AbstractQuery instance for performing database operations
+ * @param factory - Factory containing compiler, executor, decoder, and optional configuration
+ * @returns An SimpleQueryInterface instance for performing database operations
  *
  * @example
  * ```ts
- * const pool = createSimpleConnectionPool(drizzle);
- * const queryEngine = fromDrizzle(mySchema, pool, 'postgresql');
+ * const operationCompiler = new GenericSQLUOWOperationCompiler(driverConfig);
+ * const factory: UnitOfWorkFactory = {
+ *   compiler: createUOWCompilerFromOperationCompiler(operationCompiler),
+ *   executor: createExecutor(sqlDriver),
+ *   decoder: createKyselyUOWDecoder(driverConfig.databaseType),
+ * };
+ * const queryEngine = fromUnitOfWorkCompiler(mySchema, factory);
  *
- * const uow = queryEngine.createUnitOfWork('myOperation');
+ * const users = await queryEngine.find('users', (b) =>
+ *   b.whereIndex('age').where((eb) => eb('age', '>', 18))
+ * );
  * ```
  */
-export function fromDrizzle<T extends AnySchema>(
+export function fromUnitOfWorkCompiler<T extends AnySchema>(
   schema: T,
-  pool: ConnectionPool<DBType>,
-  provider: "sqlite" | "mysql" | "postgresql",
-  mapper?: TableNameMapper,
-  uowConfig?: DrizzleUOWConfig,
-  schemaNamespaceMap?: WeakMap<AnySchema, string>,
-): AbstractQuery<T, DrizzleUOWConfig> {
-  function createUOW(opts: { name?: string; config?: DrizzleUOWConfig }) {
-    const uowCompiler = createDrizzleUOWCompiler(pool, provider, mapper);
-
-    const executor: UOWExecutor<DrizzleCompiledQuery, DrizzleResult> = {
-      async executeRetrievalPhase(retrievalBatch: DrizzleCompiledQuery[]) {
-        // In dryRun mode, skip execution and return empty results
-        if (opts.config?.dryRun) {
-          return retrievalBatch.map(() => ({
-            rows: [],
-            affectedRows: 0,
-          }));
-        }
-
-        const conn = await pool.connect();
-        try {
-          const db = parseDrizzle(conn.db)[0];
-          return await executeDrizzleRetrievalPhase(db, retrievalBatch, provider);
-        } finally {
-          await conn.release();
-        }
-      },
-      async executeMutationPhase(mutationBatch: CompiledMutation<DrizzleCompiledQuery>[]) {
-        // In dryRun mode, skip execution and return success with mock internal IDs
-        if (opts.config?.dryRun) {
-          return {
-            success: true,
-            createdInternalIds: mutationBatch.map(() => null),
-          };
-        }
-
-        const conn = await pool.connect();
-        try {
-          const db = parseDrizzle(conn.db)[0];
-          return await executeDrizzleMutationPhase(db, mutationBatch, provider);
-        } finally {
-          await conn.release();
-        }
-      },
-    };
-
-    const decoder = createDrizzleUOWDecoder(provider);
+  factory: UnitOfWorkFactory,
+): SimpleQueryInterface<T, UnitOfWorkConfig> {
+  const { compiler, executor, decoder, uowConfig, schemaNamespaceMap } = factory;
 
+  function createUOW(opts: { name?: string; config?: UnitOfWorkConfig }) {
     const { onQuery, ...restUowConfig } = opts.config ?? {};
 
     return new UnitOfWork(
-      uowCompiler,
+      compiler,
       executor,
       decoder,
       opts.name,
       {
         ...restUowConfig,
-        onQuery: (query) => {
-          // Handle both CompiledQuery and CompiledMutation structures
-          // Retrieval operations return DrizzleCompiledQuery directly: { sql, params }
-          // Mutation operations return CompiledMutation: { query: DrizzleCompiledQuery, expectedAffectedRows }
-          const actualQuery =
-            query && typeof query === "object" && "query" in query
-              ? (query as CompiledMutation<DrizzleCompiledQuery>).query
-              : (query as DrizzleCompiledQuery);
-
-          opts.config?.onQuery?.(actualQuery);
-        },
+        onQuery: onQuery
+          ? (query) => {
+              // Extract the actual query from CompiledMutation if needed
+              const actualQuery = isCompiledMutation(query)
+                ? query.query
+                : (query as CompiledQuery);
+              onQuery(actualQuery);
+            }
+          : undefined,
       },
       schemaNamespaceMap,
     ).forSchema(schema);
@@ -157,18 +158,16 @@ export function fromDrizzle<T extends AnySchema>(
 
   return {
     async find(tableName, builderFn) {
-      // Safe: builderFn returns a FindBuilder (or void), which matches UnitOfWork signature
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const uow = createUOW({ config: uowConfig }).find(tableName, builderFn as any);
-      const [result] = await uow.executeRetrieve();
-      return result;
+      const uow = createUOW({ config: uowConfig });
+      uow.find(tableName, builderFn);
+      const [result]: unknown[][] = await uow.executeRetrieve();
+      return result ?? [];
     },
 
     async findWithCursor(tableName, builderFn) {
-      // Safe: builderFn returns a FindBuilder, which matches UnitOfWork signature
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const uow = createUOW({ config: uowConfig }).findWithCursor(tableName, builderFn as any);
+      const uow = createUOW({ config: uowConfig }).findWithCursor(tableName, builderFn);
       const [result] = await uow.executeRetrieve();
+      // Result from findWithCursor is always a CursorResult - the UOW decoder handles the conversion
       return result as CursorResult<unknown>;
     },
 
@@ -245,12 +244,13 @@ export function fromDrizzle<T extends AnySchema>(
 
       const findUow = createUOW({ config: uowConfig });
       findUow.find(tableName, (b) => {
-        if (condition) {
-          // Safe: condition is captured from whereIndex call with proper typing
+        // Condition might be null or undefined, only pass if defined and not null
+        if (condition !== undefined && condition !== null) {
+          // TypeScript can't infer the complex condition type from the builder
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          return b.whereIndex(indexName as ValidIndexName<typeof table>, condition as any);
+          return b.whereIndex(indexName, condition as any);
         }
-        return b.whereIndex(indexName as ValidIndexName<typeof table>);
+        return b.whereIndex(indexName);
       });
       const [records]: unknown[][] = await findUow.executeRetrieve();
 
@@ -259,8 +259,11 @@ export function fromDrizzle<T extends AnySchema>(
       }
 
       const updateUow = createUOW({ config: uowConfig });
-      for (const record of records as Array<{ id: unknown }>) {
-        updateUow.update(tableName, record.id as string, (b) => b.set(setValues));
+      for (const record of records) {
+        if (!hasIdField(record)) {
+          throw new Error("Record missing id field");
+        }
+        updateUow.update(tableName, record.id, (b) => b.set(setValues));
       }
       const { success } = await updateUow.executeMutations();
       if (!success) {
@@ -287,8 +290,11 @@ export function fromDrizzle<T extends AnySchema>(
       }
 
       const deleteUow = createUOW({ config: uowConfig });
-      for (const record of records as Array<{ id: unknown }>) {
-        deleteUow.delete(tableName, record.id as string);
+      for (const record of records) {
+        if (!hasIdField(record)) {
+          throw new Error("Record missing id field");
+        }
+        deleteUow.delete(tableName, record.id);
       }
       const { success } = await deleteUow.executeMutations();
       if (!success) {
@@ -305,5 +311,5 @@ export function fromDrizzle<T extends AnySchema>(
         },
       });
     },
-  } as AbstractQuery<T, DrizzleUOWConfig>;
+  } as SimpleQueryInterface<T, UnitOfWorkConfig>;
 }

package/src/adapters/shared/table-name-mapper.ts

@@ -0,0 +1,50 @@
+/**
+ * Sanitizes a namespace for use in database table names and TypeScript exports.
+ * Converts dashes to underscores to ensure compatibility with SQL identifiers
+ * and Drizzle's relational query system.
+ *
+ * @example
+ * sanitizeNamespace("my-fragment") // => "my_fragment"
+ */
+export function sanitizeNamespace(namespace: string): string {
+  return namespace.replace(/-/g, "_");
+}
+
+/**
+ * Maps logical table names (used by fragment authors) to physical table names (with namespace suffix)
+ */
+export interface TableNameMapper {
+  toPhysical(logicalName: string): string;
+  toLogical(physicalName: string): string;
+}
+
+/**
+ * Creates a table name mapper for a given namespace.
+ * Physical names have format: {logicalName}_{namespace} (or {logicalName}_{sanitizedNamespace} if sanitize is true)
+ *
+ * @param namespace - The namespace to use for table name prefixing
+ * @param sanitize - Whether to sanitize the namespace by converting dashes to underscores (default: false)
+ * @returns A table name mapper with toPhysical and toLogical methods
+ *
+ * @example
+ * const mapper = createTableNameMapper("my-fragment");
+ * mapper.toPhysical("users") // => "users_my-fragment"
+ *
+ * @example
+ * const mapper = createTableNameMapper("my-fragment", true);
+ * mapper.toPhysical("users") // => "users_my_fragment"
+ * mapper.toLogical("users_my_fragment") // => "users"
+ */
+export function createTableNameMapper(namespace: string, sanitize = false): TableNameMapper {
+  const processedNamespace = sanitize ? sanitizeNamespace(namespace) : namespace;
+
+  return {
+    toPhysical: (logicalName: string) => `${logicalName}_${processedNamespace}`,
+    toLogical: (physicalName: string) => {
+      if (physicalName.endsWith(`_${processedNamespace}`)) {
+        return physicalName.slice(0, -(processedNamespace.length + 1));
+      }
+      return physicalName;
+    },
+  };
+}