metal-orm 1.0.8 → 1.0.9

package/src/{utils → core/ast}/join-node.ts

@@ -1,20 +1,20 @@
-import { JoinNode } from '../ast/join';
-import { ExpressionNode } from '../ast/expression';
-import { JoinKind } from '../constants/sql';
-
-/**
- * Creates a JoinNode ready for AST insertion.
- * Centralizing this avoids copy/pasted object literals when multiple services need to synthesize joins.
- */
-export const createJoinNode = (
-  kind: JoinKind,
-  tableName: string,
-  condition: ExpressionNode,
-  relationName?: string
-): JoinNode => ({
-  type: 'Join',
-  kind,
-  table: { type: 'Table', name: tableName },
-  condition,
-  relationName
-});
+import { JoinNode } from './join.js';
+import { ExpressionNode } from './expression.js';
+import { JoinKind } from '../sql/sql.js';
+
+/**
+ * Creates a JoinNode ready for AST insertion.
+ * Centralizing this avoids copy/pasted object literals when multiple services need to synthesize joins.
+ */
+export const createJoinNode = (
+  kind: JoinKind,
+  tableName: string,
+  condition: ExpressionNode,
+  relationName?: string
+): JoinNode => ({
+  type: 'Join',
+  kind,
+  table: { type: 'Table', name: tableName },
+  condition,
+  relationName
+});

package/src/{ast → core/ast}/join.ts

@@ -1,18 +1,18 @@
-import { TableNode } from './query';
-import { ExpressionNode } from './expression';
-import { JoinKind } from '../constants/sql';
-
-/**
- * AST node representing a JOIN clause
- */
-export interface JoinNode {
-  type: 'Join';
-  /** Type of join (INNER, LEFT, RIGHT, etc.) */
-  kind: JoinKind;
-  /** Table to join */
-  table: TableNode;
-  /** Join condition expression */
-  condition: ExpressionNode;
-  /** Optional relation name for code generation */
-  relationName?: string;
-}
+import { TableNode } from './query.js';
+import { ExpressionNode } from './expression.js';
+import { JoinKind } from '../sql/sql.js';
+
+/**
+ * AST node representing a JOIN clause
+ */
+export interface JoinNode {
+  type: 'Join';
+  /** Type of join (INNER, LEFT, RIGHT, etc.) */
+  kind: JoinKind;
+  /** Table to join */
+  table: TableNode;
+  /** Join condition expression */
+  condition: ExpressionNode;
+  /** Optional relation name for code generation */
+  relationName?: string;
+}

package/src/{ast → core/ast}/query.ts

@@ -1,15 +1,15 @@
-import {
-  ColumnNode,
-  FunctionNode,
-  ExpressionNode,
-  ScalarSubqueryNode,
-  CaseExpressionNode,
-  WindowFunctionNode,
-  OperandNode
-} from './expression';
-import { JoinNode } from './join';
-import { RelationType } from '../schema/relation';
-import { OrderDirection } from '../constants/sql';
+import {
+  ColumnNode,
+  FunctionNode,
+  ExpressionNode,
+  ScalarSubqueryNode,
+  CaseExpressionNode,
+  WindowFunctionNode,
+  OperandNode
+} from './expression.js';
+import { JoinNode } from './join.js';
+import { RelationType } from '../../schema/relation.js';
+import { OrderDirection } from '../sql/sql.js';
 
 /**
  * AST node representing a table reference in a query
@@ -35,39 +35,39 @@ export interface OrderByNode {
   direction: OrderDirection;
 }
 
-/**
- * Plan describing pivot columns needed for hydration
- */
-export interface HydrationPivotPlan {
-  table: string;
-  primaryKey: string;
-  aliasPrefix: string;
-  columns: string[];
-}
-
-/**
- * Plan for hydrating relationship data
- */
-export interface HydrationRelationPlan {
-  /** Name of the relationship */
-  name: string;
-  /** Alias prefix for the relationship */
-  aliasPrefix: string;
-  /** Type of relationship */
-  type: RelationType;
-  /** Target table name */
-  targetTable: string;
-  /** Target table primary key */
-  targetPrimaryKey: string;
-  /** Foreign key column */
-  foreignKey: string;
-  /** Local key column */
-  localKey: string;
-  /** Columns to include */
-  columns: string[];
-  /** Optional pivot plan for many-to-many relationships */
-  pivot?: HydrationPivotPlan;
-}
+/**
+ * Plan describing pivot columns needed for hydration
+ */
+export interface HydrationPivotPlan {
+  table: string;
+  primaryKey: string;
+  aliasPrefix: string;
+  columns: string[];
+}
+
+/**
+ * Plan for hydrating relationship data
+ */
+export interface HydrationRelationPlan {
+  /** Name of the relationship */
+  name: string;
+  /** Alias prefix for the relationship */
+  aliasPrefix: string;
+  /** Type of relationship */
+  type: RelationType;
+  /** Target table name */
+  targetTable: string;
+  /** Target table primary key */
+  targetPrimaryKey: string;
+  /** Foreign key column */
+  foreignKey: string;
+  /** Local key column */
+  localKey: string;
+  /** Columns to include */
+  columns: string[];
+  /** Optional pivot plan for many-to-many relationships */
+  pivot?: HydrationPivotPlan;
+}
 
 /**
  * Complete hydration plan for a query
@@ -109,71 +109,71 @@ export interface CommonTableExpressionNode {
 /**
  * AST node representing a complete SELECT query
  */
-export interface SelectQueryNode {
-  type: 'SelectQuery';
-  /** Optional CTEs (WITH clauses) */
-  ctes?: CommonTableExpressionNode[];
-  /** FROM clause table */
-  from: TableNode;
-  /** SELECT clause columns */
-  columns: (ColumnNode | FunctionNode | ScalarSubqueryNode | CaseExpressionNode | WindowFunctionNode)[];
-  /** JOIN clauses */
-  joins: JoinNode[];
-  /** Optional WHERE clause */
-  where?: ExpressionNode;
-  /** Optional GROUP BY clause */
-  groupBy?: ColumnNode[];
-  /** Optional HAVING clause */
-  having?: ExpressionNode;
-  /** Optional ORDER BY clause */
-  orderBy?: OrderByNode[];
-  /** Optional LIMIT clause */
-  limit?: number;
-  /** Optional OFFSET clause */
-  offset?: number;
-  /** Optional query metadata */
-  meta?: QueryMetadata;
-  /** Optional DISTINCT clause */
-  distinct?: ColumnNode[];
-}
-
-export interface InsertQueryNode {
-  type: 'InsertQuery';
-  /** Target table */
-  into: TableNode;
-  /** Column order for inserted values */
-  columns: ColumnNode[];
-  /** Rows of values to insert */
-  values: OperandNode[][];
-  /** Optional RETURNING clause */
-  returning?: ColumnNode[];
-}
-
-export interface UpdateAssignmentNode {
-  /** Column to update */
-  column: ColumnNode;
-  /** Value to set */
-  value: OperandNode;
-}
-
-export interface UpdateQueryNode {
-  type: 'UpdateQuery';
-  /** Table being updated */
-  table: TableNode;
-  /** Assignments for SET clause */
-  set: UpdateAssignmentNode[];
-  /** Optional WHERE clause */
-  where?: ExpressionNode;
-  /** Optional RETURNING clause */
-  returning?: ColumnNode[];
-}
-
-export interface DeleteQueryNode {
-  type: 'DeleteQuery';
-  /** Table to delete from */
-  from: TableNode;
-  /** Optional WHERE clause */
-  where?: ExpressionNode;
-  /** Optional RETURNING clause */
-  returning?: ColumnNode[];
-}
+export interface SelectQueryNode {
+  type: 'SelectQuery';
+  /** Optional CTEs (WITH clauses) */
+  ctes?: CommonTableExpressionNode[];
+  /** FROM clause table */
+  from: TableNode;
+  /** SELECT clause columns */
+  columns: (ColumnNode | FunctionNode | ScalarSubqueryNode | CaseExpressionNode | WindowFunctionNode)[];
+  /** JOIN clauses */
+  joins: JoinNode[];
+  /** Optional WHERE clause */
+  where?: ExpressionNode;
+  /** Optional GROUP BY clause */
+  groupBy?: ColumnNode[];
+  /** Optional HAVING clause */
+  having?: ExpressionNode;
+  /** Optional ORDER BY clause */
+  orderBy?: OrderByNode[];
+  /** Optional LIMIT clause */
+  limit?: number;
+  /** Optional OFFSET clause */
+  offset?: number;
+  /** Optional query metadata */
+  meta?: QueryMetadata;
+  /** Optional DISTINCT clause */
+  distinct?: ColumnNode[];
+}
+
+export interface InsertQueryNode {
+  type: 'InsertQuery';
+  /** Target table */
+  into: TableNode;
+  /** Column order for inserted values */
+  columns: ColumnNode[];
+  /** Rows of values to insert */
+  values: OperandNode[][];
+  /** Optional RETURNING clause */
+  returning?: ColumnNode[];
+}
+
+export interface UpdateAssignmentNode {
+  /** Column to update */
+  column: ColumnNode;
+  /** Value to set */
+  value: OperandNode;
+}
+
+export interface UpdateQueryNode {
+  type: 'UpdateQuery';
+  /** Table being updated */
+  table: TableNode;
+  /** Assignments for SET clause */
+  set: UpdateAssignmentNode[];
+  /** Optional WHERE clause */
+  where?: ExpressionNode;
+  /** Optional RETURNING clause */
+  returning?: ColumnNode[];
+}
+
+export interface DeleteQueryNode {
+  type: 'DeleteQuery';
+  /** Table to delete from */
+  from: TableNode;
+  /** Optional WHERE clause */
+  where?: ExpressionNode;
+  /** Optional RETURNING clause */
+  returning?: ColumnNode[];
+}

package/src/core/ast/window-functions.ts

@@ -0,0 +1,140 @@
+import { ColumnDef } from '../../schema/column.js';
+import { ColumnNode, LiteralNode, JsonPathNode, WindowFunctionNode } from './expression-nodes.js';
+import { columnOperand } from './expression-builders.js';
+import { OrderDirection } from '../sql/sql.js';
+import { OrderByNode } from './query.js';
+
+const buildWindowFunction = (
+  name: string,
+  args: (ColumnNode | LiteralNode | JsonPathNode)[] = [],
+  partitionBy?: ColumnNode[],
+  orderBy?: OrderByNode[]
+): WindowFunctionNode => {
+  const node: WindowFunctionNode = {
+    type: 'WindowFunction',
+    name,
+    args
+  };
+
+  if (partitionBy && partitionBy.length) {
+    node.partitionBy = partitionBy;
+  }
+
+  if (orderBy && orderBy.length) {
+    node.orderBy = orderBy;
+  }
+
+  return node;
+};
+
+/**
+ * Creates a ROW_NUMBER window function
+ * @returns Window function node for ROW_NUMBER
+ */
+export const rowNumber = (): WindowFunctionNode => buildWindowFunction('ROW_NUMBER');
+
+/**
+ * Creates a RANK window function
+ * @returns Window function node for RANK
+ */
+export const rank = (): WindowFunctionNode => buildWindowFunction('RANK');
+
+/**
+ * Creates a DENSE_RANK window function
+ * @returns Window function node for DENSE_RANK
+ */
+export const denseRank = (): WindowFunctionNode => buildWindowFunction('DENSE_RANK');
+
+/**
+ * Creates an NTILE window function
+ * @param n - Number of buckets
+ * @returns Window function node for NTILE
+ */
+export const ntile = (n: number): WindowFunctionNode =>
+  buildWindowFunction('NTILE', [{ type: 'Literal', value: n }]);
+
+/**
+ * Creates a LAG window function
+ * @param col - Column to lag
+ * @param offset - Offset (defaults to 1)
+ * @param defaultValue - Default value if no row exists
+ * @returns Window function node for LAG
+ */
+export const lag = (col: ColumnDef | ColumnNode, offset: number = 1, defaultValue?: any): WindowFunctionNode => {
+  const args: (ColumnNode | LiteralNode | JsonPathNode)[] = [
+    columnOperand(col),
+    { type: 'Literal', value: offset }
+  ];
+  if (defaultValue !== undefined) {
+    args.push({ type: 'Literal', value: defaultValue });
+  }
+  return buildWindowFunction('LAG', args);
+};
+
+/**
+ * Creates a LEAD window function
+ * @param col - Column to lead
+ * @param offset - Offset (defaults to 1)
+ * @param defaultValue - Default value if no row exists
+ * @returns Window function node for LEAD
+ */
+export const lead = (col: ColumnDef | ColumnNode, offset: number = 1, defaultValue?: any): WindowFunctionNode => {
+  const args: (ColumnNode | LiteralNode | JsonPathNode)[] = [
+    columnOperand(col),
+    { type: 'Literal', value: offset }
+  ];
+  if (defaultValue !== undefined) {
+    args.push({ type: 'Literal', value: defaultValue });
+  }
+  return buildWindowFunction('LEAD', args);
+};
+
+/**
+ * Creates a FIRST_VALUE window function
+ * @param col - Column to get first value from
+ * @returns Window function node for FIRST_VALUE
+ */
+export const firstValue = (col: ColumnDef | ColumnNode): WindowFunctionNode =>
+  buildWindowFunction('FIRST_VALUE', [columnOperand(col)]);
+
+/**
+ * Creates a LAST_VALUE window function
+ * @param col - Column to get last value from
+ * @returns Window function node for LAST_VALUE
+ */
+export const lastValue = (col: ColumnDef | ColumnNode): WindowFunctionNode =>
+  buildWindowFunction('LAST_VALUE', [columnOperand(col)]);
+
+/**
+ * Creates a custom window function
+ * @param name - Window function name
+ * @param args - Function arguments
+ * @param partitionBy - Optional PARTITION BY columns
+ * @param orderBy - Optional ORDER BY clauses
+ * @returns Window function node
+ */
+export const windowFunction = (
+  name: string,
+  args: (ColumnDef | ColumnNode | LiteralNode | JsonPathNode)[] = [],
+  partitionBy?: (ColumnDef | ColumnNode)[],
+  orderBy?: { column: ColumnDef | ColumnNode; direction: OrderDirection }[]
+): WindowFunctionNode => {
+  const nodeArgs = args.map(arg => {
+    if (typeof (arg as LiteralNode).value !== 'undefined') {
+      return arg as LiteralNode;
+    }
+    if ('path' in arg) {
+      return arg as JsonPathNode;
+    }
+    return columnOperand(arg as ColumnDef | ColumnNode);
+  });
+
+  const partitionNodes = partitionBy?.map(col => columnOperand(col)) ?? undefined;
+  const orderNodes: OrderByNode[] | undefined = orderBy?.map(o => ({
+    type: 'OrderBy',
+    column: columnOperand(o.column),
+    direction: o.direction
+  }));
+
+  return buildWindowFunction(name, nodeArgs, partitionNodes, orderNodes);
+};

package/src/{dialect → core/dialect}/abstract.ts

@@ -1,4 +1,4 @@
-import { SelectQueryNode, InsertQueryNode, UpdateQueryNode, DeleteQueryNode } from '../ast/query';
+import { SelectQueryNode, InsertQueryNode, UpdateQueryNode, DeleteQueryNode } from '../ast/query.js';
 import {
   ExpressionNode,
   BinaryExpressionNode,
@@ -15,7 +15,7 @@ import {
   CaseExpressionNode,
   WindowFunctionNode,
   BetweenExpressionNode
-} from '../ast/expression';
+} from '../ast/expression.js';
 
 /**
  * Context for SQL compilation with parameter management
@@ -30,91 +30,91 @@ export interface CompilerContext {
 /**
  * Result of SQL compilation
  */
-export interface CompiledQuery {
-  /** Generated SQL string */
-  sql: string;
-  /** Parameters for the query */
-  params: unknown[];
-}
-
-export interface SelectCompiler {
-  compileSelect(ast: SelectQueryNode): CompiledQuery;
-}
-
-export interface InsertCompiler {
-  compileInsert(ast: InsertQueryNode): CompiledQuery;
-}
-
-export interface UpdateCompiler {
-  compileUpdate(ast: UpdateQueryNode): CompiledQuery;
-}
-
-export interface DeleteCompiler {
-  compileDelete(ast: DeleteQueryNode): CompiledQuery;
-}
-
-/**
- * Abstract base class for SQL dialect implementations
- */
-export abstract class Dialect
-  implements SelectCompiler, InsertCompiler, UpdateCompiler, DeleteCompiler
-{
+export interface CompiledQuery {
+  /** Generated SQL string */
+  sql: string;
+  /** Parameters for the query */
+  params: unknown[];
+}
+
+export interface SelectCompiler {
+  compileSelect(ast: SelectQueryNode): CompiledQuery;
+}
+
+export interface InsertCompiler {
+  compileInsert(ast: InsertQueryNode): CompiledQuery;
+}
+
+export interface UpdateCompiler {
+  compileUpdate(ast: UpdateQueryNode): CompiledQuery;
+}
+
+export interface DeleteCompiler {
+  compileDelete(ast: DeleteQueryNode): CompiledQuery;
+}
+
+/**
+ * Abstract base class for SQL dialect implementations
+ */
+export abstract class Dialect
+  implements SelectCompiler, InsertCompiler, UpdateCompiler, DeleteCompiler
+{
   /**
    * Compiles a SELECT query AST to SQL
    * @param ast - Query AST to compile
    * @returns Compiled query with SQL and parameters
    */
-  compileSelect(ast: SelectQueryNode): CompiledQuery {
-    const ctx = this.createCompilerContext();
-    const rawSql = this.compileSelectAst(ast, ctx).trim();
-    const sql = rawSql.endsWith(';') ? rawSql : `${rawSql};`;
-    return {
-      sql,
-      params: [...ctx.params]
-    };
-  }
-
-  compileInsert(ast: InsertQueryNode): CompiledQuery {
-    const ctx = this.createCompilerContext();
-    const rawSql = this.compileInsertAst(ast, ctx).trim();
-    const sql = rawSql.endsWith(';') ? rawSql : `${rawSql};`;
-    return {
-      sql,
-      params: [...ctx.params]
-    };
-  }
-
-  compileUpdate(ast: UpdateQueryNode): CompiledQuery {
-    const ctx = this.createCompilerContext();
-    const rawSql = this.compileUpdateAst(ast, ctx).trim();
-    const sql = rawSql.endsWith(';') ? rawSql : `${rawSql};`;
-    return {
-      sql,
-      params: [...ctx.params]
-    };
-  }
-
-  compileDelete(ast: DeleteQueryNode): CompiledQuery {
-    const ctx = this.createCompilerContext();
-    const rawSql = this.compileDeleteAst(ast, ctx).trim();
-    const sql = rawSql.endsWith(';') ? rawSql : `${rawSql};`;
-    return {
-      sql,
-      params: [...ctx.params]
-    };
-  }
-
-  /**
-   * Compiles SELECT query AST to SQL (to be implemented by concrete dialects)
-   * @param ast - Query AST
-   * @param ctx - Compiler context
-   * @returns SQL string
-   */
-  protected abstract compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string;
-
-  protected abstract compileInsertAst(ast: InsertQueryNode, ctx: CompilerContext): string;
-  protected abstract compileUpdateAst(ast: UpdateQueryNode, ctx: CompilerContext): string;
-  protected abstract compileDeleteAst(ast: DeleteQueryNode, ctx: CompilerContext): string;
+  compileSelect(ast: SelectQueryNode): CompiledQuery {
+    const ctx = this.createCompilerContext();
+    const rawSql = this.compileSelectAst(ast, ctx).trim();
+    const sql = rawSql.endsWith(';') ? rawSql : `${rawSql};`;
+    return {
+      sql,
+      params: [...ctx.params]
+    };
+  }
+
+  compileInsert(ast: InsertQueryNode): CompiledQuery {
+    const ctx = this.createCompilerContext();
+    const rawSql = this.compileInsertAst(ast, ctx).trim();
+    const sql = rawSql.endsWith(';') ? rawSql : `${rawSql};`;
+    return {
+      sql,
+      params: [...ctx.params]
+    };
+  }
+
+  compileUpdate(ast: UpdateQueryNode): CompiledQuery {
+    const ctx = this.createCompilerContext();
+    const rawSql = this.compileUpdateAst(ast, ctx).trim();
+    const sql = rawSql.endsWith(';') ? rawSql : `${rawSql};`;
+    return {
+      sql,
+      params: [...ctx.params]
+    };
+  }
+
+  compileDelete(ast: DeleteQueryNode): CompiledQuery {
+    const ctx = this.createCompilerContext();
+    const rawSql = this.compileDeleteAst(ast, ctx).trim();
+    const sql = rawSql.endsWith(';') ? rawSql : `${rawSql};`;
+    return {
+      sql,
+      params: [...ctx.params]
+    };
+  }
+
+  /**
+   * Compiles SELECT query AST to SQL (to be implemented by concrete dialects)
+   * @param ast - Query AST
+   * @param ctx - Compiler context
+   * @returns SQL string
+   */
+  protected abstract compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string;
+
+  protected abstract compileInsertAst(ast: InsertQueryNode, ctx: CompilerContext): string;
+  protected abstract compileUpdateAst(ast: UpdateQueryNode, ctx: CompilerContext): string;
+  protected abstract compileDeleteAst(ast: DeleteQueryNode, ctx: CompilerContext): string;
 
   /**
    * Quotes an SQL identifier (to be implemented by concrete dialects)
@@ -129,18 +129,18 @@ export abstract class Dialect
    * @param ctx - Compiler context
    * @returns SQL WHERE clause or empty string
    */
-  protected compileWhere(where: ExpressionNode | undefined, ctx: CompilerContext): string {
-    if (!where) return '';
-    return ` WHERE ${this.compileExpression(where, ctx)}`;
-  }
-
-  protected compileReturning(
-    returning: ColumnNode[] | undefined,
-    ctx: CompilerContext
-  ): string {
-    if (!returning || returning.length === 0) return '';
-    throw new Error('RETURNING is not supported by this dialect.');
-  }
+  protected compileWhere(where: ExpressionNode | undefined, ctx: CompilerContext): string {
+    if (!where) return '';
+    return ` WHERE ${this.compileExpression(where, ctx)}`;
+  }
+
+  protected compileReturning(
+    returning: ColumnNode[] | undefined,
+    ctx: CompilerContext
+  ): string {
+    if (!returning || returning.length === 0) return '';
+    throw new Error('RETURNING is not supported by this dialect.');
+  }
 
   /**
    * Generates subquery for EXISTS expressions