metal-orm 1.1.18 → 1.1.20

package/README.md

@@ -175,7 +175,7 @@ You don’t have to use decorators, but when you do, you’re still on the same
 <a id="installation"></a>
 ## Installation 📦
 
-**Requirements:** Node.js ≥ 20.0.0. For TypeScript projects, use TS 5.6+ to get the standard decorators API and typings.
+**Requirements:** Node.js ≥ 22.0.0. For TypeScript projects, use TS 5.6+ to get the standard decorators API and typings.
 
 ```bash
 # npm
@@ -196,7 +196,7 @@ MetalORM compiles SQL; you bring your own driver:
 | SQLite             | `sqlite3`         | `npm install sqlite3`           |
 | SQLite             | `better-sqlite3`  | `npm install better-sqlite3`    |
 | PostgreSQL         | `pg`              | `npm install pg`                |
-| SQL Server         | `tedious`         | `npm install tedious`           |
+| SQL Server         | `tedious`         | `npm install tedious` (Node 22+) |
 
 Pick the matching dialect (`MySqlDialect`, `SQLiteDialect`, `PostgresDialect`, `MSSQLDialect`) when compiling queries.
 

package/dist/index.cjs

@@ -2,8 +2,8 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-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)
@@ -182,6 +182,7 @@ __export(index_exports, {
   concatWs: () => concatWs,
   correlateBy: () => correlateBy,
   cos: () => cos,
+  cosineDistance: () => cosineDistance,
   cot: () => cot,
   count: () => count,
   countAll: () => countAll,
@@ -218,12 +219,14 @@ __export(index_exports, {
   denseRank: () => denseRank,
   diffSchema: () => diffSchema,
   div: () => div,
+  dotProduct: () => dotProduct,
   dtoToOpenApiSchema: () => dtoToOpenApiSchema,
   endOfMonth: () => endOfMonth,
   entityRef: () => entityRef,
   entityRefs: () => entityRefs,
   eq: () => eq,
   esel: () => esel,
+  euclideanDistance: () => euclideanDistance,
   exclude: () => exclude,
   executeFilteredPaged: () => executeFilteredPaged,
   executeHydrated: () => executeHydrated,
@@ -281,6 +284,7 @@ __export(index_exports, {
   inList: () => inList,
   inSubquery: () => inSubquery,
   initcap: () => initcap,
+  innerProduct: () => innerProduct,
   insertInto: () => insertInto,
   instr: () => instr,
   introspectSchema: () => introspectSchema,
@@ -309,6 +313,8 @@ __export(index_exports, {
   jsonPath: () => jsonPath,
   jsonSet: () => jsonSet,
   jsonify: () => jsonify,
+  l1Distance: () => l1Distance,
+  l2Distance: () => l2Distance,
   lag: () => lag,
   lastValue: () => lastValue,
   lead: () => lead,
@@ -336,6 +342,7 @@ __export(index_exports, {
   lt: () => lt,
   lte: () => lte,
   ltrim: () => ltrim,
+  manhattanDistance: () => manhattanDistance,
   mapFields: () => mapFields,
   materializeAs: () => materializeAs,
   max: () => max,
@@ -455,6 +462,8 @@ __export(index_exports, {
   validateTreeTable: () => validateTreeTable,
   valueToOperand: () => valueToOperand,
   variance: () => variance,
+  vectorDistance: () => vectorDistance,
+  vectorMatch: () => vectorMatch,
   visitExpression: () => visitExpression,
   visitOperand: () => visitOperand,
   weekOfYear: () => weekOfYear,
@@ -575,7 +584,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) => {
@@ -685,6 +696,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.
@@ -2158,13 +2190,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}`;
   }
   /**
@@ -2174,9 +2206,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}.`;
   }
   /**
@@ -2187,8 +2219,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);
       }
@@ -2204,9 +2236,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.
@@ -2214,8 +2246,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.
@@ -2224,9 +2256,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}`;
   }
   /**
@@ -2236,9 +2268,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})`;
   }
 };
@@ -2520,24 +2552,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) {
@@ -2726,6 +2758,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 ?? "");
@@ -2957,6 +3009,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}')`;
+    });
   }
 };
 
@@ -3193,6 +3253,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})`;
+    });
   }
 };
 
@@ -3394,6 +3463,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})`;
+    });
   }
 };
 
@@ -13843,6 +13921,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;
@@ -14158,12 +14280,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
@@ -14195,13 +14317,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
@@ -14210,8 +14332,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
@@ -14255,9 +14377,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
@@ -15872,9 +15994,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;
     }
@@ -15890,7 +16012,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();
@@ -16404,7 +16526,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,
@@ -16412,7 +16534,7 @@ var Orm = class {
       cacheManager: this.cacheManager
     });
     try {
-      return await session.transaction(() => fn8(session));
+      return await session.transaction(() => fn9(session));
     } finally {
       await session.dispose();
     }
@@ -21701,10 +21823,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 = {
@@ -22171,6 +22293,7 @@ async function bulkUpsert(session, table, rows, options = {}) {
   concatWs,
   correlateBy,
   cos,
+  cosineDistance,
   cot,
   count,
   countAll,
@@ -22207,12 +22330,14 @@ async function bulkUpsert(session, table, rows, options = {}) {
   denseRank,
   diffSchema,
   div,
+  dotProduct,
   dtoToOpenApiSchema,
   endOfMonth,
   entityRef,
   entityRefs,
   eq,
   esel,
+  euclideanDistance,
   exclude,
   executeFilteredPaged,
   executeHydrated,
@@ -22270,6 +22395,7 @@ async function bulkUpsert(session, table, rows, options = {}) {
   inList,
   inSubquery,
   initcap,
+  innerProduct,
   insertInto,
   instr,
   introspectSchema,
@@ -22298,6 +22424,8 @@ async function bulkUpsert(session, table, rows, options = {}) {
   jsonPath,
   jsonSet,
   jsonify,
+  l1Distance,
+  l2Distance,
   lag,
   lastValue,
   lead,
@@ -22325,6 +22453,7 @@ async function bulkUpsert(session, table, rows, options = {}) {
   lt,
   lte,
   ltrim,
+  manhattanDistance,
   mapFields,
   materializeAs,
   max,
@@ -22444,6 +22573,8 @@ async function bulkUpsert(session, table, rows, options = {}) {
   validateTreeTable,
   valueToOperand,
   variance,
+  vectorDistance,
+  vectorMatch,
   visitExpression,
   visitOperand,
   weekOfYear,