metal-orm 1.1.19 → 1.1.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.1.19",
+  "version": "1.1.21",
   "type": "module",
   "repository": {
     "type": "git",

package/src/core/ddl/dialects/mssql-schema-dialect.ts

@@ -73,6 +73,15 @@ export class MSSqlSchemaDialect extends BaseSchemaDialect {
         return 'VARBINARY(MAX)';
       case 'enum':
         return 'NVARCHAR(255)';
+      case 'vector': {
+        const dim = column.vectorOptions?.dimensions ?? column.args?.[0] ?? 3;
+        const elemType = column.vectorOptions?.elementType;
+        return elemType ? `VECTOR(${dim}, ${elemType})` : `VECTOR(${dim})`;
+      }
+      case 'halfvec': {
+        const dim = column.vectorOptions?.dimensions ?? column.args?.[0] ?? 3;
+        return `VECTOR(${dim}, float16)`;
+      }
       default:
         return renderTypeWithArgs(String(type).toUpperCase(), column.args);
     }

package/src/core/ddl/dialects/mysql-schema-dialect.ts

@@ -71,6 +71,11 @@ export class MySqlSchemaDialect extends BaseSchemaDialect {
         return column.args && Array.isArray(column.args) && column.args.length
           ? `ENUM(${column.args.map((v: string) => `'${escapeSqlString(v)}'`).join(',')})`
           : 'ENUM';
+      case 'vector':
+      case 'halfvec': {
+        const dim = column.vectorOptions?.dimensions ?? column.args?.[0] ?? 3;
+        return `VECTOR(${dim})`;
+      }
       default:
         return renderTypeWithArgs(String(type).toUpperCase(), column.args);
     }

package/src/core/ddl/dialects/postgres-schema-dialect.ts

@@ -66,6 +66,14 @@ export class PostgresSchemaDialect extends BaseSchemaDialect {
       case 'blob':
       case 'bytea':
         return 'bytea';
+      case 'vector':
+        return column.vectorOptions?.elementType === 'float16'
+          ? `halfvec(${column.vectorOptions.dimensions})`
+          : column.args?.length
+            ? `vector(${column.args[0]})`
+            : 'vector';
+      case 'halfvec':
+        return column.args?.length ? `halfvec(${column.args[0]})` : 'halfvec';
       default:
         return renderTypeWithArgs(String(type).toLowerCase(), column.args);
     }
@@ -79,10 +87,23 @@ export class PostgresSchemaDialect extends BaseSchemaDialect {
 
   renderIndex(table: TableDef, index: IndexDef): string {
     const name = index.name || deriveIndexName(table, index);
-    const cols = renderIndexColumns(this, index.columns);
+    let cols = renderIndexColumns(this, index.columns);
+    if (index.ops) {
+      cols = `${cols} ${index.ops}`;
+    }
     const unique = index.unique ? 'UNIQUE ' : '';
+    const using = index.using ? ` USING ${index.using}` : '';
+    let withClause = '';
+    if (index.with) {
+      if (typeof index.with === 'string') {
+        withClause = ` WITH (${index.with})`;
+      } else {
+        const params = Object.entries(index.with).map(([k, v]) => `${k} = ${v}`).join(', ');
+        withClause = ` WITH (${params})`;
+      }
+    }
     const where = index.where ? ` WHERE ${index.where}` : '';
-    return `CREATE ${unique}INDEX IF NOT EXISTS ${this.quoteIdentifier(name)} ON ${this.formatTableName(table)} (${cols})${where};`;
+    return `CREATE ${unique}INDEX IF NOT EXISTS ${this.quoteIdentifier(name)} ON ${this.formatTableName(table)}${using} (${cols})${withClause}${where};`;
   }
 
   supportsPartialIndexes(): boolean {

package/src/core/ddl/dialects/sqlite-schema-dialect.ts

@@ -57,6 +57,15 @@ export class SQLiteSchemaDialect extends BaseSchemaDialect {
       case 'blob':
       case 'bytea':
         return 'BLOB';
+      case 'halfvec': {
+        const dim = column.vectorOptions?.dimensions ?? column.args?.[0] ?? 3;
+        return `float16[${dim}]`;
+      }
+      case 'vector': {
+        const dim = column.vectorOptions?.dimensions ?? column.args?.[0] ?? 3;
+        const elemType = column.vectorOptions?.elementType === 'float16' ? 'float16' : 'float32';
+        return `${elemType}[${dim}]`;
+      }
       default:
         return 'TEXT';
     }

package/src/core/dialect/mssql/functions.ts

@@ -143,5 +143,15 @@ export class MssqlFunctionStrategy 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})`;
+        });
     }
 }

package/src/core/dialect/mysql/functions.ts

@@ -110,5 +110,14 @@ export class MysqlFunctionStrategy 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}')`;
+        });
     }
 }

package/src/core/dialect/postgres/functions.ts

@@ -140,6 +140,27 @@ export class PostgresFunctionStrategy 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})`;
+            }
+        });
     }
 
     private formatJsonbPathArray(pathNode: LiteralNode): string {

package/src/core/dialect/sqlite/functions.ts

@@ -151,5 +151,15 @@ export class SqliteFunctionStrategy extends StandardFunctionStrategy {
         });
 
         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})`;
+        });
     }
 }

package/src/core/functions/vector.ts

@@ -0,0 +1,141 @@
+// Pure AST Builders - No Dialect Logic Here!
+
+import { ColumnDef } from '../../schema/column-types.js';
+import { columnOperand, valueToOperand } from '../ast/expression-builders.js';
+import { FunctionNode, OperandNode, isOperandNode, TypedExpression, asType } from '../ast/expression.js';
+import { BinaryExpressionNode, LogicalExpressionNode } from '../ast/expression-nodes.js';
+import { SqlOperator } from '../sql/sql.js';
+
+export type VectorMetric =
+  | 'cosine'
+  | 'euclidean'
+  | 'l2'
+  | 'dot'
+  | 'inner_product'
+  | 'manhattan'
+  | 'l1';
+
+export type VectorInput =
+  | OperandNode
+  | ColumnDef
+  | number[]
+  | Float32Array
+  | string;
+
+const isColumnDef = (val: unknown): val is ColumnDef =>
+  !!val && typeof val === 'object' && 'type' in val && 'name' in val;
+
+const toOperand = (input: VectorInput): OperandNode => {
+  if (isOperandNode(input)) return input;
+  if (isColumnDef(input)) return columnOperand(input);
+
+  if (Array.isArray(input) || input instanceof Float32Array) {
+    const formatted = `[${Array.from(input).join(', ')}]`;
+    return valueToOperand(formatted);
+  }
+
+  return valueToOperand(input);
+};
+
+const fn = (key: string, args: OperandNode[]): FunctionNode => ({
+  type: 'Function',
+  name: key,
+  fn: key,
+  args
+});
+
+/**
+ * Calculates vector distance using a specific distance metric ('cosine', 'euclidean', 'l2', 'dot', 'inner_product', 'manhattan', 'l1').
+ * Compiles to dialect-native vector functions / operators:
+ * - SQL Server: VECTOR_DISTANCE('cosine', v1, v2)
+ * - MySQL: DISTANCE(v1, v2, 'COSINE')
+ * - PostgreSQL: (v1 <=> v2), (v1 <-> v2), (v1 <#> v2), (v1 <~> v2)
+ * - SQLite: vec_distance_cosine(v1, v2), vec_distance_L2(v1, v2)
+ */
+export const vectorDistance = (
+  metric: VectorMetric,
+  v1: VectorInput,
+  v2: VectorInput
+): TypedExpression<number> => {
+  const metricOp = valueToOperand(metric.toLowerCase());
+  return asType<number>(fn('VECTOR_DISTANCE', [metricOp, toOperand(v1), toOperand(v2)]));
+};
+
+/**
+ * Calculates Cosine distance between two vectors.
+ */
+export const cosineDistance = (v1: VectorInput, v2: VectorInput): TypedExpression<number> =>
+  vectorDistance('cosine', v1, v2);
+
+/**
+ * Calculates Euclidean (L2) distance between two vectors.
+ */
+export const l2Distance = (v1: VectorInput, v2: VectorInput): TypedExpression<number> =>
+  vectorDistance('euclidean', v1, v2);
+
+/**
+ * Alias for l2Distance. Calculates Euclidean distance between two vectors.
+ */
+export const euclideanDistance = (v1: VectorInput, v2: VectorInput): TypedExpression<number> =>
+  vectorDistance('euclidean', v1, v2);
+
+/**
+ * Calculates Inner / Dot product distance between two vectors.
+ */
+export const innerProduct = (v1: VectorInput, v2: VectorInput): TypedExpression<number> =>
+  vectorDistance('dot', v1, v2);
+
+/**
+ * Alias for innerProduct. Calculates Dot product distance between two vectors.
+ */
+export const dotProduct = (v1: VectorInput, v2: VectorInput): TypedExpression<number> =>
+  vectorDistance('dot', v1, v2);
+
+/**
+ * Calculates Manhattan (L1) distance between two vectors.
+ */
+export const l1Distance = (v1: VectorInput, v2: VectorInput): TypedExpression<number> =>
+  vectorDistance('manhattan', v1, v2);
+
+/**
+ * Alias for l1Distance. Calculates Manhattan distance between two vectors.
+ */
+export const manhattanDistance = (v1: VectorInput, v2: VectorInput): TypedExpression<number> =>
+  vectorDistance('manhattan', v1, v2);
+
+/**
+ * Builds a SQLite `sqlite-vec` KNN virtual table query predicate:
+ * `col MATCH '[...]' AND k = n`
+ *
+ * @param column - The vector virtual table column to match against.
+ * @param vector - The query vector(s) to match (raw array/string is inlined as a literal).
+ * @param k - Number of nearest neighbors to return.
+ *
+ * @example
+ * ```ts
+ * where(vectorMatch(items.embedding, [0.1, 2, 30], 5))
+ * // => "embedding" MATCH '[0.1, 2, 30]' AND k = 5
+ * ```
+ */
+export const vectorMatch = (
+  column: VectorInput,
+  vector: VectorInput,
+  k: number
+): LogicalExpressionNode => {
+  const match: BinaryExpressionNode = {
+    type: 'BinaryExpression',
+    left: toOperand(column),
+    operator: 'MATCH' as SqlOperator,
+    right: toOperand(vector)
+  };
+
+  const kNode: BinaryExpressionNode = {
+    type: 'BinaryExpression',
+    left: valueToOperand('k'),
+    operator: '=',
+    right: valueToOperand(k)
+  };
+
+  return { type: 'LogicalExpression', operator: 'AND', operands: [match, kNode] };
+};
+

package/src/index.ts

@@ -32,6 +32,7 @@ export * from './core/functions/datetime.js';
 export * from './core/functions/control-flow.js';
 export * from './core/functions/json.js';
 export * from './core/functions/array.js';
+export * from './core/functions/vector.js';
 export * from './orm/als.js';
 export * from './orm/hydration.js';
 export * from './codegen/typescript.js';

package/src/orm/relation-change-processor.ts

@@ -7,7 +7,6 @@ import { UpdateQueryBuilder } from '../query-builder/update.js';
 import { findPrimaryKey } from '../query-builder/hydration-planner.js';
 import type { BelongsToManyRelation, HasManyRelation, HasOneRelation, MorphOneRelation, MorphManyRelation, MorphToRelation } from '../schema/relation.js';
 import { RelationKinds } from '../schema/relation.js';
-import type { TableDef } from '../schema/table.js';
 import type { DbExecutor } from '../core/execution/db-executor.js';
 import type { RelationChangeEntry } from './runtime-types.js';
 import { UnitOfWork } from './unit-of-work.js';
@@ -153,7 +152,10 @@ export class RelationChangeProcessor {
     const rootId = entry.root[rootKey];
     if (rootId === undefined || rootId === null) return;
 
-    const targetId = this.resolvePrimaryKeyValue(entry.change.entity as Record<string, unknown>, relation.target);
+    const targetId = this.resolveBelongsToManyTargetValue(
+      entry.change.entity as Record<string, unknown>,
+      relation
+    );
     if (targetId === null) return;
 
     const pivotPayload = this.buildPivotPayload(relation, entry.change.pivot);
@@ -235,7 +237,7 @@ export class RelationChangeProcessor {
    * 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
    */
   private async insertPivotRow(
     relation: BelongsToManyRelation,
@@ -258,7 +260,7 @@ export class RelationChangeProcessor {
    * 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
    */
   private async updatePivotRow(
@@ -282,7 +284,7 @@ export class RelationChangeProcessor {
    * 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
    */
   private async deletePivotRow(relation: BelongsToManyRelation, rootId: string | number, targetId: string | number): Promise<void> {
     const rootCol = relation.pivotTable.columns[relation.pivotForeignKeyToRoot];
@@ -297,14 +299,16 @@ export class RelationChangeProcessor {
   }
 
   /**
-   * 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.
    */
-  private resolvePrimaryKeyValue(entity: Record<string, unknown>, table: TableDef): string | number | null {
+  private resolveBelongsToManyTargetValue(
+    entity: Record<string, unknown>,
+    relation: BelongsToManyRelation
+  ): string | number | null {
     if (!entity) return null;
-    const key = findPrimaryKey(table);
+    const key = relation.targetKey || findPrimaryKey(relation.target);
     const value = entity[key];
     if (value === undefined || value === null) return null;
     return (value as string | number | null | undefined) ?? null;

package/src/schema/column-types.ts

@@ -21,7 +21,9 @@ export const STANDARD_COLUMN_TYPES = [
   'DATETIME',
   'TIMESTAMP',
   'TIMESTAMPTZ',
-  'BOOLEAN'
+  'BOOLEAN',
+  'VECTOR',
+  'HALFVEC'
 ] as const;
 
 /** Known logical types the ORM understands. */
@@ -113,6 +115,11 @@ export interface ColumnDef<T extends ColumnType = ColumnType, TRuntime = unknown
   comment?: string;
   /** Additional arguments for the column type (e.g., VARCHAR length) */
   args?: (string | number)[];
+  /** Options specific to vector columns (dimensions, float16 vs float32, etc.) */
+  vectorOptions?: {
+    dimensions: number;
+    elementType?: 'float16' | 'float32' | 'int8' | 'bit';
+  };
   /** Table name this column belongs to (filled at runtime by defineTable) */
   table?: string;
 }
@@ -236,6 +243,32 @@ export const col = {
    */
   enum: (values: string[]): ColumnDef<'ENUM'> => ({ 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: number,
+    options?: { elementType?: 'float16' | 'float32' | 'int8' | 'bit' }
+  ): ColumnDef<'VECTOR', number[]> => ({
+    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: number): ColumnDef<'HALFVEC', number[]> => ({
+    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.

package/src/schema/table.ts

@@ -12,6 +12,12 @@ export interface IndexDef {
   columns: (string | IndexColumn)[];
   unique?: boolean;
   where?: string;
+  /** Index method / access method, e.g. 'hnsw', 'ivfflat', 'btree' */
+  using?: string;
+  /** Operator class for vector distance, e.g. 'vector_cosine_ops', 'vector_l2_ops', 'halfvec_cosine_ops' */
+  ops?: string;
+  /** Index parameters / WITH clause options, e.g. { m: 16, ef_construction: 64 } */
+  with?: Record<string, unknown> | string;
 }
 
 export interface CheckConstraint {