ts-prorm-orm 1.1.0 → 1.2.0

package/dist/query-builders/include-builder.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Include builder for the ORM
+ * Handles JOIN clauses for model associations
+ */
+import { IncludeOptions } from '../types';
+/**
+ * Result of building JOIN clauses: the combined SQL fragment and its bound values
+ */
+export interface IncludeResult {
+    sql: string;
+    values: unknown[];
+}
+/**
+ * Options controlling how an IncludeBuilder generates JOINs
+ */
+export interface IncludeBuilderOptions {
+    replacements?: Record<string, unknown>;
+    model?: unknown;
+    dialect?: {
+        escape: (value: unknown) => string;
+        escapeId: (identifier: string) => string;
+    };
+    parentAlias?: string;
+    parentKey?: string;
+    childKey?: string;
+    /** Default schema delimiter */
+    schemaDelimiter?: string;
+}
+/**
+ * IncludeBuilder class for building JOIN clauses
+ */
+export declare class IncludeBuilder {
+    private options;
+    private whereBuilder;
+    /**
+     * Creates a nested WhereBuilder (sharing replacements/model/dialect) used to
+     * render `on`, `where`, and `lateralSubquery.where` clauses on included tables
+     */
+    constructor(options?: IncludeBuilderOptions);
+    /**
+     * Build JOIN clauses from include options
+     */
+    build(includes: IncludeOptions[]): IncludeResult;
+    /**
+     * Build a single include (can handle nested includes)
+     */
+    private buildInclude;
+    /**
+     * Build a through-table join for many-to-many associations
+     */
+    private buildThroughJoin;
+    /**
+     * Get the join type based on include options
+     */
+    private getJoinType;
+    /**
+     * Build the ON clause for a join
+     */
+    private buildOnClause;
+    /**
+     * Build ON clause from WhereOptions
+     */
+    private buildOnFromWhere;
+    /**
+     * Guess the foreign key name for an association
+     */
+    private guessForeignKey;
+    /**
+     * Get the primary key of a model
+     */
+    private getPrimaryKey;
+    /**
+     * Escape an identifier
+     */
+    private escapeId;
+}
+/**
+ * Create an IncludeBuilder instance
+ */
+export declare function createIncludeBuilder(options?: IncludeBuilderOptions): IncludeBuilder;
+/**
+ * Quick helper to build include JOINs
+ */
+export declare function buildIncludes(includes: IncludeOptions[], options?: IncludeBuilderOptions): IncludeResult;
+export default IncludeBuilder;

package/dist/query-builders/index-expression-builder.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Index Expression Builder
+ * Provides ORM-like way to create functional indexes
+ */
+/**
+ * Supported SQL functions for index expressions
+ */
+export type IndexFunction = 'LOWER' | 'UPPER' | 'TRIM' | 'LTRIM' | 'RTRIM' | 'SUBSTRING' | 'SUBSTR' | 'LENGTH' | 'CONCAT' | 'COALESCE' | 'NULLIF' | 'ABS' | 'CEIL' | 'FLOOR' | 'ROUND' | 'SQRT' | 'POWER' | 'MOD' | 'NOW' | 'CURRENT_DATE' | 'CURRENT_TIME' | 'CURRENT_TIMESTAMP' | 'DATE' | 'TIME' | 'YEAR' | 'MONTH' | 'DAY' | 'HOUR' | 'MINUTE' | 'SECOND' | 'EXTRACT' | 'TO_CHAR' | 'TO_DATE' | 'TO_TIMESTAMP' | 'JSON_EXTRACT' | 'JSONB_EXTRACT' | 'CAST' | 'CONVERT';
+/**
+ * Expression type definitions
+ */
+export interface ColumnRef {
+    __type: 'column';
+    model?: string;
+    column: string;
+}
+export interface FunctionCall {
+    __type: 'function';
+    name: IndexFunction | string;
+    args: ExpressionArg[];
+}
+export interface LiteralValue {
+    __type: 'literal';
+    value: any;
+    type?: 'string' | 'number' | 'boolean' | 'date';
+}
+/** Union type for function arguments */
+export type ExpressionArg = string | ColumnRef | LiteralValue;
+/** Union type for all expression parts */
+export type ExpressionPart = ColumnRef | FunctionCall | LiteralValue;
+/**
+ * Index column definition with optional expression
+ */
+export interface IndexColumn {
+    /** Column name */
+    name: string;
+    /** Optional expression for functional index */
+    expression?: ExpressionPart;
+    /** Optional length for prefix index */
+    length?: number;
+    /** Sort order */
+    order?: 'ASC' | 'DESC';
+}
+/**
+ * Index options
+ */
+export interface IndexBuilderOptions {
+    /** Index name */
+    name?: string;
+    /** Index type: BTREE, HASH, GIN, GiST, BRIN, etc. */
+    type?: string;
+    /** Unique index */
+    unique?: boolean;
+    /** Index if not exists */
+    ifNotExists?: boolean;
+    /** Partial index WHERE clause */
+    where?: WhereCondition;
+    /** NULLS FIRST/LAST (PostgreSQL) */
+    nullsFirst?: boolean;
+}
+/**
+ * Simple WHERE condition for partial indexes
+ */
+export interface WhereCondition {
+    field: string;
+    operator: '=' | '>' | '<' | '>=' | '<=' | '!=' | '<>' | 'IS NULL' | 'IS NOT NULL' | 'IN' | 'LIKE' | 'BETWEEN';
+    value: any;
+}
+/**
+ * Builder for index expressions
+ */
+export declare class IndexExpressionBuilder {
+    private columns;
+    /**
+     * Add a simple column to the index
+     */
+    column(name: string, opts?: {
+        length?: number;
+        order?: 'ASC' | 'DESC';
+    }): IndexExpressionBuilder;
+    /**
+     * Add a functional index using a column reference
+     */
+    functional(column: string, opts?: {
+        model?: string | {
+            tableName?: string;
+            name?: string;
+        };
+        length?: number;
+        order?: 'ASC' | 'DESC';
+    }): IndexExpressionBuilder;
+    /**
+     * Add LOWER(column) expression
+     */
+    lower(column: string, opts?: {
+        order?: 'ASC' | 'DESC';
+    }): IndexExpressionBuilder;
+    /**
+     * Add UPPER(column) expression
+     */
+    upper(column: string, opts?: {
+        order?: 'ASC' | 'DESC';
+    }): IndexExpressionBuilder;
+    /**
+     * Add LENGTH(column) expression
+     */
+    length(column: string, opts?: {
+        order?: 'ASC' | 'DESC';
+    }): IndexExpressionBuilder;
+    /**
+     * Add SUBSTRING(column FROM start FOR length) expression
+     */
+    substring(column: string, start: number, length?: number, opts?: {
+        order?: 'ASC' | 'DESC';
+    }): IndexExpressionBuilder;
+    /**
+     * Add a custom function expression
+     */
+    fn(name: IndexFunction | string, args: ExpressionArg[], alias?: string): IndexExpressionBuilder;
+    /**
+     * Add COALESCE expression for handling NULLs
+     */
+    coalesce(column: string, defaultValue: any): IndexExpressionBuilder;
+    /**
+     * Add CAST expression
+     */
+    cast(column: string, asType: string): IndexExpressionBuilder;
+    /**
+     * Add JSON extract expression (PostgreSQL)
+     */
+    jsonExtract(column: string, path: string): IndexExpressionBuilder;
+    /**
+     * Get all index columns
+     */
+    getColumns(): IndexColumn[];
+    /**
+     * Build the index column expressions
+     */
+    toSQL(dialect: any): string;
+    /**
+     * Reset the builder
+     */
+    reset(): void;
+}
+/**
+ * Create a new index expression builder
+ */
+export declare function createIndexBuilder(): IndexExpressionBuilder;
+declare const _default: {
+    IndexExpressionBuilder: typeof IndexExpressionBuilder;
+    createIndexBuilder: typeof createIndexBuilder;
+};
+export default _default;

package/dist/query-builders/index.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Query Builders
+ * Exports all query builder classes and utilities
+ */
+export { getTableName, getModelName, isModel } from './model-helpers';
+export { SqlCompiler, SqlCompilerOptions } from './sql-compiler';
+export { CTEBuilder, CTEDefinition, RecursiveCTEOptions, createCTEBuilder } from './cte-builder';
+export { SubqueryBuilder, SubqueryOptions, ExistsSubqueryOptions, ScalarSubqueryOptions, } from './subquery-builder';
+export { ViewBuilder, ViewOptions, MaterializedViewOptions, createViewBuilder, } from './view-builder';
+export { IndexExpressionBuilder, IndexColumn, IndexBuilderOptions, IndexFunction, createIndexBuilder, } from './index-expression-builder';
+/** @deprecated Not used by any query path; each dialect builds its own WHERE clause. */
+export { WhereBuilder, WhereClauseResult, WhereBuilderOptions, createWhereBuilder, buildWhereClause, } from './where-builder';
+/** @deprecated Eager loading goes through `src/models/eager-load.ts`, not this builder. */
+export { IncludeBuilder, IncludeResult, IncludeBuilderOptions, createIncludeBuilder, buildIncludes, } from './include-builder';
+export { OrderBuilder, LimitOffsetBuilder, OrderLimitBuilder, OrderClauseResult, OrderLimitOptions, createOrderBuilder, createOrderLimitBuilder, buildOrder, buildLimitOffset, } from './order-limit-builder';
+export { InsertBuilder, InsertQueryResult, InsertBuilderOptions, createInsertBuilder, buildInsertQuery, buildBulkInsertQuery, } from './insert-builder';
+/** @deprecated Not used by `Model.update()`; each dialect builds its own UPDATE. */
+export { UpdateBuilder, UpdateQueryResult, UpdateBuilderOptions, createUpdateBuilder, buildUpdateQuery, buildUpdateWithOperations, } from './update-builder';
+/**
+ * Query Builder Factory
+ * Creates query builders with common configuration
+ */
+export interface QueryBuilderFactoryOptions {
+    /**
+     * Database dialect
+     */
+    dialect?: 'mysql' | 'postgres' | 'sqlite' | 'mssql' | 'mariadb';
+    /**
+     * Table name prefix
+     */
+    tablePrefix?: string;
+    /**
+     * Database schema
+     */
+    schema?: string;
+    /**
+     * Use parameterized queries
+     */
+    parameterized?: boolean;
+    /**
+     * Parameter character
+     */
+    paramChar?: string;
+}
+/**
+ * Create a query builder with the given options
+ */
+export declare function createQueryBuilder(options?: QueryBuilderFactoryOptions): {
+    sqlCompiler: any;
+};
+/**
+ * Quick query helper for simple queries
+ */
+export declare function createQuickQuery(dialect?: string): {
+    /**
+     * Build a simple SELECT query
+     */
+    select: (table: string, where?: any) => any;
+    /**
+     * Build a simple INSERT query
+     */
+    insert: (table: string, values: Record<string, any>) => any;
+    /**
+     * Build a simple UPDATE query
+     */
+    update: (table: string, values: Record<string, any>, where: any) => any;
+    /**
+     * Build a simple DELETE query
+     */
+    delete: (table: string, where: any) => any;
+    /**
+     * Build a WHERE clause
+     */
+    where: (conditions: any) => any;
+    /**
+     * Build an ORDER BY clause
+     */
+    order: (order: any) => any;
+    /**
+     * Build a LIMIT/OFFSET clause
+     */
+    limitOffset: (limit?: number | string, offset?: number | string) => any;
+};
+/**
+ * Get or create the default query builder
+ */
+export declare function getDefaultQueryBuilder(): {
+    /**
+     * Build a simple SELECT query
+     */
+    select: (table: string, where?: any) => any;
+    /**
+     * Build a simple INSERT query
+     */
+    insert: (table: string, values: Record<string, any>) => any;
+    /**
+     * Build a simple UPDATE query
+     */
+    update: (table: string, values: Record<string, any>, where: any) => any;
+    /**
+     * Build a simple DELETE query
+     */
+    delete: (table: string, where: any) => any;
+    /**
+     * Build a WHERE clause
+     */
+    where: (conditions: any) => any;
+    /**
+     * Build an ORDER BY clause
+     */
+    order: (order: any) => any;
+    /**
+     * Build a LIMIT/OFFSET clause
+     */
+    limitOffset: (limit?: number | string, offset?: number | string) => any;
+};
+/**
+ * Set the default query builder
+ */
+export declare function setDefaultQueryBuilder(builder: ReturnType<typeof createQuickQuery>): void;
+export { SqlCompiler as SqlCompilerDefault } from './sql-compiler';

package/dist/query-builders/index.js

@@ -33,10 +33,19 @@ var index_expression_builder_1 = require("./index-expression-builder");
 Object.defineProperty(exports, "IndexExpressionBuilder", { enumerable: true, get: function () { return index_expression_builder_1.IndexExpressionBuilder; } });
 Object.defineProperty(exports, "createIndexBuilder", { enumerable: true, get: function () { return index_expression_builder_1.createIndexBuilder; } });
 // Export modular query builders
+//
+// NOTE: `WhereBuilder`, `IncludeBuilder` and `UpdateBuilder` below are NOT on
+// any runtime query path. Every dialect implements its own `buildWhereClause`,
+// and eager loading goes through `src/models/eager-load.ts`. These are kept for
+// callers that construct SQL fragments directly, but changing them has no
+// effect on `findAll`/`update`/`include` behaviour - see
+// `src/models/COVERAGE-AUDIT.md`. Prefer the model APIs.
+/** @deprecated Not used by any query path; each dialect builds its own WHERE clause. */
 var where_builder_1 = require("./where-builder");
 Object.defineProperty(exports, "WhereBuilder", { enumerable: true, get: function () { return where_builder_1.WhereBuilder; } });
 Object.defineProperty(exports, "createWhereBuilder", { enumerable: true, get: function () { return where_builder_1.createWhereBuilder; } });
 Object.defineProperty(exports, "buildWhereClause", { enumerable: true, get: function () { return where_builder_1.buildWhereClause; } });
+/** @deprecated Eager loading goes through `src/models/eager-load.ts`, not this builder. */
 var include_builder_1 = require("./include-builder");
 Object.defineProperty(exports, "IncludeBuilder", { enumerable: true, get: function () { return include_builder_1.IncludeBuilder; } });
 Object.defineProperty(exports, "createIncludeBuilder", { enumerable: true, get: function () { return include_builder_1.createIncludeBuilder; } });
@@ -54,6 +63,7 @@ Object.defineProperty(exports, "InsertBuilder", { enumerable: true, get: functio
 Object.defineProperty(exports, "createInsertBuilder", { enumerable: true, get: function () { return insert_builder_1.createInsertBuilder; } });
 Object.defineProperty(exports, "buildInsertQuery", { enumerable: true, get: function () { return insert_builder_1.buildInsertQuery; } });
 Object.defineProperty(exports, "buildBulkInsertQuery", { enumerable: true, get: function () { return insert_builder_1.buildBulkInsertQuery; } });
+/** @deprecated Not used by `Model.update()`; each dialect builds its own UPDATE. */
 var update_builder_1 = require("./update-builder");
 Object.defineProperty(exports, "UpdateBuilder", { enumerable: true, get: function () { return update_builder_1.UpdateBuilder; } });
 Object.defineProperty(exports, "createUpdateBuilder", { enumerable: true, get: function () { return update_builder_1.createUpdateBuilder; } });

package/dist/query-builders/insert-builder.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Insert query builder for the ORM
+ * Handles INSERT queries including bulk inserts and upserts
+ */
+export interface InsertQueryResult {
+    sql: string;
+    values: unknown[];
+    generatedIds?: unknown[];
+}
+export interface InsertBuilderOptions {
+    returning?: boolean | string[];
+    upsert?: boolean;
+    conflictFields?: string[];
+    dialect?: {
+        escape: (value: unknown) => string;
+        escapeId: (identifier: string) => string;
+    };
+}
+/**
+ * InsertBuilder class for building INSERT queries
+ */
+export declare class InsertBuilder {
+    private options;
+    constructor(options?: InsertBuilderOptions);
+    /**
+     * Build an INSERT query for a single record
+     */
+    build(tableName: string, values: Record<string, unknown>): InsertQueryResult;
+    /**
+     * Build a bulk INSERT query
+     */
+    buildBulk(tableName: string, records: Record<string, unknown>[]): InsertQueryResult;
+    /**
+     * Build an upsert (INSERT ... ON CONFLICT) query
+     */
+    private buildUpsert;
+    /**
+     * Build a bulk upsert query
+     */
+    private buildBulkUpsert;
+    /**
+     * Build the RETURNING clause
+     */
+    private buildReturningClause;
+    /**
+     * Escape an identifier
+     */
+    private escapeId;
+}
+/**
+ * Create an InsertBuilder instance
+ */
+export declare function createInsertBuilder(options?: InsertBuilderOptions): InsertBuilder;
+/**
+ * Quick helper to build an INSERT query
+ */
+export declare function buildInsertQuery(tableName: string, values: Record<string, unknown>, options?: InsertBuilderOptions): InsertQueryResult;
+/**
+ * Quick helper to build a bulk INSERT query
+ */
+export declare function buildBulkInsertQuery(tableName: string, records: Record<string, unknown>[], options?: InsertBuilderOptions): InsertQueryResult;
+export default InsertBuilder;

package/dist/query-builders/model-helpers.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Model Helpers
+ * Utilities for working with Model classes in builders
+ */
+/**
+ * Get table name from a model class or string
+ */
+export declare function getTableName(model: string | {
+    tableName?: string;
+    name?: string;
+}): string;
+/**
+ * Check if value is a model class (has tableName or name property)
+ */
+export declare function isModel(value: any): boolean;
+/**
+ * Get model name from model class
+ */
+export declare function getModelName(model: string | {
+    tableName?: string;
+    name?: string;
+}): string;
+declare const _default: {
+    getTableName: typeof getTableName;
+    isModel: typeof isModel;
+    getModelName: typeof getModelName;
+};
+export default _default;

package/dist/query-builders/order-limit-builder.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Order and Limit builder for the ORM
+ * Handles ORDER BY, LIMIT, and OFFSET clauses
+ */
+import { Order, ModelStatic } from '../types';
+export interface OrderLimitOptions {
+    replacements?: Record<string, unknown>;
+    model?: ModelStatic<any>;
+    dialect?: {
+        name?: string;
+        escapeId: (identifier: string) => string;
+    };
+}
+export interface OrderClauseResult {
+    sql: string;
+}
+/**
+ * OrderBuilder class for building ORDER BY clauses
+ */
+export declare class OrderBuilder {
+    private options;
+    constructor(options?: OrderLimitOptions);
+    /**
+     * Build an ORDER BY clause from Order options
+     */
+    build(order: Order | undefined): OrderClauseResult;
+    /**
+     * Build a single order item
+     */
+    private buildOrderItem;
+    /**
+     * Escape an identifier
+     */
+    private escapeId;
+}
+/**
+ * LimitBuilder class for building LIMIT and OFFSET clauses
+ */
+export declare class LimitOffsetBuilder {
+    private options;
+    constructor(options?: OrderLimitOptions);
+    /**
+     * Build LIMIT and OFFSET clauses
+     * Handles SQLite which requires LIMIT when using OFFSET
+     */
+    build(limit?: number | string, offset?: number | string): string;
+}
+/**
+ * Combined Order and Limit builder
+ */
+export declare class OrderLimitBuilder {
+    private orderBuilder;
+    private limitOffsetBuilder;
+    constructor(options?: OrderLimitOptions);
+    /**
+     * Build ORDER BY clause
+     */
+    buildOrder(order: Order | undefined): OrderClauseResult;
+    /**
+     * Build LIMIT/OFFSET clause
+     */
+    buildLimitOffset(limit?: number | string, offset?: number | string): string;
+    /**
+     * Build both ORDER BY and LIMIT/OFFSET
+     */
+    build(order?: Order, limit?: number | string, offset?: number | string): string;
+}
+/**
+ * Create an OrderBuilder instance
+ */
+export declare function createOrderBuilder(options?: OrderLimitOptions): OrderBuilder;
+/**
+ * Create an OrderLimitBuilder instance
+ */
+export declare function createOrderLimitBuilder(options?: OrderLimitOptions): OrderLimitBuilder;
+/**
+ * Quick helper to build ORDER BY clause
+ */
+export declare function buildOrder(order: Order, options?: OrderLimitOptions): OrderClauseResult;
+/**
+ * Quick helper to build LIMIT/OFFSET clause
+ */
+export declare function buildLimitOffset(limit?: number | string, offset?: number | string): string;
+export default OrderLimitBuilder;