ts-prorm-orm 1.2.3 → 2.1.0

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 });

package/dist/decorators/audit.d.ts

@@ -1,5 +1,5 @@
 /**
- * @Audit class decorator — automatically record model lifecycle events to an
+ * `@Audit` class decorator — automatically record model lifecycle events to an
  * in-memory audit log.
  *
  * When applied to a model class the decorator registers beforeCreate,
@@ -8,12 +8,14 @@
  *
  * Example:
  *
+ * ```ts
  *   @Audit({ tableName: 'audit_log', trackFields: ['name', 'email'] })
  *   class User extends Model { ... }
  *
  *   // After create/update/destroy hooks fire:
  *   const log = getAuditLog(User);
  *   clearAuditLog(User);
+ * ```
  */
 export interface AuditOptions {
     /** Name of the conceptual audit table (used as label in entries). Default: 'audit_log'. */

package/dist/decorators/audit.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * @Audit class decorator — automatically record model lifecycle events to an
+ * `@Audit` class decorator — automatically record model lifecycle events to an
  * in-memory audit log.
  *
  * When applied to a model class the decorator registers beforeCreate,
@@ -9,12 +9,14 @@
  *
  * Example:
  *
+ * ```ts
  *   @Audit({ tableName: 'audit_log', trackFields: ['name', 'email'] })
  *   class User extends Model { ... }
  *
  *   // After create/update/destroy hooks fire:
  *   const log = getAuditLog(User);
  *   clearAuditLog(User);
+ * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getAuditLog = getAuditLog;

package/dist/decorators/check.d.ts

@@ -1,34 +1,34 @@
 /**
- * @Check decorator for the ORM — generates CHECK constraints without writing raw SQL.
+ * `@Check` decorator for the ORM — generates CHECK constraints without writing raw SQL.
  *
  * Supports ORM-native operator syntax that gets converted to SQL CHECK expressions.
  *
  * Usage Examples:
  *
  * // Column-level check with ORM operators
- * @Check({ age: { $gte: 18 } })
+ * `@Check`({ age: { $gte: 18 } })
  * age: number;
  *
  * // Multiple column checks
- * @Check({
+ * `@Check`({
  *   status: { $in: ['active', 'pending', 'draft'] },
  *   email: { $regex: '^[^@]+@[^@]+$' }
  * })
  * email: string;
  *
  * // Custom condition with message
- * @Check({
+ * `@Check`({
  *   condition: (row) => row.startDate < row.endDate,
  *   message: 'Start date must be before end date'
  * })
  * startDate: Date;
  *
  * // Column-level check (explicit column)
- * @CheckColumn('price', { $gte: 0 }, 'Price must be positive')
- * @CheckColumn('quantity', { $gt: 0 }, 'Quantity must be greater than zero')
+ * `@CheckColumn`('price', { $gte: 0 }, 'Price must be positive')
+ * `@CheckColumn`('quantity', { $gt: 0 }, 'Quantity must be greater than zero')
  *
  * // Table-level check (multiple columns)
- * @CheckTable({
+ * `@CheckTable`({
  *   condition: (row) => row.quantity * row.price >= row.minimumOrder,
  *   message: 'Total must meet minimum order amount'
  * })
@@ -155,21 +155,21 @@ export type CheckDialect = 'mysql' | 'mariadb' | 'postgres' | 'mssql' | 'oracle'
  */
 export declare function operatorToSQL(fieldName: string, operator: CheckOperator, dialect?: CheckDialect): string;
 /**
- * @Check decorator — attach CHECK constraints to a column or multiple columns.
+ * `@Check` decorator — attach CHECK constraints to a column or multiple columns.
  *
  * For column-level use (on class property):
- * @Check({ age: { $gte: 18 } })
+ * `@Check`({ age: { $gte: 18 } })
  * age: number;
  *
  * For multiple checks:
- * @Check({
+ * `@Check`({
  *   status: { $in: ['active', 'pending'] },
  *   email: { $regex: '^[^@]+@[^@]+$' }
  * })
  * email: string;
  *
  * For row-level condition:
- * @Check({
+ * `@Check`({
  *   condition: (row) => row.startDate < row.endDate,
  *   message: 'Start date must be before end date'
  * })
@@ -177,16 +177,16 @@ export declare function operatorToSQL(fieldName: string, operator: CheckOperator
  */
 export declare function Check(options: CheckConstraintOptions): PropertyDecorator;
 /**
- * @CheckColumn decorator — explicit column-level CHECK constraint.
+ * `@CheckColumn` decorator — explicit column-level CHECK constraint.
  *
- * @CheckColumn('price', { $gte: 0 }, 'Price must be positive')
+ * `@CheckColumn`('price', { $gte: 0 }, 'Price must be positive')
  * price: number;
  */
 export declare function CheckColumn(column: string, operator: CheckOperator, message?: string): PropertyDecorator;
 /**
- * @CheckTable decorator — table-level CHECK constraint with multi-column conditions.
+ * `@CheckTable` decorator — table-level CHECK constraint with multi-column conditions.
  *
- * @CheckTable({
+ * `@CheckTable`({
  *   condition: (row) => row.quantity * row.price >= row.minimumOrder,
  *   message: 'Total must meet minimum order amount'
  * })

package/dist/decorators/check.js

@@ -1,35 +1,35 @@
 "use strict";
 /**
- * @Check decorator for the ORM — generates CHECK constraints without writing raw SQL.
+ * `@Check` decorator for the ORM — generates CHECK constraints without writing raw SQL.
  *
  * Supports ORM-native operator syntax that gets converted to SQL CHECK expressions.
  *
  * Usage Examples:
  *
  * // Column-level check with ORM operators
- * @Check({ age: { $gte: 18 } })
+ * `@Check`({ age: { $gte: 18 } })
  * age: number;
  *
  * // Multiple column checks
- * @Check({
+ * `@Check`({
  *   status: { $in: ['active', 'pending', 'draft'] },
  *   email: { $regex: '^[^@]+@[^@]+$' }
  * })
  * email: string;
  *
  * // Custom condition with message
- * @Check({
+ * `@Check`({
  *   condition: (row) => row.startDate < row.endDate,
  *   message: 'Start date must be before end date'
  * })
  * startDate: Date;
  *
  * // Column-level check (explicit column)
- * @CheckColumn('price', { $gte: 0 }, 'Price must be positive')
- * @CheckColumn('quantity', { $gt: 0 }, 'Quantity must be greater than zero')
+ * `@CheckColumn`('price', { $gte: 0 }, 'Price must be positive')
+ * `@CheckColumn`('quantity', { $gt: 0 }, 'Quantity must be greater than zero')
  *
  * // Table-level check (multiple columns)
- * @CheckTable({
+ * `@CheckTable`({
  *   condition: (row) => row.quantity * row.price >= row.minimumOrder,
  *   message: 'Total must meet minimum order amount'
  * })
@@ -270,21 +270,21 @@ function conditionToSQL(condition, paramNames) {
 }
 // ==================== Decorators ====================
 /**
- * @Check decorator — attach CHECK constraints to a column or multiple columns.
+ * `@Check` decorator — attach CHECK constraints to a column or multiple columns.
  *
  * For column-level use (on class property):
- * @Check({ age: { $gte: 18 } })
+ * `@Check`({ age: { $gte: 18 } })
  * age: number;
  *
  * For multiple checks:
- * @Check({
+ * `@Check`({
  *   status: { $in: ['active', 'pending'] },
  *   email: { $regex: '^[^@]+@[^@]+$' }
  * })
  * email: string;
  *
  * For row-level condition:
- * @Check({
+ * `@Check`({
  *   condition: (row) => row.startDate < row.endDate,
  *   message: 'Start date must be before end date'
  * })
@@ -328,9 +328,9 @@ function Check(options) {
     };
 }
 /**
- * @CheckColumn decorator — explicit column-level CHECK constraint.
+ * `@CheckColumn` decorator — explicit column-level CHECK constraint.
  *
- * @CheckColumn('price', { $gte: 0 }, 'Price must be positive')
+ * `@CheckColumn`('price', { $gte: 0 }, 'Price must be positive')
  * price: number;
  */
 function CheckColumn(column, operator, message) {
@@ -348,9 +348,9 @@ function CheckColumn(column, operator, message) {
     };
 }
 /**
- * @CheckTable decorator — table-level CHECK constraint with multi-column conditions.
+ * `@CheckTable` decorator — table-level CHECK constraint with multi-column conditions.
  *
- * @CheckTable({
+ * `@CheckTable`({
  *   condition: (row) => row.quantity * row.price >= row.minimumOrder,
  *   message: 'Total must meet minimum order amount'
  * })

package/dist/decorators/collate.d.ts

@@ -6,6 +6,7 @@
  *
  * Usage:
  *
+ * ```ts
  *   // Column-level collation
  *   class User extends Model {
  *     @SetCollate(CollateEnum.UTF8MB4_UNICODE_CI)
@@ -38,6 +39,7 @@
  *     lcCtype: 'es_ES.UTF-8',
  *     template: 'template0',
  *   });
+ * ```
  */
 /**
  * MySQL/MariaDB collation constants
@@ -255,33 +257,42 @@ export interface OrderByOptions {
  * Decorator to set column-level collation
  *
  * Usage:
+ * ```ts
  *   @Collate(Collate.UTF8MB4_UNICODE_CI)
  *   @Column
  *   name: string;
+ * ```
  *
  * Or with options:
+ * ```ts
  *   @Collate({ collate: Collate.UTF8MB4_BIN, unique: true })
  *   @Column
  *   email: string;
+ * ```
  */
 /**
  * Decorator to set column-level collation
  *
  * Usage:
+ * ```ts
  *   @SetCollate(CollateEnum.UTF8MB4_UNICODE_CI)
  *   @Column
  *   name: string;
+ * ```
  *
  * Or with options:
+ * ```ts
  *   @SetCollate({ collate: CollateEnum.UTF8MB4_BIN, unique: true })
  *   @Column
  *   email: string;
+ * ```
  */
 export declare function SetCollate(collation: string | CollateOptions): ClassDecorator & PropertyDecorator;
 /**
  * Decorator to set database-level options
  *
  * Usage:
+ * ```ts
  *   @Database({
  *     name: 'miapp',
  *     encoding: 'UTF8',
@@ -290,22 +301,27 @@ export declare function SetCollate(collation: string | CollateOptions): ClassDec
  *     connectionLimit: 25,
  *   })
  *   class Config extends Model {}
+ * ```
  */
 export declare function Database(options: DatabaseOptions): ClassDecorator;
 /**
  * Decorator to set table-level collation and options
  *
  * Usage:
+ * ```ts
  *   @TableCollate({ collate: 'utf8mb4_spanish_ci', engine: 'InnoDB' })
  *   class User extends Model {}
+ * ```
  */
 export declare function TableCollate(options: TableCollateOptions): ClassDecorator;
 /**
  * Decorator to specify order by with collation
  *
  * Usage:
+ * ```ts
  *   @OrderBy('name', 'ASC', Collate.UTF8MB4_SPANISH_CI)
  *   class User extends Model {}
+ * ```
  */
 export declare function OrderBy(column: string, direction?: 'ASC' | 'DESC', collate?: string): ClassDecorator;
 /**

package/dist/decorators/collate.js

@@ -7,6 +7,7 @@
  *
  * Usage:
  *
+ * ```ts
  *   // Column-level collation
  *   class User extends Model {
  *     @SetCollate(CollateEnum.UTF8MB4_UNICODE_CI)
@@ -39,6 +40,7 @@
  *     lcCtype: 'es_ES.UTF-8',
  *     template: 'template0',
  *   });
+ * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Locale = exports.LocaleEnum = exports.Collate = exports.CollateEnum = void 0;
@@ -158,27 +160,35 @@ const orderByMetadata = new Map();
  * Decorator to set column-level collation
  *
  * Usage:
+ * ```ts
  *   @Collate(Collate.UTF8MB4_UNICODE_CI)
  *   @Column
  *   name: string;
+ * ```
  *
  * Or with options:
+ * ```ts
  *   @Collate({ collate: Collate.UTF8MB4_BIN, unique: true })
  *   @Column
  *   email: string;
+ * ```
  */
 /**
  * Decorator to set column-level collation
  *
  * Usage:
+ * ```ts
  *   @SetCollate(CollateEnum.UTF8MB4_UNICODE_CI)
  *   @Column
  *   name: string;
+ * ```
  *
  * Or with options:
+ * ```ts
  *   @SetCollate({ collate: CollateEnum.UTF8MB4_BIN, unique: true })
  *   @Column
  *   email: string;
+ * ```
  */
 function SetCollate(collation) {
     return function (target, propertyKey) {
@@ -202,6 +212,7 @@ function SetCollate(collation) {
  * Decorator to set database-level options
  *
  * Usage:
+ * ```ts
  *   @Database({
  *     name: 'miapp',
  *     encoding: 'UTF8',
@@ -210,6 +221,7 @@ function SetCollate(collation) {
  *     connectionLimit: 25,
  *   })
  *   class Config extends Model {}
+ * ```
  */
 function Database(options) {
     return function (target) {
@@ -220,8 +232,10 @@ function Database(options) {
  * Decorator to set table-level collation and options
  *
  * Usage:
+ * ```ts
  *   @TableCollate({ collate: 'utf8mb4_spanish_ci', engine: 'InnoDB' })
  *   class User extends Model {}
+ * ```
  */
 function TableCollate(options) {
     return function (target) {
@@ -232,8 +246,10 @@ function TableCollate(options) {
  * Decorator to specify order by with collation
  *
  * Usage:
+ * ```ts
  *   @OrderBy('name', 'ASC', Collate.UTF8MB4_SPANISH_CI)
  *   class User extends Model {}
+ * ```
  */
 function OrderBy(column, direction = 'ASC', collate) {
     return function (target) {

package/dist/decorators/comment.d.ts

@@ -1,5 +1,5 @@
 /**
- * @Comment decorator for database schema annotations
+ * `@Comment` decorator for database schema annotations
  *
  * Provides the ability to add comments to various database objects:
  * - Table-level comments (on model classes)
@@ -9,6 +9,7 @@
  *
  * Usage:
  *
+ * ```ts
  *  @Comment('This table stores user information')
  *  class User extends Model { ... }
  *
@@ -19,6 +20,7 @@
  *  @Column
  *  @Comment('User email address')
  *  email: string;
+ * ```
  */
 export interface CommentOptions {
     value: string;

package/dist/decorators/comment.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * @Comment decorator for database schema annotations
+ * `@Comment` decorator for database schema annotations
  *
  * Provides the ability to add comments to various database objects:
  * - Table-level comments (on model classes)
@@ -10,6 +10,7 @@
  *
  * Usage:
  *
+ * ```ts
  *  @Comment('This table stores user information')
  *  class User extends Model { ... }
  *
@@ -20,6 +21,7 @@
  *  @Column
  *  @Comment('User email address')
  *  email: string;
+ * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CommentRegistry = void 0;