metal-orm 1.0.2 → 1.0.4

package/src/dialect/abstract.ts

@@ -17,17 +17,35 @@ import {
   BetweenExpressionNode
 } from '../ast/expression';
 
+/**
+ * Context for SQL compilation with parameter management
+ */
 export interface CompilerContext {
+  /** Array of parameters */
   params: unknown[];
+  /** Function to add a parameter and get its placeholder */
   addParameter(value: unknown): string;
 }
 
+/**
+ * Result of SQL compilation
+ */
 export interface CompiledQuery {
+  /** Generated SQL string */
   sql: string;
+  /** Parameters for the query */
   params: unknown[];
 }
 
+/**
+ * Abstract base class for SQL dialect implementations
+ */
 export abstract class Dialect {
+  /**
+   * 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();
@@ -38,20 +56,40 @@ export abstract class Dialect {
     };
   }
 
+  /**
+   * 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;
 
+  /**
+   * Quotes an SQL identifier (to be implemented by concrete dialects)
+   * @param id - Identifier to quote
+   * @returns Quoted identifier
+   */
   abstract quoteIdentifier(id: string): string;
 
+  /**
+   * Compiles a WHERE clause
+   * @param where - WHERE expression
+   * @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)}`;
   }
 
   /**
-   * Gera a subquery para EXISTS.
-   * Regra: sempre força SELECT 1, ignorando a lista de colunas.
-   * Mantém FROM, JOINs, WHERE, GROUP BY, ORDER BY, LIMIT/OFFSET.
-   * Não adiciona ';' no final.
+   * Generates subquery for EXISTS expressions
+   * Rule: Always forces SELECT 1, ignoring column list
+   * Maintains FROM, JOINs, WHERE, GROUP BY, ORDER BY, LIMIT/OFFSET
+   * Does not add ';' at the end
+   * @param ast - Query AST
+   * @param ctx - Compiler context
+   * @returns SQL for EXISTS subquery
    */
   protected compileSelectForExists(ast: SelectQueryNode, ctx: CompilerContext): string {
     const full = this.compileSelectAst(ast, ctx).trim().replace(/;$/, '');
@@ -65,6 +103,10 @@ export abstract class Dialect {
     return `SELECT 1${tail}`;
   }
 
+  /**
+   * Creates a new compiler context
+   * @returns Compiler context with parameter management
+   */
   protected createCompilerContext(): CompilerContext {
     const params: unknown[] = [];
     let counter = 0;
@@ -78,6 +120,11 @@ export abstract class Dialect {
     };
   }
 
+  /**
+   * Formats a parameter placeholder
+   * @param index - Parameter index
+   * @returns Formatted placeholder string
+   */
   protected formatPlaceholder(index: number): string {
     return '?';
   }
@@ -92,35 +139,63 @@ export abstract class Dialect {
     this.registerDefaultExpressionCompilers();
   }
 
+  /**
+   * Registers an expression compiler for a specific node type
+   * @param type - Expression node type
+   * @param compiler - Compiler function
+   */
   protected registerExpressionCompiler<T extends ExpressionNode>(type: T['type'], compiler: (node: T, ctx: CompilerContext) => string): void {
     this.expressionCompilers.set(type, compiler as (node: ExpressionNode, ctx: CompilerContext) => string);
   }
 
+  /**
+   * Registers an operand compiler for a specific node type
+   * @param type - Operand node type
+   * @param compiler - Compiler function
+   */
   protected registerOperandCompiler<T extends OperandNode>(type: T['type'], compiler: (node: T, ctx: CompilerContext) => string): void {
     this.operandCompilers.set(type, compiler as (node: OperandNode, ctx: CompilerContext) => string);
   }
 
-  protected compileExpression(node: ExpressionNode, ctx: CompilerContext): string {
-    const compiler = this.expressionCompilers.get(node.type);
-    return compiler ? compiler(node, ctx) : '';
-  }
+  /**
+   * Compiles an expression node
+   * @param node - Expression node to compile
+   * @param ctx - Compiler context
+   * @returns Compiled SQL expression
+   */
+  protected compileExpression(node: ExpressionNode, ctx: CompilerContext): string {
+    const compiler = this.expressionCompilers.get(node.type);
+    if (!compiler) {
+      throw new Error(`Unsupported expression node type "${node.type}" for ${this.constructor.name}`);
+    }
+    return compiler(node, ctx);
+  }
 
-  protected compileOperand(node: OperandNode, ctx: CompilerContext): string {
-    const compiler = this.operandCompilers.get(node.type);
-    return compiler ? compiler(node, ctx) : '';
-  }
+  /**
+   * Compiles an operand node
+   * @param node - Operand node to compile
+   * @param ctx - Compiler context
+   * @returns Compiled SQL operand
+   */
+  protected compileOperand(node: OperandNode, ctx: CompilerContext): string {
+    const compiler = this.operandCompilers.get(node.type);
+    if (!compiler) {
+      throw new Error(`Unsupported operand node type "${node.type}" for ${this.constructor.name}`);
+    }
+    return compiler(node, ctx);
+  }
 
   private registerDefaultExpressionCompilers(): void {
-    this.registerExpressionCompiler('BinaryExpression', (binary: BinaryExpressionNode, ctx) => {
-      const left = this.compileOperand(binary.left, ctx);
-      const right = this.compileOperand(binary.right, ctx);
-      const base = `${left} ${binary.operator} ${right}`;
-      if (binary.escape) {
-        const escapeOperand = this.compileOperand(binary.escape, ctx);
-        return `${base} ESCAPE ${escapeOperand}`;
-      }
-      return base;
-    });
+    this.registerExpressionCompiler('BinaryExpression', (binary: BinaryExpressionNode, ctx) => {
+      const left = this.compileOperand(binary.left, ctx);
+      const right = this.compileOperand(binary.right, ctx);
+      const base = `${left} ${binary.operator} ${right}`;
+      if (binary.escape) {
+        const escapeOperand = this.compileOperand(binary.escape, ctx);
+        return `${base} ESCAPE ${escapeOperand}`;
+      }
+      return base;
+    });
 
     this.registerExpressionCompiler('LogicalExpression', (logical: LogicalExpressionNode, ctx) => {
       if (logical.operands.length === 0) return '';

package/src/dialect/mssql/index.ts

@@ -2,25 +2,52 @@ import { CompilerContext, Dialect } from '../abstract';
 import { SelectQueryNode } from '../../ast/query';
 import { JsonPathNode } from '../../ast/expression';
 
+/**
+ * Microsoft SQL Server dialect implementation
+ */
 export class SqlServerDialect extends Dialect {
+  /**
+   * Creates a new SqlServerDialect instance
+   */
   public constructor() {
     super();
   }
 
+  /**
+   * Quotes an identifier using SQL Server bracket syntax
+   * @param id - Identifier to quote
+   * @returns Quoted identifier
+   */
   quoteIdentifier(id: string): string {
     return `[${id}]`;
   }
 
+  /**
+   * Compiles JSON path expression using SQL Server syntax
+   * @param node - JSON path node
+   * @returns SQL Server JSON path expression
+   */
   protected compileJsonPath(node: JsonPathNode): string {
     const col = `${this.quoteIdentifier(node.column.table)}.${this.quoteIdentifier(node.column.name)}`;
     // SQL Server uses JSON_VALUE(col, '$.path')
     return `JSON_VALUE(${col}, '${node.path}')`;
   }
 
+  /**
+   * Formats parameter placeholders using SQL Server named parameter syntax
+   * @param index - Parameter index
+   * @returns Named parameter placeholder
+   */
   protected formatPlaceholder(index: number): string {
     return `@p${index}`;
   }
 
+  /**
+   * Compiles SELECT query AST to SQL Server SQL
+   * @param ast - Query AST
+   * @param ctx - Compiler context
+   * @returns SQL Server SQL string
+   */
   protected compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string {
     const columns = ast.columns.map(c => {
       let expr = '';

package/src/dialect/mysql/index.ts

@@ -2,21 +2,43 @@ import { CompilerContext, Dialect } from '../abstract';
 import { SelectQueryNode } from '../../ast/query';
 import { JsonPathNode } from '../../ast/expression';
 
+/**
+ * MySQL dialect implementation
+ */
 export class MySqlDialect extends Dialect {
+  /**
+   * Creates a new MySqlDialect instance
+   */
   public constructor() {
     super();
   }
 
+  /**
+   * Quotes an identifier using MySQL backtick syntax
+   * @param id - Identifier to quote
+   * @returns Quoted identifier
+   */
   quoteIdentifier(id: string): string {
     return `\`${id}\``;
   }
 
+  /**
+   * Compiles JSON path expression using MySQL syntax
+   * @param node - JSON path node
+   * @returns MySQL JSON path expression
+   */
   protected compileJsonPath(node: JsonPathNode): string {
     const col = `${this.quoteIdentifier(node.column.table)}.${this.quoteIdentifier(node.column.name)}`;
     // MySQL 5.7+ uses col->'$.path'
     return `${col}->'${node.path}'`;
   }
 
+  /**
+   * Compiles SELECT query AST to MySQL SQL
+   * @param ast - Query AST
+   * @param ctx - Compiler context
+   * @returns MySQL SQL string
+   */
   protected compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string {
     const columns = ast.columns.map(c => {
       let expr = '';

package/src/dialect/postgres/index.ts

@@ -2,21 +2,43 @@ import { CompilerContext, Dialect } from '../abstract';
 import { SelectQueryNode } from '../../ast/query';
 import { JsonPathNode } from '../../ast/expression';
 
+/**
+ * PostgreSQL dialect implementation
+ */
 export class PostgresDialect extends Dialect {
+  /**
+   * Creates a new PostgresDialect instance
+   */
   public constructor() {
     super();
   }
 
+  /**
+   * Quotes an identifier using PostgreSQL double-quote syntax
+   * @param id - Identifier to quote
+   * @returns Quoted identifier
+   */
   quoteIdentifier(id: string): string {
     return `"${id}"`;
   }
 
+  /**
+   * Compiles JSON path expression using PostgreSQL syntax
+   * @param node - JSON path node
+   * @returns PostgreSQL JSON path expression
+   */
   protected compileJsonPath(node: JsonPathNode): string {
     const col = `${this.quoteIdentifier(node.column.table)}.${this.quoteIdentifier(node.column.name)}`;
     // Postgres uses col->>'path' for text extraction
     return `${col}->>'${node.path}'`;
   }
 
+  /**
+   * Compiles SELECT query AST to PostgreSQL SQL
+   * @param ast - Query AST
+   * @param ctx - Compiler context
+   * @returns PostgreSQL SQL string
+   */
   protected compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string {
     const columns = ast.columns.map(c => {
       let expr = '';

package/src/dialect/sqlite/index.ts

@@ -2,21 +2,43 @@ import { CompilerContext, Dialect } from '../abstract';
 import { SelectQueryNode } from '../../ast/query';
 import { JsonPathNode } from '../../ast/expression';
 
+/**
+ * SQLite dialect implementation
+ */
 export class SqliteDialect extends Dialect {
+  /**
+   * Creates a new SqliteDialect instance
+   */
   public constructor() {
     super();
   }
 
+  /**
+   * Quotes an identifier using SQLite double-quote syntax
+   * @param id - Identifier to quote
+   * @returns Quoted identifier
+   */
   quoteIdentifier(id: string): string {
     return `"${id}"`;
   }
 
+  /**
+   * Compiles JSON path expression using SQLite syntax
+   * @param node - JSON path node
+   * @returns SQLite JSON path expression
+   */
   protected compileJsonPath(node: JsonPathNode): string {
     const col = `${this.quoteIdentifier(node.column.table)}.${this.quoteIdentifier(node.column.name)}`;
     // SQLite uses json_extract(col, '$.path')
     return `json_extract(${col}, '${node.path}')`;
   }
 
+  /**
+   * Compiles SELECT query AST to SQLite SQL
+   * @param ast - Query AST
+   * @param ctx - Compiler context
+   * @returns SQLite SQL string
+   */
   protected compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string {
     const columns = ast.columns.map(c => {
       let expr = '';

package/src/runtime/als.ts

@@ -1,9 +1,19 @@
 // In a real Node environment: import { AsyncLocalStorage } from 'node:async_hooks';
 
-// Browser Shim
+/**
+ * Browser-compatible implementation of AsyncLocalStorage
+ * Provides a simple in-memory store for browser environments
+ * @typeParam T - Type of the stored data
+ */
 export class AsyncLocalStorage<T> {
   private store: T | undefined;
 
+  /**
+   * Executes a callback with the specified store value
+   * @param store - Value to store during callback execution
+   * @param callback - Function to execute with the store value
+   * @returns Result of the callback function
+   */
   run<R>(store: T, callback: () => R): R {
     this.store = store;
     try {
@@ -13,6 +23,10 @@ export class AsyncLocalStorage<T> {
     }
   }
 
+  /**
+   * Gets the currently stored value
+   * @returns Current store value or undefined if none exists
+   */
   getStore(): T | undefined {
     return this.store;
   }

package/src/runtime/hydration.ts

@@ -1,7 +1,12 @@
-import { HydrationPlan } from '../ast/query';
-
-const isRelationKey = (key: string) => key.includes('__');
-
+import { HydrationPlan } from '../ast/query';
+import { isRelationAlias, makeRelationAlias } from '../utils/relation-alias';
+
+/**
+ * Hydrates query results according to a hydration plan
+ * @param rows - Raw database rows
+ * @param plan - Hydration plan
+ * @returns Hydrated result objects with nested relations
+ */
 export const hydrateRows = (rows: Record<string, any>[], plan?: HydrationPlan): Record<string, any>[] => {
   if (!plan || !rows.length) return rows;
 
@@ -12,28 +17,28 @@ export const hydrateRows = (rows: Record<string, any>[], plan?: HydrationPlan):
     if (rootId === undefined) return;
 
     if (!rootMap.has(rootId)) {
-      const base: Record<string, any> = {};
-      const baseKeys = plan.rootColumns.length ? plan.rootColumns : Object.keys(row).filter(k => !isRelationKey(k));
-      baseKeys.forEach(key => { base[key] = row[key]; });
-      plan.relations.forEach(rel => { base[rel.name] = []; });
-      rootMap.set(rootId, base);
+      const base: Record<string, any> = {};
+      const baseKeys = plan.rootColumns.length ? plan.rootColumns : Object.keys(row).filter(k => !isRelationAlias(k));
+      baseKeys.forEach(key => { base[key] = row[key]; });
+      plan.relations.forEach(rel => { base[rel.name] = []; });
+      rootMap.set(rootId, base);
     }
 
     const parent = rootMap.get(rootId);
 
     plan.relations.forEach(rel => {
-      const childPkKey = `${rel.aliasPrefix}__${rel.targetPrimaryKey}`;
-      const childPk = row[childPkKey];
+      const childPkKey = makeRelationAlias(rel.aliasPrefix, rel.targetPrimaryKey);
+      const childPk = row[childPkKey];
       if (childPk === null || childPk === undefined) return;
 
       const bucket = parent[rel.name] as any[];
       if (bucket.some(item => item[rel.targetPrimaryKey] === childPk)) return;
 
       const child: Record<string, any> = {};
-      rel.columns.forEach(col => {
-        const key = `${rel.aliasPrefix}__${col}`;
-        child[col] = row[key];
-      });
+      rel.columns.forEach(col => {
+        const key = makeRelationAlias(rel.aliasPrefix, col);
+        child[col] = row[key];
+      });
 
       bucket.push(child);
     });

package/src/schema/column.ts

@@ -1,19 +1,59 @@
+/**
+ * Supported column data types for database schema definitions
+ */
 export type ColumnType = 'INT' | 'VARCHAR' | 'JSON' | 'ENUM' | 'BOOLEAN';
 
+/**
+ * Definition of a database column
+ */
 export interface ColumnDef {
-  name: string; // filled at runtime by defineTable
+  /** Column name (filled at runtime by defineTable) */
+  name: string;
+  /** Data type of the column */
   type: ColumnType;
+  /** Whether this column is a primary key */
   primary?: boolean;
+  /** Whether this column cannot be null */
   notNull?: boolean;
-  args?: any[]; // for varchar length etc
-  table?: string; // Filled at runtime by defineTable
+  /** Additional arguments for the column type (e.g., VARCHAR length) */
+  args?: any[];
+  /** Table name this column belongs to (filled at runtime by defineTable) */
+  table?: string;
 }
 
-// Column Factory
+/**
+ * Factory for creating column definitions with common data types
+ */
 export const col = {
+  /**
+   * Creates an integer column definition
+   * @returns ColumnDef with INT type
+   */
   int: (): ColumnDef => ({ name: '', type: 'INT' }),
+
+  /**
+   * Creates a variable character column definition
+   * @param length - Maximum length of the string
+   * @returns ColumnDef with VARCHAR type
+   */
   varchar: (length: number): ColumnDef => ({ name: '', type: 'VARCHAR', args: [length] }),
+
+  /**
+   * Creates a JSON column definition
+   * @returns ColumnDef with JSON type
+   */
   json: (): ColumnDef => ({ name: '', type: 'JSON' }),
+
+  /**
+   * Creates a boolean column definition
+   * @returns ColumnDef with BOOLEAN type
+   */
   boolean: (): ColumnDef => ({ name: '', type: 'BOOLEAN' }),
+
+  /**
+   * Marks a column definition as a primary key
+   * @param def - Column definition to modify
+   * @returns Modified ColumnDef with primary: true
+   */
   primaryKey: (def: ColumnDef): ColumnDef => ({ ...def, primary: true })
-};
+};

package/src/schema/relation.ts

@@ -1,28 +1,63 @@
 import { TableDef } from './table';
 
+/**
+ * Types of relationships supported between tables
+ */
 export const RelationKinds = {
+    /** One-to-many relationship */
     HasMany: 'HAS_MANY',
+    /** Many-to-one relationship */
     BelongsTo: 'BELONGS_TO',
 } as const;
 
+/**
+ * Type representing the supported relationship kinds
+ */
 export type RelationType = (typeof RelationKinds)[keyof typeof RelationKinds];
 
+/**
+ * Base properties common to all relationship types
+ */
 interface BaseRelation {
+    /** Target table of the relationship */
     target: TableDef;
-    foreignKey: string; // The column on the child table
-    localKey?: string;  // Usually 'id'
+    /** Foreign key column name on the child table */
+    foreignKey: string;
+    /** Local key column name (usually 'id') */
+    localKey?: string;
 }
 
+/**
+ * One-to-many relationship definition
+ */
 export interface HasManyRelation extends BaseRelation {
     type: typeof RelationKinds.HasMany;
 }
 
+/**
+ * Many-to-one relationship definition
+ */
 export interface BelongsToRelation extends BaseRelation {
     type: typeof RelationKinds.BelongsTo;
 }
 
+/**
+ * Union type representing any supported relationship definition
+ */
 export type RelationDef = HasManyRelation | BelongsToRelation;
 
+/**
+ * Creates a one-to-many relationship definition
+ * @param target - Target table of the relationship
+ * @param foreignKey - Foreign key column name on the child table
+ * @param localKey - Local key column name (defaults to 'id')
+ * @returns HasManyRelation definition
+ *
+ * @example
+ * ```typescript
+ * hasMany(usersTable, 'user_id')
+ * ```
+ */
 export const hasMany = (target: TableDef, foreignKey: string, localKey: string = 'id'): HasManyRelation => ({
     type: RelationKinds.HasMany,
     target,
@@ -30,6 +65,18 @@ export const hasMany = (target: TableDef, foreignKey: string, localKey: string =
     localKey,
 });
 
+/**
+ * Creates a many-to-one relationship definition
+ * @param target - Target table of the relationship
+ * @param foreignKey - Foreign key column name on the child table
+ * @param localKey - Local key column name (defaults to 'id')
+ * @returns BelongsToRelation definition
+ *
+ * @example
+ * ```typescript
+ * belongsTo(usersTable, 'user_id')
+ * ```
+ */
 export const belongsTo = (target: TableDef, foreignKey: string, localKey: string = 'id'): BelongsToRelation => ({
     type: RelationKinds.BelongsTo,
     target,

package/src/schema/table.ts

@@ -1,14 +1,38 @@
 import { ColumnDef } from './column';
 import { RelationDef } from './relation';
 
+/**
+ * Definition of a database table with its columns and relationships
+ * @typeParam T - Type of the columns record
+ */
 export interface TableDef<T extends Record<string, ColumnDef> = Record<string, ColumnDef>> {
+  /** Name of the table */
   name: string;
+  /** Record of column definitions keyed by column name */
   columns: T;
+  /** Record of relationship definitions keyed by relation name */
   relations: Record<string, RelationDef>;
 }
 
+/**
+ * Creates a table definition with columns and relationships
+ * @typeParam T - Type of the columns record
+ * @param name - Name of the table
+ * @param columns - Record of column definitions
+ * @param relations - Record of relationship definitions (optional)
+ * @returns Complete table definition with runtime-filled column metadata
+ *
+ * @example
+ * ```typescript
+ * const usersTable = defineTable('users', {
+ *   id: col.primaryKey(col.int()),
+ *   name: col.varchar(255),
+ *   email: col.varchar(255)
+ * });
+ * ```
+ */
 export const defineTable = <T extends Record<string, ColumnDef>>(
-    name: string, 
+    name: string,
     columns: T,
     relations: Record<string, RelationDef> = {}
 ): TableDef<T> => {
@@ -17,6 +41,6 @@ export const defineTable = <T extends Record<string, ColumnDef>>(
     (acc as any)[key] = { ...def, name: key, table: name };
     return acc;
   }, {} as T);
-  
+
   return { name, columns: colsWithNames, relations };
-};
+};

package/src/utils/join-node.ts

@@ -0,0 +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
+});