@fragno-dev/db 0.1.14 → 0.2.0

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

@@ -0,0 +1,211 @@
+import { sql, type BinaryOperator } from "kysely";
+import {
+  type AnyColumn,
+  type AnyTable,
+  Column,
+  FragnoId,
+  FragnoReference,
+} from "../../../schema/create";
+import type { Condition } from "../../../query/condition-builder";
+import { createSQLSerializer } from "../../../query/serialize/create-sql-serializer";
+import type { TableNameMapper } from "../../shared/table-name-mapper";
+import type { DriverConfig } from "../driver-config";
+import { ReferenceSubquery, resolveFragnoIdValue } from "../../../query/value-encoding";
+import type { AnyKysely, AnyExpressionBuilder, AnyExpressionWrapper } from "./sql-query-compiler";
+
+/**
+ * Returns the fully qualified SQL name for a column (table.column).
+ *
+ * @param column - The column to get the full name for
+ * @param mapper - Optional table name mapper for namespace prefixing
+ * @returns The fully qualified SQL name in the format "tableName.columnName"
+ * @internal
+ */
+export function fullSQLName(column: AnyColumn, mapper?: TableNameMapper): string {
+  const tableName = mapper ? mapper.toPhysical(column.tableName) : column.tableName;
+  return `${tableName}.${column.name}`;
+}
+
+/**
+ * Builds a WHERE clause expression from a Condition tree.
+ *
+ * Recursively processes condition objects to build Kysely WHERE expressions.
+ * Handles comparison operators, logical AND/OR/NOT, and special string operators
+ * like "contains", "starts with", and "ends with".
+ *
+ * @param condition - The condition tree to build the WHERE clause from
+ * @param eb - Kysely expression builder for constructing SQL expressions
+ * @param database - The database type (affects SQL generation)
+ * @param mapper - Optional table name mapper for namespace prefixing
+ * @param table - The table being queried (used for resolving reference columns)
+ * @returns A Kysely expression wrapper representing the WHERE clause
+ * @internal
+ */
+export function buildWhere(
+  condition: Condition,
+  eb: AnyExpressionBuilder,
+  driverConfig: DriverConfig,
+  mapper?: TableNameMapper,
+  table?: AnyTable,
+): AnyExpressionWrapper {
+  const serializer = createSQLSerializer(driverConfig);
+
+  if (condition.type === "compare") {
+    const left = condition.a;
+    const op = condition.operator;
+    let val = condition.b;
+
+    if (!(val instanceof Column)) {
+      // Handle reference columns specially
+      if (left.role === "reference" && table) {
+        if (typeof val === "string") {
+          // String external ID - create subquery to lookup internal ID
+          const relation = Object.values(table.relations).find((rel) =>
+            rel.on.some(([localCol]) => localCol === left.ormName),
+          );
+          if (relation) {
+            const refTable = relation.table;
+            const internalIdCol = refTable.getInternalIdColumn();
+            const idCol = refTable.getIdColumn();
+            const physicalTableName = mapper
+              ? mapper.toPhysical(refTable.ormName)
+              : refTable.ormName;
+
+            val = eb
+              .selectFrom(physicalTableName)
+              .select(internalIdCol.name)
+              .where(idCol.name, "=", val)
+              .limit(1);
+          }
+        } else if (val instanceof FragnoId && val.internalId !== undefined) {
+          // FragnoId with internal ID - use it directly (no serialization needed)
+          val = val.internalId;
+        } else if (val instanceof FragnoId && val.internalId === undefined) {
+          // FragnoId without internal ID - create subquery using external ID
+          const relation = Object.values(table.relations).find((rel) =>
+            rel.on.some(([localCol]) => localCol === left.ormName),
+          );
+          if (relation) {
+            const refTable = relation.table;
+            const internalIdCol = refTable.getInternalIdColumn();
+            const idCol = refTable.getIdColumn();
+            const physicalTableName = mapper
+              ? mapper.toPhysical(refTable.ormName)
+              : refTable.ormName;
+
+            val = eb
+              .selectFrom(physicalTableName)
+              .select(internalIdCol.name)
+              .where(idCol.name, "=", val.externalId)
+              .limit(1);
+          }
+        } else if (val instanceof FragnoReference) {
+          // FragnoReference - use internal ID directly (no serialization needed)
+          val = val.internalId;
+        } else {
+          // Other values - resolve and serialize
+          const resolvedVal = resolveFragnoIdValue(val, left);
+          val = serializer.serialize(resolvedVal, left);
+        }
+      } else {
+        // Non-reference columns - resolve FragnoId/FragnoReference and serialize
+        const resolvedVal = resolveFragnoIdValue(val, left);
+        val = serializer.serialize(resolvedVal, left);
+      }
+    }
+
+    let v: BinaryOperator;
+    let rhs: unknown;
+
+    switch (op) {
+      case "contains":
+        v = "like";
+        rhs =
+          val instanceof Column
+            ? sql`concat('%', ${eb.ref(fullSQLName(val, mapper))}, '%')`
+            : `%${val}%`;
+        break;
+      case "not contains":
+        v = "not like";
+        rhs =
+          val instanceof Column
+            ? sql`concat('%', ${eb.ref(fullSQLName(val, mapper))}, '%')`
+            : `%${val}%`;
+        break;
+      case "starts with":
+        v = "like";
+        rhs =
+          val instanceof Column ? sql`concat(${eb.ref(fullSQLName(val, mapper))}, '%')` : `${val}%`;
+        break;
+      case "not starts with":
+        v = "not like";
+        rhs =
+          val instanceof Column ? sql`concat(${eb.ref(fullSQLName(val, mapper))}, '%')` : `${val}%`;
+        break;
+      case "ends with":
+        v = "like";
+        rhs =
+          val instanceof Column ? sql`concat('%', ${eb.ref(fullSQLName(val, mapper))})` : `%${val}`;
+        break;
+      case "not ends with":
+        v = "not like";
+        rhs =
+          val instanceof Column ? sql`concat('%', ${eb.ref(fullSQLName(val, mapper))})` : `%${val}`;
+        break;
+      default:
+        v = op;
+        rhs = val instanceof Column ? eb.ref(fullSQLName(val, mapper)) : val;
+    }
+
+    return eb(fullSQLName(left, mapper), v, rhs);
+  }
+
+  // Nested conditions
+  if (condition.type === "and") {
+    return eb.and(condition.items.map((v) => buildWhere(v, eb, driverConfig, mapper, table)));
+  }
+
+  if (condition.type === "not") {
+    return eb.not(buildWhere(condition.item, eb, driverConfig, mapper, table));
+  }
+
+  return eb.or(condition.items.map((v) => buildWhere(v, eb, driverConfig, mapper, table)));
+}
+
+/**
+ * Process reference subqueries in encoded values, converting them to Kysely SQL subqueries
+ *
+ * @param values - The encoded values that may contain ReferenceSubquery objects
+ * @param kysely - The Kysely database instance for building subqueries
+ * @param mapper - Optional table name mapper for namespace prefixing
+ * @returns Processed values with subqueries in place of ReferenceSubquery markers
+ * @internal
+ */
+export function processReferenceSubqueries(
+  values: Record<string, unknown>,
+  kysely: AnyKysely,
+  mapper?: TableNameMapper,
+): Record<string, unknown> {
+  const processed: Record<string, unknown> = {};
+  const getTableName = (table: AnyTable) => (mapper ? mapper.toPhysical(table.name) : table.name);
+
+  for (const [key, value] of Object.entries(values)) {
+    if (value instanceof ReferenceSubquery) {
+      const refTable = value.referencedTable;
+      const externalId = value.externalIdValue;
+      const tableName = getTableName(refTable);
+      const internalIdCol = refTable.getInternalIdColumn().name;
+      const idCol = refTable.getIdColumn().name;
+
+      processed[key] = kysely
+        .selectFrom(tableName)
+        .select(internalIdCol)
+        .where(idCol, "=", externalId)
+        .limit(1);
+    } else {
+      processed[key] = value;
+    }
+  }
+
+  return processed;
+}

package/src/adapters/generic-sql/result-interpreter.ts

@@ -0,0 +1,102 @@
+import type { QueryResult } from "../../sql-driver/sql-driver";
+import type { DriverConfig } from "./driver-config";
+
+/**
+ * Interprets query results from different SQL drivers.
+ *
+ * Different drivers return affected rows information in different formats.
+ * This class uses the driver-specific extraction logic defined in DriverConfig
+ * to normalize the affected rows count to a bigint value.
+ */
+export class ResultInterpreter {
+  readonly #driverConfig: DriverConfig;
+  constructor(driverConfig: DriverConfig) {
+    this.#driverConfig = driverConfig;
+  }
+
+  /**
+   * Extract the number of affected rows from a query result.
+   * Only works for drivers that support affected rows reporting.
+   *
+   * @param result - The query result from the SQL driver
+   * @returns The number of rows affected by the operation as bigint
+   * @throws Error if driver doesn't support affected rows or extraction fails
+   */
+  getAffectedRows(result: QueryResult<unknown>): bigint {
+    if (!this.#driverConfig.extractAffectedRows) {
+      throw new Error(
+        `Driver ${this.#driverConfig.driverType} does not support affected rows reporting.`,
+      );
+    }
+
+    // QueryResult doesn't have an index signature, but drivers return objects with dynamic properties
+    return this.#driverConfig.extractAffectedRows(result as unknown as Record<string, unknown>);
+  }
+
+  /**
+   * Extract internal ID from INSERT result (RETURNING clause).
+   *
+   * @param result - The query result from the SQL driver
+   * @returns The internal ID as bigint
+   * @throws Error if driver doesn't support RETURNING, no rows returned, or column not found
+   */
+  getCreatedInternalId(result: QueryResult<unknown>): bigint {
+    if (!this.#driverConfig.supportsReturning || !this.#driverConfig.internalIdColumn) {
+      throw new Error(`Driver ${this.#driverConfig.driverType} does not support RETURNING clause.`);
+    }
+
+    if (!Array.isArray(result.rows) || result.rows.length === 0) {
+      throw new Error(`No rows returned from INSERT with RETURNING clause.`);
+    }
+
+    const row = result.rows[0] as Record<string, unknown>;
+    const columnName = this.#driverConfig.internalIdColumn;
+
+    if (!(columnName in row)) {
+      throw new Error(`Expected column "${columnName}" not found in RETURNING result.`);
+    }
+
+    const rawId = row[columnName];
+    return this.#normalizeIntegerId(rawId);
+  }
+
+  /**
+   * Get count of returned rows as bigint.
+   *
+   * @param result - The query result from the SQL driver
+   * @returns The number of rows returned as bigint
+   */
+  getReturnedRowCount(result: QueryResult<unknown>): bigint {
+    if (!Array.isArray(result.rows)) {
+      return BigInt(0);
+    }
+    return BigInt(result.rows.length);
+  }
+
+  /**
+   * Normalize integer values to bigint.
+   * Handles different driver return types (bigint, number, string).
+   *
+   * @param value - The value to normalize
+   * @returns The normalized bigint value
+   * @throws Error if value cannot be converted to bigint
+   */
+  #normalizeIntegerId(value: unknown): bigint {
+    if (value === null || value === undefined) {
+      throw new Error(`Cannot normalize null or undefined value to bigint`);
+    }
+    if (typeof value === "bigint") {
+      return value;
+    }
+    if (typeof value === "number") {
+      if (Number.isNaN(value) || !Number.isFinite(value)) {
+        throw new Error(`Cannot normalize NaN or non-finite number to bigint`);
+      }
+      return BigInt(value);
+    }
+    if (typeof value === "string") {
+      return BigInt(value);
+    }
+    throw new Error(`Cannot normalize value to bigint: ${typeof value}`);
+  }
+}