metal-orm 1.0.13 → 1.0.15

package/src/core/functions/numeric.ts

@@ -0,0 +1,179 @@
+// Pure AST Builders - No Dialect Logic Here!
+
+import { ColumnDef } from '../../schema/column.js';
+import { columnOperand, valueToOperand } from '../ast/expression-builders.js';
+import { FunctionNode, OperandNode, isOperandNode } from '../ast/expression.js';
+
+type OperandInput = OperandNode | ColumnDef | string | number | boolean | null;
+
+const isColumnDef = (val: any): val is ColumnDef => !!val && typeof val === 'object' && 'type' in val && 'name' in val;
+
+const toOperand = (input: OperandInput): OperandNode => {
+    if (isOperandNode(input)) return input;
+    if (isColumnDef(input)) return columnOperand(input);
+    return valueToOperand(input as any);
+};
+
+const fn = (key: string, args: OperandInput[]): FunctionNode => ({
+    type: 'Function',
+    name: key,
+    fn: key,
+    args: args.map(toOperand)
+});
+
+// ----------------------
+// Helper Functions
+// ----------------------
+
+/**
+ * Helper: ABS(x) - Returns the absolute value of a number
+ */
+export const abs = (value: OperandInput): FunctionNode => fn('ABS', [value]);
+
+/**
+ * Helper: ACOS(x) - Returns the arccosine (inverse cosine)
+ */
+export const acos = (value: OperandInput): FunctionNode => fn('ACOS', [value]);
+
+/**
+ * Helper: ASIN(x) - Returns the arcsine (inverse sine)
+ */
+export const asin = (value: OperandInput): FunctionNode => fn('ASIN', [value]);
+
+/**
+ * Helper: ATAN(x) - Returns the arctangent (inverse tangent)
+ */
+export const atan = (value: OperandInput): FunctionNode => fn('ATAN', [value]);
+
+/**
+ * Helper: ATAN2(y, x) - Returns the arctangent of the two arguments
+ */
+export const atan2 = (y: OperandInput, x: OperandInput): FunctionNode => fn('ATAN2', [y, x]);
+
+/**
+ * Helper: CEIL(x) / CEILING(x) - Returns the smallest integer >= x
+ */
+export const ceil = (value: OperandInput): FunctionNode => fn('CEIL', [value]);
+
+/**
+ * Helper: CEILING(x) - Alias for CEIL
+ */
+export const ceiling = (value: OperandInput): FunctionNode => fn('CEILING', [value]);
+
+/**
+ * Helper: COS(x) - Returns the cosine of a number (in radians)
+ */
+export const cos = (value: OperandInput): FunctionNode => fn('COS', [value]);
+
+/**
+ * Helper: COT(x) - Returns the cotangent of a number
+ */
+export const cot = (value: OperandInput): FunctionNode => fn('COT', [value]);
+
+/**
+ * Helper: DEGREES(x) - Converts radians to degrees
+ */
+export const degrees = (value: OperandInput): FunctionNode => fn('DEGREES', [value]);
+
+/**
+ * Helper: EXP(x) - Returns e raised to the power of the argument
+ */
+export const exp = (value: OperandInput): FunctionNode => fn('EXP', [value]);
+
+/**
+ * Helper: FLOOR(x) - Returns the largest integer <= x
+ */
+export const floor = (value: OperandInput): FunctionNode => fn('FLOOR', [value]);
+
+/**
+ * Helper: LN(x) - Returns the natural logarithm (base e)
+ */
+export const ln = (value: OperandInput): FunctionNode => fn('LN', [value]);
+
+/**
+ * Helper: LOG(x) - Returns the base-10 logarithm
+ */
+export const log = (value: OperandInput): FunctionNode => fn('LOG', [value]);
+
+/**
+ * Helper: LOG10(x) - Returns the base-10 logarithm
+ */
+export const log10 = (value: OperandInput): FunctionNode => fn('LOG10', [value]);
+
+/**
+ * Helper: LOG(base, x) - Returns the logarithm of x for a specific base
+ */
+export const logBase = (base: OperandInput, value: OperandInput): FunctionNode => fn('LOG_BASE', [base, value]);
+
+/**
+ * Helper: MOD(x, y) - Returns the remainder of x/y
+ */
+export const mod = (x: OperandInput, y: OperandInput): FunctionNode => fn('MOD', [x, y]);
+
+/**
+ * Helper: PI() - Returns the value of PI (approx. 3.14159...)
+ */
+export const pi = (): FunctionNode => fn('PI', []);
+
+/**
+ * Helper: POWER(x, y) - Returns x raised to the power of y
+ */
+export const power = (x: OperandInput, y: OperandInput): FunctionNode => fn('POWER', [x, y]);
+
+/**
+ * Helper: POW(x, y) - Alias for POWER
+ */
+export const pow = (x: OperandInput, y: OperandInput): FunctionNode => fn('POW', [x, y]);
+
+/**
+ * Helper: RADIANS(x) - Converts degrees to radians
+ */
+export const radians = (value: OperandInput): FunctionNode => fn('RADIANS', [value]);
+
+/**
+ * Helper: RAND() / RANDOM() - Returns a random number
+ */
+export const random = (): FunctionNode => fn('RANDOM', []);
+
+/**
+ * Helper: RAND() - Alias for RANDOM (returns float 0-1)
+ */
+export const rand = (): FunctionNode => fn('RAND', []);
+
+/**
+ * Helper: ROUND(x[, decimals]) - Rounds a number to specified decimal places
+ */
+export const round = (value: OperandInput, decimals?: OperandInput): FunctionNode =>
+    decimals === undefined ? fn('ROUND', [value]) : fn('ROUND', [value, decimals]);
+
+/**
+ * Helper: SIGN(x) - Returns the sign of a number (-1, 0, 1)
+ */
+export const sign = (value: OperandInput): FunctionNode => fn('SIGN', [value]);
+
+/**
+ * Helper: SIN(x) - Returns the sine of a number (in radians)
+ */
+export const sin = (value: OperandInput): FunctionNode => fn('SIN', [value]);
+
+/**
+ * Helper: SQRT(x) - Returns the square root of a number
+ */
+export const sqrt = (value: OperandInput): FunctionNode => fn('SQRT', [value]);
+
+/**
+ * Helper: TAN(x) - Returns the tangent of a number (in radians)
+ */
+export const tan = (value: OperandInput): FunctionNode => fn('TAN', [value]);
+
+/**
+ * Helper: TRUNC(x[, decimals]) / TRUNCATE(x, decimals) - Truncates a number without rounding
+ */
+export const trunc = (value: OperandInput, decimals?: OperandInput): FunctionNode =>
+    decimals === undefined ? fn('TRUNC', [value]) : fn('TRUNC', [value, decimals]);
+
+/**
+ * Helper: TRUNCATE(x, decimals) - Alias for TRUNC
+ */
+export const truncate = (value: OperandInput, decimals: OperandInput): FunctionNode =>
+    fn('TRUNCATE', [value, decimals]);

package/src/core/functions/standard-strategy.ts

@@ -0,0 +1,47 @@
+import { FunctionStrategy, FunctionRenderer, FunctionRenderContext } from './types.js';
+
+export class StandardFunctionStrategy implements FunctionStrategy {
+    protected renderers: Map<string, FunctionRenderer> = new Map();
+
+    constructor() {
+        this.registerStandard();
+    }
+
+    protected registerStandard() {
+        // Register ANSI standard implementations
+        this.add('ABS', ({ compiledArgs }) => `ABS(${compiledArgs[0]})`);
+        this.add('UPPER', ({ compiledArgs }) => `UPPER(${compiledArgs[0]})`);
+        this.add('LOWER', ({ compiledArgs }) => `LOWER(${compiledArgs[0]})`);
+        this.add('LENGTH', ({ compiledArgs }) => `LENGTH(${compiledArgs[0]})`);
+        this.add('TRIM', ({ compiledArgs }) => `TRIM(${compiledArgs[0]})`);
+        this.add('LTRIM', ({ compiledArgs }) => `LTRIM(${compiledArgs[0]})`);
+        this.add('RTRIM', ({ compiledArgs }) => `RTRIM(${compiledArgs[0]})`);
+        this.add('SUBSTRING', ({ compiledArgs }) => `SUBSTRING(${compiledArgs.join(', ')})`);
+        this.add('CONCAT', ({ compiledArgs }) => `CONCAT(${compiledArgs.join(', ')})`);
+        this.add('NOW', () => `NOW()`);
+        this.add('CURRENT_DATE', () => `CURRENT_DATE`);
+        this.add('CURRENT_TIME', () => `CURRENT_TIME`);
+        this.add('EXTRACT', ({ compiledArgs }) => `EXTRACT(${compiledArgs[0]} FROM ${compiledArgs[1]})`);
+        this.add('YEAR', ({ compiledArgs }) => `EXTRACT(YEAR FROM ${compiledArgs[0]})`);
+        this.add('MONTH', ({ compiledArgs }) => `EXTRACT(MONTH FROM ${compiledArgs[0]})`);
+        this.add('DAY', ({ compiledArgs }) => `EXTRACT(DAY FROM ${compiledArgs[0]})`);
+        this.add('DATE_ADD', ({ compiledArgs }) => `(${compiledArgs[0]} + INTERVAL ${compiledArgs[1]} ${compiledArgs[2]})`);
+        this.add('DATE_SUB', ({ compiledArgs }) => `(${compiledArgs[0]} - INTERVAL ${compiledArgs[1]} ${compiledArgs[2]})`);
+        this.add('DATE_DIFF', ({ compiledArgs }) => `DATEDIFF(${compiledArgs[0]}, ${compiledArgs[1]})`);
+        this.add('DATE_FORMAT', ({ compiledArgs }) => `DATE_FORMAT(${compiledArgs[0]}, ${compiledArgs[1]})`);
+        this.add('UNIX_TIMESTAMP', () => `UNIX_TIMESTAMP()`);
+        this.add('FROM_UNIXTIME', ({ compiledArgs }) => `FROM_UNIXTIME(${compiledArgs[0]})`);
+        this.add('END_OF_MONTH', ({ compiledArgs }) => `LAST_DAY(${compiledArgs[0]})`);
+        this.add('DAY_OF_WEEK', ({ compiledArgs }) => `DAYOFWEEK(${compiledArgs[0]})`);
+        this.add('WEEK_OF_YEAR', ({ compiledArgs }) => `WEEKOFYEAR(${compiledArgs[0]})`);
+        this.add('DATE_TRUNC', ({ compiledArgs }) => `DATE_TRUNC(${compiledArgs[0]}, ${compiledArgs[1]})`);
+    }
+
+    protected add(name: string, renderer: FunctionRenderer) {
+        this.renderers.set(name, renderer);
+    }
+
+    getRenderer(name: string): FunctionRenderer | undefined {
+        return this.renderers.get(name);
+    }
+}

package/src/core/functions/text.ts

@@ -0,0 +1,147 @@
+// Pure AST Builders - No Dialect Logic Here!
+
+import { ColumnDef } from '../../schema/column.js';
+import { columnOperand, valueToOperand } from '../ast/expression-builders.js';
+import { FunctionNode, OperandNode, isOperandNode } from '../ast/expression.js';
+
+type OperandInput = OperandNode | ColumnDef | string | number | boolean | null;
+
+const isColumnDef = (val: any): val is ColumnDef => !!val && typeof val === 'object' && 'type' in val && 'name' in val;
+
+const toOperand = (input: OperandInput): OperandNode => {
+  if (isOperandNode(input)) return input;
+  if (isColumnDef(input)) return columnOperand(input);
+  return valueToOperand(input as any);
+};
+
+const fn = (key: string, args: OperandInput[]): FunctionNode => ({
+  type: 'Function',
+  name: key,
+  fn: key,
+  args: args.map(toOperand)
+});
+
+/**
+ * Helper: LOWER(str)
+ */
+export const lower = (value: OperandInput): FunctionNode => fn('LOWER', [value]);
+
+/**
+ * Helper: UPPER(str)
+ */
+export const upper = (value: OperandInput): FunctionNode => fn('UPPER', [value]);
+
+/**
+ * Helper: ASCII(str)
+ */
+export const ascii = (value: OperandInput): FunctionNode => fn('ASCII', [value]);
+
+/**
+ * Helper: CHAR(code[, code...])
+ */
+export const char = (...codes: OperandInput[]): FunctionNode => {
+  if (codes.length === 0) throw new Error('char() expects at least 1 argument');
+  return fn('CHAR', codes);
+};
+
+/**
+ * Helper: CHAR_LENGTH(str)
+ */
+export const charLength = (value: OperandInput): FunctionNode => fn('CHAR_LENGTH', [value]);
+
+/**
+ * Helper: LENGTH(str)
+ */
+export const length = (value: OperandInput): FunctionNode => fn('LENGTH', [value]);
+
+/**
+ * Helper: TRIM([chars FROM] str)
+ */
+export const trim = (value: OperandInput, chars?: OperandInput): FunctionNode =>
+  chars === undefined ? fn('TRIM', [value]) : fn('TRIM', [value, chars]);
+
+/**
+ * Helper: LTRIM(str)
+ */
+export const ltrim = (value: OperandInput): FunctionNode => fn('LTRIM', [value]);
+
+/**
+ * Helper: RTRIM(str)
+ */
+export const rtrim = (value: OperandInput): FunctionNode => fn('RTRIM', [value]);
+
+/**
+ * Helper: CONCAT(arg1, arg2, ...)
+ */
+export const concat = (...args: OperandInput[]): FunctionNode => {
+  if (args.length < 2) throw new Error('concat() expects at least 2 arguments');
+  return fn('CONCAT', args);
+};
+
+/**
+ * Helper: CONCAT_WS(separator, arg1, arg2, ...)
+ */
+export const concatWs = (separator: OperandInput, ...args: OperandInput[]): FunctionNode => {
+  if (args.length < 1) throw new Error('concatWs() expects at least 2 arguments including the separator');
+  return fn('CONCAT_WS', [separator, ...args]);
+};
+
+/**
+ * Helper: SUBSTR(str, start[, length])
+ */
+export const substr = (value: OperandInput, start: OperandInput, length?: OperandInput): FunctionNode =>
+  length === undefined ? fn('SUBSTR', [value, start]) : fn('SUBSTR', [value, start, length]);
+
+/**
+ * Helper: LEFT(str, length)
+ */
+export const left = (value: OperandInput, len: OperandInput): FunctionNode => fn('LEFT', [value, len]);
+
+/**
+ * Helper: RIGHT(str, length)
+ */
+export const right = (value: OperandInput, len: OperandInput): FunctionNode => fn('RIGHT', [value, len]);
+
+/**
+ * Helper: POSITION(substring IN string)
+ */
+export const position = (substring: OperandInput, value: OperandInput): FunctionNode => fn('POSITION', [substring, value]);
+
+/**
+ * Helper: INSTR(string, substring)
+ */
+export const instr = (value: OperandInput, substring: OperandInput): FunctionNode => fn('INSTR', [value, substring]);
+
+/**
+ * Helper: LOCATE(substring, string[, start])
+ */
+export const locate = (substring: OperandInput, value: OperandInput, start?: OperandInput): FunctionNode =>
+  start === undefined ? fn('LOCATE', [substring, value]) : fn('LOCATE', [substring, value, start]);
+
+/**
+ * Helper: REPLACE(string, search, replace)
+ */
+export const replace = (value: OperandInput, search: OperandInput, replacement: OperandInput): FunctionNode =>
+  fn('REPLACE', [value, search, replacement]);
+
+/**
+ * Helper: REPEAT(string, count)
+ */
+export const repeat = (value: OperandInput, count: OperandInput): FunctionNode => fn('REPEAT', [value, count]);
+
+/**
+ * Helper: LPAD(string, length, padstr)
+ */
+export const lpad = (value: OperandInput, len: OperandInput, pad: OperandInput): FunctionNode =>
+  fn('LPAD', [value, len, pad]);
+
+/**
+ * Helper: RPAD(string, length, padstr)
+ */
+export const rpad = (value: OperandInput, len: OperandInput, pad: OperandInput): FunctionNode =>
+  fn('RPAD', [value, len, pad]);
+
+/**
+ * Helper: SPACE(count)
+ */
+export const space = (count: OperandInput): FunctionNode => fn('SPACE', [count]);

package/src/core/functions/types.ts

@@ -0,0 +1,18 @@
+import { FunctionNode } from '../ast/expression.js';
+
+export interface FunctionRenderContext {
+    node: FunctionNode;
+    compiledArgs: string[];
+    // Helper to allow dialects to call back into the compiler if needed
+    // compileOperand: (node: OperandNode) => string;
+}
+
+export type FunctionRenderer = (ctx: FunctionRenderContext) => string;
+
+export interface FunctionStrategy {
+    /**
+     * Returns a renderer for a specific function name (e.g. "DATE_ADD").
+     * Returns undefined if this dialect doesn't support the function.
+     */
+    getRenderer(functionName: string): FunctionRenderer | undefined;
+}

package/src/core/hydration/types.ts

@@ -0,0 +1,57 @@
+import { RelationType } from '../../schema/relation.js';
+
+/**
+ * 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
+ */
+export interface HydrationPlan {
+  /** Root table name */
+  rootTable: string;
+  /** Root table primary key */
+  rootPrimaryKey: string;
+  /** Root table columns */
+  rootColumns: string[];
+  /** Relationship hydration plans */
+  relations: HydrationRelationPlan[];
+}
+
+/**
+ * Metadata bag for attaching hydration to query ASTs without coupling AST types.
+ */
+export interface HydrationMetadata {
+  hydration?: HydrationPlan;
+  [key: string]: unknown;
+}

package/src/decorators/bootstrap.ts

@@ -1,6 +1,7 @@
 import { SelectQueryBuilder } from '../query-builder/select.js';
 import {
   hasMany,
+  hasOne,
   belongsTo,
   belongsToMany,
   RelationKinds,
@@ -51,6 +52,15 @@ const buildRelationDefinitions = (
 
   for (const [name, relation] of Object.entries(meta.relations)) {
     switch (relation.kind) {
+      case RelationKinds.HasOne: {
+        relations[name] = hasOne(
+          resolveTableTarget(relation.target, tableMap),
+          relation.foreignKey,
+          relation.localKey,
+          relation.cascade
+        );
+        break;
+      }
       case RelationKinds.HasMany: {
         relations[name] = hasMany(
           resolveTableTarget(relation.target, tableMap),

package/src/decorators/relations.ts

@@ -16,6 +16,10 @@ export interface HasManyOptions extends BaseRelationOptions {
   foreignKey: string;
 }
 
+export interface HasOneOptions extends BaseRelationOptions {
+  foreignKey: string;
+}
+
 export interface BelongsToOptions extends BaseRelationOptions {
   foreignKey: string;
 }
@@ -79,6 +83,17 @@ export function HasMany(options: HasManyOptions) {
   }));
 }
 
+export function HasOne(options: HasOneOptions) {
+  return createFieldDecorator(propertyName => ({
+    kind: RelationKinds.HasOne,
+    propertyKey: propertyName,
+    target: options.target,
+    foreignKey: options.foreignKey,
+    localKey: options.localKey,
+    cascade: options.cascade
+  }));
+}
+
 export function BelongsTo(options: BelongsToOptions) {
   return createFieldDecorator(propertyName => ({
     kind: RelationKinds.BelongsTo,

package/src/index.ts

@@ -1,28 +1,39 @@
-
 export * from './schema/table.js';
 export * from './schema/column.js';
 export * from './schema/relation.js';
 export * from './schema/types.js';
-export * from './query-builder/select.js';
-export * from './query-builder/insert.js';
-export * from './query-builder/update.js';
-export * from './query-builder/delete.js';
-export * from './core/ast/expression.js';
-export * from './core/dialect/mysql/index.js';
-export * from './core/dialect/mssql/index.js';
-export * from './core/dialect/sqlite/index.js';
-export * from './core/dialect/postgres/index.js';
-export * from './core/ddl/schema-generator.js';
-export * from './core/ddl/schema-types.js';
-export * from './core/ddl/schema-diff.js';
-export * from './core/ddl/schema-introspect.js';
-export * from './orm/als.js';
-export * from './orm/hydration.js';
-export * from './codegen/typescript.js';
-export * from './orm/orm-context.js';
-export * from './orm/entity.js';
+export * from './query-builder/select.js';
+export * from './query-builder/insert.js';
+export * from './query-builder/update.js';
+export * from './query-builder/delete.js';
+export * from './core/ast/expression.js';
+export * from './core/hydration/types.js';
+export * from './core/dialect/mysql/index.js';
+export * from './core/dialect/mssql/index.js';
+export * from './core/dialect/sqlite/index.js';
+export * from './core/dialect/postgres/index.js';
+export * from './core/ddl/schema-generator.js';
+export * from './core/ddl/schema-types.js';
+export * from './core/ddl/schema-diff.js';
+export * from './core/ddl/schema-introspect.js';
+export * from './core/ddl/introspect/registry.js';
+export * from './core/functions/text.js';
+export * from './core/functions/numeric.js';
+export * from './core/functions/datetime.js';
+export * from './orm/als.js';
+export * from './orm/hydration.js';
+export * from './codegen/typescript.js';
+export * from './orm/orm-context.js';
+export * from './orm/entity.js';
 export * from './orm/lazy-batch.js';
 export * from './orm/relations/has-many.js';
 export * from './orm/relations/belongs-to.js';
 export * from './orm/relations/many-to-many.js';
 export * from './orm/execute.js';
+
+// NEW: execution abstraction + helpers
+export * from './core/execution/db-executor.js';
+export * from './core/execution/executors/postgres-executor.js';
+export * from './core/execution/executors/mysql-executor.js';
+export * from './core/execution/executors/sqlite-executor.js';
+export * from './core/execution/executors/mssql-executor.js';

package/src/orm/entity-metadata.ts

@@ -25,6 +25,12 @@ export interface HasManyRelationMetadata extends BaseRelationMetadata {
   localKey?: string;
 }
 
+export interface HasOneRelationMetadata extends BaseRelationMetadata {
+  kind: typeof RelationKinds.HasOne;
+  foreignKey: string;
+  localKey?: string;
+}
+
 export interface BelongsToRelationMetadata extends BaseRelationMetadata {
   kind: typeof RelationKinds.BelongsTo;
   foreignKey: string;
@@ -44,6 +50,7 @@ export interface BelongsToManyRelationMetadata extends BaseRelationMetadata {
 
 export type RelationMetadata =
   | HasManyRelationMetadata
+  | HasOneRelationMetadata
   | BelongsToRelationMetadata
   | BelongsToManyRelationMetadata;