ts-prorm-orm 1.1.0 → 1.2.0

package/dist/decorators/storage.d.ts

@@ -0,0 +1,561 @@
+/**
+ * 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 {}
+ */
+import 'reflect-metadata';
+/**
+ * Storage engine types for MySQL/MariaDB
+ */
+export type StorageEngine = 'InnoDB' | 'MyISAM' | 'MEMORY' | 'CSV' | 'MERGE' | 'ARCHIVE' | 'BLACKHOLE';
+/**
+ * Row format types for MySQL/MariaDB
+ */
+export type RowFormat = 'DEFAULT' | 'DYNAMIC' | 'FIXED' | 'COMPRESSED' | 'REDUNDANT' | 'COMPACT';
+/**
+ * Partition bound specification for decorator usage
+ * (includes all properties for convenience)
+ */
+interface PartitionBoundInternal {
+    from?: string | number | Date;
+    to?: string | number | Date;
+    values?: (string | number)[];
+    modulus?: number;
+    remainder?: number;
+}
+/**
+ * Options for @Partition decorator (PostgreSQL 10+)
+ */
+interface PartitionOptionsInternal {
+    type: 'range' | 'list' | 'hash';
+    column: string | string[];
+    partitions?: PartitionDefinitionInternal[];
+}
+/**
+ * Individual partition definition
+ */
+interface PartitionDefinitionInternal {
+    name: string;
+    bound?: PartitionBoundInternal;
+}
+/**
+ * Options for @Storage decorator
+ */
+export interface StorageOptions {
+    /**
+     * Storage engine to use (MySQL/MariaDB)
+     * Default: 'InnoDB'
+     */
+    engine?: StorageEngine;
+    /**
+     * Row format for the table
+     * Default: 'DYNAMIC' for InnoDB
+     */
+    rowFormat?: RowFormat;
+    /**
+     * Encryption for the table (MySQL 8.0+)
+     */
+    encryption?: boolean | string;
+    /**
+     * Table comment
+     */
+    comment?: string;
+    /**
+     * Average row length estimate
+     */
+    avgRowLength?: number;
+    /**
+     * Maximum number of rows
+     */
+    maxRows?: number;
+    /**
+     * Minimum number of rows
+     */
+    minRows?: number;
+    /**
+     * Table password
+     */
+    password?: string;
+    /**
+     * Tablespace name (MySQL)
+     */
+    tablespace?: string;
+}
+/**
+ * Options for @Tablespace decorator (PostgreSQL)
+ */
+export interface TablespaceOptions {
+    /**
+     * Name of the tablespace
+     */
+    name: string;
+    /**
+     * Index tablespace (if different)
+     */
+    indexTablespace?: string;
+    /**
+     * Storage parameters for the tablespace
+     */
+    parameters?: Record<string, string | number>;
+}
+/**
+ * Cluster type for SQL Server
+ */
+export type ClusterType = 'clustered' | 'nonclustered';
+/**
+ * Options for @Clustered decorator (SQL Server)
+ */
+export interface ClusteredOptions {
+    /**
+     * Type of cluster
+     * Default: 'clustered'
+     */
+    type?: ClusterType;
+    /**
+     * Whether to create a unique index
+     * Default: false
+     */
+    unique?: boolean;
+    /**
+     * Index fill factor (0-100)
+     */
+    fillFactor?: number;
+    /**
+     * Include columns (for non-clustered)
+     */
+    include?: string[];
+    /**
+     * Index options
+     */
+    options?: Record<string, string | number>;
+}
+/**
+ * Compression method for PostgreSQL
+ */
+export type CompressionAlgorithm = 'pglz' | 'lz4';
+/**
+ * Options for @Compression decorator (PostgreSQL)
+ */
+export interface CompressionOptions {
+    /**
+     * Compression algorithm
+     * Default: 'pglz'
+     */
+    algorithm?: CompressionAlgorithm;
+    /**
+     * Compression level (0-9 for pglz, 1-9 for lz4)
+     * Default: 6
+     */
+    level?: number;
+    /**
+     * Whether to compress during WAL replay
+     */
+    compressLevel?: number;
+}
+/**
+ * Replica identity types for PostgreSQL logical replication
+ */
+export type ReplicaIdentityType = 'FULL' | 'DEFAULT' | 'INDEX' | 'NOTHING';
+/**
+ * Options for @ReplicaIdentity decorator (PostgreSQL)
+ */
+export interface ReplicaIdentityOptions {
+    /**
+     * Type of replica identity
+     * 'FULL' - all columns
+     * 'DEFAULT' - primary key
+     * 'INDEX' - index columns
+     * 'NOTHING' - no additional info
+     */
+    type: ReplicaIdentityType;
+    /**
+     * Index name (required if type is 'INDEX')
+     */
+    index?: string;
+}
+/**
+ * Options for @Statistics decorator (PostgreSQL)
+ */
+export interface StatisticsOptions {
+    /**
+     * What to collect statistics on
+     * 'columns' - column statistics
+     * 'all' - table and columns
+     */
+    for?: 'columns' | 'all';
+    /**
+     * Columns to collect statistics on (for columns mode)
+     */
+    columns?: string[];
+    /**
+     * Statistics target (1-10000)
+     */
+    target?: number;
+}
+/**
+ * ON COMMIT options for temp tables (PostgreSQL)
+ */
+export type OnCommitOption = 'PRESERVE ROWS' | 'DELETE ROWS' | 'DROP';
+/**
+ * Options for @Inherits decorator (PostgreSQL)
+ */
+export interface InheritsOptions {
+    /**
+     * Parent table name
+     */
+    parentTable: string;
+    /**
+     * Whether this is ONLY inheritance (excludes parent columns)
+     * Default: false
+     */
+    only?: boolean;
+}
+/**
+ * Options for @ColumnStorage decorator (column-level storage)
+ */
+export interface ColumnStorageOptions {
+    /**
+     * Column compression (PostgreSQL)
+     */
+    compression?: string;
+    /**
+     * Using for column (PostgreSQL)
+     */
+    using?: string;
+    /**
+     * Storage parameter (PostgreSQL)
+     */
+    storage?: string;
+}
+/**
+ * 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
+ */
+export declare function Storage(options?: StorageOptions): ClassDecorator;
+/**
+ * Decorator to specify tablespace for a table (PostgreSQL/MySQL).
+ *
+ * Usage:
+ *
+ *   @Tablespace('fast_storage')
+ *   @Table
+ *   class LargeTable extends Model {}
+ *
+ * @param name - Tablespace name
+ */
+export declare function Tablespace(name: string): ClassDecorator;
+/**
+ * Decorator to specify tablespace with options (PostgreSQL).
+ *
+ * Usage:
+ *
+ *   @Tablespace({ name: 'fast_storage', indexTablespace: 'idx_space' })
+ *   @Table
+ *   class LargeTable extends Model {}
+ *
+ * @param options - Tablespace options
+ */
+export declare function TablespaceOptions(options: TablespaceOptions): ClassDecorator;
+/**
+ * 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
+ */
+export declare function Clustered(options?: boolean | ClusteredOptions): ClassDecorator;
+/**
+ * Decorator to specify compression options (PostgreSQL).
+ *
+ * Usage:
+ *
+ *   @Compression({ algorithm: 'lz4', level: 6 })
+ *   @Table
+ *   class LargeTable extends Model {}
+ *
+ * @param options - Compression options
+ */
+export declare function Compression(options?: CompressionOptions): ClassDecorator;
+/**
+ * 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
+ */
+export declare function ReplicaIdentity(options: string | ReplicaIdentityOptions): ClassDecorator;
+/**
+ * Decorator to configure statistics collection (PostgreSQL).
+ *
+ * Usage:
+ *
+ *   @Statistics({ for: 'columns', target: 500 })
+ *   @Table
+ *   class UserData extends Model {}
+ *
+ * @param options - Statistics options
+ */
+export declare function Statistics(options?: StatisticsOptions): ClassDecorator;
+/**
+ * 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
+ */
+export declare function OnCommit(option: OnCommitOption): ClassDecorator;
+/**
+ * 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)
+ */
+export declare function Inherits(options: string | InheritsOptions): ClassDecorator;
+/**
+ * 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
+ */
+export declare function Partition(options: PartitionOptionsInternal): ClassDecorator;
+/**
+ * Decorator to specify column-level storage options (PostgreSQL).
+ *
+ * Usage:
+ *
+ *   @Column(DataTypes.BLOB)
+ *   @ColumnStorage({ compression: 'pglz' })
+ *   blobData: Buffer;
+ *
+ * @param options - Column storage options
+ */
+export declare function ColumnStorage(options: ColumnStorageOptions): PropertyDecorator;
+/**
+ * Get storage options for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns Storage options or undefined
+ */
+export declare function getStorageOptions(target: object): StorageOptions | undefined;
+/**
+ * Get tablespace options for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns Tablespace options or undefined
+ */
+export declare function getTablespaceOptions(target: object): TablespaceOptions | undefined;
+/**
+ * Get clustered index options for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns Clustered options or undefined
+ */
+export declare function getClusteredOptions(target: object): ClusteredOptions | undefined;
+/**
+ * Get compression options for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns Compression options or undefined
+ */
+export declare function getCompressionOptions(target: object): CompressionOptions | undefined;
+/**
+ * Get replica identity options for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns Replica identity options or undefined
+ */
+export declare function getReplicaIdentityOptions(target: object): ReplicaIdentityOptions | undefined;
+/**
+ * Get statistics options for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns Statistics options or undefined
+ */
+export declare function getStatisticsOptions(target: object): StatisticsOptions | undefined;
+/**
+ * Get ON COMMIT option for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns ON COMMIT option or undefined
+ */
+export declare function getOnCommitOption(target: object): {
+    option: OnCommitOption;
+} | undefined;
+/**
+ * Get inheritance options for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns Inheritance options or undefined
+ */
+export declare function getInheritsOptions(target: object): InheritsOptions | undefined;
+/**
+ * Get column storage options for a property.
+ *
+ * @param target - The target object
+ * @param propertyKey - The property key
+ * @returns Column storage options or undefined
+ */
+export declare function getColumnStorageOptions(target: object, propertyKey: string | symbol): ColumnStorageOptions | undefined;
+/**
+ * Generate storage-related SQL for a model.
+ *
+ * @param options - Storage options
+ * @param dialect - Database dialect
+ * @returns Array of SQL statements
+ */
+export declare function generateStorageSQL(options: StorageOptions, dialect: string): string[];
+/**
+ * Generate tablespace SQL for a model.
+ *
+ * @param options - Tablespace options
+ * @param dialect - Database dialect
+ * @returns SQL string or undefined
+ */
+export declare function generateTablespaceSQL(options: TablespaceOptions, dialect: string): string | undefined;
+/**
+ * Generate clustered index SQL.
+ *
+ * @param options - Clustered options
+ * @returns SQL string or undefined
+ */
+export declare function generateClusteredSQL(options: ClusteredOptions): string | undefined;
+/**
+ * Generate compression SQL (PostgreSQL).
+ *
+ * @param options - Compression options
+ * @returns SQL string or undefined
+ */
+export declare function generateCompressionSQL(options: CompressionOptions): string | undefined;
+/**
+ * Generate replica identity SQL (PostgreSQL).
+ *
+ * @param options - Replica identity options
+ * @returns SQL string
+ */
+export declare function generateReplicaIdentitySQL(options: ReplicaIdentityOptions): string;
+/**
+ * Generate statistics SQL (PostgreSQL).
+ *
+ * @param options - Statistics options
+ * @param tableName - Table name
+ * @returns SQL string or undefined
+ */
+export declare function generateStatisticsSQL(options: StatisticsOptions, tableName: string): string | undefined;
+/**
+ * Generate inheritance SQL (PostgreSQL).
+ *
+ * @param options - Inheritance options
+ * @returns SQL string
+ */
+export declare function generateInheritsSQL(options: InheritsOptions): string;
+/**
+ * Get partition options for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns Partition options or undefined
+ */
+export declare function getPartitionOptions(target: object): PartitionOptionsInternal | undefined;
+/**
+ * Generate partition by clause SQL (PostgreSQL 10+).
+ *
+ * @param options - Partition options
+ * @returns SQL string
+ */
+export declare function generatePartitionSQL(options: PartitionOptionsInternal): string;
+/**
+ * Generate partition bound SQL.
+ *
+ * @param bound - Partition bound options
+ * @param type - Partition type (range, list, hash)
+ * @returns SQL string
+ */
+export declare function generatePartitionBoundSQL(bound: PartitionBoundInternal, type: 'range' | 'list' | 'hash'): string;
+export {};