@fragno-dev/db 0.0.1 → 0.1.0

package/src/adapters/kysely/kysely-uow-compiler.ts

@@ -0,0 +1,271 @@
+import type { CompiledQuery } from "kysely";
+import type { AnyColumn, AnySchema, FragnoId } from "../../schema/create";
+import type {
+  CompiledMutation,
+  MutationOperation,
+  RetrievalOperation,
+  UOWCompiler,
+} from "../../query/unit-of-work";
+import type { KyselyConfig } from "./kysely-adapter";
+import { createKyselyQueryCompiler } from "./kysely-query-compiler";
+import { createKyselyQueryBuilder } from "./kysely-query-builder";
+import { buildCondition, type Condition } from "../../query/condition-builder";
+import { decodeCursor, serializeCursorValues } from "../../query/cursor";
+import type { AnySelectClause } from "../../query/query";
+
+/**
+ * Create a Kysely-specific Unit of Work compiler
+ *
+ * This compiler translates UOW operations into Kysely CompiledQuery objects
+ * that can be executed as a batch/transaction.
+ *
+ * @param schema - The database schema
+ * @param config - Kysely configuration
+ * @returns A UOWCompiler instance for Kysely
+ */
+export function createKyselyUOWCompiler<TSchema extends AnySchema>(
+  schema: TSchema,
+  config: KyselyConfig,
+): UOWCompiler<TSchema, CompiledQuery> {
+  const queryCompiler = createKyselyQueryCompiler(schema, config);
+  const queryBuilder = createKyselyQueryBuilder(config.db, config.provider);
+  const { provider } = config;
+
+  function toTable(name: unknown) {
+    const table = schema.tables[name as string];
+    if (!table) {
+      throw new Error(`Invalid table name ${name}.`);
+    }
+    return table;
+  }
+
+  return {
+    compileRetrievalOperation(op: RetrievalOperation<TSchema>): CompiledQuery | null {
+      switch (op.type) {
+        case "count": {
+          return queryCompiler.count(op.table.name, {
+            where: op.options.where,
+          });
+        }
+
+        case "find": {
+          // Map UOW FindOptions to query compiler's FindManyOptions
+          const {
+            useIndex: _useIndex,
+            orderByIndex,
+            joins: join,
+            after,
+            before,
+            pageSize,
+            ...findManyOptions
+          } = op.options;
+
+          // Get index columns for ordering and cursor pagination
+          let indexColumns: AnyColumn[] = [];
+          let orderDirection: "asc" | "desc" = "asc";
+
+          if (orderByIndex) {
+            const index = op.table.indexes[orderByIndex.indexName];
+            orderDirection = orderByIndex.direction;
+
+            if (!index) {
+              // If _primary index doesn't exist, fall back to internal ID column
+              // (which is the actual primary key and maintains insertion order)
+              if (orderByIndex.indexName === "_primary") {
+                indexColumns = [op.table.getIdColumn()];
+              } else {
+                throw new Error(
+                  `Index "${orderByIndex.indexName}" not found on table "${op.table.name}"`,
+                );
+              }
+            } else {
+              // Order by all columns in the index with the specified direction
+              indexColumns = index.columns;
+            }
+          }
+
+          // Convert orderByIndex to orderBy format
+          let orderBy: [AnyColumn, "asc" | "desc"][] | undefined;
+          if (indexColumns.length > 0) {
+            orderBy = indexColumns.map((col) => [col, orderDirection]);
+          }
+
+          // Handle cursor pagination - build a cursor condition
+          let cursorCondition: Condition | undefined;
+
+          if ((after || before) && indexColumns.length > 0) {
+            const cursor = after || before;
+            const cursorData = decodeCursor(cursor!);
+            const serializedValues = serializeCursorValues(cursorData, indexColumns, provider);
+
+            // Build tuple comparison for cursor pagination
+            // For "after" with "asc": (col1, col2, ...) > (val1, val2, ...)
+            // For "before" with "desc": reverse the comparison
+            const isAfter = !!after;
+            const useGreaterThan =
+              (isAfter && orderDirection === "asc") || (!isAfter && orderDirection === "desc");
+
+            if (indexColumns.length === 1) {
+              // Simple single-column case
+              const col = indexColumns[0]!;
+              const val = serializedValues[col.ormName];
+              const operator = useGreaterThan ? ">" : "<";
+              cursorCondition = {
+                type: "compare",
+                a: col,
+                operator,
+                b: val,
+              };
+            } else {
+              // Multi-column tuple comparison - not yet supported for Kysely
+              throw new Error(
+                "Multi-column cursor pagination is not yet supported in Kysely Unit of Work implementation",
+              );
+            }
+          }
+
+          // Combine user where clause with cursor condition
+          let combinedWhere: Condition | undefined;
+          if (findManyOptions.where) {
+            const whereResult = buildCondition(op.table.columns, findManyOptions.where);
+            if (whereResult === true) {
+              combinedWhere = undefined;
+            } else if (whereResult === false) {
+              return null;
+            } else {
+              combinedWhere = whereResult;
+            }
+          }
+
+          if (cursorCondition) {
+            if (combinedWhere) {
+              combinedWhere = {
+                type: "and",
+                items: [combinedWhere, cursorCondition],
+              };
+            } else {
+              combinedWhere = cursorCondition;
+            }
+          }
+
+          // When we have joins or need to bypass buildFindOptions, use queryBuilder directly
+          if (join && join.length > 0) {
+            return queryBuilder.findMany(op.table, {
+              // Safe cast: select from UOW matches SimplifyFindOptions requirement
+              select: (findManyOptions.select ?? true) as AnySelectClause,
+              where: combinedWhere,
+              orderBy,
+              limit: pageSize,
+              join,
+            });
+          }
+
+          return queryCompiler.findMany(op.table.name, {
+            ...findManyOptions,
+            where: combinedWhere ? () => combinedWhere! : undefined,
+            orderBy: orderBy?.map(([col, dir]) => [col.ormName, dir]),
+            limit: pageSize,
+          });
+        }
+      }
+    },
+
+    compileMutationOperation(
+      op: MutationOperation<TSchema>,
+    ): CompiledMutation<CompiledQuery> | null {
+      switch (op.type) {
+        case "create":
+          // queryCompiler.create() calls encodeValues() which handles runtime defaults
+          return {
+            query: queryCompiler.create(op.table, op.values),
+            expectedAffectedRows: null, // creates don't need affected row checks
+          };
+
+        case "update": {
+          const table = toTable(op.table);
+          const idColumn = table.getIdColumn();
+          const versionColumn = table.getVersionColumn();
+
+          const externalId = typeof op.id === "string" ? op.id : op.id.externalId;
+          const versionToCheck = getVersionToCheck(op.id, op.checkVersion);
+
+          // Build WHERE clause that filters by ID and optionally by version
+          const whereClause =
+            versionToCheck !== undefined
+              ? () =>
+                  buildCondition(table.columns, (eb) =>
+                    eb.and(
+                      eb(idColumn.ormName, "=", externalId),
+                      eb(versionColumn.ormName, "=", versionToCheck),
+                    ),
+                  )
+              : () => buildCondition(table.columns, (eb) => eb(idColumn.ormName, "=", externalId));
+
+          const query = queryCompiler.updateMany(op.table, {
+            where: whereClause,
+            set: op.set,
+          });
+
+          return query
+            ? {
+                query,
+                expectedAffectedRows: op.checkVersion ? 1 : null,
+              }
+            : null;
+        }
+
+        case "delete": {
+          const table = toTable(op.table);
+          const idColumn = table.getIdColumn();
+          const versionColumn = table.getVersionColumn();
+
+          // Extract external ID based on whether op.id is FragnoId or string
+          const externalId = typeof op.id === "string" ? op.id : op.id.externalId;
+          const versionToCheck = getVersionToCheck(op.id, op.checkVersion);
+
+          // Build WHERE clause that filters by ID and optionally by version
+          const whereClause =
+            versionToCheck !== undefined
+              ? () =>
+                  buildCondition(table.columns, (eb) =>
+                    eb.and(
+                      eb(idColumn.ormName, "=", externalId),
+                      eb(versionColumn.ormName, "=", versionToCheck),
+                    ),
+                  )
+              : () => buildCondition(table.columns, (eb) => eb(idColumn.ormName, "=", externalId));
+
+          const query = queryCompiler.deleteMany(op.table, {
+            where: whereClause,
+          });
+
+          return query
+            ? {
+                query,
+                expectedAffectedRows: op.checkVersion ? 1 : null,
+              }
+            : null;
+        }
+      }
+    },
+  };
+}
+
+/**
+ * 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.
+ */
+function 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;
+}

package/src/adapters/kysely/kysely-uow-executor.ts

@@ -0,0 +1,149 @@
+import type { Kysely, QueryResult } from "kysely";
+import type { CompiledMutation, MutationResult } from "../../query/unit-of-work";
+
+function getAffectedRows(result: QueryResult<unknown>): number {
+  const affectedRows =
+    result.numAffectedRows ??
+    result.numChangedRows ??
+    // PGLite returns `affectedRows` instead of `numAffectedRows` or `numChangedRows`
+    ("affectedRows" in result &&
+    (typeof result["affectedRows"] === "number" || typeof result["affectedRows"] === "bigint")
+      ? result["affectedRows"]
+      : undefined);
+
+  if (affectedRows === undefined) {
+    throw new Error("No affected rows found");
+  }
+
+  if (affectedRows > Number.MAX_SAFE_INTEGER) {
+    throw new Error(
+      `affectedRows BigInt value ${affectedRows.toString()} exceeds JS safe integer range`,
+    );
+  }
+
+  return Number(affectedRows);
+}
+
+/**
+ * Execute the retrieval phase of a Unit of Work using Kysely
+ *
+ * All retrieval queries are executed inside a single transaction to ensure
+ * snapshot isolation - all reads see a consistent view of the database.
+ *
+ * @param kysely - The Kysely database instance
+ * @param retrievalBatch - Array of compiled retrieval queries
+ * @returns Array of query results matching the retrieval operations order
+ *
+ * @example
+ * ```ts
+ * const retrievalResults = await executeKyselyRetrievalPhase(kysely, compiled.retrievalBatch);
+ * const [users, posts] = retrievalResults;
+ * ```
+ */
+export async function executeKyselyRetrievalPhase(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  kysely: Kysely<any>,
+  retrievalBatch: (Kysely<unknown>["executeQuery"] extends (query: infer Q) => unknown
+    ? Q
+    : never)[],
+): Promise<unknown[]> {
+  // If no retrieval operations, return empty array immediately
+  if (retrievalBatch.length === 0) {
+    return [];
+  }
+
+  const retrievalResults: unknown[] = [];
+
+  // Execute all retrieval queries inside a transaction for snapshot isolation
+  await kysely.transaction().execute(async (tx) => {
+    for (const query of retrievalBatch) {
+      const result = await tx.executeQuery(query);
+      retrievalResults.push(result.rows);
+    }
+  });
+
+  return retrievalResults;
+}
+
+/**
+ * Execute the mutation phase of a Unit of Work using Kysely
+ *
+ * All mutation queries are executed in a transaction with optimistic locking.
+ * If any version check fails, the entire transaction is rolled back and
+ * success=false is returned.
+ *
+ * @param kysely - The Kysely database instance
+ * @param mutationBatch - Array of compiled mutation queries with expected affected rows
+ * @returns Object with success flag and internal IDs from create operations
+ *
+ * @example
+ * ```ts
+ * const { success, createdInternalIds } = await executeKyselyMutationPhase(kysely, compiled.mutationBatch);
+ * if (!success) {
+ *   console.log("Version conflict detected, retrying...");
+ * }
+ * ```
+ */
+export async function executeKyselyMutationPhase(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  kysely: Kysely<any>,
+  mutationBatch: CompiledMutation<
+    Kysely<unknown>["executeQuery"] extends (query: infer Q) => unknown ? Q : never
+  >[],
+): Promise<MutationResult> {
+  // If there are no mutations, return success immediately
+  if (mutationBatch.length === 0) {
+    return { success: true, createdInternalIds: [] };
+  }
+
+  const createdInternalIds: (bigint | null)[] = [];
+
+  // Execute mutation batch in a transaction
+  try {
+    await kysely.transaction().execute(async (tx) => {
+      for (const compiledMutation of mutationBatch) {
+        const result = await tx.executeQuery(compiledMutation.query);
+
+        // For creates (expectedAffectedRows === null), try to extract internal ID
+        if (compiledMutation.expectedAffectedRows === null) {
+          // Check if result has rows (RETURNING clause supported)
+          if (Array.isArray(result.rows) && result.rows.length > 0) {
+            const row = result.rows[0] as Record<string, unknown>;
+            if ("_internalId" in row || "_internal_id" in row) {
+              const internalId = (row["_internalId"] ?? row["_internal_id"]) as bigint;
+              createdInternalIds.push(internalId);
+            } else {
+              // RETURNING supported but _internalId not found
+              createdInternalIds.push(null);
+            }
+          } else {
+            // No RETURNING support (e.g., MySQL)
+            createdInternalIds.push(null);
+          }
+        } else {
+          // Check affected rows for updates/deletes
+          const affectedRows = getAffectedRows(result);
+
+          if (affectedRows !== compiledMutation.expectedAffectedRows) {
+            // Version conflict detected - the UPDATE/DELETE didn't affect the expected number of rows
+            // This means either the row doesn't exist or the version has changed
+            throw new Error(
+              `Version conflict: expected ${compiledMutation.expectedAffectedRows} rows affected, but got ${affectedRows}`,
+            );
+          }
+        }
+      }
+    });
+
+    return { success: true, createdInternalIds };
+  } catch (error) {
+    // Transaction failed - could be version conflict or other constraint violation
+    // Return success=false to indicate the UOW should be retried
+    if (error instanceof Error && error.message.includes("Version conflict")) {
+      return { success: false };
+    }
+
+    // Other database errors should be thrown
+    throw error;
+  }
+}