@fragno-dev/db 0.1.15 → 0.2.0

package/src/adapters/generic-sql/query/generic-sql-uow-operation-compiler.ts

@@ -0,0 +1,314 @@
+import { UOWOperationCompiler } from "../../shared/uow-operation-compiler";
+import type { CompiledQuery } from "kysely";
+import type { DriverConfig } from "../driver-config";
+import type { TableNameMapper } from "../../shared/table-name-mapper";
+import type {
+  RetrievalOperation,
+  MutationOperation,
+  CompiledMutation,
+} from "../../../query/unit-of-work/unit-of-work";
+import type { AnyColumn, AnySchema } from "../../../schema/create";
+import { buildCondition } from "../../../query/condition-builder";
+import { createSQLQueryCompiler } from "./create-sql-query-compiler";
+import { SQLQueryCompiler } from "./sql-query-compiler";
+import { buildCursorCondition } from "./cursor-utils";
+import type { Condition } from "../../../query/condition-builder";
+import { buildFindOptions } from "../../../query/orm/orm";
+import type { AnySelectClause } from "../../../query/simple-query-interface";
+import { createColdKysely } from "../migration/cold-kysely";
+
+/**
+ * Generic SQL UOW Operation Compiler.
+ *
+ * Uses SQLQueryCompiler for dialect-specific SQL generation while handling
+ * high-level business logic like cursor pagination, version checking, and index resolution.
+ */
+export class GenericSQLUOWOperationCompiler extends UOWOperationCompiler<CompiledQuery> {
+  constructor(
+    driverConfig: DriverConfig,
+    mapperFactory?: (namespace: string | undefined) => TableNameMapper | undefined,
+  ) {
+    super(driverConfig, mapperFactory);
+  }
+
+  /**
+   * Get SQL compiler for a specific namespace
+   */
+  private getSQLCompiler(namespace: string | undefined): SQLQueryCompiler {
+    const mapper = this.getMapperForOperation(namespace);
+    const kysely = createColdKysely(this.driverConfig.databaseType);
+    return createSQLQueryCompiler(kysely, this.driverConfig, mapper);
+  }
+
+  override compileCount(
+    op: RetrievalOperation<AnySchema> & { type: "count" },
+  ): CompiledQuery | null {
+    const sqlCompiler = this.getSQLCompiler(op.namespace);
+
+    // Build where condition
+    let conditions = op.options.where
+      ? buildCondition(op.table.columns, op.options.where)
+      : undefined;
+
+    if (conditions === true) {
+      conditions = undefined;
+    }
+    if (conditions === false) {
+      return null;
+    }
+
+    return sqlCompiler.compileCount(op.table, { where: conditions });
+  }
+
+  override compileFind(op: RetrievalOperation<AnySchema> & { type: "find" }): CompiledQuery | null {
+    const sqlCompiler = this.getSQLCompiler(op.namespace);
+
+    // Extract options
+    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
+        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
+    // TODO: Multi-column cursor pagination not yet supported
+    if ((after || before) && indexColumns.length > 1) {
+      throw new Error(
+        "Multi-column cursor pagination is not yet supported in Generic SQL implementation",
+      );
+    }
+    const cursorCondition = buildCursorCondition(
+      after || before,
+      indexColumns,
+      orderDirection,
+      !!after,
+      this.driverConfig,
+    );
+
+    // 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;
+      }
+    }
+
+    // For cursor pagination, fetch one extra item to determine if there's a next page
+    const effectiveLimit = pageSize && op.withCursor ? pageSize + 1 : pageSize;
+
+    // When we have joins, use the query builder directly
+    if (join && join.length > 0) {
+      return sqlCompiler.compileFindMany(op.table, {
+        select: (findManyOptions.select ?? true) as AnySelectClause,
+        where: combinedWhere,
+        orderBy,
+        limit: effectiveLimit,
+        join,
+      });
+    }
+
+    // Otherwise, use buildFindOptions to process the query options
+    const compiledOptions = buildFindOptions(op.table, {
+      ...findManyOptions,
+      where: combinedWhere ? () => combinedWhere! : undefined,
+      orderBy: orderBy?.map(([col, dir]) => [col.ormName, dir]),
+      limit: effectiveLimit,
+    });
+
+    if (compiledOptions === false) {
+      return null;
+    }
+
+    return sqlCompiler.compileFindMany(op.table, compiledOptions);
+  }
+
+  override compileCreate(
+    op: MutationOperation<AnySchema> & { type: "create" },
+  ): CompiledMutation<CompiledQuery> | null {
+    const sqlCompiler = this.getSQLCompiler(op.namespace);
+    const table = this.getTable(op.schema, op.table);
+
+    return {
+      query: sqlCompiler.compileCreate(table, op.values),
+      op: "create",
+      expectedAffectedRows: null, // creates don't need affected row checks
+      expectedReturnedRows: null,
+    };
+  }
+
+  override compileUpdate(
+    op: MutationOperation<AnySchema> & { type: "update" },
+  ): CompiledMutation<CompiledQuery> | null {
+    const sqlCompiler = this.getSQLCompiler(op.namespace);
+    const table = this.getTable(op.schema, op.table);
+    const idColumn = table.getIdColumn();
+    const versionColumn = table.getVersionColumn();
+
+    const externalId = this.getExternalId(op.id);
+    const versionToCheck = this.getVersionToCheck(op.id, op.checkVersion);
+
+    // Build WHERE clause that filters by ID and optionally by version
+    const conditionsResult =
+      versionToCheck !== undefined
+        ? buildCondition(table.columns, (eb) =>
+            eb.and(
+              eb(idColumn.ormName, "=", externalId),
+              eb(versionColumn.ormName, "=", versionToCheck),
+            ),
+          )
+        : buildCondition(table.columns, (eb) => eb(idColumn.ormName, "=", externalId));
+
+    if (conditionsResult === false) {
+      return null;
+    }
+
+    const conditions: Condition | undefined =
+      conditionsResult === true ? undefined : conditionsResult;
+
+    // Determine if we should use RETURNING-based checking
+    // Use RETURNING when driver supports it but doesn't support affected rows reporting
+    const useReturningForCheck =
+      op.checkVersion &&
+      this.driverConfig.supportsReturning &&
+      !this.driverConfig.supportsRowsAffected;
+
+    const query = sqlCompiler.compileUpdate(table, {
+      set: op.set,
+      where: conditions,
+      returning: useReturningForCheck,
+    });
+
+    return {
+      query,
+      op: "update",
+      expectedAffectedRows: useReturningForCheck ? null : op.checkVersion ? 1n : null,
+      expectedReturnedRows: useReturningForCheck ? 1 : null,
+    };
+  }
+
+  override compileDelete(
+    op: MutationOperation<AnySchema> & { type: "delete" },
+  ): CompiledMutation<CompiledQuery> | null {
+    const sqlCompiler = this.getSQLCompiler(op.namespace);
+    const table = this.getTable(op.schema, op.table);
+    const idColumn = table.getIdColumn();
+    const versionColumn = table.getVersionColumn();
+
+    const externalId = this.getExternalId(op.id);
+    const versionToCheck = this.getVersionToCheck(op.id, op.checkVersion);
+
+    // Build WHERE clause that filters by ID and optionally by version
+    const conditionsResult =
+      versionToCheck !== undefined
+        ? buildCondition(table.columns, (eb) =>
+            eb.and(
+              eb(idColumn.ormName, "=", externalId),
+              eb(versionColumn.ormName, "=", versionToCheck),
+            ),
+          )
+        : buildCondition(table.columns, (eb) => eb(idColumn.ormName, "=", externalId));
+
+    if (conditionsResult === false) {
+      return null;
+    }
+
+    const conditions: Condition | undefined =
+      conditionsResult === true ? undefined : conditionsResult;
+
+    // Determine if we should use RETURNING-based checking
+    // Use RETURNING when driver supports it but doesn't support affected rows reporting
+    const useReturningForCheck =
+      op.checkVersion &&
+      this.driverConfig.supportsReturning &&
+      !this.driverConfig.supportsRowsAffected;
+
+    const query = sqlCompiler.compileDelete(table, {
+      where: conditions,
+      returning: useReturningForCheck,
+    });
+
+    return {
+      query,
+      op: "delete",
+      expectedAffectedRows: useReturningForCheck ? null : op.checkVersion ? 1n : null,
+      expectedReturnedRows: useReturningForCheck ? 1 : null,
+    };
+  }
+
+  override compileCheck(
+    op: MutationOperation<AnySchema> & { type: "check" },
+  ): CompiledMutation<CompiledQuery> {
+    const sqlCompiler = this.getSQLCompiler(op.namespace);
+    const table = this.getTable(op.schema, op.table);
+    const idColumn = table.getIdColumn();
+    const versionColumn = table.getVersionColumn();
+
+    const externalId = op.id.externalId;
+    const version = op.id.version;
+
+    // Build a SELECT 1 query to check if the row exists with the correct version
+    const condition = buildCondition(table.columns, (eb) =>
+      eb.and(eb(idColumn.ormName, "=", externalId), eb(versionColumn.ormName, "=", version)),
+    );
+
+    if (typeof condition === "boolean") {
+      throw new Error("Condition is a boolean, but should be a condition object.");
+    }
+
+    return {
+      query: sqlCompiler.compileCheck(table, condition),
+      op: "check",
+      expectedAffectedRows: null,
+      expectedReturnedRows: 1, // Check that exactly 1 row was returned
+    };
+  }
+}

package/src/adapters/generic-sql/query/select-builder.test.ts

@@ -0,0 +1,256 @@
+import { describe, expect, it } from "vitest";
+import { column, idColumn, referenceColumn, schema } from "../../../schema/create";
+import { mapSelect, extendSelect } from "./select-builder";
+
+describe("select-builder", () => {
+  const testSchema = schema((s) => {
+    return s
+      .addTable("users", (t) => {
+        return t
+          .addColumn("id", idColumn())
+          .addColumn("name", column("string"))
+          .addColumn("email", column("string"))
+          .addColumn("age", column("integer").nullable())
+          .addColumn("isActive", column("bool"))
+          .addColumn("createdAt", column("timestamp"));
+      })
+      .addTable("posts", (t) => {
+        return t
+          .addColumn("id", idColumn())
+          .addColumn("title", column("string"))
+          .addColumn("content", column("string"))
+          .addColumn("userId", referenceColumn())
+          .addColumn("viewCount", column("integer").defaultTo(0))
+          .addColumn("publishedAt", column("timestamp").nullable());
+      })
+      .addReference("author", {
+        type: "one",
+        from: { table: "posts", column: "userId" },
+        to: { table: "users", column: "id" },
+      });
+  });
+
+  const usersTable = testSchema.tables.users;
+  const postsTable = testSchema.tables.posts;
+
+  describe("mapSelect", () => {
+    it("should map select clause with array of keys", () => {
+      const result = mapSelect(["id", "name", "email"], usersTable);
+      expect(result).toEqual([
+        "users.id as id",
+        "users.name as name",
+        "users.email as email",
+        "users._internalId as _internalId",
+        "users._version as _version",
+      ]);
+    });
+
+    it("should map select all columns when true", () => {
+      const result = mapSelect(true, usersTable);
+      expect(result).toEqual([
+        "users.id as id",
+        "users.name as name",
+        "users.email as email",
+        "users.age as age",
+        "users.isActive as isActive",
+        "users.createdAt as createdAt",
+        "users._internalId as _internalId",
+        "users._version as _version",
+      ]);
+    });
+
+    it("should map select with relation prefix", () => {
+      const result = mapSelect(["id", "name"], usersTable, { relation: "author" });
+      expect(result).toEqual([
+        "users.id as author:id",
+        "users.name as author:name",
+        "users._internalId as author:_internalId",
+        "users._version as author:_version",
+      ]);
+    });
+
+    it("should map select with custom table name", () => {
+      const result = mapSelect(["id", "title"], postsTable, { tableName: "p" });
+      expect(result).toEqual([
+        "p.id as id",
+        "p.title as title",
+        "p._internalId as _internalId",
+        "p._version as _version",
+      ]);
+    });
+
+    it("should map select with both relation and custom table name", () => {
+      const result = mapSelect(["id", "title"], postsTable, {
+        relation: "posts",
+        tableName: "p",
+      });
+      expect(result).toEqual([
+        "p.id as posts:id",
+        "p.title as posts:title",
+        "p._internalId as posts:_internalId",
+        "p._version as posts:_version",
+      ]);
+    });
+
+    it("should handle single column select", () => {
+      const result = mapSelect(["name"], usersTable);
+      expect(result).toEqual([
+        "users.name as name",
+        "users._internalId as _internalId",
+        "users._version as _version",
+      ]);
+    });
+
+    it("should skip hidden columns when explicitly selecting", () => {
+      // When an array is passed, hidden columns should not be included in the select
+      // (unless they are in the array), but they should always be added at the end
+      const result = mapSelect(["name", "email"], usersTable);
+      // Should not duplicate _internalId or _version in the main select
+      expect(result).toEqual([
+        "users.name as name",
+        "users.email as email",
+        "users._internalId as _internalId",
+        "users._version as _version",
+      ]);
+    });
+
+    it("should always include hidden columns", () => {
+      // Hidden columns (_internalId, _version) should always be included
+      const result = mapSelect(["name"], usersTable);
+      expect(result.some((col) => col.includes("_internalId"))).toBe(true);
+      expect(result.some((col) => col.includes("_version"))).toBe(true);
+    });
+
+    it("should handle empty select array", () => {
+      const result = mapSelect([], usersTable);
+      // Should still include hidden columns
+      expect(result).toEqual(["users._internalId as _internalId", "users._version as _version"]);
+    });
+
+    it("should work with different table schemas", () => {
+      const result = mapSelect(["id", "title", "content"], postsTable);
+      expect(result).toEqual([
+        "posts.id as id",
+        "posts.title as title",
+        "posts.content as content",
+        "posts._internalId as _internalId",
+        "posts._version as _version",
+      ]);
+    });
+  });
+
+  describe("extendSelect", () => {
+    it("should extend array select with new key", () => {
+      const builder = extendSelect(["name", "email"]);
+      builder.extend("id");
+      const compiled = builder.compile();
+
+      expect(compiled.result).toEqual(["name", "email", "id"]);
+      expect(compiled.extendedKeys).toEqual(["id"]);
+    });
+
+    it("should not duplicate existing keys", () => {
+      const builder = extendSelect(["name", "email"]);
+      builder.extend("name");
+      const compiled = builder.compile();
+
+      expect(compiled.result).toEqual(["name", "email"]);
+      expect(compiled.extendedKeys).toEqual([]);
+    });
+
+    it("should handle true select clause", () => {
+      const builder = extendSelect(true);
+      builder.extend("id");
+      const compiled = builder.compile();
+
+      expect(compiled.result).toBe(true);
+      expect(compiled.extendedKeys).toEqual([]);
+    });
+
+    it("should track multiple extended keys", () => {
+      const builder = extendSelect(["name"]);
+      builder.extend("id");
+      builder.extend("email");
+      builder.extend("age");
+      const compiled = builder.compile();
+
+      expect(compiled.result).toEqual(["name", "id", "email", "age"]);
+      expect(compiled.extendedKeys).toEqual(["id", "email", "age"]);
+    });
+
+    it("should remove extended keys from record", () => {
+      const builder = extendSelect(["name", "email"]);
+      builder.extend("id");
+      const compiled = builder.compile();
+
+      const record = { id: "123", name: "John", email: "john@example.com", age: 30 };
+      compiled.removeExtendedKeys(record);
+
+      expect(record).toEqual({ name: "John", email: "john@example.com", age: 30 });
+    });
+
+    it("should not remove non-extended keys", () => {
+      const builder = extendSelect(["name", "email", "id"]);
+      builder.extend("age");
+      const compiled = builder.compile();
+
+      const record = { id: "123", name: "John", email: "john@example.com", age: 30 };
+      compiled.removeExtendedKeys(record);
+
+      expect(record).toEqual({ id: "123", name: "John", email: "john@example.com" });
+    });
+
+    it("should handle empty extended keys", () => {
+      const builder = extendSelect(["name", "email"]);
+      const compiled = builder.compile();
+
+      const record = { name: "John", email: "john@example.com" };
+      compiled.removeExtendedKeys(record);
+
+      expect(record).toEqual({ name: "John", email: "john@example.com" });
+    });
+
+    it("should handle multiple extends with duplicates", () => {
+      const builder = extendSelect(["name"]);
+      builder.extend("id");
+      builder.extend("email");
+      builder.extend("id"); // Duplicate
+      const compiled = builder.compile();
+
+      // Should not duplicate 'id'
+      expect(compiled.result).toEqual(["name", "id", "email"]);
+      expect(compiled.extendedKeys).toEqual(["id", "email"]);
+    });
+
+    it("should return mutated record from removeExtendedKeys", () => {
+      const builder = extendSelect(["name"]);
+      builder.extend("id");
+      const compiled = builder.compile();
+
+      const record = { id: "123", name: "John" };
+      const result = compiled.removeExtendedKeys(record);
+
+      // Should return the same record (mutated)
+      expect(result).toBe(record);
+      expect(result).toEqual({ name: "John" });
+    });
+
+    it("should handle extending with empty original select", () => {
+      const builder = extendSelect([]);
+      builder.extend("id");
+      builder.extend("name");
+      const compiled = builder.compile();
+
+      expect(compiled.result).toEqual(["id", "name"]);
+      expect(compiled.extendedKeys).toEqual(["id", "name"]);
+    });
+
+    it("should preserve original select order", () => {
+      const builder = extendSelect(["email", "name"]);
+      builder.extend("id");
+      const compiled = builder.compile();
+
+      expect(compiled.result).toEqual(["email", "name", "id"]);
+    });
+  });
+});

package/src/adapters/generic-sql/query/select-builder.ts

@@ -0,0 +1,137 @@
+import type { AnyTable } from "../../../schema/create";
+import type { AnySelectClause } from "../../../query/simple-query-interface";
+
+/**
+ * Maps a select clause to SQL column names with optional aliases.
+ *
+ * Converts application-level select clauses (either array of keys or "select all")
+ * into SQL-compatible column selections with proper aliasing for relations.
+ *
+ * @param select - The select clause (array of keys or true for all columns)
+ * @param table - The table schema containing column definitions
+ * @param options - Optional configuration
+ * @param options.relation - Relation name to prefix in aliases (for joined data)
+ * @param options.tableName - Override the table name in the SQL (defaults to table.name)
+ * @returns Array of SQL select strings in the format "tableName.columnName as alias"
+ * @internal
+ */
+export function mapSelect(
+  select: AnySelectClause,
+  table: AnyTable,
+  options: {
+    relation?: string;
+    tableName?: string;
+  } = {},
+): string[] {
+  const { relation, tableName = table.name } = options;
+  const out: string[] = [];
+  const keys = Array.isArray(select) ? select : Object.keys(table.columns);
+
+  for (const key of keys) {
+    const col = table.columns[key];
+
+    // Skip hidden columns when explicitly selecting
+    if (Array.isArray(select) && col.isHidden) {
+      continue;
+    }
+
+    // Add the column to the select list
+    const name = relation ? `${relation}:${key}` : key;
+    out.push(`${tableName}.${col.name} as ${name}`);
+  }
+
+  // Always include hidden columns (for FragnoId construction with internal ID and version)
+  for (const key in table.columns) {
+    const col = table.columns[key];
+    if (col.isHidden && !keys.includes(key)) {
+      const name = relation ? `${relation}:${key}` : key;
+      out.push(`${tableName}.${col.name} as ${name}`);
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Result type from compiling a select clause with extensions.
+ * @internal
+ */
+export interface CompiledSelect {
+  /**
+   * The final select clause to use in the query
+   */
+  result: AnySelectClause;
+
+  /**
+   * Keys that were added to the select clause (not originally requested)
+   */
+  extendedKeys: string[];
+
+  /**
+   * Removes the extended keys from a record (mutates the record).
+   * Used to clean up keys that were only needed for join operations.
+   *
+   * @param record - The record to remove extended keys from
+   * @returns The same record with extended keys removed
+   */
+  removeExtendedKeys: (record: Record<string, unknown>) => Record<string, unknown>;
+}
+
+/**
+ * Builder for extending a select clause with additional keys.
+ * @internal
+ */
+export interface SelectBuilder {
+  /**
+   * Adds a key to the select clause if not already present.
+   * Tracks which keys were added for later removal.
+   *
+   * @param key - The key to add to the select clause
+   */
+  extend: (key: string) => void;
+
+  /**
+   * Compiles the select clause into its final form.
+   *
+   * @returns The compiled select information
+   */
+  compile: () => CompiledSelect;
+}
+
+/**
+ * Creates a builder that can extend a select clause with additional keys.
+ *
+ * This is useful when you need to temporarily include columns for join operations
+ * or other internal processing, but don't want them in the final result.
+ *
+ * @param original - The original select clause from the user
+ * @returns A select builder with extend() and compile() methods
+ * @internal
+ */
+export function extendSelect(original: AnySelectClause): SelectBuilder {
+  const select = Array.isArray(original) ? new Set(original) : true;
+  const extendedKeys: string[] = [];
+
+  return {
+    extend(key) {
+      if (select === true || select.has(key)) {
+        return;
+      }
+
+      select.add(key);
+      extendedKeys.push(key);
+    },
+    compile() {
+      return {
+        result: select instanceof Set ? Array.from(select) : true,
+        extendedKeys,
+        removeExtendedKeys(record) {
+          for (const key of extendedKeys) {
+            delete record[key];
+          }
+          return record;
+        },
+      };
+    },
+  };
+}