ts-prorm-orm 1.1.0 → 1.2.1

package/dist/decorators/collate.d.ts

@@ -0,0 +1,346 @@
+/**
+ * Database Collate and Locale Decorators / Annotations for ts-prorm-orm
+ *
+ * Provides decorators and enums for managing database collation, locale settings,
+ * and encoding options at the column, table, and database levels.
+ *
+ * Usage:
+ *
+ *   // Column-level collation
+ *   class User extends Model {
+ *     @SetCollate(CollateEnum.UTF8MB4_UNICODE_CI)
+ *     @Column
+ *     name: string;
+ *
+ *     @SetCollate(CollateEnum.UTF8MB4_BIN)
+ *     @Column
+ *     password: string;
+ *   }
+ *
+ *   // Table-level collation
+ *   @TableCollate({ collate: CollateEnum.UTF8MB4_SPANISH_CI })
+ *   class User extends Model {}
+ *
+ *   // Database-level locale settings
+ *   @Database({
+ *     name: 'miapp',
+ *     encoding: 'UTF8',
+ *     lcCollate: LocaleEnum.ES_ES,
+ *     lcCtype: LocaleEnum.ES_ES,
+ *   })
+ *   class Config extends Model {}
+ *
+ *   // Create database with locale
+ *   await prorm.createDatabase({
+ *     name: 'miapp',
+ *     encoding: 'UTF8',
+ *     lcCollate: 'es_ES.UTF-8',
+ *     lcCtype: 'es_ES.UTF-8',
+ *     template: 'template0',
+ *   });
+ */
+/**
+ * MySQL/MariaDB collation constants
+ */
+export declare const CollateEnum: {
+    readonly UTF8_GENERAL_CI: "utf8_general_ci";
+    readonly UTF8_UNICODE_CI: "utf8_unicode_ci";
+    readonly UTF8MB4_GENERAL_CI: "utf8mb4_general_ci";
+    readonly UTF8MB4_UNICODE_CI: "utf8mb4_unicode_ci";
+    readonly UTF8MB4_BIN: "utf8mb4_bin";
+    readonly UTF8MB4_SPANISH_CI: "utf8mb4_spanish_ci";
+    readonly UTF8MB4_SPANISH2_CI: "utf8mb4_spanish2_ci";
+    readonly UTF8MB4_GERMAN_CI: "utf8mb4_german_ci";
+    readonly UTF8MB4_SWEDISH_CI: "utf8mb4_swedish_ci";
+    readonly UTF8MB4_NOPAD: "utf8mb4_nopad";
+    readonly UTF8_NOPAD: "utf8_nopad";
+    readonly BINARY: "binary";
+    readonly ASCII_GENERAL_CI: "ascii_general_ci";
+    readonly ASCII_BIN: "ascii_bin";
+};
+/**
+ * Type representing a collation value
+ */
+export type CollateType = (typeof CollateEnum)[keyof typeof CollateEnum];
+/**
+ * @deprecated Use CollateEnum instead
+ */
+export declare const Collate: {
+    readonly UTF8_GENERAL_CI: "utf8_general_ci";
+    readonly UTF8_UNICODE_CI: "utf8_unicode_ci";
+    readonly UTF8MB4_GENERAL_CI: "utf8mb4_general_ci";
+    readonly UTF8MB4_UNICODE_CI: "utf8mb4_unicode_ci";
+    readonly UTF8MB4_BIN: "utf8mb4_bin";
+    readonly UTF8MB4_SPANISH_CI: "utf8mb4_spanish_ci";
+    readonly UTF8MB4_SPANISH2_CI: "utf8mb4_spanish2_ci";
+    readonly UTF8MB4_GERMAN_CI: "utf8mb4_german_ci";
+    readonly UTF8MB4_SWEDISH_CI: "utf8mb4_swedish_ci";
+    readonly UTF8MB4_NOPAD: "utf8mb4_nopad";
+    readonly UTF8_NOPAD: "utf8_nopad";
+    readonly BINARY: "binary";
+    readonly ASCII_GENERAL_CI: "ascii_general_ci";
+    readonly ASCII_BIN: "ascii_bin";
+};
+/**
+ * Common database locales for POSIX locale strings
+ */
+export declare const LocaleEnum: {
+    readonly ES_ES: "es_ES.UTF-8";
+    readonly ES_MX: "es_MX.UTF-8";
+    readonly ES_AR: "es_AR.UTF-8";
+    readonly ES_CO: "es_CO.UTF-8";
+    readonly ES_CL: "es_CL.UTF-8";
+    readonly EN_US: "en_US.UTF-8";
+    readonly EN_GB: "en_GB.UTF-8";
+    readonly EN_AU: "en_AU.UTF-8";
+    readonly EN_CA: "en_CA.UTF-8";
+    readonly DE_DE: "de_DE.UTF-8";
+    readonly DE_AT: "de_AT.UTF-8";
+    readonly DE_CH: "de_CH.UTF-8";
+    readonly FR_FR: "fr_FR.UTF-8";
+    readonly FR_CA: "fr_CA.UTF-8";
+    readonly PT_BR: "pt_BR.UTF-8";
+    readonly PT_PT: "pt_PT.UTF-8";
+    readonly IT_IT: "it_IT.UTF-8";
+    readonly NL_NL: "nl_NL.UTF-8";
+    readonly NL_BE: "nl_BE.UTF-8";
+    readonly SV_SE: "sv_SE.UTF-8";
+    readonly NB_NO: "nb_NO.UTF-8";
+    readonly NN_NO: "nn_NO.UTF-8";
+    readonly DA_DK: "da_DK.UTF-8";
+    readonly FI_FI: "fi_FI.UTF-8";
+    readonly PL_PL: "pl_PL.UTF-8";
+    readonly RU_RU: "ru_RU.UTF-8";
+    readonly JA_JP: "ja_JP.UTF-8";
+    readonly ZH_CN: "zh_CN.UTF-8";
+    readonly ZH_TW: "zh_TW.UTF-8";
+    readonly ZH_HK: "zh_HK.UTF-8";
+    readonly KO_KR: "ko_KR.UTF-8";
+    readonly AR_SA: "ar_SA.UTF-8";
+};
+/**
+ * Type representing a locale value
+ */
+export type LocaleType = (typeof LocaleEnum)[keyof typeof LocaleEnum];
+/**
+ * @deprecated Use LocaleEnum instead
+ */
+export declare const Locale: {
+    readonly ES_ES: "es_ES.UTF-8";
+    readonly ES_MX: "es_MX.UTF-8";
+    readonly ES_AR: "es_AR.UTF-8";
+    readonly ES_CO: "es_CO.UTF-8";
+    readonly ES_CL: "es_CL.UTF-8";
+    readonly EN_US: "en_US.UTF-8";
+    readonly EN_GB: "en_GB.UTF-8";
+    readonly EN_AU: "en_AU.UTF-8";
+    readonly EN_CA: "en_CA.UTF-8";
+    readonly DE_DE: "de_DE.UTF-8";
+    readonly DE_AT: "de_AT.UTF-8";
+    readonly DE_CH: "de_CH.UTF-8";
+    readonly FR_FR: "fr_FR.UTF-8";
+    readonly FR_CA: "fr_CA.UTF-8";
+    readonly PT_BR: "pt_BR.UTF-8";
+    readonly PT_PT: "pt_PT.UTF-8";
+    readonly IT_IT: "it_IT.UTF-8";
+    readonly NL_NL: "nl_NL.UTF-8";
+    readonly NL_BE: "nl_BE.UTF-8";
+    readonly SV_SE: "sv_SE.UTF-8";
+    readonly NB_NO: "nb_NO.UTF-8";
+    readonly NN_NO: "nn_NO.UTF-8";
+    readonly DA_DK: "da_DK.UTF-8";
+    readonly FI_FI: "fi_FI.UTF-8";
+    readonly PL_PL: "pl_PL.UTF-8";
+    readonly RU_RU: "ru_RU.UTF-8";
+    readonly JA_JP: "ja_JP.UTF-8";
+    readonly ZH_CN: "zh_CN.UTF-8";
+    readonly ZH_TW: "zh_TW.UTF-8";
+    readonly ZH_HK: "zh_HK.UTF-8";
+    readonly KO_KR: "ko_KR.UTF-8";
+    readonly AR_SA: "ar_SA.UTF-8";
+};
+/**
+ * Options for database creation/configuration
+ */
+export interface DatabaseOptions {
+    /**
+     * Database name
+     */
+    name: string;
+    /**
+     * Character encoding (e.g., 'UTF8', 'LATIN1')
+     */
+    encoding?: string;
+    /**
+     * LC_COLLATE setting for string sort order
+     */
+    lcCollate?: string;
+    /**
+     * LC_CTYPE setting for character classification
+     */
+    lcCtype?: string;
+    /**
+     * Template database to use (PostgreSQL)
+     */
+    template?: string;
+    /**
+     * Tablespace for the database (PostgreSQL)
+     */
+    tablespace?: string;
+    /**
+     * Connection pool limit
+     */
+    connectionLimit?: number;
+    /**
+     * If true, database is a template (PostgreSQL)
+     */
+    isTemplate?: boolean;
+    /**
+     * Database collation (MySQL/MariaDB)
+     */
+    collate?: string;
+}
+/**
+ * Options for column-level collation
+ */
+export interface CollateOptions {
+    /**
+     * The collation to apply to the column
+     */
+    collate?: string;
+    /**
+     * Whether this is a primary key column
+     */
+    primaryKey?: boolean;
+    /**
+     * Whether this column should be unique
+     */
+    unique?: boolean;
+}
+/**
+ * Options for table-level collation
+ */
+export interface TableCollateOptions {
+    /**
+     * Table collation
+     */
+    collate?: string;
+    /**
+     * Table engine (MySQL)
+     */
+    engine?: string;
+    /**
+     * Table comment
+     */
+    comment?: string;
+}
+/**
+ * OrderBy options with locale support
+ */
+export interface OrderByOptions {
+    /**
+     * Column name to order by
+     */
+    column: string;
+    /**
+     * Sort direction
+     */
+    direction?: 'ASC' | 'DESC';
+    /**
+     * Collation to use for sorting
+     */
+    collate?: string;
+}
+/**
+ * Decorator to set column-level collation
+ *
+ * Usage:
+ *   @Collate(Collate.UTF8MB4_UNICODE_CI)
+ *   @Column
+ *   name: string;
+ *
+ * Or with options:
+ *   @Collate({ collate: Collate.UTF8MB4_BIN, unique: true })
+ *   @Column
+ *   email: string;
+ */
+/**
+ * Decorator to set column-level collation
+ *
+ * Usage:
+ *   @SetCollate(CollateEnum.UTF8MB4_UNICODE_CI)
+ *   @Column
+ *   name: string;
+ *
+ * Or with options:
+ *   @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:
+ *   @Database({
+ *     name: 'miapp',
+ *     encoding: 'UTF8',
+ *     lcCollate: 'es_ES.UTF-8',
+ *     lcCtype: 'es_ES.UTF-8',
+ *     connectionLimit: 25,
+ *   })
+ *   class Config extends Model {}
+ */
+export declare function Database(options: DatabaseOptions): ClassDecorator;
+/**
+ * Decorator to set table-level collation and options
+ *
+ * Usage:
+ *   @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:
+ *   @OrderBy('name', 'ASC', Collate.UTF8MB4_SPANISH_CI)
+ *   class User extends Model {}
+ */
+export declare function OrderBy(column: string, direction?: 'ASC' | 'DESC', collate?: string): ClassDecorator;
+/**
+ * Get collation metadata for a model class
+ */
+export declare function getCollateMetadata(target: any): Map<string, string>;
+/**
+ * Get column collation from a model class and property
+ */
+export declare function getColumnCollate(target: any, propertyKey: string): string | undefined;
+/**
+ * Get database options for a model class
+ */
+export declare function getDatabaseOptions(target: any): DatabaseOptions | undefined;
+/**
+ * Get table collation options for a model class
+ */
+export declare function getTableCollateOptions(target: any): TableCollateOptions | undefined;
+/**
+ * Get order by options for a model class
+ */
+export declare function getOrderByOptions(target: any): OrderByOptions[];
+/**
+ * Clear all collate metadata (useful for testing)
+ */
+export declare function clearCollateMetadata(): void;
+/**
+ * Generate SQL for creating a database with locale settings
+ */
+export declare function generateCreateDatabaseSQL(options: DatabaseOptions): string;
+/**
+ * Generate SQL for altering table collation
+ */
+export declare function generateAlterTableCollateSQL(tableName: string, collate: string): string;
+/**
+ * Generate SQL for column collation
+ */
+export declare function generateColumnCollateSQL(columnName: string, collate: string): string;

package/dist/decorators/comment.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @Comment decorator for database schema annotations
+ *
+ * Provides the ability to add comments to various database objects:
+ * - Table-level comments (on model classes)
+ * - Column-level comments (on model fields)
+ * - Index comments
+ * - Constraint comments
+ *
+ * Usage:
+ *
+ *  @Comment('This table stores user information')
+ *  class User extends Model { ... }
+ *
+ *  @Column
+ *  @Comment('User unique identifier')
+ *  id: number;
+ *
+ *  @Column
+ *  @Comment('User email address')
+ *  email: string;
+ */
+export interface CommentOptions {
+    value: string;
+}
+export declare function Comment(value: string): ClassDecorator & PropertyDecorator;
+export declare function getTableComment(target: Function): string | undefined;
+export declare function getFieldComment(target: Function, fieldName: string): string | undefined;
+export declare function getAllFieldComments(target: Function): Record<string, string>;
+export declare function setIndexComment(target: Function, indexName: string, comment: string): void;
+export declare function getIndexComment(target: Function, indexName: string): string | undefined;
+export declare function getAllIndexComments(target: Function): Record<string, string>;
+export declare function setConstraintComment(target: Function, constraintName: string, comment: string): void;
+export declare function getConstraintComment(target: Function, constraintName: string): string | undefined;
+export declare function getAllConstraintComments(target: Function): Record<string, string>;
+export declare const CommentRegistry: {
+    getTableComment: typeof getTableComment;
+    getFieldComment: typeof getFieldComment;
+    getAllFieldComments: typeof getAllFieldComments;
+    setIndexComment: typeof setIndexComment;
+    getIndexComment: typeof getIndexComment;
+    getAllIndexComments: typeof getAllIndexComments;
+    setConstraintComment: typeof setConstraintComment;
+    getConstraintComment: typeof getConstraintComment;
+    getAllConstraintComments: typeof getAllConstraintComments;
+    clearComments(target: Function): void;
+};
+export type CommentDialect = 'mysql' | 'mariadb' | 'postgres' | 'mssql' | 'oracle' | 'sqlite';
+export declare function generateCommentSQL(target: Function, tableName?: string, dialect?: CommentDialect): string[];
+export declare function generateIndexCommentSQL(target: Function, tableName: string, dialect?: CommentDialect): string[];
+export declare function generateConstraintCommentSQL(target: Function, tableName: string, dialect?: CommentDialect): string[];

package/dist/decorators/database-settings.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Database-level settings decorators for the ORM.
+ *
+ * Allows controlling database-level settings for models:
+ * - Foreign key checks (MySQL/MariaDB)
+ * - Unique checks
+ * - Autocommit
+ * - SQL mode
+ * - Other session-level settings
+ *
+ * Usage:
+ *
+ *   // Disable FK checks for entire model
+ *   @ForeignKeyChecks({ enabled: false })
+ *   class ImportData extends Model {}
+ *
+ *   // Disable FK checks at table level
+ *   @Table({ foreignKeyChecks: false })
+ *   class TempData extends Model {}
+ *
+ *   // Set database-level settings
+ *   @DatabaseSetting('unique_checks', false)
+ *   @DatabaseSetting('autocommit', false)
+ *   @DatabaseSetting('sql_mode', 'STRICT_TRANS_TABLES')
+ *   class ImportData extends Model {}
+ *
+ *   // In transaction
+ *   await prorm.transaction(async () => {
+ *     await prorm.setForeignKeyChecks(false);
+ *     // Bulk import without FK validation
+ *     await prorm.setForeignKeyChecks(true);
+ *   });
+ */
+import 'reflect-metadata';
+/**
+ * Database setting value types
+ */
+export type DatabaseSettingValue = string | number | boolean | null;
+/**
+ * Options for @ForeignKeyChecks decorator
+ */
+export interface ForeignKeyChecksOptions {
+    /**
+     * Whether to enable or disable foreign key checks
+     * Default: true (enabled)
+     */
+    enabled?: boolean;
+    /**
+     * Optional description for documentation
+     */
+    description?: string;
+}
+/**
+ * Options for @DatabaseSetting decorator
+ */
+export interface DatabaseSettingOptions {
+    /**
+     * The setting name
+     * Examples: 'unique_checks', 'autocommit', 'sql_mode', 'foreign_key_checks'
+     */
+    name: string;
+    /**
+     * The value to set
+     */
+    value: DatabaseSettingValue;
+    /**
+     * Whether this setting should be applied per-session or globally
+     * Default: 'session'
+     */
+    scope?: 'session' | 'global';
+    /**
+     * Optional description for documentation
+     */
+    description?: string;
+}
+/**
+ * Model-level database settings collected from decorators
+ */
+export interface ModelDatabaseSettings {
+    /**
+     * Foreign key checks setting
+     */
+    foreignKeyChecks?: boolean;
+    /**
+     * Unique checks setting
+     */
+    uniqueChecks?: boolean;
+    /**
+     * Autocommit setting
+     */
+    autocommit?: boolean;
+    /**
+     * SQL mode setting
+     */
+    sqlMode?: string;
+    /**
+     * Additional settings
+     */
+    additionalSettings?: Record<string, DatabaseSettingValue>;
+}
+/**
+ * Decorator to control foreign key checks for a model.
+ *
+ * Useful for bulk imports or data migrations where you need to
+ * temporarily disable FK validation.
+ *
+ * Usage:
+ *
+ *   @ForeignKeyChecks({ enabled: false })
+ *   class ImportData extends Model {
+ *     // fields...
+ *   }
+ *
+ * @param options - Foreign key check options
+ */
+export declare function ForeignKeyChecks(options?: ForeignKeyChecksOptions): ClassDecorator;
+/**
+ * Decorator to set database-level settings for a model.
+ *
+ * These settings are applied when the model is used and can control
+ * session-level database behavior.
+ *
+ * Usage:
+ *
+ *   @DatabaseSetting('unique_checks', false)
+ *   @DatabaseSetting('autocommit', false)
+ *   @DatabaseSetting('sql_mode', 'STRICT_TRANS_TABLES')
+ *   class ImportData extends Model {
+ *     // fields...
+ *   }
+ *
+ * @param name - The setting name
+ * @param value - The value to set
+ */
+export declare function DatabaseSetting(name: string, value: DatabaseSettingValue): ClassDecorator;
+/**
+ * Get foreign key checks setting for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns The foreign key checks setting or undefined
+ */
+export declare function getForeignKeyChecksSetting(target: object): boolean | undefined;
+/**
+ * Get all database settings for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns The database settings object
+ */
+export declare function getDatabaseSettings(target: object): ModelDatabaseSettings | undefined;
+/**
+ * Check if foreign key checks are disabled for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns True if FK checks are disabled
+ */
+export declare function isForeignKeyChecksDisabled(target: object): boolean;
+/**
+ * Get all model database settings including inherited settings.
+ *
+ * Walks the prototype chain to collect all settings from parent classes.
+ *
+ * @param target - The target class or prototype
+ * @returns Combined database settings from all levels
+ */
+export declare function getAllDatabaseSettings(target: object): ModelDatabaseSettings;
+/**
+ * Generate SQL to apply database settings.
+ *
+ * @param settings - The database settings
+ * @returns Array of SQL statements to execute
+ */
+export declare function generateSettingsSQL(settings: ModelDatabaseSettings): string[];
+/**
+ * Create a context manager for temporarily changing database settings.
+ *
+ * Usage:
+ *
+ *   const settingsManager = createSettingsContext({
+ *     foreignKeyChecks: false,
+ *     uniqueChecks: false
+ *   });
+ *
+ *   await settingsManager.execute(async () => {
+ *     // Bulk insert without FK checks
+ *     await Model.bulkCreate(data);
+ *   });
+ *
+ * @param settings - Settings to apply during execution
+ * @returns Context manager with execute method
+ */
+export declare function createSettingsContext(settings: Partial<ModelDatabaseSettings>): {
+    execute: <T>(fn: () => Promise<T>) => Promise<T>;
+};