ts-prorm-orm 1.2.3 → 2.0.0

package/dist/core/hooks-manager.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Lifecycle hook registries for a Prorm instance.
+ *
+ * `HooksManager` holds instance-wide hooks (define/sync/connect/destroy/...);
+ * `ModelHooks` holds the per-model set. Both were declared inline in prorm.ts,
+ * above the Prorm class.
+ *
+ * Not to be confused with `src/hooks/hooks-manager.ts` - a separate,
+ * currently unreferenced model-level hook system that shares the class name.
+ */
+import type { HookCallback, Connection, SyncOptions } from './types';
+import type { AttributeOptions, ModelStatic, DestroyOptions, ReloadOptions } from '../types';
+import type { ModelOptions as ModelOptionsType } from '../types';
+/** Loose model type, matching the alias prorm.ts uses. */
+type AnyModel = 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;
+}
+/**
+ * Model-level hooks manager
+ */
+export declare class ModelHooks {
+    private beforeSyncHooks;
+    private afterSyncHooks;
+    /**
+     * Register a beforeSync hook on the model
+     */
+    beforeSync(callback: HookCallback): void;
+    /**
+     * Register an afterSync hook on the model
+     */
+    afterSync(callback: HookCallback): void;
+    /**
+     * Run beforeSync hooks
+     */
+    runBeforeSync(options: SyncOptions): Promise<void>;
+    /**
+     * Run afterSync hooks
+     */
+    runAfterSync(options: SyncOptions): Promise<void>;
+}
+export {};

package/dist/core/hooks-manager.js

@@ -0,0 +1,291 @@
+"use strict";
+/**
+ * Lifecycle hook registries for a Prorm instance.
+ *
+ * `HooksManager` holds instance-wide hooks (define/sync/connect/destroy/...);
+ * `ModelHooks` holds the per-model set. Both were declared inline in prorm.ts,
+ * above the Prorm class.
+ *
+ * Not to be confused with `src/hooks/hooks-manager.ts` - a separate,
+ * currently unreferenced model-level hook system that shares the class name.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModelHooks = exports.HooksManager = void 0;
+/**
+ * Hook manager for Prorm instance
+ */
+class HooksManager {
+    constructor() {
+        this.beforeDefineHooks = [];
+        this.afterDefineHooks = [];
+        this.beforeSyncHooks = [];
+        this.afterSyncHooks = [];
+        this.beforeConnectHooks = [];
+        this.afterConnectHooks = [];
+        this.beforeDisconnectHooks = [];
+        this.afterDisconnectHooks = [];
+        this.beforeDestroyHooks = [];
+        this.afterDestroyHooks = [];
+        this.beforeUpsertHooks = [];
+        this.afterUpsertHooks = [];
+        this.beforeReloadHooks = [];
+    }
+    /**
+     * Register a beforeDefine hook
+     */
+    beforeDefine(callback) {
+        this.beforeDefineHooks.push(callback);
+    }
+    /**
+     * Register an afterDefine hook
+     */
+    afterDefine(callback) {
+        this.afterDefineHooks.push(callback);
+    }
+    /**
+     * Register a beforeSync hook
+     */
+    beforeSync(callback) {
+        this.beforeSyncHooks.push(callback);
+    }
+    /**
+     * Register an afterSync hook
+     */
+    afterSync(callback) {
+        this.afterSyncHooks.push(callback);
+    }
+    /**
+     * Register a beforeConnect hook
+     */
+    beforeConnect(callback) {
+        this.beforeConnectHooks.push(callback);
+    }
+    /**
+     * Register an afterConnect hook
+     */
+    afterConnect(callback) {
+        this.afterConnectHooks.push(callback);
+    }
+    /**
+     * Register a beforeDisconnect hook
+     */
+    beforeDisconnect(callback) {
+        this.beforeDisconnectHooks.push(callback);
+    }
+    /**
+     * Register an afterDisconnect hook
+     */
+    afterDisconnect(callback) {
+        this.afterDisconnectHooks.push(callback);
+    }
+    /**
+     * Register a beforeDestroy hook
+     */
+    beforeDestroy(callback) {
+        this.beforeDestroyHooks.push(callback);
+    }
+    /**
+     * Register an afterDestroy hook
+     */
+    afterDestroy(callback) {
+        this.afterDestroyHooks.push(callback);
+    }
+    /**
+     * Register a beforeUpsert hook
+     */
+    beforeUpsert(callback) {
+        this.beforeUpsertHooks.push(callback);
+    }
+    /**
+     * Register an afterUpsert hook
+     */
+    afterUpsert(callback) {
+        this.afterUpsertHooks.push(callback);
+    }
+    /**
+     * Register a beforeReload hook
+     */
+    beforeReload(callback) {
+        this.beforeReloadHooks.push(callback);
+    }
+    /**
+     * Execute all beforeDefine hooks
+     */
+    async runBeforeDefine(modelName, attributes, options) {
+        for (const hook of this.beforeDefineHooks) {
+            await hook({ modelName, attributes, options });
+        }
+    }
+    /**
+     * Execute all afterDefine hooks
+     */
+    async runAfterDefine(model) {
+        for (const hook of this.afterDefineHooks) {
+            await hook({ model });
+        }
+    }
+    /**
+     * Execute all beforeSync hooks
+     */
+    async runBeforeSync(options) {
+        for (const hook of this.beforeSyncHooks) {
+            await hook({ options });
+        }
+    }
+    /**
+     * Execute all afterSync hooks
+     */
+    async runAfterSync(options) {
+        for (const hook of this.afterSyncHooks) {
+            await hook({ options });
+        }
+    }
+    /**
+     * Execute all beforeConnect hooks
+     */
+    async runBeforeConnect() {
+        for (const hook of this.beforeConnectHooks) {
+            await hook();
+        }
+    }
+    /**
+     * Execute all afterConnect hooks
+     * @param connection - The connection object to pass to hooks
+     */
+    async runAfterConnect(connection) {
+        for (const hook of this.afterConnectHooks) {
+            await hook(connection);
+        }
+    }
+    /**
+     * Execute all beforeDisconnect hooks
+     * @param connection - The connection object to pass to hooks
+     */
+    async runBeforeDisconnect(connection) {
+        for (const hook of this.beforeDisconnectHooks) {
+            await hook(connection);
+        }
+    }
+    /**
+     * Execute all afterDisconnect hooks
+     * @param connection - The connection object to pass to hooks
+     */
+    async runAfterDisconnect(connection) {
+        for (const hook of this.afterDisconnectHooks) {
+            await hook(connection);
+        }
+    }
+    /**
+     * Execute all beforeDestroy hooks
+     * @param options - The destroy options
+     */
+    async runBeforeDestroy(options) {
+        for (const hook of this.beforeDestroyHooks) {
+            await hook({ options });
+        }
+    }
+    /**
+     * Execute all afterDestroy hooks
+     * @param options - The destroy options
+     */
+    async runAfterDestroy(options) {
+        for (const hook of this.afterDestroyHooks) {
+            await hook({ options });
+        }
+    }
+    /**
+     * Execute all beforeUpsert hooks
+     * @param options - The upsert options
+     */
+    async runBeforeUpsert(options) {
+        for (const hook of this.beforeUpsertHooks) {
+            await hook({ options });
+        }
+    }
+    /**
+     * Execute all afterUpsert hooks
+     * @param options - The upsert options
+     */
+    async runAfterUpsert(options) {
+        for (const hook of this.afterUpsertHooks) {
+            await hook({ options });
+        }
+    }
+    /**
+     * Execute all beforeReload hooks
+     * @param options - The reload options
+     */
+    async runBeforeReload(options) {
+        for (const hook of this.beforeReloadHooks) {
+            await hook({ options });
+        }
+    }
+    /**
+     * Add a hook by name
+     * @param hookName - The name of the hook (e.g., 'beforeDefine', 'afterSync')
+     * @param callback - The hook callback function
+     */
+    addHook(hookName, callback) {
+        const methodName = hookName;
+        if (typeof this[methodName] === 'function') {
+            this[methodName](callback);
+        }
+    }
+    /**
+     * Clear all hooks
+     */
+    clearHooks() {
+        this.beforeDefineHooks = [];
+        this.afterDefineHooks = [];
+        this.beforeSyncHooks = [];
+        this.afterSyncHooks = [];
+        this.beforeConnectHooks = [];
+        this.afterConnectHooks = [];
+        this.beforeDisconnectHooks = [];
+        this.afterDisconnectHooks = [];
+        this.beforeDestroyHooks = [];
+        this.afterDestroyHooks = [];
+        this.beforeUpsertHooks = [];
+        this.afterUpsertHooks = [];
+        this.beforeReloadHooks = [];
+    }
+}
+exports.HooksManager = HooksManager;
+/**
+ * Model-level hooks manager
+ */
+class ModelHooks {
+    constructor() {
+        this.beforeSyncHooks = [];
+        this.afterSyncHooks = [];
+    }
+    /**
+     * Register a beforeSync hook on the model
+     */
+    beforeSync(callback) {
+        this.beforeSyncHooks.push(callback);
+    }
+    /**
+     * Register an afterSync hook on the model
+     */
+    afterSync(callback) {
+        this.afterSyncHooks.push(callback);
+    }
+    /**
+     * Run beforeSync hooks
+     */
+    async runBeforeSync(options) {
+        for (const hook of this.beforeSyncHooks) {
+            await hook({ options });
+        }
+    }
+    /**
+     * Run afterSync hooks
+     */
+    async runAfterSync(options) {
+        for (const hook of this.afterSyncHooks) {
+            await hook({ options });
+        }
+    }
+}
+exports.ModelHooks = ModelHooks;

package/dist/core/types.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Types and interfaces for the Prorm instance API.
+ *
+ * These were declared inline in prorm.ts, scattered above and below the
+ * 7,500-line Prorm class. They are re-exported from prorm.ts so the public API
+ * is unchanged.
+ */
+import type { AttributeOptions, ModelStatic } from '../types';
+import type { ModelOptions as ModelOptionsType } from '../types';
+import type { Transaction } from '../transaction';
+import { QueryTypes } from '../types/query-types';
+import type { Col, Literal } from './expressions';
+/**
+ * Hook types for the ORM
+ */
+export type HookCallback = (...args: any[]) => void | Promise<void>;
+/**
+ * Every model lifecycle hook the ORM fires.
+ *
+ * Typing hook names as a union rather than `string` makes a misspelled hook a
+ * compile error instead of a callback that silently never runs - which is
+ * exactly how eleven of these went unnoticed.
+ */
+export type HookName = 'beforeValidate' | 'afterValidate' | 'beforeCreate' | 'afterCreate' | 'beforeUpdate' | 'afterUpdate' | 'beforeDestroy' | 'afterDestroy' | 'beforeSave' | 'afterSave' | 'beforeUpsert' | 'afterUpsert' | 'beforeFind' | 'afterFind' | 'beforeCount' | 'beforeBulkCreate' | 'afterBulkCreate' | 'beforeBulkUpdate' | 'afterBulkUpdate' | 'beforeBulkDestroy' | 'afterBulkDestroy';
+/** A model's hook map, as passed to `define(..., { hooks })`. */
+export type ModelHookMap = Partial<Record<HookName, HookCallback>>;
+/**
+ * Connection type for hook callbacks
+ */
+export interface Connection {
+    id: string;
+    createdAt: number;
+    [key: string]: any;
+}
+/**
+ * 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;
+}
+/**
+ * Options for raw query execution
+ */
+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>;
+}
+/** The shape stored in `Prorm.modelDefinitions`. */
+export type PrormModelDefinition = {
+    attributes: Record<string, AttributeOptions>;
+    options: ModelOptionsType;
+};
+/**
+ * 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;
+}

package/dist/core/types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Types and interfaces for the Prorm instance API.
+ *
+ * These were declared inline in prorm.ts, scattered above and below the
+ * 7,500-line Prorm class. They are re-exported from prorm.ts so the public API
+ * is unchanged.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });