ts-prorm-orm 1.1.0 → 1.2.0

package/dist/decorators/fk-constraints.d.ts

@@ -0,0 +1,387 @@
+/**
+ * Foreign Key Constraints and Column Options Decorators for the ORM.
+ *
+ * Provides decorators for:
+ * - FK cascade options (ON DELETE, ON UPDATE)
+ * - FK references definition
+ * - Deferrable constraints
+ * - Unique constraints
+ * - Auto-increment / Identity configuration
+ * - Generated columns (PostgreSQL 12+)
+ * - Exclusion constraints
+ *
+ * Usage Examples:
+ *
+ * // Foreign Key cascade options
+ * @OnDelete('CASCADE')
+ * @OnUpdate('CASCADE')
+ * @References({ model: Role, key: 'id' })
+ * roleId: number;
+ *
+ * // Multiple FK options with deferrable
+ * @OnDelete('RESTRICT')
+ * @OnUpdate('SET NULL')
+ * @References({
+ *   model: User,
+ *   key: 'id',
+ *   deferrable: 'INITIALLY DEFERRED'
+ * })
+ * assignedTo: number;
+ *
+ * // Deferrable constraint
+ * @Deferrable('INITIALLY DEFERRED')
+ * @Unique('user_email')
+ * email: string;
+ *
+ * // AutoIncrement with custom settings
+ * @AutoIncrement({
+ *   start: 1000,
+ *   increment: 1,
+ *   cache: 1000,
+ *   minValue: 1,
+ *   maxValue: 999999,
+ *   cycle: false,
+ *   sequence: 'user_id_seq'
+ * })
+ * id: number;
+ *
+ * // Sequence-based identity (PostgreSQL)
+ * @Identity({
+ *   type: 'ALWAYS',
+ *   start: 1,
+ *   increment: 1
+ * })
+ * id: number;
+ *
+ * // Generated column (PostgreSQL 12+)
+ * @GeneratedAlways({
+ *   as: 'id + 1',
+ *   stored: true
+ * })
+ * sequenceNumber: number;
+ *
+ * // Exclusion constraint (PostgreSQL)
+ * @Exclusion({
+ *   using: 'daterange',
+ *   elements: ['daterange WITH &&']
+ * })
+ * bookingRange: [Date, Date];
+ */
+import 'reflect-metadata';
+/**
+ * Foreign key action types for ON DELETE / ON UPDATE
+ */
+export type ForeignKeyAction = 'CASCADE' | 'RESTRICT' | 'SET NULL' | 'SET DEFAULT' | 'NO ACTION';
+/**
+ * Deferrable type for foreign key constraints
+ */
+export type DeferrableType = 'NOT DEFERRABLE' | 'INITIALLY IMMEDIATE' | 'INITIALLY DEFERRED';
+/**
+ * Identity type for auto-increment columns
+ */
+export type IdentityType = 'ALWAYS' | 'BY DEFAULT';
+/**
+ * Options for @References decorator
+ */
+export interface ReferencesOptions {
+    /** Referenced model (class or string model name) */
+    model: Function | string;
+    /** Referenced column key (default: 'id') */
+    key?: string;
+    /** FK constraint name (auto-generated if not provided) */
+    name?: string;
+    /** Make constraint deferrable */
+    deferrable?: DeferrableType;
+}
+/**
+ * Options for @Deferrable decorator
+ */
+export interface DeferrableOptions {
+    /** Deferrable type */
+    deferrable: DeferrableType;
+    /** Override for specific operation */
+    deferFor?: DeferrableType;
+}
+/**
+ * Options for @AutoIncrement decorator
+ */
+export interface AutoIncrementOptions {
+    /** Starting value for the sequence */
+    start?: number;
+    /** Increment value */
+    increment?: number;
+    /** Number of values to cache */
+    cache?: number;
+    /** Minimum value */
+    minValue?: number;
+    /** Maximum value */
+    maxValue?: number;
+    /** Whether to cycle when exhausted */
+    cycle?: boolean;
+    /** Custom sequence name (PostgreSQL) */
+    sequence?: string;
+}
+/**
+ * Options for @Identity decorator (PostgreSQL sequences)
+ */
+export interface IdentityOptions {
+    /** Identity type: ALWAYS or BY DEFAULT */
+    type?: IdentityType;
+    /** Starting value */
+    start?: number;
+    /** Increment value */
+    increment?: number;
+    /** Cache size */
+    cache?: number;
+    /** Minimum value */
+    min?: number;
+    /** Maximum value */
+    max?: number;
+    /** Whether to cycle */
+    cycle?: boolean;
+}
+/**
+ * Options for @GeneratedAlways decorator (PostgreSQL 12+)
+ */
+export interface GeneratedAlwaysOptions {
+    /** SQL expression for generated column */
+    as: string;
+    /** Whether column is stored (vs virtual) */
+    stored?: boolean;
+    /** Column type (required for stored generated columns) */
+    type?: string;
+}
+/**
+ * Options for @Exclusion decorator (PostgreSQL)
+ */
+export interface ExclusionOptions {
+    /** Index using method (gist, btree, etc.) */
+    using?: string;
+    /** Exclusion elements with operators */
+    elements: string[];
+    /** Constraint name */
+    name?: string;
+}
+/**
+ * Metadata stored on property
+ */
+export interface ForeignKeyMetadata {
+    propertyName: string;
+    onDelete?: ForeignKeyAction;
+    onUpdate?: ForeignKeyAction;
+    references?: ReferencesOptions;
+    deferrable?: DeferrableOptions;
+}
+export interface UniqueMetadata {
+    propertyName: string;
+    constraintName?: string;
+}
+export interface AutoIncrementMetadata {
+    propertyName: string;
+    options: AutoIncrementOptions;
+}
+export interface IdentityMetadata {
+    propertyName: string;
+    options: IdentityOptions;
+}
+export interface GeneratedAlwaysMetadata {
+    propertyName: string;
+    options: GeneratedAlwaysOptions;
+}
+export interface ExclusionMetadata {
+    propertyName: string;
+    options: ExclusionOptions;
+}
+/**
+ * @OnDelete - Specify foreign key ON DELETE action
+ *
+ * @OnDelete('CASCADE')
+ * roleId: number;
+ *
+ * @param action - The delete action (CASCADE, RESTRICT, SET NULL, SET DEFAULT, NO ACTION)
+ */
+export declare function OnDelete(action: ForeignKeyAction): PropertyDecorator;
+/**
+ * @OnUpdate - Specify foreign key ON UPDATE action
+ *
+ * @OnUpdate('CASCADE')
+ * roleId: number;
+ *
+ * @param action - The update action (CASCADE, RESTRICT, SET NULL, SET DEFAULT, NO ACTION)
+ */
+export declare function OnUpdate(action: ForeignKeyAction): PropertyDecorator;
+/**
+ * @References - Define foreign key references
+ *
+ * @References({ model: Role, key: 'id' })
+ * roleId: number;
+ *
+ * @References({
+ *   model: User,
+ *   key: 'id',
+ *   deferrable: 'INITIALLY DEFERRED'
+ * })
+ * assignedTo: number;
+ *
+ * @param options - Reference configuration
+ */
+export declare function References(options: ReferencesOptions): PropertyDecorator;
+/**
+ * @Deferrable - Make constraint deferrable
+ *
+ * @Deferrable('INITIALLY DEFERRED')
+ * email: string;
+ *
+ * // With operation override
+ * @Deferrable({
+ *   deferrable: 'INITIALLY IMMEDIATE',
+ *   deferFor: 'NOT DEFERRABLE'
+ * })
+ * departmentId: number;
+ *
+ * @param options - Deferrable configuration (string or object)
+ */
+export declare function Deferrable(options: DeferrableType | DeferrableOptions): PropertyDecorator;
+/**
+ * @Unique - Add unique constraint to a column
+ *
+ * @Unique('user_email')
+ * email: string;
+ *
+ * @param name - Optional constraint name
+ */
+export declare function Unique(name?: string): PropertyDecorator;
+/**
+ * @AutoIncrement - Configure auto-increment with custom settings
+ *
+ * @AutoIncrement({
+ *   start: 1000,
+ *   increment: 1,
+ *   cache: 1000,
+ *   minValue: 1,
+ *   maxValue: 999999,
+ *   cycle: false,
+ *   sequence: 'user_id_seq'
+ * })
+ * id: number;
+ *
+ * @param options - Auto-increment configuration
+ */
+export declare function AutoIncrement(options: AutoIncrementOptions): PropertyDecorator;
+/**
+ * @Identity - Configure sequence-based identity (PostgreSQL)
+ *
+ * @Identity({
+ *   type: 'ALWAYS',
+ *   start: 1,
+ *   increment: 1
+ * })
+ * id: number;
+ *
+ * @param options - Identity configuration
+ */
+export declare function Identity(options: IdentityOptions): PropertyDecorator;
+/**
+ * @GeneratedAlways - Define a generated column (PostgreSQL 12+)
+ *
+ * @GeneratedAlways({
+ *   as: 'id + 1',
+ *   stored: true
+ * })
+ * sequenceNumber: number;
+ *
+ * @param options - Generated column configuration
+ */
+export declare function GeneratedAlways(options: GeneratedAlwaysOptions): PropertyDecorator;
+/**
+ * @Exclusion - Define exclusion constraint (PostgreSQL)
+ *
+ * @Exclusion({
+ *   using: 'daterange',
+ *   elements: ['daterange WITH &&']
+ * })
+ * bookingRange: [Date, Date];
+ *
+ * @param options - Exclusion constraint configuration
+ */
+export declare function Exclusion(options: ExclusionOptions): PropertyDecorator;
+/**
+ * Get foreign key metadata for a property.
+ */
+export declare function getForeignKeyMetadata(target: object, propertyKey: string): ForeignKeyMetadata | undefined;
+/**
+ * Get all foreign key metadata for a class.
+ */
+export declare function getAllForeignKeyMetadata(target: object): Map<string, ForeignKeyMetadata>;
+/**
+ * Get unique metadata for a property.
+ */
+export declare function getUniqueMetadata(target: object, propertyKey: string): UniqueMetadata | undefined;
+/**
+ * Get all unique metadata for a class.
+ */
+export declare function getAllUniqueMetadata(target: object): Map<string, UniqueMetadata>;
+/**
+ * Get auto-increment metadata for a property.
+ */
+export declare function getAutoIncrementMetadata(target: object, propertyKey: string): AutoIncrementMetadata | undefined;
+/**
+ * Get all auto-increment metadata for a class.
+ */
+export declare function getAllAutoIncrementMetadata(target: object): Map<string, AutoIncrementMetadata>;
+/**
+ * Get identity metadata for a property.
+ */
+export declare function getIdentityMetadata(target: object, propertyKey: string): IdentityMetadata | undefined;
+/**
+ * Get all identity metadata for a class.
+ */
+export declare function getAllIdentityMetadata(target: object): Map<string, IdentityMetadata>;
+/**
+ * Get generated always metadata for a property.
+ */
+export declare function getGeneratedAlwaysMetadata(target: object, propertyKey: string): GeneratedAlwaysMetadata | undefined;
+/**
+ * Get all generated always metadata for a class.
+ */
+export declare function getAllGeneratedAlwaysMetadata(target: object): Map<string, GeneratedAlwaysMetadata>;
+/**
+ * Get exclusion metadata for a property.
+ */
+export declare function getExclusionMetadata(target: object, propertyKey: string): ExclusionMetadata | undefined;
+/**
+ * Get all exclusion metadata for a class.
+ */
+export declare function getAllExclusionMetadata(target: object): Map<string, ExclusionMetadata>;
+/**
+ * Build ON DELETE SQL clause.
+ */
+export declare function buildOnDeleteSQL(action: ForeignKeyAction): string;
+/**
+ * Build ON UPDATE SQL clause.
+ */
+export declare function buildOnUpdateSQL(action: ForeignKeyAction): string;
+/**
+ * Build REFERENCES SQL clause.
+ */
+export declare function buildReferencesSQL(options: ReferencesOptions): string;
+/**
+ * Build DEFERRABLE SQL clause.
+ */
+export declare function buildDeferrableSQL(options: DeferrableOptions): string;
+/**
+ * Build AUTO_INCREMENT / IDENTITY SQL.
+ */
+export declare function buildAutoIncrementSQL(options: AutoIncrementOptions): string;
+/**
+ * Build IDENTITY SQL (PostgreSQL).
+ */
+export declare function buildIdentitySQL(options: IdentityOptions): string;
+/**
+ * Build GENERATED ALWAYS SQL (PostgreSQL 12+).
+ */
+export declare function buildGeneratedAlwaysSQL(options: GeneratedAlwaysOptions): string;
+/**
+ * Build EXCLUSION constraint SQL (PostgreSQL).
+ */
+export declare function buildExclusionSQL(tableName: string, options: ExclusionOptions): string;

package/dist/decorators/foreign-table.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @ForeignTable class decorator
+ * for PostgreSQL FOREIGN TABLE with Redis caching
+ */
+import type { Prorm } from '../prorm';
+export interface RedisClient {
+    set(key: string, value: string, mode?: string, ttl?: number): Promise<string>;
+    get(key: string): Promise<string | null>;
+    del(key: string): Promise<number>;
+    exists(key: string): Promise<number>;
+    expire(key: string, seconds: number): Promise<number>;
+    ttl(key: string): Promise<number>;
+    multi(): RedisMulti;
+}
+export interface RedisMulti {
+    set(key: string, value: string, mode?: string, ttl?: number): RedisMulti;
+    get(key: string): RedisMulti;
+    del(key: string): RedisMulti;
+    expire(key: string, seconds: number): RedisMulti;
+    exec(): Promise<Array<[Error | null, any]>>;
+}
+export interface ForeignTableCacheOptions {
+    redis?: boolean;
+    ttl?: number;
+    keyPrefix?: string;
+}
+export interface ForeignTableUserMapping {
+    user: string;
+    options?: Record<string, string>;
+}
+export interface ForeignTableOptions {
+    server: string;
+    foreignSchema?: string;
+    options?: Record<string, string>;
+    userMappings?: ForeignTableUserMapping[];
+    columns?: Record<string, {
+        type: string;
+        options?: string;
+    }>;
+    cache?: ForeignTableCacheOptions;
+    ifNotExists?: boolean;
+    schema?: string;
+}
+export declare function setForeignTableRedisClient(client: RedisClient): void;
+export declare function getForeignTableRedisClient(): RedisClient | null;
+export declare function ForeignTable(options: ForeignTableOptions): (target: Function) => void;
+export declare function getForeignTableOptions(target: Function): ForeignTableOptions | undefined;
+export declare function isForeignTable(target: Function): boolean;
+export declare function cacheForeignTableOptions(target: Function, options?: ForeignTableOptions): Promise<void>;
+export declare function getCachedForeignTableOptions(target: Function): Promise<ForeignTableOptions | null>;
+export declare function invalidateForeignTableCache(target: Function): Promise<void>;
+export declare function warmupForeignTableCache(target: Function, prorm: Prorm): Promise<void>;
+export declare const ForeignTableRegistry: {
+    getOptions(target: Function): ForeignTableOptions | undefined;
+    isForeignTable(target: Function): boolean;
+    getSQL(target: Function): string;
+};

package/dist/decorators/generated.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Generated Column decorators for the ORM.
+ *
+ * Supports database-level computed columns:
+ * - VIRTUAL: Computed on read, not stored in DB
+ * - STORED: Computed on write, physically stored in DB
+ * - IDENTITY: Auto-increment primary key configuration
+ *
+ * Usage:
+ *
+ *   // Virtual computed column (default)
+ *   @Generated()
+ *   get fullName() {
+ *     return `${this.firstName} ${this.lastName}`;
+ *   }
+ *
+ *   // Stored computed column
+ *   @Generated('stored')
+ *   get total() {
+ *     return this.price * this.quantity;
+ *   }
+ *
+ *   // With custom expression
+ *   @Generated({
+ *     as: 'CONCAT(first_name, " ", last_name)',
+ *     type: 'varchar(255)',
+ *     stored: true
+ *   })
+ *   fullName: string;
+ *
+ *   // Identity/Auto-increment configuration
+ *   @Generated({
+ *     identity: true,
+ *     start: 1,
+ *     increment: 1,
+ *     cache: 1000
+ *   })
+ *   id: number;
+ */
+import 'reflect-metadata';
+/**
+ * Generated column type - how the column value is computed
+ */
+export type GeneratedType = 'virtual' | 'stored';
+/**
+ * Supported SQL dialect identifiers used throughout the ORM
+ */
+export type GeneratedDialect = 'mysql' | 'mariadb' | 'postgres' | 'mssql' | 'oracle' | 'sqlite';
+/**
+ * Options for @Generated decorator
+ */
+export interface GeneratedOptions {
+    /**
+     * Column type (required for stored/generated columns)
+     * Example: 'varchar(255)', 'integer', 'decimal(10,2)'
+     */
+    type?: string;
+    /**
+     * SQL expression for the generated column
+     * Example: 'CONCAT(first_name, " ", last_name)', 'price * quantity'
+     */
+    as?: string;
+    /**
+     * Whether the column is stored or virtual
+     * - 'virtual' (default): Computed on read, not stored in DB
+     * - 'stored': Computed on write, physically stored in DB
+     */
+    stored?: boolean;
+    /**
+     * Enable identity/auto-increment for the column
+     * PostgreSQL: IDENTITY, MySQL: AUTO_INCREMENT
+     */
+    identity?: boolean;
+    /**
+     * Starting value for identity sequence
+     * PostgreSQL: START WITH, MySQL: auto_increment
+     */
+    start?: number;
+    /**
+     * Increment value for identity sequence
+     * PostgreSQL: INCREMENT BY, MySQL: auto_increment_increment
+     */
+    increment?: number;
+    /**
+     * Number of sequence values to cache
+     * PostgreSQL: CACHE, MySQL: auto_increment_cache_size
+     */
+    cache?: number;
+    /**
+     * Minimum value for the sequence
+     */
+    min?: number;
+    /**
+     * Maximum value for the sequence
+     */
+    max?: number;
+    /**
+     * Whether the sequence cycles when exhausted
+     */
+    cycle?: boolean;
+    /**
+     * Custom sequence name (PostgreSQL specific)
+     */
+    sequence?: string;
+}
+/**
+ * Metadata stored on the target (class or property)
+ */
+export interface GeneratedMetadata {
+    /**
+     * The property name this decorator is applied to
+     */
+    propertyName?: string;
+    /**
+     * Whether it's a getter (for class property getters)
+     */
+    isGetter?: boolean;
+    /**
+     * Generated column options
+     */
+    options: GeneratedOptions;
+}
+/**
+ * Decorator for generated/computed columns.
+ *
+ * Usage with getter (for computed properties):
+ *
+ *   class User extends Model {
+ *     @Generated()
+ *     get fullName() {
+ *       return `${this.firstName} ${this.lastName}`;
+ *     }
+ *   }
+ *
+ * Usage with options:
+ *
+ *   @Generated({
+ *     as: 'CONCAT(first_name, " ", last_name)',
+ *     type: 'varchar(255)',
+ *     stored: true
+ *   })
+ *   fullName: string;
+ *
+ * @param options - Generated column options or just storage type
+ */
+export declare function Generated(options?: GeneratedOptions | GeneratedType): PropertyDecorator;
+/**
+ * Decorator specifically for identity/auto-increment columns.
+ *
+ * Usage:
+ *
+ *   @Generated({
+ *     identity: true,
+ *     start: 1,
+ *     increment: 1,
+ *     cache: 1000
+ *   })
+ *   id: number;
+ *
+ * @param options - Identity configuration options
+ */
+export declare function Identity(options: GeneratedOptions): PropertyDecorator;
+/**
+ * Get generated column metadata for a property.
+ *
+ * @param target - The target class or prototype
+ * @param propertyKey - The property name
+ * @returns The generated metadata or undefined
+ */
+export declare function getGeneratedMetadata(target: object, propertyKey: string): GeneratedMetadata | undefined;
+/**
+ * Get identity metadata for a property.
+ *
+ * @param target - The target class or prototype
+ * @param propertyKey - The property name
+ * @returns The identity metadata or undefined
+ */
+export declare function getIdentityMetadata(target: object, propertyKey: string): GeneratedMetadata | undefined;
+/**
+ * Get all generated column metadata for a class.
+ *
+ * @param target - The target class or prototype
+ * @returns Map of property names to their generated metadata
+ */
+export declare function getAllGeneratedMetadata(target: object): Map<string, GeneratedMetadata>;
+/**
+ * Get all identity metadata for a class.
+ *
+ * @param target - The target class or prototype
+ * @returns Map of property names to their identity metadata
+ */
+export declare function getAllIdentityMetadata(target: object): Map<string, GeneratedMetadata>;
+/**
+ * Check if a property is a generated column.
+ *
+ * @param target - The target class or prototype
+ * @param propertyKey - The property name
+ * @returns True if the property is generated
+ */
+export declare function isGeneratedColumn(target: object, propertyKey: string): boolean;
+/**
+ * Check if a property is an identity/auto-increment column.
+ *
+ * @param target - The target class or prototype
+ * @param propertyKey - The property name
+ * @returns True if the property is an identity column
+ */
+export declare function isIdentityColumn(target: object, propertyKey: string): boolean;
+/**
+ * Build the SQL expression for a generated column.
+ *
+ * @param options - The generated column options
+ * @returns The SQL expression string
+ */
+export declare function buildGeneratedSQL(options: GeneratedOptions): string;
+/**
+ * Check if generated column is stored (persisted) or virtual.
+ *
+ * When `options.stored` is explicitly set, that value is used as-is.
+ * When it is left unspecified, the default depends on the target dialect:
+ * - PostgreSQL (before v18) only supports `STORED` generated columns —
+ *   `VIRTUAL` is not a valid option, so it defaults to `true` (stored).
+ * - MySQL/MariaDB support both `VIRTUAL` and `STORED`, and default to
+ *   `VIRTUAL` (the lighter-weight option), so this defaults to `false`.
+ * - Other dialects (sqlite, mssql, oracle) also default to `false`
+ *   (virtual/computed, not persisted), matching their typical defaults.
+ *
+ * @param options - The generated column options
+ * @param dialect - The target SQL dialect (defaults to 'mysql' for backwards compatibility)
+ * @returns True if stored, false if virtual
+ */
+export declare function isStored(options: GeneratedOptions, dialect?: GeneratedDialect): boolean;