ts-prorm-orm 1.1.0

package/dist/decorators/storage.js

@@ -0,0 +1,580 @@
+"use strict";
+/**
+ * Storage engine and physical storage decorators for the ORM.
+ *
+ * Provides decorators for configuring storage-level database options:
+ * - Storage engine (MySQL/MariaDB)
+ * - Tablespace (PostgreSQL)
+ * - Clustered/Non-clustered indexes (SQL Server)
+ * - Compression (PostgreSQL)
+ * - Row format and format options
+ * - Inheritance
+ * - Replica identity for replication
+ * - Statistics
+ * - ON COMMIT for temp tables
+ *
+ * Usage:
+ *
+ *   // MySQL/MariaDB storage engine
+ *   @Storage({ engine: 'InnoDB', rowFormat: 'DYNAMIC' })
+ *   class Order extends Model {}
+ *
+ *   // PostgreSQL tablespace
+ *   @Tablespace('tablespace_name')
+ *   @Table
+ *   class LargeTable extends Model {}
+ *
+ *   // SQL Server clustered index
+ *   @Clustered(true)
+ *   @Index({ columns: ['id'] })
+ *   class Data extends Model {}
+ *
+ *   // PostgreSQL compression
+ *   @Compression({ level: 6 })
+ *   @Column
+ *   blobData: Buffer;
+ *
+ *   // PostgreSQL inheritance
+ *   @Inherits('parent_table')
+ *   class ChildTable extends Model {}
+ *
+ *   // PostgreSQL replica identity
+ *   @ReplicaIdentity('FULL')
+ *   class SensitiveData extends Model {}
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Storage = Storage;
+exports.Tablespace = Tablespace;
+exports.TablespaceOptions = TablespaceOptions;
+exports.Clustered = Clustered;
+exports.Compression = Compression;
+exports.ReplicaIdentity = ReplicaIdentity;
+exports.Statistics = Statistics;
+exports.OnCommit = OnCommit;
+exports.Inherits = Inherits;
+exports.Partition = Partition;
+exports.ColumnStorage = ColumnStorage;
+exports.getStorageOptions = getStorageOptions;
+exports.getTablespaceOptions = getTablespaceOptions;
+exports.getClusteredOptions = getClusteredOptions;
+exports.getCompressionOptions = getCompressionOptions;
+exports.getReplicaIdentityOptions = getReplicaIdentityOptions;
+exports.getStatisticsOptions = getStatisticsOptions;
+exports.getOnCommitOption = getOnCommitOption;
+exports.getInheritsOptions = getInheritsOptions;
+exports.getColumnStorageOptions = getColumnStorageOptions;
+exports.generateStorageSQL = generateStorageSQL;
+exports.generateTablespaceSQL = generateTablespaceSQL;
+exports.generateClusteredSQL = generateClusteredSQL;
+exports.generateCompressionSQL = generateCompressionSQL;
+exports.generateReplicaIdentitySQL = generateReplicaIdentitySQL;
+exports.generateStatisticsSQL = generateStatisticsSQL;
+exports.generateInheritsSQL = generateInheritsSQL;
+exports.getPartitionOptions = getPartitionOptions;
+exports.generatePartitionSQL = generatePartitionSQL;
+exports.generatePartitionBoundSQL = generatePartitionBoundSQL;
+require("reflect-metadata");
+// ==================== Metadata Keys ====================
+const STORAGE_KEY = Symbol('prorm:storage');
+const TABLESPACE_KEY = Symbol('prorm:tablespace');
+const CLUSTERED_KEY = Symbol('prorm:clustered');
+const COMPRESSION_KEY = Symbol('prorm:compression');
+const REPLICA_IDENTITY_KEY = Symbol('prorm:replicaIdentity');
+const STATISTICS_KEY = Symbol('prorm:statistics');
+const ON_COMMIT_KEY = Symbol('prorm:onCommit');
+const INHERITS_KEY = Symbol('prorm:inherits');
+const COLUMN_STORAGE_KEY = Symbol('prorm:columnStorage');
+const PARTITION_KEY = Symbol('prorm:partition');
+// ==================== Class Decorators ====================
+/**
+ * Decorator to configure storage engine and table storage options.
+ *
+ * Usage:
+ *
+ *   @Storage({ engine: 'InnoDB', rowFormat: 'DYNAMIC' })
+ *   class Order extends Model {}
+ *
+ *   @Storage({ engine: 'MyISAM', rowFormat: 'FIXED' })
+ *   class LogData extends Model {}
+ *
+ * @param options - Storage configuration options
+ */
+function Storage(options = {}) {
+    return function (target) {
+        Reflect.defineMetadata(STORAGE_KEY, {
+            engine: options.engine || 'InnoDB',
+            rowFormat: options.rowFormat || 'DYNAMIC',
+            encryption: options.encryption,
+            comment: options.comment,
+            avgRowLength: options.avgRowLength,
+            maxRows: options.maxRows,
+            minRows: options.minRows,
+            password: options.password,
+            tablespace: options.tablespace,
+        }, target);
+    };
+}
+/**
+ * Decorator to specify tablespace for a table (PostgreSQL/MySQL).
+ *
+ * Usage:
+ *
+ *   @Tablespace('fast_storage')
+ *   @Table
+ *   class LargeTable extends Model {}
+ *
+ * @param name - Tablespace name
+ */
+function Tablespace(name) {
+    return function (target) {
+        Reflect.defineMetadata(TABLESPACE_KEY, { name }, target);
+    };
+}
+/**
+ * Decorator to specify tablespace with options (PostgreSQL).
+ *
+ * Usage:
+ *
+ *   @Tablespace({ name: 'fast_storage', indexTablespace: 'idx_space' })
+ *   @Table
+ *   class LargeTable extends Model {}
+ *
+ * @param options - Tablespace options
+ */
+function TablespaceOptions(options) {
+    return function (target) {
+        Reflect.defineMetadata(TABLESPACE_KEY, options, target);
+    };
+}
+/**
+ * Decorator to create a clustered or non-clustered index (SQL Server).
+ *
+ * Usage:
+ *
+ *   @Clustered(true)
+ *   @Index({ columns: ['id'] })
+ *   class Data extends Model {}
+ *
+ *   @Clustered({ type: 'nonclustered', include: ['name', 'email'] })
+ *   @Index({ columns: ['id'] })
+ *   class UserData extends Model {}
+ *
+ * @param options - Cluster options
+ */
+function Clustered(options = true) {
+    return function (target) {
+        const clusteredOptions = typeof options === 'boolean' ? { type: options ? 'clustered' : 'nonclustered' } : options;
+        Reflect.defineMetadata(CLUSTERED_KEY, clusteredOptions, target);
+    };
+}
+/**
+ * Decorator to specify compression options (PostgreSQL).
+ *
+ * Usage:
+ *
+ *   @Compression({ algorithm: 'lz4', level: 6 })
+ *   @Table
+ *   class LargeTable extends Model {}
+ *
+ * @param options - Compression options
+ */
+function Compression(options = {}) {
+    return function (target) {
+        Reflect.defineMetadata(COMPRESSION_KEY, {
+            algorithm: options.algorithm || 'pglz',
+            level: options.level ?? 6,
+            compressLevel: options.compressLevel,
+        }, target);
+    };
+}
+/**
+ * Decorator to set replica identity for logical replication (PostgreSQL).
+ *
+ * Usage:
+ *
+ *   @ReplicaIdentity('FULL')
+ *   class SensitiveData extends Model {}
+ *
+ *   @ReplicaIdentity({ type: 'INDEX', index: 'idx_user_email' })
+ *   class UserData extends Model {}
+ *
+ * @param options - Replica identity type or options
+ */
+function ReplicaIdentity(options) {
+    return function (target) {
+        const replicaOptions = typeof options === 'string' ? { type: options } : options;
+        Reflect.defineMetadata(REPLICA_IDENTITY_KEY, replicaOptions, target);
+    };
+}
+/**
+ * Decorator to configure statistics collection (PostgreSQL).
+ *
+ * Usage:
+ *
+ *   @Statistics({ for: 'columns', target: 500 })
+ *   @Table
+ *   class UserData extends Model {}
+ *
+ * @param options - Statistics options
+ */
+function Statistics(options = {}) {
+    return function (target) {
+        Reflect.defineMetadata(STATISTICS_KEY, {
+            for: options.for || 'columns',
+            columns: options.columns,
+            target: options.target,
+        }, target);
+    };
+}
+/**
+ * Decorator to set ON COMMIT behavior for temp tables (PostgreSQL).
+ *
+ * Usage:
+ *
+ *   @OnCommit('PRESERVE ROWS')
+ *   @Table({ temporary: true })
+ *   class TempData extends Model {}
+ *
+ * @param option - ON COMMIT option
+ */
+function OnCommit(option) {
+    return function (target) {
+        Reflect.defineMetadata(ON_COMMIT_KEY, { option }, target);
+    };
+}
+/**
+ * Decorator to specify table inheritance (PostgreSQL).
+ *
+ * Usage:
+ *
+ *   @Inherits('parent_table')
+ *   class ChildTable extends Model {}
+ *
+ *   @Inherits({ parentTable: 'parent', only: true })
+ *   class ChildOnlyTable extends Model {}
+ *
+ * @param options - Inheritance options (table name string or options object)
+ */
+function Inherits(options) {
+    return function (target) {
+        const inheritsOptions = typeof options === 'string' ? { parentTable: options } : options;
+        Reflect.defineMetadata(INHERITS_KEY, inheritsOptions, target);
+    };
+}
+/**
+ * Decorator to configure table partitioning (PostgreSQL 10+).
+ *
+ * Usage:
+ *
+ *   // Range partition by date
+ *   @Partition({ type: 'range', column: 'order_date' })
+ *   @Table
+ *   class Order extends Model {}
+ *
+ *   // List partition by region
+ *   @Partition({ type: 'list', column: 'region' })
+ *   @Table
+ *   class Customer extends Model {}
+ *
+ *   // Hash partition by id
+ *   @Partition({ type: 'hash', column: 'id' })
+ *   @Table
+ *   class Log extends Model {}
+ *
+ * @param options - Partition configuration options
+ */
+function Partition(options) {
+    return function (target) {
+        Reflect.defineMetadata(PARTITION_KEY, options, target);
+    };
+}
+// ==================== Property Decorators ====================
+/**
+ * Decorator to specify column-level storage options (PostgreSQL).
+ *
+ * Usage:
+ *
+ *   @Column(DataTypes.BLOB)
+ *   @ColumnStorage({ compression: 'pglz' })
+ *   blobData: Buffer;
+ *
+ * @param options - Column storage options
+ */
+function ColumnStorage(options) {
+    return function (target, propertyKey) {
+        const existing = Reflect.getMetadata(COLUMN_STORAGE_KEY, target) || {};
+        existing[propertyKey] = options;
+        Reflect.defineMetadata(COLUMN_STORAGE_KEY, existing, target);
+    };
+}
+// ==================== Helper Functions ====================
+/**
+ * Get storage options for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns Storage options or undefined
+ */
+function getStorageOptions(target) {
+    return Reflect.getMetadata(STORAGE_KEY, target);
+}
+/**
+ * Get tablespace options for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns Tablespace options or undefined
+ */
+function getTablespaceOptions(target) {
+    return Reflect.getMetadata(TABLESPACE_KEY, target);
+}
+/**
+ * Get clustered index options for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns Clustered options or undefined
+ */
+function getClusteredOptions(target) {
+    return Reflect.getMetadata(CLUSTERED_KEY, target);
+}
+/**
+ * Get compression options for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns Compression options or undefined
+ */
+function getCompressionOptions(target) {
+    return Reflect.getMetadata(COMPRESSION_KEY, target);
+}
+/**
+ * Get replica identity options for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns Replica identity options or undefined
+ */
+function getReplicaIdentityOptions(target) {
+    return Reflect.getMetadata(REPLICA_IDENTITY_KEY, target);
+}
+/**
+ * Get statistics options for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns Statistics options or undefined
+ */
+function getStatisticsOptions(target) {
+    return Reflect.getMetadata(STATISTICS_KEY, target);
+}
+/**
+ * Get ON COMMIT option for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns ON COMMIT option or undefined
+ */
+function getOnCommitOption(target) {
+    return Reflect.getMetadata(ON_COMMIT_KEY, target);
+}
+/**
+ * Get inheritance options for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns Inheritance options or undefined
+ */
+function getInheritsOptions(target) {
+    return Reflect.getMetadata(INHERITS_KEY, target);
+}
+/**
+ * Get column storage options for a property.
+ *
+ * @param target - The target object
+ * @param propertyKey - The property key
+ * @returns Column storage options or undefined
+ */
+function getColumnStorageOptions(target, propertyKey) {
+    const all = Reflect.getMetadata(COLUMN_STORAGE_KEY, target);
+    return all?.[propertyKey];
+}
+/**
+ * Generate storage-related SQL for a model.
+ *
+ * @param options - Storage options
+ * @param dialect - Database dialect
+ * @returns Array of SQL statements
+ */
+function generateStorageSQL(options, dialect) {
+    const statements = [];
+    if (dialect === 'mysql' || dialect === 'mariadb') {
+        if (options.engine) {
+            statements.push(`ENGINE = ${options.engine}`);
+        }
+        if (options.rowFormat) {
+            statements.push(`ROW_FORMAT = ${options.rowFormat}`);
+        }
+        if (options.tablespace) {
+            statements.push(`TABLESPACE = ${options.tablespace}`);
+        }
+        if (options.encryption !== undefined) {
+            const encValue = typeof options.encryption === 'string'
+                ? `'${options.encryption}'`
+                : options.encryption
+                    ? "'Y'"
+                    : "'N'";
+            statements.push(`ENCRYPTION = ${encValue}`);
+        }
+        if (options.comment) {
+            statements.push(`COMMENT = '${options.comment}'`);
+        }
+        if (options.avgRowLength) {
+            statements.push(`AVG_ROW_LENGTH = ${options.avgRowLength}`);
+        }
+        if (options.maxRows) {
+            statements.push(`MAX_ROWS = ${options.maxRows}`);
+        }
+        if (options.minRows) {
+            statements.push(`MIN_ROWS = ${options.minRows}`);
+        }
+    }
+    return statements;
+}
+/**
+ * Generate tablespace SQL for a model.
+ *
+ * @param options - Tablespace options
+ * @param dialect - Database dialect
+ * @returns SQL string or undefined
+ */
+function generateTablespaceSQL(options, dialect) {
+    if (dialect === 'postgres') {
+        let sql = `TABLESPACE ${options.name}`;
+        if (options.indexTablespace) {
+            sql += ` INDEX TABLESPACE ${options.indexTablespace}`;
+        }
+        return sql;
+    }
+    if ((dialect === 'mysql' || dialect === 'mariadb') && options.name) {
+        return `TABLESPACE = ${options.name}`;
+    }
+    return undefined;
+}
+/**
+ * Generate clustered index SQL.
+ *
+ * @param options - Clustered options
+ * @returns SQL string or undefined
+ */
+function generateClusteredSQL(options) {
+    const { type, unique, fillFactor, include } = options;
+    if (type === 'clustered') {
+        let sql = 'CLUSTERED';
+        if (unique)
+            sql = 'UNIQUE ' + sql;
+        if (fillFactor)
+            sql += ` (FILLFACTOR = ${fillFactor})`;
+        return sql;
+    }
+    if (type === 'nonclustered') {
+        let sql = 'NONCLUSTERED';
+        if (unique)
+            sql = 'UNIQUE ' + sql;
+        if (fillFactor)
+            sql += ` (FILLFACTOR = ${fillFactor})`;
+        if (include && include.length > 0) {
+            sql += ` INCLUDE (${include.join(', ')})`;
+        }
+        return sql;
+    }
+    return undefined;
+}
+/**
+ * Generate compression SQL (PostgreSQL).
+ *
+ * @param options - Compression options
+ * @returns SQL string or undefined
+ */
+function generateCompressionSQL(options) {
+    if (options.algorithm) {
+        return `COMPRESSION ${options.algorithm} (COMPRESS_LEVEL ${options.level || 6})`;
+    }
+    return undefined;
+}
+/**
+ * Generate replica identity SQL (PostgreSQL).
+ *
+ * @param options - Replica identity options
+ * @returns SQL string
+ */
+function generateReplicaIdentitySQL(options) {
+    if (options.type === 'INDEX' && options.index) {
+        return `REPLICA IDENTITY INDEX ${options.index}`;
+    }
+    return `REPLICA IDENTITY ${options.type}`;
+}
+/**
+ * Generate statistics SQL (PostgreSQL).
+ *
+ * @param options - Statistics options
+ * @param tableName - Table name
+ * @returns SQL string or undefined
+ */
+function generateStatisticsSQL(options, tableName) {
+    if (options.for === 'columns' && options.columns?.length) {
+        const colStats = options.columns.map((col) => `${col} (${options.target || 100})`).join(', ');
+        return `ALTER TABLE ${tableName} ALTER COLUMN ${colStats} SET STATISTICS ${options.target || 100}`;
+    }
+    if (options.for === 'all') {
+        return `ALTER TABLE ${tableName} ALTER COLUMN ${options.columns?.[0] || 'id'} SET STATISTICS ${options.target || 100}`;
+    }
+    return undefined;
+}
+/**
+ * Generate inheritance SQL (PostgreSQL).
+ *
+ * @param options - Inheritance options
+ * @returns SQL string
+ */
+function generateInheritsSQL(options) {
+    const keyword = options.only ? 'INHERITS ONLY' : 'INHERITS';
+    return `${keyword} (${options.parentTable})`;
+}
+/**
+ * Get partition options for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns Partition options or undefined
+ */
+function getPartitionOptions(target) {
+    return Reflect.getMetadata(PARTITION_KEY, target);
+}
+/**
+ * Generate partition by clause SQL (PostgreSQL 10+).
+ *
+ * @param options - Partition options
+ * @returns SQL string
+ */
+function generatePartitionSQL(options) {
+    const columns = Array.isArray(options.column) ? options.column.join(', ') : options.column;
+    return `${options.type.toUpperCase()} (${columns})`;
+}
+/**
+ * Generate partition bound SQL.
+ *
+ * @param bound - Partition bound options
+ * @param type - Partition type (range, list, hash)
+ * @returns SQL string
+ */
+function generatePartitionBoundSQL(bound, type) {
+    if (type === 'range') {
+        const from = bound.from instanceof Date ? bound.from.toISOString().split('T')[0] : bound.from;
+        const to = bound.to
+            ? bound.to instanceof Date
+                ? bound.to.toISOString().split('T')[0]
+                : bound.to
+            : 'MAXVALUE';
+        return `FROM (${from}) TO (${to})`;
+    }
+    if (type === 'list') {
+        const values = bound.values?.map((v) => (typeof v === 'string' ? `'${v}'` : v)).join(', ') || '';
+        return `IN (${values})`;
+    }
+    if (type === 'hash') {
+        return `WITH (MODULUS ${bound.modulus}, REMAINDER ${bound.remainder})`;
+    }
+    return '';
+}