@fragno-dev/db 0.1.14 → 0.2.0

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,118 +101,73 @@ 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(
-      schema,
-      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);
   }
 
   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>;
     },
 
@@ -246,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();
 
@@ -260,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) {
@@ -288,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) {
@@ -306,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;
+    },
+  };
+}

package/src/adapters/shared/uow-operation-compiler.ts

@@ -0,0 +1,211 @@
+import type { AnyColumn, AnySchema, AnyTable, FragnoId } from "../../schema/create";
+import type { Condition } from "../../query/condition-builder";
+import type {
+  CompiledMutation,
+  RetrievalOperation,
+  MutationOperation,
+  UOWCompiler,
+} from "../../query/unit-of-work/unit-of-work";
+import { Cursor } from "../../query/cursor";
+import type { DriverConfig } from "../generic-sql/driver-config";
+import { createTableNameMapper, type TableNameMapper } from "./table-name-mapper";
+
+/**
+ * Options for compiling a find operation with cursor pagination
+ */
+export interface FindCompilationOptions {
+  /** Index columns used for ordering */
+  indexColumns: AnyColumn[];
+  /** Order direction for the index */
+  orderDirection: "asc" | "desc";
+  /** User-provided where condition */
+  userWhere: Condition | boolean | undefined;
+  /** Cursor string or Cursor object for pagination (after) */
+  after?: string | Cursor;
+  /** Cursor string or Cursor object for pagination (before) */
+  before?: string | Cursor;
+  /** Page size for pagination */
+  pageSize?: number;
+  /** Whether this is a high-level cursor API call (affects limit calculation) */
+  withCursor?: boolean;
+  /** Driver config for cursor serialization */
+  driverConfig: DriverConfig;
+}
+
+/**
+ * Result of cursor condition building
+ */
+export interface CursorConditionResult {
+  /** The combined where condition (user where + cursor condition) */
+  where: Condition | undefined;
+  /** The effective limit to use (may be pageSize + 1 for cursor detection) */
+  limit: number | undefined;
+}
+
+/**
+ * Abstract base class for Unit of Work operation compilers
+ *
+ * This class provides a structure and utilities for implementing UOW compilers
+ * for different ORM/query builders (Kysely, Drizzle, etc.).
+ *
+ * Subclasses must implement the abstract methods for each operation type,
+ * and can use the provided utility methods for common tasks.
+ *
+ * @template TCompiledQuery - The type of compiled query for the target ORM
+ */
+export abstract class UOWOperationCompiler<TCompiledQuery> {
+  #driverConfig: DriverConfig;
+  #mapperFactory?: (namespace: string | undefined) => TableNameMapper | undefined;
+
+  constructor(
+    driverConfig: DriverConfig,
+    mapperFactory?: (namespace: string | undefined) => TableNameMapper | undefined,
+  ) {
+    this.#driverConfig = driverConfig;
+    this.#mapperFactory = mapperFactory;
+  }
+
+  protected get driverConfig(): DriverConfig {
+    return this.#driverConfig;
+  }
+
+  protected get mapperFactory():
+    | ((namespace: string | undefined) => TableNameMapper | undefined)
+    | undefined {
+    return this.#mapperFactory;
+  }
+
+  abstract compileCount(
+    op: RetrievalOperation<AnySchema> & { type: "count" },
+  ): TCompiledQuery | null;
+
+  abstract compileFind(op: RetrievalOperation<AnySchema> & { type: "find" }): TCompiledQuery | null;
+
+  /**
+   * Compile a create operation
+   */
+  abstract compileCreate(
+    op: MutationOperation<AnySchema> & { type: "create" },
+  ): CompiledMutation<TCompiledQuery> | null;
+
+  abstract compileUpdate(
+    op: MutationOperation<AnySchema> & { type: "update" },
+  ): CompiledMutation<TCompiledQuery> | null;
+
+  abstract compileDelete(
+    op: MutationOperation<AnySchema> & { type: "delete" },
+  ): CompiledMutation<TCompiledQuery> | null;
+
+  abstract compileCheck(
+    op: MutationOperation<AnySchema> & { type: "check" },
+  ): CompiledMutation<TCompiledQuery> | null;
+
+  // ==================== Utility Methods ====================
+
+  /**
+   * Get the mapper for a specific operation based on its namespace
+   */
+  protected getMapperForOperation(namespace: string | undefined): TableNameMapper | undefined {
+    return this.#mapperFactory
+      ? this.#mapperFactory(namespace)
+      : namespace
+        ? createTableNameMapper(namespace)
+        : undefined;
+  }
+
+  /**
+   * Get a table from a schema by name
+   * @throws Error if table is not found
+   */
+  protected getTable(schema: AnySchema, tableName: string): AnyTable {
+    const table = schema.tables[tableName];
+    if (!table) {
+      throw new Error(`Invalid table name ${tableName}.`);
+    }
+    return table;
+  }
+
+  /**
+   * Get the version to check for a given ID and checkVersion flag
+   * @returns The version to check or undefined if no check is required
+   * @throws Error if the ID is a string and checkVersion is true
+   */
+  protected getVersionToCheck(id: FragnoId | string, checkVersion: boolean): number | undefined {
+    if (!checkVersion) {
+      return undefined;
+    }
+
+    if (typeof id === "string") {
+      throw new Error(
+        `Cannot use checkVersion with a string ID. Version checking requires a FragnoId with version information.`,
+      );
+    }
+
+    return id.version;
+  }
+
+  /**
+   * Extract external ID from FragnoId or string
+   */
+  protected getExternalId(id: FragnoId | string): string {
+    return typeof id === "string" ? id : id.externalId;
+  }
+
+  /**
+   * Get the physical table name for an operation, applying namespace mapping if needed
+   */
+  protected getPhysicalTableName(logicalName: string, namespace: string | undefined): string {
+    const mapper = this.getMapperForOperation(namespace);
+    return mapper ? mapper.toPhysical(logicalName) : logicalName;
+  }
+}
+
+/**
+ * Creates a UOWCompiler from a UOWOperationCompiler by dispatching operations
+ * to the appropriate specific compilation methods based on operation type.
+ *
+ * @template TCompiledQuery - The type of compiled query for the target ORM
+ * @param operationCompiler - The operation compiler to wrap
+ * @returns A UOWCompiler instance that delegates to the operation compiler
+ */
+export function createUOWCompilerFromOperationCompiler<TCompiledQuery>(
+  operationCompiler: UOWOperationCompiler<TCompiledQuery>,
+): UOWCompiler<TCompiledQuery> {
+  return {
+    compileRetrievalOperation(op: RetrievalOperation<AnySchema>): TCompiledQuery | null {
+      switch (op.type) {
+        case "count":
+          return operationCompiler.compileCount(op);
+        case "find":
+          return operationCompiler.compileFind(op);
+        default: {
+          const exhaustiveCheck: never = op;
+          throw new Error(
+            `Unknown retrieval operation type: ${(exhaustiveCheck as RetrievalOperation<AnySchema>).type}`,
+          );
+        }
+      }
+    },
+
+    compileMutationOperation(
+      op: MutationOperation<AnySchema>,
+    ): CompiledMutation<TCompiledQuery> | null {
+      switch (op.type) {
+        case "create":
+          return operationCompiler.compileCreate(op);
+        case "update":
+          return operationCompiler.compileUpdate(op);
+        case "delete":
+          return operationCompiler.compileDelete(op);
+        case "check":
+          return operationCompiler.compileCheck(op);
+        default: {
+          const exhaustiveCheck: never = op;
+          throw new Error(
+            `Unknown mutation operation type: ${(exhaustiveCheck as MutationOperation<AnySchema>).type}`,
+          );
+        }
+      }
+    },
+  };
+}