ts-prorm-orm 1.2.2 → 2.0.0

package/dist/prorm.d.ts

@@ -6,347 +6,34 @@ import { Dialect, ColumnDefinition, TableOptions, CreateExtensionOptions, DropEx
 import { ForeignDataManager, ForeignServerOptions, UserMappingOptions, ForeignTableOptions, ImportForeignSchemaOptions, ServerInfo } from './foreign-data';
 import { UserManager } from './user-management';
 import { DatabaseConnectionPool } from './connection-pool';
-import { PrormOptions, ModelStatic, ModelOptions as ModelOptionsType, AttributeOptions, DestroyOptions, ReloadOptions, Transaction, TransactionOptions, DataType } from './types';
+import { PrormOptions, ModelStatic, ModelOptions as ModelOptionsType, AttributeOptions, Transaction, TransactionOptions, DataType } from './types';
 import { ExternalStoreRegistry } from './external-fields';
 import type { RegisterStoreOptions } from './external-fields';
 import { Logger } from './logging';
 import { ValidationError } from './errors';
 import { type IsolationLevelValue } from './sql-constants';
 type AnyModel = any;
-/**
- * Hook types for the ORM
- */
-export type HookCallback = (...args: any[]) => void | Promise<void>;
-/**
- * Connection type for hook callbacks
- */
-export interface Connection {
-    id: string;
-    createdAt: number;
-    [key: string]: any;
-}
-/**
- * Hook manager for Prorm instance
- */
-export declare class HooksManager {
-    private beforeDefineHooks;
-    private afterDefineHooks;
-    private beforeSyncHooks;
-    private afterSyncHooks;
-    private beforeConnectHooks;
-    private afterConnectHooks;
-    private beforeDisconnectHooks;
-    private afterDisconnectHooks;
-    private beforeDestroyHooks;
-    private afterDestroyHooks;
-    private beforeUpsertHooks;
-    private afterUpsertHooks;
-    private beforeReloadHooks;
-    /**
-     * Register a beforeDefine hook
-     */
-    beforeDefine(callback: HookCallback): void;
-    /**
-     * Register an afterDefine hook
-     */
-    afterDefine(callback: HookCallback): void;
-    /**
-     * Register a beforeSync hook
-     */
-    beforeSync(callback: HookCallback): void;
-    /**
-     * Register an afterSync hook
-     */
-    afterSync(callback: HookCallback): void;
-    /**
-     * Register a beforeConnect hook
-     */
-    beforeConnect(callback: HookCallback): void;
-    /**
-     * Register an afterConnect hook
-     */
-    afterConnect(callback: HookCallback): void;
-    /**
-     * Register a beforeDisconnect hook
-     */
-    beforeDisconnect(callback: HookCallback): void;
-    /**
-     * Register an afterDisconnect hook
-     */
-    afterDisconnect(callback: HookCallback): void;
-    /**
-     * Register a beforeDestroy hook
-     */
-    beforeDestroy(callback: HookCallback): void;
-    /**
-     * Register an afterDestroy hook
-     */
-    afterDestroy(callback: HookCallback): void;
-    /**
-     * Register a beforeUpsert hook
-     */
-    beforeUpsert(callback: HookCallback): void;
-    /**
-     * Register an afterUpsert hook
-     */
-    afterUpsert(callback: HookCallback): void;
-    /**
-     * Register a beforeReload hook
-     */
-    beforeReload(callback: HookCallback): void;
-    /**
-     * Execute all beforeDefine hooks
-     */
-    runBeforeDefine(modelName: string, attributes: Record<string, AttributeOptions>, options: ModelOptionsType): Promise<void>;
-    /**
-     * Execute all afterDefine hooks
-     */
-    runAfterDefine(model: ModelStatic<AnyModel>): Promise<void>;
-    /**
-     * Execute all beforeSync hooks
-     */
-    runBeforeSync(options: SyncOptions): Promise<void>;
-    /**
-     * Execute all afterSync hooks
-     */
-    runAfterSync(options: SyncOptions): Promise<void>;
-    /**
-     * Execute all beforeConnect hooks
-     */
-    runBeforeConnect(): Promise<void>;
-    /**
-     * Execute all afterConnect hooks
-     * @param connection - The connection object to pass to hooks
-     */
-    runAfterConnect(connection: Connection): Promise<void>;
-    /**
-     * Execute all beforeDisconnect hooks
-     * @param connection - The connection object to pass to hooks
-     */
-    runBeforeDisconnect(connection: Connection): Promise<void>;
-    /**
-     * Execute all afterDisconnect hooks
-     * @param connection - The connection object to pass to hooks
-     */
-    runAfterDisconnect(connection: Connection): Promise<void>;
-    /**
-     * Execute all beforeDestroy hooks
-     * @param options - The destroy options
-     */
-    runBeforeDestroy(options: DestroyOptions): Promise<void>;
-    /**
-     * Execute all afterDestroy hooks
-     * @param options - The destroy options
-     */
-    runAfterDestroy(options: DestroyOptions): Promise<void>;
-    /**
-     * Execute all beforeUpsert hooks
-     * @param options - The upsert options
-     */
-    runBeforeUpsert(options: any): Promise<void>;
-    /**
-     * Execute all afterUpsert hooks
-     * @param options - The upsert options
-     */
-    runAfterUpsert(options: any): Promise<void>;
-    /**
-     * Execute all beforeReload hooks
-     * @param options - The reload options
-     */
-    runBeforeReload(options: ReloadOptions): Promise<void>;
-    /**
-     * Add a hook by name
-     * @param hookName - The name of the hook (e.g., 'beforeDefine', 'afterSync')
-     * @param callback - The hook callback function
-     */
-    addHook(hookName: string, callback: HookCallback): void;
-    /**
-     * Clear all hooks
-     */
-    clearHooks(): void;
-}
-/**
- * Options for sync method
- */
-export interface SyncOptions {
-    /**
-     * If true, drops all tables and recreates them.
-     * WARNING: This will destroy all data in the tables!
-     * @default false
-     */
-    force?: boolean;
-    /**
-     * If true, alter tables to match model definitions.
-     * This will add new columns, remove extra columns, and change column types as needed.
-     * Preserves existing data in the table.
-     * Can be an object with { drop: false } to prevent dropping columns
-     * @default false
-     */
-    alter?: boolean | {
-        drop?: boolean;
-    };
-    /**
-     * Regular expression to match the database name.
-     * Sync will only proceed if the database name matches this pattern.
-     * Useful for development vs production environments.
-     * Example: /test/ - only syncs if database name contains "test"
-     */
-    match?: RegExp;
-    /**
-     * Custom logging function
-     */
-    logging?: boolean | ((sql: string, timing?: number) => void);
-    /**
-     * If true, run sync hooks (beforeSync, afterSync, etc.)
-     * @default true
-     */
-    hooks?: boolean;
-    /**
-     * If true, also sync indexes
-     * @default true
-     */
-    indexes?: boolean;
-    /**
-     * If true, also sync foreign key constraints
-     * @default true
-     */
-    constraints?: boolean;
-}
-/**
- * Represents a raw SQL literal value
- * Used for inserting raw SQL expressions into queries
- *
- * @example
- * // Use in default values
- * createdAt: { type: DATE, defaultValue: prorm.literal('NOW()') }
- *
- * @example
- * // Use in updates
- * User.update({ count: prorm.literal('count + 1') }, {...})
- *
- * @example
- * // Use in select with calculations
- * User.findAll({ attributes: [[prorm.literal('1 + 1'), 'two']] })
- */
-export declare class Literal {
-    readonly val: string;
-    constructor(sql: string);
-    /**
-     * Get the raw SQL string
-     */
-    toString(): string;
-}
-/**
- * Class representing a column reference for use with Prorm functions
- * Used to create properly quoted column identifiers
- *
- * @example
- * // Single column: col('name') -> "name"
- * // Table and column: col('User', 'name') -> "User"."name"
- * // Dot notation: col('table.column') -> "table"."column"
- */
-export declare class Col {
-    private readonly col;
-    /**
-     * Create a column reference
-     * @param tableOrColumn - Table name (if second param provided) or column name
-     * @param column - Column name (if first param is table name)
-     */
-    constructor(tableOrColumn: string, column?: string);
-    /**
-     * Get the SQL representation of the column
-     */
-    toSql(): string;
-    /**
-     * Get the column as a string
-     */
-    toString(): string;
-}
+import { HooksManager } from './core/hooks-manager';
+import { Literal, Col } from './core/expressions';
+import type { HookCallback, HookName, ModelHookMap, Connection, SyncOptions, RawQueryResult, QueryOptions, Fn, Cast, WhereObject, AndOrObject, JsonObject } from './core/types';
+export { HooksManager, Literal, Col };
+export type { HookCallback, HookName, ModelHookMap, Connection, SyncOptions, RawQueryResult, QueryOptions, Fn, Cast, WhereObject, AndOrObject, JsonObject, };
 /**
  * Query types for raw SQL queries
  */
-export declare enum QueryTypes {
-    SELECT = "SELECT",
-    INSERT = "INSERT",
-    UPDATE = "UPDATE",
-    DELETE = "DELETE",
-    BULKDELETE = "BULKDELETE",
-    BULKINSERT = "BULKINSERT",
-    UPSERT = "UPSERT",
-    VERSION = "VERSION",
-    SHOWTABLES = "SHOWTABLES",
-    DESCRIBE = "DESCRIBE",
-    RAW = "RAW"
-}
+import { QueryTypes } from './types/query-types';
+export { QueryTypes };
 /**
- * Options for raw query execution
+ * The part of `ConnectionManager` a `Prorm` instance needs in order to resolve
+ * `FindOptions.using` - i.e. to look up a sibling connection by name.
+ *
+ * Declared structurally so prorm.ts doesn't have to import
+ * connection-manager.ts (which already imports Prorm, so a real import would
+ * close a cycle). `ConnectionManager` satisfies it as-is.
  */
-export interface RawQueryResult {
-    rows: unknown[];
-    count: number;
-    isSelect: boolean;
-}
-export interface QueryOptions {
-    /**
-     * Query type - determines how results are processed
-     * Forces the query type for result handling
-     * - SELECT: Returns array of rows
-     * - INSERT: Returns [rows, created]
-     * - UPDATE: Returns affected count
-     * - DELETE: Returns affected count
-     * - BULKDELETE: Returns affected count
-     * - UPSERT: Returns [rows, created]
-     */
-    type?: QueryTypes | 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE' | 'BULKDELETE' | 'UPSERT' | 'BULKINSERT' | 'VERSION' | 'SHOWTABLES' | 'DESCRIBE' | 'RAW';
-    /**
-     * Replacements for named (:param) or positional (?) placeholders
-     * For named: { username: 'john' } replaces :username in SQL
-     * For positional: ['john', 'smith'] replaces ? in order
-     */
-    replacements?: Record<string, unknown> | unknown[];
-    /**
-     * Return raw results without model instantiation
-     */
-    raw?: boolean;
-    /**
-     * Whether to log the query
-     */
-    logging?: boolean | ((sql: string, timing?: number) => void);
-    /**
-     * When true, logs query execution time
-     */
-    benchmark?: boolean;
-    /**
-     * Transaction to use for the query
-     */
-    transaction?: Transaction;
-    /**
-     * Retry configuration for query execution
-     * On connection failure or retryable errors, retry up to max times
-     * @param max - Maximum number of retry attempts
-     * @param match - Array of error message patterns that trigger retry
-     *
-     * @example
-     * // Retry on connection refused or timeout errors
-     * await prorm.query('SELECT * FROM users', {
-     *   retry: { max: 3, match: ['Connection refused', 'Timeout', 'ECONNREFUSED'] }
-     * });
-     */
-    retry?: {
-        max: number;
-        match?: string[];
-    };
-    /**
-     * Map raw query results to a model instance
-     * When true, maps the result rows to ModelInstance objects using the provided model
-     * @default false
-     */
-    mapToModel?: boolean;
-    /**
-     * Model to use for mapping raw results to model instances
-     * Used together with mapToModel to create ModelInstance objects from raw query results
-     */
-    model?: ModelStatic<any>;
+export interface ConnectionRegistry {
+    getConnection(name: string): Prorm | undefined;
+    getConnectionNames(): string[];
 }
 /**
  * Main Prorm class with error handling and logging
@@ -356,6 +43,17 @@ export declare class Prorm extends EventEmitter {
     private _fdwManager;
     private _userManager;
     private _models;
+    /**
+     * The registry this instance was created by, if any.
+     *
+     * `ConnectionManager.addConnection()` sets this on the instance it builds,
+     * which is what makes `FindOptions.using` work: a query can name a sibling
+     * connection and be routed to that connection's copy of the model. Nothing
+     * else assigned it before, so `using` threw "Available: none" on every call.
+     * Typed structurally (rather than as `ConnectionManager`) to keep prorm.ts
+     * free of an import cycle with connection-manager.ts.
+     */
+    connectionManager: ConnectionRegistry | null;
     /**
      * Get all models as an object for backward compatibility
      * Allows accessing models via prorm.models.ModelName
@@ -694,11 +392,25 @@ export declare class Prorm extends EventEmitter {
     }): Promise<void>;
     /**
      * Disable foreign key checks for the current session
+     *
+     * On PostgreSQL this issues `SET session_replication_role = 'replica'`, which
+     * needs superuser or a role granted `SET ON PARAMETER
+     * session_replication_role` (PostgreSQL 15+).
+     *
+     * @throws {UnsupportedForeignKeyChecksError} on dialects with no
+     * session-level switch (SQL Server, Oracle and Db2 are per-table; Redshift,
+     * Snowflake and ClickHouse never enforce foreign keys).
      * @returns Promise that resolves when foreign key checks are disabled
      */
     disableForeignKeyChecks(): Promise<void>;
     /**
      * Enable foreign key checks for the current session
+     *
+     * The inverse of {@link disableForeignKeyChecks}, with the same dialect
+     * support and the same PostgreSQL privilege requirement.
+     *
+     * @throws {UnsupportedForeignKeyChecksError} on dialects with no
+     * session-level switch
      * @returns Promise that resolves when foreign key checks are enabled
      */
     enableForeignKeyChecks(): Promise<void>;
@@ -710,11 +422,24 @@ export declare class Prorm extends EventEmitter {
     setIsolationLevel(level: IsolationLevelValue): Promise<void>;
     /**
      * Get SQL for disabling foreign key checks for the current dialect
+     *
+     * Routing lives in `sql-constants.getForeignKeyChecksSQL` so that the three
+     * mutually incompatible statements (SQLite's PRAGMA, MySQL's session
+     * variable, PostgreSQL's `session_replication_role`) are chosen from one
+     * table. This used to fall through to MySQL syntax for every dialect it did
+     * not name - PostgreSQL included - so `disableForeignKeyChecks()` threw a
+     * syntax error at the server on most of the supported databases.
+     *
+     * @throws {UnsupportedForeignKeyChecksError} when the dialect has no
+     * session-level equivalent
      * @returns SQL string for disabling foreign key checks
      */
     getDisableForeignKeyChecksSQL(): string;
     /**
      * Get SQL for enabling foreign key checks for the current dialect
+     *
+     * @throws {UnsupportedForeignKeyChecksError} when the dialect has no
+     * session-level equivalent
      * @returns SQL string for enabling foreign key checks
      */
     getEnableForeignKeyChecksSQL(): string;
@@ -726,11 +451,27 @@ export declare class Prorm extends EventEmitter {
     getSetIsolationLevelSQL(level: IsolationLevelValue): string;
     /**
      * Disable unique key checks for the current session (MySQL/MariaDB only)
+     *
+     * The no-op on other dialects is deliberate, and is not the same situation as
+     * the foreign key switch above. `SET UNIQUE_CHECKS` is a MySQL/MariaDB
+     * *optimisation* hint: it defers uniqueness verification on InnoDB secondary
+     * indexes during bulk loads. No other supported database has a session
+     * setting that suspends unique constraint checking - PostgreSQL's
+     * `session_replication_role = 'replica'` suppresses triggers and foreign
+     * keys but still enforces unique indexes - so there is nothing to translate
+     * it to. Skipping the statement leaves the database in exactly the state the
+     * caller already had (uniqueness enforced), which is safe; throwing would
+     * break the common `disableUniqueKeyChecks(); bulkCreate(); enable...()`
+     * bulk-load pattern on every non-MySQL dialect for no benefit.
+     *
      * @returns Promise that resolves when unique key checks are disabled
      */
     disableUniqueKeyChecks(): Promise<void>;
     /**
      * Enable unique key checks for the current session (MySQL/MariaDB only)
+     *
+     * A no-op elsewhere, for the reason given on {@link disableUniqueKeyChecks}.
+     *
      * @returns Promise that resolves when unique key checks are enabled
      */
     enableUniqueKeyChecks(): Promise<void>;
@@ -1662,6 +1403,54 @@ export declare class Prorm extends EventEmitter {
      * registered, so callers can report them rather than silently skipping.
      */
     private _unresolvedAssociationTargets;
+    /**
+     * Run a `findAll` against the connection named by `FindOptions.using`.
+     *
+     * `using` lets one query hop to a sibling database registered on the same
+     * `ConnectionManager` (`User.findAll({ using: 'analytics' })`). The target
+     * connection has its own models, so this re-dispatches to *that*
+     * connection's copy of the model by name and drops `using` from the options
+     * so the delegate runs the query normally instead of bouncing forever.
+     *
+     * Both failure modes report what is actually available, since a typo in a
+     * connection name and a model that was never defined on the target
+     * connection are otherwise indistinguishable from "the query returned
+     * nothing".
+     */
+    private _findAllUsingConnection;
+    /**
+     * Resolve an `include` list into concrete, per-association entries.
+     *
+     * Every pass that reads an include - the cross-table `$assoc.col$` rewrite,
+     * the parent-filtering (`required`) pass, and the eager loader itself - is
+     * written against an entry that carries a `model`. `{ all: true }` carries
+     * none, so each of those passes has to see the *expanded* list or it silently
+     * does nothing for `all`: that is how `include: [{ all: true, required: true }]`
+     * came to load the associations without narrowing the parents, while the
+     * equivalent explicit include filtered correctly.
+     *
+     * Expansion is idempotent - a list with no `all` entry comes back as the same
+     * entries - so running it here as well as inside `loadIncludes()` is safe.
+     */
+    private _expandIncludes;
+    /**
+     * Narrow a WHERE clause by the query's filtering (`required`) includes.
+     *
+     * Shared by `findAll`, `_countRows` and `_aggregate` so that a filtering
+     * include restricts the rows, the count and an aggregate to the same set.
+     * Returns `null` when some include can match no parent at all - the whole
+     * query is then empty, and each caller spells "empty" its own way (no rows,
+     * a count of 0, a null aggregate).
+     *
+     * Several includes can constrain the *same* parent column, and since
+     * `{ all: true, required: true }` expands to one include per association that
+     * is now the common case rather than a corner. Their key sets are intersected
+     * here. They must not be emitted as two conditions on one key: a
+     * `{ id: { $and: [{ $in: [...] }, { $in: [...] }] } }` shape is not something
+     * the where-builders recognize, and it collapsed to a single `"id" = ?` -
+     * which is why two `required` includes used to return the wrong rows.
+     */
+    private _applyRequiredIncludeFilters;
     /**
      * Issue a real `SELECT COUNT(...)` for a model.
      *
@@ -1670,6 +1459,9 @@ export declare class Prorm extends EventEmitter {
      *  - `col` picks the counted expression (`COUNT("col")`)
      *  - `distinct: true` counts distinct values of `col`, or of the primary key
      *  - `group` returns the number of groups
+     *
+     * A query carrying `union` branches is counted over the combined query rather
+     * than this model's table alone - see the derived-table note below.
      */
     private _countRows;
     /**
@@ -1683,6 +1475,31 @@ export declare class Prorm extends EventEmitter {
      * include soft-deleted rows that `findAll` excluded.
      */
     private _aggregate;
+    /**
+     * Log one executed query, and emit the events that hang off it.
+     *
+     * Every statement the ORM issues should route through here. Query logging was
+     * previously inlined at four call sites and only some ran it, so `count`,
+     * `bulkCreate`, `increment` and the aggregates emitted nothing - turning
+     * logging on showed an incomplete picture of what the ORM was doing.
+     */
+    private _logQuery;
+    /**
+     * Apply `+/- delta` to numeric columns in a single UPDATE.
+     *
+     * Backs `Model.increment` / `Model.decrement`. The arithmetic happens in the
+     * database, so two concurrent callers both land - a read-modify-write in
+     * application code silently drops one of them.
+     */
+    private _applyDelta;
+    /**
+     * Update many rows to different values in one statement.
+     *
+     * Backs `Model.bulkUpdate`. Compiles one UPDATE with a CASE expression per
+     * column - portable across every supported dialect - instead of N round
+     * trips.
+     */
+    private _bulkUpdate;
     /**
      * The view of this instance that the shared eager-loader needs.
      */
@@ -1714,8 +1531,36 @@ export declare class Prorm extends EventEmitter {
      * Alter sync mode - modifies tables to match models (preserves data)
      */
     private syncAlter;
+    /**
+     * Make sure the model's declared composite unique keys are enforced on an
+     * existing table, as a unique index.
+     *
+     * `alterTable` reconciles columns only, and on SQLite reconciling a column
+     * means rebuilding the table - which drops the table-level UNIQUE constraint
+     * that `createTableFromModel` put in the CREATE TABLE text. Without this step
+     * a single `sync({ alter: true })` would silently un-enforce a unique key the
+     * model still declares, which is the same silent-data-integrity failure the
+     * unique key support was added to fix.
+     *
+     * A unique index enforces exactly the same rule as a unique constraint and,
+     * unlike `ADD CONSTRAINT`, every dialect here can create one. Existing
+     * indexes are listed first so re-syncing is idempotent on dialects whose
+     * `addIndex` has no IF NOT EXISTS.
+     *
+     * This deliberately does not remove unique keys the model no longer declares
+     * (dropping a constraint is not a change to make implicitly), and it will
+     * fail loudly if the table already holds rows that violate a newly declared
+     * key - which is the honest outcome, not something to swallow.
+     */
+    private reconcileUniqueKeys;
     /**
      * Alter a table to match model definition
+     *
+     * Scope note: this reconciles *columns* only - it adds, changes and (with
+     * `drop`) removes them. Table-level constraints are not diffed against the
+     * database. The composite unique keys collected by `collectUniqueKeys` are
+     * the exception, and they are handled just after this runs, by
+     * `reconcileUniqueKeys`, because a column rebuild would otherwise drop them.
      */
     private alterTable;
     /**
@@ -1997,85 +1842,6 @@ export declare class Prorm extends EventEmitter {
         model?: ModelStatic<AnyModel>;
     }): Promise<ValidationError | null>;
 }
-/**
- * Represents a SQL function expression
- * Used with prorm.fn() to create SQL functions like COUNT, UPPER, YEAR, etc.
- */
-export interface Fn {
-    /**
-     * The SQL function name (e.g., 'COUNT', 'UPPER', 'YEAR')
-     */
-    fn: string;
-    /**
-     * The arguments to the function (can be column references, literals, or other functions)
-     */
-    args: (string | Col | Fn | Literal)[];
-}
-/**
- * Represents a SQL CAST expression
- * Used to cast a value to a specific data type
- */
-export interface Cast {
-    /**
-     * Type identifier for CAST
-     */
-    $type: 'cast';
-    /**
-     * The value to cast (column reference, literal, or function)
-     */
-    value: string | Col | Fn | Literal;
-    /**
-     * The target data type (e.g., 'VARCHAR', 'INTEGER', 'DATE', 'BOOLEAN')
-     */
-    type: string;
-}
-/**
- * Represents a WHERE condition for complex queries
- */
-export interface WhereObject {
-    /**
-     * Type identifier for WHERE
-     */
-    $type: 'where';
-    /**
-     * The column or expression to compare
-     */
-    col: Col | Fn | Literal;
-    /**
-     * The value or condition to compare against
-     */
-    value: unknown;
-}
-/**
- * Represents an AND or OR combination of conditions
- */
-export interface AndOrObject {
-    /**
-     * Type identifier - 'and' or 'or'
-     */
-    $type: 'and' | 'or';
-    /**
-     * The conditions to combine
-     */
-    conditions: unknown[];
-}
-/**
- * Represents a JSON path query for JSON columns
- */
-export interface JsonObject {
-    /**
-     * Type identifier for JSON
-     */
-    $type: 'json';
-    /**
-     * The JSON path to query (dot notation or array notation)
-     */
-    path: string;
-    /**
-     * Optional value to compare against
-     */
-    value?: unknown;
-}
 /**
  * DataTypes for model definitions
  */