@vibeorm/runtime 1.0.0

package/src/where-builder.ts

@@ -0,0 +1,737 @@
+/**
+ * Compiles a Prisma-style WhereInput object into parameterized SQL WHERE clauses.
+ */
+
+import type { ModelMeta, ModelMetaMap, ScalarFieldMeta, RelationFieldMeta } from "./types.ts";
+import { getScalarFieldMap, getModelByNameMap, PgArray } from "./types.ts";
+
+type WhereClause = {
+  sql: string;
+  values: unknown[];
+};
+
+/** Per-query context for deterministic subquery aliasing. */
+type WhereContext = {
+  subqueryAliasCounter: number;
+};
+
+/**
+ * Build a WHERE clause from a Prisma-style where input.
+ * Returns { sql, values } where sql uses $N placeholders.
+ */
+export function buildWhereClause(params: {
+  where: Record<string, unknown> | undefined;
+  modelMeta: { readonly name?: string; readonly dbName: string; readonly scalarFields: readonly ScalarFieldMeta[]; readonly relationFields?: readonly RelationFieldMeta[]; readonly primaryKey?: readonly string[] };
+  allModelsMeta: ModelMetaMap;
+  paramOffset?: number;
+  /** @internal Used for recursive calls to maintain deterministic alias numbering. */
+  _ctx?: WhereContext;
+}): WhereClause {
+  const { where, modelMeta, allModelsMeta, paramOffset = 0 } = params;
+  // Create a fresh context for top-level calls; reuse existing context for recursive calls.
+  // This ensures identical WHERE structures always produce the same SQL text.
+  const ctx = params._ctx ?? { subqueryAliasCounter: 0 };
+
+  if (!where || Object.keys(where).length === 0) {
+    return { sql: "", values: [] };
+  }
+
+  const sfMap = getScalarFieldMap({ scalarFields: modelMeta.scalarFields });
+  const conditions: string[] = [];
+  const values: unknown[] = [];
+  let paramIdx = paramOffset;
+
+  for (const [key, value] of Object.entries(where)) {
+    if (value === undefined) continue;
+
+    // Logical combinators
+    if (key === "AND") {
+      const items = Array.isArray(value) ? value : [value];
+      const subClauses = items.map((item: Record<string, unknown>) => {
+        const sub = buildWhereClause({
+          where: item,
+          modelMeta,
+          allModelsMeta,
+          paramOffset: paramIdx,
+          _ctx: ctx,
+        });
+        paramIdx += sub.values.length;
+        values.push(...sub.values);
+        return sub.sql;
+      });
+      const filtered = subClauses.filter(Boolean);
+      if (filtered.length > 0) {
+        conditions.push(`(${filtered.join(" AND ")})`);
+      }
+      continue;
+    }
+
+    if (key === "OR") {
+      const items = value as Record<string, unknown>[];
+      const subClauses = items.map((item) => {
+        const sub = buildWhereClause({
+          where: item,
+          modelMeta,
+          allModelsMeta,
+          paramOffset: paramIdx,
+          _ctx: ctx,
+        });
+        paramIdx += sub.values.length;
+        values.push(...sub.values);
+        return sub.sql;
+      });
+      const filtered = subClauses.filter(Boolean);
+      if (filtered.length > 0) {
+        conditions.push(`(${filtered.join(" OR ")})`);
+      }
+      continue;
+    }
+
+    if (key === "NOT") {
+      const items = Array.isArray(value) ? value : [value];
+      const subClauses = items.map((item: Record<string, unknown>) => {
+        const sub = buildWhereClause({
+          where: item,
+          modelMeta,
+          allModelsMeta,
+          paramOffset: paramIdx,
+          _ctx: ctx,
+        });
+        paramIdx += sub.values.length;
+        values.push(...sub.values);
+        return sub.sql;
+      });
+      const filtered = subClauses.filter(Boolean);
+      if (filtered.length > 0) {
+        // Each element in the NOT array is individually negated:
+        // NOT: [A, B] → NOT(A) AND NOT(B)  (Prisma semantics)
+        const negated = filtered.map((clause) => `NOT (${clause})`);
+        conditions.push(negated.join(" AND "));
+      }
+      continue;
+    }
+
+    // Find if this is a scalar field
+    const scalarField = sfMap.get(key);
+    if (scalarField) {
+      const col = `"${modelMeta.dbName}"."${scalarField.dbName}"`;
+      const result = buildScalarFilter({
+        col,
+        value,
+        paramIdx,
+      });
+      conditions.push(result.sql);
+      values.push(...result.values);
+      paramIdx += result.values.length;
+      continue;
+    }
+
+    // Check if it's a relation filter (some/every/none/is/isNot)
+    const relationFields = modelMeta.relationFields ?? [];
+    const relationField = relationFields.find((r) => r.name === key);
+    if (relationField && typeof value === "object" && value !== null) {
+      const result = buildRelationFilter({
+        parentModelMeta: modelMeta as ModelMeta,
+        relationField,
+        filter: value as Record<string, unknown>,
+        allModelsMeta,
+        paramIdx,
+        ctx,
+      });
+      if (result.sql) {
+        conditions.push(result.sql);
+        values.push(...result.values);
+        paramIdx += result.values.length;
+      }
+      continue;
+    }
+  }
+
+  const sql = conditions.length > 0 ? conditions.join(" AND ") : "";
+  return { sql, values };
+}
+
+// ─── Relation Filter Compiler ─────────────────────────────────────
+
+/**
+ * Compile a relation filter into EXISTS / NOT EXISTS subqueries.
+ *
+ * To-many (isList): { some: {...}, none: {...}, every: {...} }
+ *   some  → EXISTS (SELECT 1 FROM related WHERE fk = pk AND <nested>)
+ *   none  → NOT EXISTS (SELECT 1 FROM related WHERE fk = pk AND <nested>)
+ *   every → NOT EXISTS (SELECT 1 FROM related WHERE fk = pk AND NOT (<nested>))
+ *
+ * To-one (!isList): { is: {...} | null, isNot: {...} | null }
+ *   is: null    → parent.fk IS NULL  (FK side) or NOT EXISTS (related side)
+ *   is: {...}   → EXISTS (SELECT 1 FROM related WHERE join AND <nested>)
+ *   isNot: null → parent.fk IS NOT NULL  (FK side) or EXISTS (related side)
+ *   isNot: {...}→ NOT EXISTS (SELECT 1 FROM related WHERE join AND <nested>)
+ *
+ * Also supports shorthand: { relationName: { field: value } } → same as { some: ... } for lists
+ */
+function buildRelationFilter(params: {
+  parentModelMeta: ModelMeta;
+  relationField: RelationFieldMeta;
+  filter: Record<string, unknown>;
+  allModelsMeta: ModelMetaMap;
+  paramIdx: number;
+  ctx: WhereContext;
+}): WhereClause {
+  const { parentModelMeta, relationField, filter, allModelsMeta, paramIdx, ctx } = params;
+
+  // Resolve related model metadata
+  const modelMap = getModelByNameMap({ allModelsMeta });
+  const relatedModelMeta = modelMap.get(relationField.relatedModel);
+  if (!relatedModelMeta) return { sql: "", values: [] };
+
+  const parentTable = `"${parentModelMeta.dbName}"`;
+  // Self-referential relations need a unique alias to avoid ambiguity
+  const isSelfRef = parentModelMeta.dbName === relatedModelMeta.dbName;
+  const relatedTable = isSelfRef
+    ? `"__sr_${relatedModelMeta.dbName}_${ctx.subqueryAliasCounter++}"`
+    : `"${relatedModelMeta.dbName}"`;
+  // For self-referential subqueries, we need FROM "Table" AS "alias"
+  const relatedFrom = isSelfRef
+    ? `"${relatedModelMeta.dbName}" ${relatedTable}`
+    : relatedTable;
+
+  // Resolve the join condition between parent and related
+  const joinCondition = resolveJoinCondition({
+    parentModelMeta,
+    relationField,
+    relatedModelMeta,
+    parentAlias: parentTable,
+    relatedAlias: relatedTable,
+  });
+  if (!joinCondition) return { sql: "", values: [] };
+
+  if (relationField.isList) {
+    // To-many: some / none / every / shorthand
+    return buildToManyRelationFilter({
+      filter,
+      relatedModelMeta,
+      relatedTable,
+      relatedFrom,
+      joinCondition,
+      allModelsMeta,
+      paramIdx,
+      ctx,
+    });
+  } else {
+    // To-one: is / isNot / shorthand (treated as "is")
+    return buildToOneRelationFilter({
+      filter,
+      parentModelMeta,
+      relationField,
+      relatedModelMeta,
+      parentTable,
+      relatedTable,
+      relatedFrom,
+      joinCondition,
+      allModelsMeta,
+      paramIdx,
+      ctx,
+    });
+  }
+}
+
+function buildToManyRelationFilter(params: {
+  filter: Record<string, unknown>;
+  relatedModelMeta: ModelMeta;
+  relatedTable: string;
+  relatedFrom: string;
+  joinCondition: string;
+  allModelsMeta: ModelMetaMap;
+  paramIdx: number;
+  ctx: WhereContext;
+}): WhereClause {
+  const { filter, relatedModelMeta, relatedTable, relatedFrom, joinCondition, allModelsMeta, paramIdx, ctx } = params;
+
+  // For self-referential relations, create a modelMeta copy with the alias as dbName
+  // so nested buildWhereClause generates column refs using the alias
+  const nestedModelMeta = relatedFrom !== relatedTable
+    ? { ...relatedModelMeta, dbName: relatedTable.replace(/^"|"$/g, "") }
+    : relatedModelMeta;
+
+  const conditions: string[] = [];
+  const values: unknown[] = [];
+  let idx = paramIdx;
+
+  for (const [op, nestedWhere] of Object.entries(filter)) {
+    if (nestedWhere === undefined) continue;
+
+    if (op === "some" || op === "every" || op === "none") {
+      const nested = buildWhereClause({
+        where: nestedWhere as Record<string, unknown>,
+        modelMeta: nestedModelMeta,
+        allModelsMeta,
+        paramOffset: idx,
+        _ctx: ctx,
+      });
+      idx += nested.values.length;
+      values.push(...nested.values);
+
+      const nestedCondition = nested.sql ? ` AND ${nested.sql}` : "";
+
+      if (op === "some") {
+        conditions.push(
+          `EXISTS (SELECT 1 FROM ${relatedFrom} WHERE ${joinCondition}${nestedCondition})`
+        );
+      } else if (op === "none") {
+        conditions.push(
+          `NOT EXISTS (SELECT 1 FROM ${relatedFrom} WHERE ${joinCondition}${nestedCondition})`
+        );
+      } else {
+        // every: NOT EXISTS (... WHERE join AND NOT (nested))
+        // If no nested filter, every is trivially true (vacuous truth)
+        if (nested.sql) {
+          conditions.push(
+            `NOT EXISTS (SELECT 1 FROM ${relatedFrom} WHERE ${joinCondition} AND NOT (${nested.sql}))`
+          );
+        }
+      }
+    } else {
+      // Shorthand: treat { field: value } as { some: { field: value } }
+      // Only process if this looks like a scalar field on the related model
+      const isRelatedScalar = relatedModelMeta.scalarFields.some((f) => f.name === op);
+      if (isRelatedScalar) {
+        // Re-process the whole filter as { some: filter }
+        const nested = buildWhereClause({
+          where: filter,
+          modelMeta: nestedModelMeta,
+          allModelsMeta,
+          paramOffset: idx,
+          _ctx: ctx,
+        });
+        idx += nested.values.length;
+        values.push(...nested.values);
+        const nestedCondition = nested.sql ? ` AND ${nested.sql}` : "";
+        conditions.push(
+          `EXISTS (SELECT 1 FROM ${relatedFrom} WHERE ${joinCondition}${nestedCondition})`
+        );
+        break; // We consumed the entire filter object
+      }
+    }
+  }
+
+  return {
+    sql: conditions.length > 0 ? conditions.join(" AND ") : "",
+    values,
+  };
+}
+
+function buildToOneRelationFilter(params: {
+  filter: Record<string, unknown>;
+  parentModelMeta: ModelMeta;
+  relationField: RelationFieldMeta;
+  relatedModelMeta: ModelMeta;
+  parentTable: string;
+  relatedTable: string;
+  relatedFrom: string;
+  joinCondition: string;
+  allModelsMeta: ModelMetaMap;
+  paramIdx: number;
+  ctx: WhereContext;
+}): WhereClause {
+  const {
+    filter, parentModelMeta, relationField, relatedModelMeta,
+    parentTable, relatedTable, relatedFrom, joinCondition, allModelsMeta, paramIdx, ctx,
+  } = params;
+
+  const parentSfMap = getScalarFieldMap({ scalarFields: parentModelMeta.scalarFields });
+  // For self-referential relations, create a modelMeta copy with the alias as dbName
+  const nestedModelMeta = relatedFrom !== relatedTable
+    ? { ...relatedModelMeta, dbName: relatedTable.replace(/^"|"$/g, "") }
+    : relatedModelMeta;
+
+  const conditions: string[] = [];
+  const values: unknown[] = [];
+  let idx = paramIdx;
+
+  for (const [op, nestedWhere] of Object.entries(filter)) {
+    if (nestedWhere === undefined) continue;
+
+    if (op === "is") {
+      if (nestedWhere === null) {
+        // is: null → FK IS NULL or NOT EXISTS
+        if (relationField.isForeignKey && relationField.fields.length > 0) {
+          const fkField = relationField.fields[0]!;
+          const fkScalar = parentSfMap.get(fkField);
+          const fkDbName = fkScalar?.dbName ?? fkField;
+          conditions.push(`${parentTable}."${fkDbName}" IS NULL`);
+        } else {
+          conditions.push(
+            `NOT EXISTS (SELECT 1 FROM ${relatedFrom} WHERE ${joinCondition})`
+          );
+        }
+      } else {
+        const nested = buildWhereClause({
+          where: nestedWhere as Record<string, unknown>,
+          modelMeta: nestedModelMeta,
+          allModelsMeta,
+          paramOffset: idx,
+          _ctx: ctx,
+        });
+        idx += nested.values.length;
+        values.push(...nested.values);
+        const nestedCondition = nested.sql ? ` AND ${nested.sql}` : "";
+        conditions.push(
+          `EXISTS (SELECT 1 FROM ${relatedFrom} WHERE ${joinCondition}${nestedCondition})`
+        );
+      }
+    } else if (op === "isNot") {
+      if (nestedWhere === null) {
+        // isNot: null → FK IS NOT NULL or EXISTS
+        if (relationField.isForeignKey && relationField.fields.length > 0) {
+          const fkField = relationField.fields[0]!;
+          const fkScalar = parentSfMap.get(fkField);
+          const fkDbName = fkScalar?.dbName ?? fkField;
+          conditions.push(`${parentTable}."${fkDbName}" IS NOT NULL`);
+        } else {
+          conditions.push(
+            `EXISTS (SELECT 1 FROM ${relatedFrom} WHERE ${joinCondition})`
+          );
+        }
+      } else {
+        const nested = buildWhereClause({
+          where: nestedWhere as Record<string, unknown>,
+          modelMeta: nestedModelMeta,
+          allModelsMeta,
+          paramOffset: idx,
+          _ctx: ctx,
+        });
+        idx += nested.values.length;
+        values.push(...nested.values);
+        const nestedCondition = nested.sql ? ` AND ${nested.sql}` : "";
+        conditions.push(
+          `NOT EXISTS (SELECT 1 FROM ${relatedFrom} WHERE ${joinCondition}${nestedCondition})`
+        );
+      }
+    } else {
+      // Shorthand: treat as { is: filter }
+      const isRelatedScalar = relatedModelMeta.scalarFields.some((f) => f.name === op);
+      if (isRelatedScalar) {
+        const nested = buildWhereClause({
+          where: filter,
+          modelMeta: nestedModelMeta,
+          allModelsMeta,
+          paramOffset: idx,
+          _ctx: ctx,
+        });
+        idx += nested.values.length;
+        values.push(...nested.values);
+        const nestedCondition = nested.sql ? ` AND ${nested.sql}` : "";
+        conditions.push(
+          `EXISTS (SELECT 1 FROM ${relatedFrom} WHERE ${joinCondition}${nestedCondition})`
+        );
+        break; // Consumed the whole filter
+      }
+    }
+  }
+
+  return {
+    sql: conditions.length > 0 ? conditions.join(" AND ") : "",
+    values,
+  };
+}
+
+/**
+ * Resolve the SQL join condition between parent and related model.
+ * Returns a string like: "related"."fkCol" = "parent"."pkCol"
+ */
+function resolveJoinCondition(params: {
+  parentModelMeta: ModelMeta;
+  relationField: RelationFieldMeta;
+  relatedModelMeta: ModelMeta;
+  parentAlias: string;
+  relatedAlias: string;
+}): string | null {
+  const { parentModelMeta, relationField, relatedModelMeta, parentAlias, relatedAlias } = params;
+  const parentSfMap = getScalarFieldMap({ scalarFields: parentModelMeta.scalarFields });
+  const relatedSfMap = getScalarFieldMap({ scalarFields: relatedModelMeta.scalarFields });
+
+  if (relationField.isForeignKey && relationField.fields.length > 0) {
+    // Parent holds the FK (e.g., Post.authorId → User.id)
+    // Join: related.pk = parent.fk
+    const fkField = relationField.fields[0]!;
+    const refField = relationField.references[0]!;
+    const fkScalar = parentSfMap.get(fkField);
+    const refScalar = relatedSfMap.get(refField);
+    const fkDbName = fkScalar?.dbName ?? fkField;
+    const refDbName = refScalar?.dbName ?? refField;
+    return `${relatedAlias}."${refDbName}" = ${parentAlias}."${fkDbName}"`;
+  }
+
+  // Related model holds the FK — find the reverse relation
+  // Use relationName for disambiguation (critical for self-referential models)
+  const parentRelationName = (relationField as { relationName?: string }).relationName;
+  const reverseRelation = relatedModelMeta.relationFields.find(
+    (r) => r.relatedModel === parentModelMeta.name && r.isForeignKey && r.fields.length > 0 &&
+      (!parentRelationName || (r as { relationName?: string }).relationName === parentRelationName)
+  );
+
+  if (reverseRelation) {
+    const fkField = reverseRelation.fields[0]!;
+    const refField = reverseRelation.references[0]!;
+    const fkScalar = relatedSfMap.get(fkField);
+    const refScalar = parentSfMap.get(refField);
+    const fkDbName = fkScalar?.dbName ?? fkField;
+    const refDbName = refScalar?.dbName ?? refField;
+    return `${relatedAlias}."${fkDbName}" = ${parentAlias}."${refDbName}"`;
+  }
+
+  // Fallback convention
+  const pkField = parentModelMeta.primaryKey?.[0] ?? "id";
+  const pkScalar = parentSfMap.get(pkField);
+  const pkDbName = pkScalar?.dbName ?? pkField;
+  const fkGuess = `${parentModelMeta.name!.charAt(0).toLowerCase()}${parentModelMeta.name!.slice(1)}Id`;
+  return `${relatedAlias}."${fkGuess}" = ${parentAlias}."${pkDbName}"`;
+}
+
+// ─── Scalar Filter Compiler ───────────────────────────────────────
+
+function buildScalarFilter(params: {
+  col: string;
+  value: unknown;
+  paramIdx: number;
+}): WhereClause {
+  const { col, value, paramIdx } = params;
+  let idx = paramIdx;
+
+  // Direct value comparison (shorthand): where: { email: "test@example.com" }
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean" ||
+    typeof value === "bigint" ||
+    value instanceof Date
+  ) {
+    if (value === null) {
+      return { sql: `${col} IS NULL`, values: [] };
+    }
+    idx++;
+    return { sql: `${col} = $${idx}`, values: [value] };
+  }
+
+  // Filter object: where: { email: { contains: "test" } }
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    const filter = value as Record<string, unknown>;
+    const conditions: string[] = [];
+    const values: unknown[] = [];
+
+    for (const [op, operand] of Object.entries(filter)) {
+      if (operand === undefined) continue;
+
+      switch (op) {
+        case "equals": {
+          if (operand === null) {
+            conditions.push(`${col} IS NULL`);
+          } else if (filter.mode === "insensitive") {
+            idx++;
+            conditions.push(`LOWER(${col}) = LOWER($${idx})`);
+            values.push(operand);
+          } else {
+            idx++;
+            conditions.push(`${col} = $${idx}`);
+            values.push(operand);
+          }
+          break;
+        }
+        case "not": {
+          if (operand === null) {
+            conditions.push(`${col} IS NOT NULL`);
+          } else if (typeof operand === "object" && operand !== null) {
+            // Nested filter
+            const sub = buildScalarFilter({ col, value: operand, paramIdx: idx });
+            conditions.push(`NOT (${sub.sql})`);
+            values.push(...sub.values);
+            idx += sub.values.length;
+          } else {
+            idx++;
+            conditions.push(`${col} != $${idx}`);
+            values.push(operand);
+          }
+          break;
+        }
+        case "in": {
+          const arr = operand as unknown[];
+          if (arr.length === 0) {
+            conditions.push("FALSE");
+          } else {
+            idx++;
+            conditions.push(`${col} = ANY($${idx})`);
+            values.push(new PgArray(arr));
+          }
+          break;
+        }
+        case "notIn": {
+          const arr = operand as unknown[];
+          if (arr.length === 0) {
+            // NOT IN empty array = always true, skip
+          } else {
+            idx++;
+            conditions.push(`${col} <> ALL($${idx})`);
+            values.push(new PgArray(arr));
+          }
+          break;
+        }
+        case "lt": {
+          idx++;
+          conditions.push(`${col} < $${idx}`);
+          values.push(operand);
+          break;
+        }
+        case "lte": {
+          idx++;
+          conditions.push(`${col} <= $${idx}`);
+          values.push(operand);
+          break;
+        }
+        case "gt": {
+          idx++;
+          conditions.push(`${col} > $${idx}`);
+          values.push(operand);
+          break;
+        }
+        case "gte": {
+          idx++;
+          conditions.push(`${col} >= $${idx}`);
+          values.push(operand);
+          break;
+        }
+        case "contains": {
+          idx++;
+          const mode = filter.mode === "insensitive" ? "ILIKE" : "LIKE";
+          conditions.push(`${col} ${mode} $${idx}`);
+          values.push(`%${operand}%`);
+          break;
+        }
+        case "startsWith": {
+          idx++;
+          const mode = filter.mode === "insensitive" ? "ILIKE" : "LIKE";
+          conditions.push(`${col} ${mode} $${idx}`);
+          values.push(`${operand}%`);
+          break;
+        }
+        case "endsWith": {
+          idx++;
+          const mode = filter.mode === "insensitive" ? "ILIKE" : "LIKE";
+          conditions.push(`${col} ${mode} $${idx}`);
+          values.push(`%${operand}`);
+          break;
+        }
+        case "mode":
+          // Handled by contains/startsWith/endsWith
+          break;
+
+        // ─── JSON Filter Operators (PostgreSQL JSONB) ──────────
+        case "path": {
+          // path is consumed by other JSON operators, not standalone
+          break;
+        }
+        case "string_contains": {
+          const path = filter.path as string[] | undefined;
+          const jsonCol = path && path.length > 0
+            ? `(${col}${path.map((p) => `->>'${p}'`).join("")})`
+            : `(${col}#>>'{}')`;
+          idx++;
+          const jmode = filter.mode === "insensitive" ? "ILIKE" : "LIKE";
+          conditions.push(`${jsonCol} ${jmode} $${idx}`);
+          values.push(`%${operand}%`);
+          break;
+        }
+        case "string_starts_with": {
+          const path = filter.path as string[] | undefined;
+          const jsonCol = path && path.length > 0
+            ? `(${col}${path.map((p) => `->>'${p}'`).join("")})`
+            : `(${col}#>>'{}')`;
+          idx++;
+          const jmode = filter.mode === "insensitive" ? "ILIKE" : "LIKE";
+          conditions.push(`${jsonCol} ${jmode} $${idx}`);
+          values.push(`${operand}%`);
+          break;
+        }
+        case "string_ends_with": {
+          const path = filter.path as string[] | undefined;
+          const jsonCol = path && path.length > 0
+            ? `(${col}${path.map((p) => `->>'${p}'`).join("")})`
+            : `(${col}#>>'{}')`;
+          idx++;
+          const jmode = filter.mode === "insensitive" ? "ILIKE" : "LIKE";
+          conditions.push(`${jsonCol} ${jmode} $${idx}`);
+          values.push(`%${operand}`);
+          break;
+        }
+        case "array_contains": {
+          const path = filter.path as string[] | undefined;
+          const target = path && path.length > 0
+            ? `${col}${path.map((p) => `->'${p}'`).join("")}`
+            : col;
+          idx++;
+          conditions.push(`${target} @> $${idx}::jsonb`);
+          values.push(JSON.stringify(operand));
+          break;
+        }
+        case "array_starts_with": {
+          const path = filter.path as string[] | undefined;
+          const target = path && path.length > 0
+            ? `${col}${path.map((p) => `->'${p}'`).join("")}`
+            : col;
+          idx++;
+          conditions.push(`${target}->0 = $${idx}::jsonb`);
+          values.push(JSON.stringify(operand));
+          break;
+        }
+        case "array_ends_with": {
+          const path = filter.path as string[] | undefined;
+          const target = path && path.length > 0
+            ? `${col}${path.map((p) => `->'${p}'`).join("")}`
+            : col;
+          idx++;
+          conditions.push(`${target}->-1 = $${idx}::jsonb`);
+          values.push(JSON.stringify(operand));
+          break;
+        }
+
+        // ─── Scalar List (Array) Filter Operators ──────────────
+        case "has": {
+          idx++;
+          conditions.push(`$${idx} = ANY(${col})`);
+          values.push(operand);
+          break;
+        }
+        case "hasEvery": {
+          idx++;
+          conditions.push(`${col} @> $${idx}`);
+          values.push(operand);
+          break;
+        }
+        case "hasSome": {
+          idx++;
+          conditions.push(`${col} && $${idx}`);
+          values.push(operand);
+          break;
+        }
+        case "isEmpty": {
+          if (operand === true) {
+            conditions.push(`(array_length(${col}, 1) IS NULL)`);
+          } else {
+            conditions.push(`(array_length(${col}, 1) IS NOT NULL)`);
+          }
+          break;
+        }
+
+        default:
+          break;
+      }
+    }
+
+    return {
+      sql: conditions.length > 0 ? conditions.join(" AND ") : "TRUE",
+      values,
+    };
+  }
+
+  return { sql: "", values: [] };
+}