ts-prorm-orm 1.1.0

package/dist/decorators/fk-constraints.js

@@ -0,0 +1,594 @@
+"use strict";
+/**
+ * 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];
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OnDelete = OnDelete;
+exports.OnUpdate = OnUpdate;
+exports.References = References;
+exports.Deferrable = Deferrable;
+exports.Unique = Unique;
+exports.AutoIncrement = AutoIncrement;
+exports.Identity = Identity;
+exports.GeneratedAlways = GeneratedAlways;
+exports.Exclusion = Exclusion;
+exports.getForeignKeyMetadata = getForeignKeyMetadata;
+exports.getAllForeignKeyMetadata = getAllForeignKeyMetadata;
+exports.getUniqueMetadata = getUniqueMetadata;
+exports.getAllUniqueMetadata = getAllUniqueMetadata;
+exports.getAutoIncrementMetadata = getAutoIncrementMetadata;
+exports.getAllAutoIncrementMetadata = getAllAutoIncrementMetadata;
+exports.getIdentityMetadata = getIdentityMetadata;
+exports.getAllIdentityMetadata = getAllIdentityMetadata;
+exports.getGeneratedAlwaysMetadata = getGeneratedAlwaysMetadata;
+exports.getAllGeneratedAlwaysMetadata = getAllGeneratedAlwaysMetadata;
+exports.getExclusionMetadata = getExclusionMetadata;
+exports.getAllExclusionMetadata = getAllExclusionMetadata;
+exports.buildOnDeleteSQL = buildOnDeleteSQL;
+exports.buildOnUpdateSQL = buildOnUpdateSQL;
+exports.buildReferencesSQL = buildReferencesSQL;
+exports.buildDeferrableSQL = buildDeferrableSQL;
+exports.buildAutoIncrementSQL = buildAutoIncrementSQL;
+exports.buildIdentitySQL = buildIdentitySQL;
+exports.buildGeneratedAlwaysSQL = buildGeneratedAlwaysSQL;
+exports.buildExclusionSQL = buildExclusionSQL;
+require("reflect-metadata");
+// ==================== Metadata Keys ====================
+const FOREIGN_KEY_META_KEY = Symbol('orm:foreignKey');
+const UNIQUE_META_KEY = Symbol('orm:unique');
+const AUTO_INCREMENT_META_KEY = Symbol('orm:autoIncrement');
+const IDENTITY_META_KEY = Symbol('orm:identity');
+const GENERATED_ALWAYS_META_KEY = Symbol('orm:generatedAlways');
+const EXCLUSION_META_KEY = Symbol('orm:exclusion');
+// ==================== OnDelete Decorator ====================
+/**
+ * @OnDelete - Specify foreign key ON DELETE action
+ *
+ * @OnDelete('CASCADE')
+ * roleId: number;
+ *
+ * @param action - The delete action (CASCADE, RESTRICT, SET NULL, SET DEFAULT, NO ACTION)
+ */
+function OnDelete(action) {
+    return function (target, propertyKey) {
+        const key = String(propertyKey);
+        const existing = Reflect.getMetadata(FOREIGN_KEY_META_KEY, target, key) || {
+            propertyName: key,
+        };
+        Reflect.defineMetadata(FOREIGN_KEY_META_KEY, { ...existing, onDelete: action }, target, key);
+    };
+}
+// ==================== OnUpdate Decorator ====================
+/**
+ * @OnUpdate - Specify foreign key ON UPDATE action
+ *
+ * @OnUpdate('CASCADE')
+ * roleId: number;
+ *
+ * @param action - The update action (CASCADE, RESTRICT, SET NULL, SET DEFAULT, NO ACTION)
+ */
+function OnUpdate(action) {
+    return function (target, propertyKey) {
+        const key = String(propertyKey);
+        const existing = Reflect.getMetadata(FOREIGN_KEY_META_KEY, target, key) || {
+            propertyName: key,
+        };
+        Reflect.defineMetadata(FOREIGN_KEY_META_KEY, { ...existing, onUpdate: action }, target, key);
+    };
+}
+// ==================== References Decorator ====================
+/**
+ * @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
+ */
+function References(options) {
+    return function (target, propertyKey) {
+        const key = String(propertyKey);
+        const existing = Reflect.getMetadata(FOREIGN_KEY_META_KEY, target, key) || {
+            propertyName: key,
+        };
+        Reflect.defineMetadata(FOREIGN_KEY_META_KEY, { ...existing, references: options }, target, key);
+    };
+}
+// ==================== Deferrable Decorator ====================
+/**
+ * @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)
+ */
+function Deferrable(options) {
+    return function (target, propertyKey) {
+        const key = String(propertyKey);
+        const existing = Reflect.getMetadata(FOREIGN_KEY_META_KEY, target, key) || {
+            propertyName: key,
+        };
+        const deferOpts = typeof options === 'string' ? { deferrable: options } : options;
+        Reflect.defineMetadata(FOREIGN_KEY_META_KEY, { ...existing, deferrable: deferOpts }, target, key);
+    };
+}
+// ==================== Unique Decorator ====================
+/**
+ * @Unique - Add unique constraint to a column
+ *
+ * @Unique('user_email')
+ * email: string;
+ *
+ * @param name - Optional constraint name
+ */
+function Unique(name) {
+    return function (target, propertyKey) {
+        const key = String(propertyKey);
+        const metadata = {
+            propertyName: key,
+            constraintName: name,
+        };
+        Reflect.defineMetadata(UNIQUE_META_KEY, metadata, target, key);
+    };
+}
+// ==================== AutoIncrement Decorator ====================
+/**
+ * @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
+ */
+function AutoIncrement(options) {
+    return function (target, propertyKey) {
+        const key = String(propertyKey);
+        const metadata = {
+            propertyName: key,
+            options,
+        };
+        Reflect.defineMetadata(AUTO_INCREMENT_META_KEY, metadata, target, key);
+    };
+}
+// ==================== Identity Decorator ====================
+/**
+ * @Identity - Configure sequence-based identity (PostgreSQL)
+ *
+ * @Identity({
+ *   type: 'ALWAYS',
+ *   start: 1,
+ *   increment: 1
+ * })
+ * id: number;
+ *
+ * @param options - Identity configuration
+ */
+function Identity(options) {
+    return function (target, propertyKey) {
+        const key = String(propertyKey);
+        const metadata = {
+            propertyName: key,
+            options,
+        };
+        Reflect.defineMetadata(IDENTITY_META_KEY, metadata, target, key);
+    };
+}
+// ==================== GeneratedAlways Decorator ====================
+/**
+ * @GeneratedAlways - Define a generated column (PostgreSQL 12+)
+ *
+ * @GeneratedAlways({
+ *   as: 'id + 1',
+ *   stored: true
+ * })
+ * sequenceNumber: number;
+ *
+ * @param options - Generated column configuration
+ */
+function GeneratedAlways(options) {
+    return function (target, propertyKey) {
+        const key = String(propertyKey);
+        const metadata = {
+            propertyName: key,
+            options,
+        };
+        Reflect.defineMetadata(GENERATED_ALWAYS_META_KEY, metadata, target, key);
+    };
+}
+// ==================== Exclusion Decorator ====================
+/**
+ * @Exclusion - Define exclusion constraint (PostgreSQL)
+ *
+ * @Exclusion({
+ *   using: 'daterange',
+ *   elements: ['daterange WITH &&']
+ * })
+ * bookingRange: [Date, Date];
+ *
+ * @param options - Exclusion constraint configuration
+ */
+function Exclusion(options) {
+    return function (target, propertyKey) {
+        const key = String(propertyKey);
+        const metadata = {
+            propertyName: key,
+            options,
+        };
+        Reflect.defineMetadata(EXCLUSION_META_KEY, metadata, target, key);
+    };
+}
+// ==================== Helper Functions ====================
+/**
+ * Get foreign key metadata for a property.
+ */
+function getForeignKeyMetadata(target, propertyKey) {
+    return Reflect.getMetadata(FOREIGN_KEY_META_KEY, target, propertyKey);
+}
+/**
+ * Get all foreign key metadata for a class.
+ */
+function getAllForeignKeyMetadata(target) {
+    const result = new Map();
+    const keys = Object.getOwnPropertyNames(target);
+    for (const key of keys) {
+        const metadata = getForeignKeyMetadata(target, key);
+        if (metadata) {
+            result.set(key, metadata);
+        }
+    }
+    // Check prototype chain
+    const proto = Object.getPrototypeOf(target);
+    if (proto && Object.getPrototypeOf(proto) !== null) {
+        const inherited = getAllForeignKeyMetadata(proto);
+        for (const [key, value] of inherited) {
+            if (!result.has(key)) {
+                result.set(key, value);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Get unique metadata for a property.
+ */
+function getUniqueMetadata(target, propertyKey) {
+    return Reflect.getMetadata(UNIQUE_META_KEY, target, propertyKey);
+}
+/**
+ * Get all unique metadata for a class.
+ */
+function getAllUniqueMetadata(target) {
+    const result = new Map();
+    const keys = Object.getOwnPropertyNames(target);
+    for (const key of keys) {
+        const metadata = getUniqueMetadata(target, key);
+        if (metadata) {
+            result.set(key, metadata);
+        }
+    }
+    const proto = Object.getPrototypeOf(target);
+    if (proto && Object.getPrototypeOf(proto) !== null) {
+        const inherited = getAllUniqueMetadata(proto);
+        for (const [key, value] of inherited) {
+            if (!result.has(key)) {
+                result.set(key, value);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Get auto-increment metadata for a property.
+ */
+function getAutoIncrementMetadata(target, propertyKey) {
+    return Reflect.getMetadata(AUTO_INCREMENT_META_KEY, target, propertyKey);
+}
+/**
+ * Get all auto-increment metadata for a class.
+ */
+function getAllAutoIncrementMetadata(target) {
+    const result = new Map();
+    const keys = Object.getOwnPropertyNames(target);
+    for (const key of keys) {
+        const metadata = getAutoIncrementMetadata(target, key);
+        if (metadata) {
+            result.set(key, metadata);
+        }
+    }
+    const proto = Object.getPrototypeOf(target);
+    if (proto && Object.getPrototypeOf(proto) !== null) {
+        const inherited = getAllAutoIncrementMetadata(proto);
+        for (const [key, value] of inherited) {
+            if (!result.has(key)) {
+                result.set(key, value);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Get identity metadata for a property.
+ */
+function getIdentityMetadata(target, propertyKey) {
+    return Reflect.getMetadata(IDENTITY_META_KEY, target, propertyKey);
+}
+/**
+ * Get all identity metadata for a class.
+ */
+function getAllIdentityMetadata(target) {
+    const result = new Map();
+    const keys = Object.getOwnPropertyNames(target);
+    for (const key of keys) {
+        const metadata = getIdentityMetadata(target, key);
+        if (metadata) {
+            result.set(key, metadata);
+        }
+    }
+    const proto = Object.getPrototypeOf(target);
+    if (proto && Object.getPrototypeOf(proto) !== null) {
+        const inherited = getAllIdentityMetadata(proto);
+        for (const [key, value] of inherited) {
+            if (!result.has(key)) {
+                result.set(key, value);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Get generated always metadata for a property.
+ */
+function getGeneratedAlwaysMetadata(target, propertyKey) {
+    return Reflect.getMetadata(GENERATED_ALWAYS_META_KEY, target, propertyKey);
+}
+/**
+ * Get all generated always metadata for a class.
+ */
+function getAllGeneratedAlwaysMetadata(target) {
+    const result = new Map();
+    const keys = Object.getOwnPropertyNames(target);
+    for (const key of keys) {
+        const metadata = getGeneratedAlwaysMetadata(target, key);
+        if (metadata) {
+            result.set(key, metadata);
+        }
+    }
+    const proto = Object.getPrototypeOf(target);
+    if (proto && Object.getPrototypeOf(proto) !== null) {
+        const inherited = getAllGeneratedAlwaysMetadata(proto);
+        for (const [key, value] of inherited) {
+            if (!result.has(key)) {
+                result.set(key, value);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Get exclusion metadata for a property.
+ */
+function getExclusionMetadata(target, propertyKey) {
+    return Reflect.getMetadata(EXCLUSION_META_KEY, target, propertyKey);
+}
+/**
+ * Get all exclusion metadata for a class.
+ */
+function getAllExclusionMetadata(target) {
+    const result = new Map();
+    const keys = Object.getOwnPropertyNames(target);
+    for (const key of keys) {
+        const metadata = getExclusionMetadata(target, key);
+        if (metadata) {
+            result.set(key, metadata);
+        }
+    }
+    const proto = Object.getPrototypeOf(target);
+    if (proto && Object.getPrototypeOf(proto) !== null) {
+        const inherited = getAllExclusionMetadata(proto);
+        for (const [key, value] of inherited) {
+            if (!result.has(key)) {
+                result.set(key, value);
+            }
+        }
+    }
+    return result;
+}
+// ==================== SQL Builders ====================
+/**
+ * Build ON DELETE SQL clause.
+ */
+function buildOnDeleteSQL(action) {
+    return `ON DELETE ${action}`;
+}
+/**
+ * Build ON UPDATE SQL clause.
+ */
+function buildOnUpdateSQL(action) {
+    return `ON UPDATE ${action}`;
+}
+/**
+ * Build REFERENCES SQL clause.
+ */
+function buildReferencesSQL(options) {
+    const modelName = typeof options.model === 'string' ? options.model : options.model.name;
+    const key = options.key || 'id';
+    let sql = `REFERENCES "${modelName}"("${key}")`;
+    if (options.deferrable) {
+        sql += ` DEFERRABLE ${options.deferrable}`;
+    }
+    return sql;
+}
+/**
+ * Build DEFERRABLE SQL clause.
+ */
+function buildDeferrableSQL(options) {
+    let sql = `DEFERRABLE ${options.deferrable}`;
+    if (options.deferFor) {
+        sql += ` INITIALLY ${options.deferFor === 'NOT DEFERRABLE' ? 'NOT DEFERRED' : options.deferFor.replace('INITIALLY ', '')}`;
+    }
+    return sql;
+}
+/**
+ * Build AUTO_INCREMENT / IDENTITY SQL.
+ */
+function buildAutoIncrementSQL(options) {
+    const parts = [];
+    if (options.start !== undefined) {
+        parts.push(`START WITH ${options.start}`);
+    }
+    if (options.increment !== undefined) {
+        parts.push(`INCREMENT BY ${options.increment}`);
+    }
+    if (options.minValue !== undefined) {
+        parts.push(`MINVALUE ${options.minValue}`);
+    }
+    if (options.maxValue !== undefined) {
+        parts.push(`MAXVALUE ${options.maxValue}`);
+    }
+    if (options.cache !== undefined) {
+        parts.push(`CACHE ${options.cache}`);
+    }
+    if (options.cycle) {
+        parts.push('CYCLE');
+    }
+    if (options.sequence) {
+        parts.push(`SEQUENCE ${options.sequence}`);
+    }
+    return parts.length > 0 ? parts.join(' ') : '';
+}
+/**
+ * Build IDENTITY SQL (PostgreSQL).
+ */
+function buildIdentitySQL(options) {
+    const type = options.type || 'ALWAYS';
+    const parts = [`GENERATED ${type} AS IDENTITY`];
+    if (options.start !== undefined || options.increment !== undefined) {
+        const seqParts = ['('];
+        if (options.start !== undefined) {
+            seqParts.push(`START WITH ${options.start}`);
+        }
+        if (options.increment !== undefined) {
+            seqParts.push(`INCREMENT BY ${options.increment}`);
+        }
+        if (options.min !== undefined) {
+            seqParts.push(`MINVALUE ${options.min}`);
+        }
+        if (options.max !== undefined) {
+            seqParts.push(`MAXVALUE ${options.max}`);
+        }
+        if (options.cache !== undefined) {
+            seqParts.push(`CACHE ${options.cache}`);
+        }
+        if (options.cycle) {
+            seqParts.push('CYCLE');
+        }
+        seqParts.push(')');
+        parts.push(seqParts.join(' '));
+    }
+    return parts.join(' ');
+}
+/**
+ * Build GENERATED ALWAYS SQL (PostgreSQL 12+).
+ */
+function buildGeneratedAlwaysSQL(options) {
+    const stored = options.stored ? 'STORED' : 'VIRTUAL';
+    return `GENERATED ALWAYS AS (${options.as}) ${stored}`;
+}
+/**
+ * Build EXCLUSION constraint SQL (PostgreSQL).
+ */
+function buildExclusionSQL(tableName, options) {
+    const name = options.name || `excl_${tableName}_${Date.now().toString(36)}`;
+    const using = options.using || 'gist';
+    const elements = options.elements.join(', ');
+    return `CONSTRAINT "${name}" EXCLUDE USING ${using} (${elements})`;
+}