metal-orm 1.1.19 → 1.1.21

package/dist/index.js

@@ -6,8 +6,8 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   if (typeof require !== "undefined") return require.apply(this, arguments);
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
-var __esm = (fn8, res) => function __init() {
-  return fn8 && (res = (0, fn8[__getOwnPropNames(fn8)[0]])(fn8 = 0)), res;
+var __esm = (fn9, res) => function __init() {
+  return fn9 && (res = (0, fn9[__getOwnPropNames(fn9)[0]])(fn9 = 0)), res;
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -143,7 +143,9 @@ var STANDARD_COLUMN_TYPES = [
   "DATETIME",
   "TIMESTAMP",
   "TIMESTAMPTZ",
-  "BOOLEAN"
+  "BOOLEAN",
+  "VECTOR",
+  "HALFVEC"
 ];
 var STANDARD_TYPE_SET = new Set(STANDARD_COLUMN_TYPES.map((t) => t.toLowerCase()));
 var normalizeColumnType = (type) => {
@@ -253,6 +255,27 @@ var col = {
    * @param values - Enum values
    */
   enum: (values) => ({ name: "", type: "ENUM", args: values }),
+  /**
+   * Creates a vector column definition
+   * @param dimensions - Vector dimensions
+   * @param options - Vector options (e.g. elementType: 'float16' | 'float32')
+   */
+  vector: (dimensions, options) => ({
+    name: "",
+    type: "VECTOR",
+    args: [dimensions],
+    vectorOptions: { dimensions, ...options }
+  }),
+  /**
+   * Creates a half-precision (float16) vector column definition (pgvector halfvec / SQL Server float16 vector / sqlite-vec float16)
+   * @param dimensions - Vector dimensions
+   */
+  halfvec: (dimensions) => ({
+    name: "",
+    type: "HALFVEC",
+    args: [dimensions],
+    vectorOptions: { dimensions, elementType: "float16" }
+  }),
   /**
    * Creates a column definition with a custom SQL type.
    * Useful for dialect-specific types without polluting the standard set.
@@ -1726,13 +1749,13 @@ var FunctionTableFormatter = class {
    * @param dialect - The dialect instance for compiling operands.
    * @returns SQL function table expression (e.g., "LATERAL schema.func(args) WITH ORDINALITY AS alias(col1, col2)").
    */
-  static format(fn8, ctx, dialect) {
-    const schemaPart = this.formatSchema(fn8, dialect);
-    const args = this.formatArgs(fn8, ctx, dialect);
-    const base = this.formatBase(fn8, schemaPart, args);
-    const lateral = this.formatLateral(fn8);
-    const alias = this.formatAlias(fn8, dialect);
-    const colAliases = this.formatColumnAliases(fn8, dialect);
+  static format(fn9, ctx, dialect) {
+    const schemaPart = this.formatSchema(fn9, dialect);
+    const args = this.formatArgs(fn9, ctx, dialect);
+    const base = this.formatBase(fn9, schemaPart, args);
+    const lateral = this.formatLateral(fn9);
+    const alias = this.formatAlias(fn9, dialect);
+    const colAliases = this.formatColumnAliases(fn9, dialect);
     return `${lateral}${base}${alias}${colAliases}`;
   }
   /**
@@ -1742,9 +1765,9 @@ var FunctionTableFormatter = class {
    * @returns Schema prefix (e.g., "schema.") or empty string.
    * @internal
    */
-  static formatSchema(fn8, dialect) {
-    if (!fn8.schema) return "";
-    const quoted = dialect ? dialect.quoteIdentifier(fn8.schema) : fn8.schema;
+  static formatSchema(fn9, dialect) {
+    if (!fn9.schema) return "";
+    const quoted = dialect ? dialect.quoteIdentifier(fn9.schema) : fn9.schema;
     return `${quoted}.`;
   }
   /**
@@ -1755,8 +1778,8 @@ var FunctionTableFormatter = class {
    * @returns Comma-separated function arguments.
    * @internal
    */
-  static formatArgs(fn8, ctx, dialect) {
-    return (fn8.args || []).map((a) => {
+  static formatArgs(fn9, ctx, dialect) {
+    return (fn9.args || []).map((a) => {
       if (ctx && dialect) {
         return dialect.compileOperand(a, ctx);
       }
@@ -1772,9 +1795,9 @@ var FunctionTableFormatter = class {
    * @returns Base function call expression (e.g., "schema.func(args) WITH ORDINALITY").
    * @internal
    */
-  static formatBase(fn8, schemaPart, args) {
-    const ordinality = fn8.withOrdinality ? " WITH ORDINALITY" : "";
-    return `${schemaPart}${fn8.name}(${args})${ordinality}`;
+  static formatBase(fn9, schemaPart, args) {
+    const ordinality = fn9.withOrdinality ? " WITH ORDINALITY" : "";
+    return `${schemaPart}${fn9.name}(${args})${ordinality}`;
   }
   /**
    * Formats the LATERAL keyword if present.
@@ -1782,8 +1805,8 @@ var FunctionTableFormatter = class {
    * @returns "LATERAL " or empty string.
    * @internal
    */
-  static formatLateral(fn8) {
-    return fn8.lateral ? "LATERAL " : "";
+  static formatLateral(fn9) {
+    return fn9.lateral ? "LATERAL " : "";
   }
   /**
    * Formats the table alias for the function table.
@@ -1792,9 +1815,9 @@ var FunctionTableFormatter = class {
    * @returns " AS alias" or empty string.
    * @internal
    */
-  static formatAlias(fn8, dialect) {
-    if (!fn8.alias) return "";
-    const quoted = dialect ? dialect.quoteIdentifier(fn8.alias) : fn8.alias;
+  static formatAlias(fn9, dialect) {
+    if (!fn9.alias) return "";
+    const quoted = dialect ? dialect.quoteIdentifier(fn9.alias) : fn9.alias;
     return ` AS ${quoted}`;
   }
   /**
@@ -1804,9 +1827,9 @@ var FunctionTableFormatter = class {
    * @returns "(col1, col2, ...)" or empty string.
    * @internal
    */
-  static formatColumnAliases(fn8, dialect) {
-    if (!fn8.columnAliases || !fn8.columnAliases.length) return "";
-    const aliases = fn8.columnAliases.map((col2) => dialect ? dialect.quoteIdentifier(col2) : col2).join(", ");
+  static formatColumnAliases(fn9, dialect) {
+    if (!fn9.columnAliases || !fn9.columnAliases.length) return "";
+    const aliases = fn9.columnAliases.map((col2) => dialect ? dialect.quoteIdentifier(col2) : col2).join(", ");
     return `(${aliases})`;
   }
 };
@@ -2088,24 +2111,24 @@ var SqlDialectBase = class extends Dialect {
     }
     return this.compileTableSource(tableSource);
   }
-  compileFunctionTable(fn8, ctx) {
-    const key = fn8.key ?? fn8.name;
+  compileFunctionTable(fn9, ctx) {
+    const key = fn9.key ?? fn9.name;
     if (ctx) {
       const renderer = this.tableFunctionStrategy.getRenderer(key);
       if (renderer) {
-        const compiledArgs = (fn8.args ?? []).map((arg) => this.compileOperand(arg, ctx));
+        const compiledArgs = (fn9.args ?? []).map((arg) => this.compileOperand(arg, ctx));
         return renderer({
-          node: fn8,
+          node: fn9,
           compiledArgs,
           compileOperand: (operand) => this.compileOperand(operand, ctx),
           quoteIdentifier: this.quoteIdentifier.bind(this)
         });
       }
-      if (fn8.key) {
+      if (fn9.key) {
         throw new Error(`Table function "${key}" is not supported by dialect "${this.dialect}".`);
       }
     }
-    return FunctionTableFormatter.format(fn8, ctx, this);
+    return FunctionTableFormatter.format(fn9, ctx, this);
   }
   compileDerivedTable(table, ctx) {
     if (!table.alias) {
@@ -2294,6 +2317,26 @@ var PostgresFunctionStrategy = class extends StandardFunctionStrategy {
       const pathArray = this.formatJsonbPathArray(pathNode);
       return `jsonb_set(${compiledArgs[0]}, ${pathArray}, ${compiledArgs[2]}::jsonb, true)`;
     });
+    this.add("VECTOR_DISTANCE", ({ node, compiledArgs }) => {
+      if (compiledArgs.length !== 3) throw new Error("VECTOR_DISTANCE expects 3 arguments (metric, v1, v2)");
+      const metric = node.args[0]?.type === "Literal" ? String(node.args[0].value).toLowerCase() : compiledArgs[0].replace(/['"]/g, "").toLowerCase();
+      const [, v1, v2] = compiledArgs;
+      switch (metric) {
+        case "cosine":
+          return `(${v1} <=> ${v2})`;
+        case "euclidean":
+        case "l2":
+          return `(${v1} <-> ${v2})`;
+        case "dot":
+        case "inner_product":
+          return `(${v1} <#> ${v2})`;
+        case "manhattan":
+        case "l1":
+          return `(${v1} <~> ${v2})`;
+        default:
+          return `(${v1} <=> ${v2})`;
+      }
+    });
   }
   formatJsonbPathArray(pathNode) {
     const rawPath = String(pathNode.value ?? "");
@@ -2525,6 +2568,14 @@ var MysqlFunctionStrategy = class extends StandardFunctionStrategy {
       if (compiledArgs.length !== 2) throw new Error("ARRAY_APPEND expects 2 arguments (array, value)");
       return `JSON_ARRAY_APPEND(${compiledArgs[0]}, '$', ${compiledArgs[1]})`;
     });
+    this.add("VECTOR_DISTANCE", ({ node, compiledArgs }) => {
+      if (compiledArgs.length !== 3) throw new Error("VECTOR_DISTANCE expects 3 arguments (metric, v1, v2)");
+      let metric = node.args[0]?.type === "Literal" ? String(node.args[0].value).toUpperCase() : compiledArgs[0].replace(/['"]/g, "").toUpperCase();
+      if (metric === "L2") metric = "EUCLIDEAN";
+      if (metric === "INNER_PRODUCT") metric = "DOT";
+      const [, v1, v2] = compiledArgs;
+      return `DISTANCE(${v1}, ${v2}, '${metric}')`;
+    });
   }
 };
 
@@ -2761,6 +2812,15 @@ var SqliteFunctionStrategy = class extends StandardFunctionStrategy {
       return `json_array_append(${compiledArgs[0]}, '$', ${compiledArgs[1]})`;
     });
     this.add("CHR", ({ compiledArgs }) => `CHAR(${compiledArgs[0]})`);
+    this.add("VECTOR_DISTANCE", ({ node, compiledArgs }) => {
+      if (compiledArgs.length !== 3) throw new Error("VECTOR_DISTANCE expects 3 arguments (metric, v1, v2)");
+      const metric = node.args[0]?.type === "Literal" ? String(node.args[0].value).toLowerCase() : compiledArgs[0].replace(/['"]/g, "").toLowerCase();
+      const [, v1, v2] = compiledArgs;
+      if (metric === "euclidean" || metric === "l2") {
+        return `vec_distance_L2(${v1}, ${v2})`;
+      }
+      return `vec_distance_cosine(${v1}, ${v2})`;
+    });
   }
 };
 
@@ -2962,6 +3022,15 @@ var MssqlFunctionStrategy = class extends StandardFunctionStrategy {
     this.add("ARRAY_APPEND", () => {
       throw new Error("ARRAY_APPEND is not supported on SQL Server");
     });
+    this.add("VECTOR_DISTANCE", ({ node, compiledArgs }) => {
+      if (compiledArgs.length !== 3) throw new Error("VECTOR_DISTANCE expects 3 arguments (metric, v1, v2)");
+      let metric = node.args[0]?.type === "Literal" ? String(node.args[0].value).toLowerCase() : compiledArgs[0].replace(/['"]/g, "").toLowerCase();
+      if (metric === "l2") metric = "euclidean";
+      if (metric === "l1") metric = "manhattan";
+      if (metric === "inner_product") metric = "dot";
+      const [, v1, v2] = compiledArgs;
+      return `VECTOR_DISTANCE('${metric}', ${v1}, ${v2})`;
+    });
   }
 };
 
@@ -13411,6 +13480,50 @@ var fn7 = (key, args) => ({
 var afn3 = (key, args) => asType(fn7(key, args));
 var arrayAppend = (array, value) => afn3("ARRAY_APPEND", [array, value]);
 
+// src/core/functions/vector.ts
+var isColumnDef7 = (val) => !!val && typeof val === "object" && "type" in val && "name" in val;
+var toOperand8 = (input) => {
+  if (isOperandNode(input)) return input;
+  if (isColumnDef7(input)) return columnOperand(input);
+  if (Array.isArray(input) || input instanceof Float32Array) {
+    const formatted = `[${Array.from(input).join(", ")}]`;
+    return valueToOperand(formatted);
+  }
+  return valueToOperand(input);
+};
+var fn8 = (key, args) => ({
+  type: "Function",
+  name: key,
+  fn: key,
+  args
+});
+var vectorDistance = (metric, v1, v2) => {
+  const metricOp = valueToOperand(metric.toLowerCase());
+  return asType(fn8("VECTOR_DISTANCE", [metricOp, toOperand8(v1), toOperand8(v2)]));
+};
+var cosineDistance = (v1, v2) => vectorDistance("cosine", v1, v2);
+var l2Distance = (v1, v2) => vectorDistance("euclidean", v1, v2);
+var euclideanDistance = (v1, v2) => vectorDistance("euclidean", v1, v2);
+var innerProduct = (v1, v2) => vectorDistance("dot", v1, v2);
+var dotProduct = (v1, v2) => vectorDistance("dot", v1, v2);
+var l1Distance = (v1, v2) => vectorDistance("manhattan", v1, v2);
+var manhattanDistance = (v1, v2) => vectorDistance("manhattan", v1, v2);
+var vectorMatch = (column, vector, k) => {
+  const match = {
+    type: "BinaryExpression",
+    left: toOperand8(column),
+    operator: "MATCH",
+    right: toOperand8(vector)
+  };
+  const kNode = {
+    type: "BinaryExpression",
+    left: valueToOperand("k"),
+    operator: "=",
+    right: valueToOperand(k)
+  };
+  return { type: "LogicalExpression", operator: "AND", operands: [match, kNode] };
+};
+
 // src/orm/als.ts
 var AsyncLocalStorage = class {
   store;
@@ -13726,12 +13839,12 @@ var TypeScriptGenerator = class {
   printBinaryExpression(binary) {
     const left2 = this.printOperand(binary.left);
     const right2 = this.printOperand(binary.right);
-    const fn8 = this.mapOp(binary.operator);
+    const fn9 = this.mapOp(binary.operator);
     const args = [left2, right2];
     if (binary.escape) {
       args.push(this.printOperand(binary.escape));
     }
-    return `${fn8}(${args.join(", ")})`;
+    return `${fn9}(${args.join(", ")})`;
   }
   /**
    * Prints a logical expression to TypeScript code
@@ -13763,13 +13876,13 @@ var TypeScriptGenerator = class {
    */
   printInExpression(inExpr) {
     const left2 = this.printOperand(inExpr.left);
-    const fn8 = this.mapOp(inExpr.operator);
+    const fn9 = this.mapOp(inExpr.operator);
     if (Array.isArray(inExpr.right)) {
       const values = inExpr.right.map((v) => this.printOperand(v)).join(", ");
-      return `${fn8}(${left2}, [${values}])`;
+      return `${fn9}(${left2}, [${values}])`;
     }
     const subquery = this.inlineChain(this.buildSelectLines(inExpr.right.query));
-    return `${fn8}(${left2}, (${subquery}))`;
+    return `${fn9}(${left2}, (${subquery}))`;
   }
   /**
    * Prints a null expression to TypeScript code
@@ -13778,8 +13891,8 @@ var TypeScriptGenerator = class {
    */
   printNullExpression(nullExpr) {
     const left2 = this.printOperand(nullExpr.left);
-    const fn8 = this.mapOp(nullExpr.operator);
-    return `${fn8}(${left2})`;
+    const fn9 = this.mapOp(nullExpr.operator);
+    return `${fn9}(${left2})`;
   }
   /**
    * Prints a BETWEEN expression to TypeScript code
@@ -13823,9 +13936,9 @@ var TypeScriptGenerator = class {
    * @param fn - Function node
    * @returns TypeScript code representation
    */
-  printFunctionOperand(fn8) {
-    const args = fn8.args.map((a) => this.printOperand(a)).join(", ");
-    return `${fn8.name.toLowerCase()}(${args})`;
+  printFunctionOperand(fn9) {
+    const args = fn9.args.map((a) => this.printOperand(a)).join(", ");
+    return `${fn9.name.toLowerCase()}(${args})`;
   }
   /**
    * Prints a JSON path operand to TypeScript code
@@ -14516,7 +14629,10 @@ var RelationChangeProcessor = class {
     const rootKey = relation.localKey || findPrimaryKey(entry.rootTable);
     const rootId = entry.root[rootKey];
     if (rootId === void 0 || rootId === null) return;
-    const targetId = this.resolvePrimaryKeyValue(entry.change.entity, relation.target);
+    const targetId = this.resolveBelongsToManyTargetValue(
+      entry.change.entity,
+      relation
+    );
     if (targetId === null) return;
     const pivotPayload = this.buildPivotPayload(relation, entry.change.pivot);
     if (entry.change.kind === "update") {
@@ -14588,7 +14704,7 @@ var RelationChangeProcessor = class {
    * Inserts a pivot row for belongs-to-many relations.
    * @param relation - The belongs-to-many relation
    * @param rootId - The root entity's primary key value
-   * @param targetId - The target entity's primary key value
+   * @param targetId - The target entity's relation key value
    */
   async insertPivotRow(relation, rootId, targetId, pivotPayload) {
     const payload = {
@@ -14604,7 +14720,7 @@ var RelationChangeProcessor = class {
    * Updates a pivot row for belongs-to-many relations.
    * @param relation - The belongs-to-many relation
    * @param rootId - The root entity's primary key value
-   * @param targetId - The target entity's primary key value
+   * @param targetId - The target entity's relation key value
    * @param pivotPayload - The pivot columns to update
    */
   async updatePivotRow(relation, rootId, targetId, pivotPayload) {
@@ -14619,7 +14735,7 @@ var RelationChangeProcessor = class {
    * Deletes a pivot row for belongs-to-many relations.
    * @param relation - The belongs-to-many relation
    * @param rootId - The root entity's primary key value
-   * @param targetId - The target entity's primary key value
+   * @param targetId - The target entity's relation key value
    */
   async deletePivotRow(relation, rootId, targetId) {
     const rootCol = relation.pivotTable.columns[relation.pivotForeignKeyToRoot];
@@ -14632,14 +14748,13 @@ var RelationChangeProcessor = class {
     await this.executor.executeSql(compiled.sql, compiled.params);
   }
   /**
-   * Resolves the primary key value from an entity.
-   * @param entity - The entity
-   * @param table - The table definition
-   * @returns The primary key value or null
+   * Resolves the target-side key value used by a belongs-to-many relation.
+   * The declared targetKey is part of the relation contract and takes
+   * precedence over the target table primary key.
    */
-  resolvePrimaryKeyValue(entity, table) {
+  resolveBelongsToManyTargetValue(entity, relation) {
     if (!entity) return null;
-    const key = findPrimaryKey(table);
+    const key = relation.targetKey || findPrimaryKey(relation.target);
     const value = entity[key];
     if (value === void 0 || value === null) return null;
     return value ?? null;
@@ -15440,9 +15555,9 @@ var OrmSession = class {
    * @returns The result of the function
    * @throws If the transaction fails
    */
-  async transaction(fn8) {
+  async transaction(fn9) {
     if (!this.executor.capabilities.transactions) {
-      const result = await fn8(this);
+      const result = await fn9(this);
       await this.commit();
       return result;
     }
@@ -15458,7 +15573,7 @@ var OrmSession = class {
     }
     this.transactionDepth += 1;
     try {
-      const result = await fn8(this);
+      const result = await fn9(this);
       this.throwIfRollbackOnly();
       await this.flushWithHooks();
       this.throwIfRollbackOnly();
@@ -15972,7 +16087,7 @@ var Orm = class {
    * @returns The result of the function
    * @throws If the transaction fails
    */
-  async transaction(fn8) {
+  async transaction(fn9) {
     const executor = this.executorFactory.createTransactionalExecutor();
     const session = new OrmSession({
       orm: this,
@@ -15980,7 +16095,7 @@ var Orm = class {
       cacheManager: this.cacheManager
     });
     try {
-      return await session.transaction(() => fn8(session));
+      return await session.transaction(() => fn9(session));
     } finally {
       await session.dispose();
     }
@@ -21269,10 +21384,10 @@ async function runChunk(task, chunkIndex, totalChunks, rowsInChunk, timing, onCh
   }
   return result;
 }
-async function maybeTransaction(session, transactional, fn8) {
-  if (!transactional) return fn8();
+async function maybeTransaction(session, transactional, fn9) {
+  if (!transactional) return fn9();
   const ormSession = session;
-  return ormSession.transaction(fn8);
+  return ormSession.transaction(fn9);
 }
 function aggregateOutcomes(outcomes) {
   const result = {
@@ -21738,6 +21853,7 @@ export {
   concatWs,
   correlateBy,
   cos,
+  cosineDistance,
   cot,
   count,
   countAll,
@@ -21774,12 +21890,14 @@ export {
   denseRank,
   diffSchema,
   div,
+  dotProduct,
   dtoToOpenApiSchema,
   endOfMonth,
   entityRef,
   entityRefs,
   eq,
   esel,
+  euclideanDistance,
   exclude,
   executeFilteredPaged,
   executeHydrated,
@@ -21837,6 +21955,7 @@ export {
   inList,
   inSubquery,
   initcap,
+  innerProduct,
   insertInto,
   instr,
   introspectSchema,
@@ -21865,6 +21984,8 @@ export {
   jsonPath,
   jsonSet,
   jsonify,
+  l1Distance,
+  l2Distance,
   lag,
   lastValue,
   lead,
@@ -21892,6 +22013,7 @@ export {
   lt,
   lte,
   ltrim,
+  manhattanDistance,
   mapFields,
   materializeAs,
   max,
@@ -22011,6 +22133,8 @@ export {
   validateTreeTable,
   valueToOperand,
   variance,
+  vectorDistance,
+  vectorMatch,
   visitExpression,
   visitOperand,
   weekOfYear,