ts-prorm-orm 1.1.0

package/dist/decorators/collate.js

@@ -0,0 +1,329 @@
+"use strict";
+/**
+ * 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',
+ *   });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Locale = exports.LocaleEnum = exports.Collate = exports.CollateEnum = void 0;
+exports.SetCollate = SetCollate;
+exports.Database = Database;
+exports.TableCollate = TableCollate;
+exports.OrderBy = OrderBy;
+exports.getCollateMetadata = getCollateMetadata;
+exports.getColumnCollate = getColumnCollate;
+exports.getDatabaseOptions = getDatabaseOptions;
+exports.getTableCollateOptions = getTableCollateOptions;
+exports.getOrderByOptions = getOrderByOptions;
+exports.clearCollateMetadata = clearCollateMetadata;
+exports.generateCreateDatabaseSQL = generateCreateDatabaseSQL;
+exports.generateAlterTableCollateSQL = generateAlterTableCollateSQL;
+exports.generateColumnCollateSQL = generateColumnCollateSQL;
+// ==================== Collate Enum ====================
+/**
+ * MySQL/MariaDB collation constants
+ */
+exports.CollateEnum = {
+    // UTF-8 collations
+    UTF8_GENERAL_CI: 'utf8_general_ci',
+    UTF8_UNICODE_CI: 'utf8_unicode_ci',
+    UTF8MB4_GENERAL_CI: 'utf8mb4_general_ci',
+    UTF8MB4_UNICODE_CI: 'utf8mb4_unicode_ci',
+    UTF8MB4_BIN: 'utf8mb4_bin',
+    // Spanish
+    UTF8MB4_SPANISH_CI: 'utf8mb4_spanish_ci',
+    UTF8MB4_SPANISH2_CI: 'utf8mb4_spanish2_ci',
+    // German
+    UTF8MB4_GERMAN_CI: 'utf8mb4_german_ci',
+    // Swedish
+    UTF8MB4_SWEDISH_CI: 'utf8mb4_swedish_ci',
+    // Unicode
+    UTF8MB4_NOPAD: 'utf8mb4_nopad',
+    UTF8_NOPAD: 'utf8_nopad',
+    // Binary
+    BINARY: 'binary',
+    // ASCII
+    ASCII_GENERAL_CI: 'ascii_general_ci',
+    ASCII_BIN: 'ascii_bin',
+};
+/**
+ * @deprecated Use CollateEnum instead
+ */
+exports.Collate = exports.CollateEnum;
+// ==================== Locale Enum ====================
+/**
+ * Common database locales for POSIX locale strings
+ */
+exports.LocaleEnum = {
+    // Spanish locales
+    ES_ES: 'es_ES.UTF-8',
+    ES_MX: 'es_MX.UTF-8',
+    ES_AR: 'es_AR.UTF-8',
+    ES_CO: 'es_CO.UTF-8',
+    ES_CL: 'es_CL.UTF-8',
+    // English locales
+    EN_US: 'en_US.UTF-8',
+    EN_GB: 'en_GB.UTF-8',
+    EN_AU: 'en_AU.UTF-8',
+    EN_CA: 'en_CA.UTF-8',
+    // German locale
+    DE_DE: 'de_DE.UTF-8',
+    DE_AT: 'de_AT.UTF-8',
+    DE_CH: 'de_CH.UTF-8',
+    // French locales
+    FR_FR: 'fr_FR.UTF-8',
+    FR_CA: 'fr_CA.UTF-8',
+    // Portuguese locales
+    PT_BR: 'pt_BR.UTF-8',
+    PT_PT: 'pt_PT.UTF-8',
+    // Italian
+    IT_IT: 'it_IT.UTF-8',
+    // Dutch
+    NL_NL: 'nl_NL.UTF-8',
+    NL_BE: 'nl_BE.UTF-8',
+    // Swedish
+    SV_SE: 'sv_SE.UTF-8',
+    // Norwegian
+    NB_NO: 'nb_NO.UTF-8',
+    NN_NO: 'nn_NO.UTF-8',
+    // Danish
+    DA_DK: 'da_DK.UTF-8',
+    // Finnish
+    FI_FI: 'fi_FI.UTF-8',
+    // Polish
+    PL_PL: 'pl_PL.UTF-8',
+    // Russian
+    RU_RU: 'ru_RU.UTF-8',
+    // Japanese
+    JA_JP: 'ja_JP.UTF-8',
+    // Chinese
+    ZH_CN: 'zh_CN.UTF-8',
+    ZH_TW: 'zh_TW.UTF-8',
+    ZH_HK: 'zh_HK.UTF-8',
+    // Korean
+    KO_KR: 'ko_KR.UTF-8',
+    // Arabic
+    AR_SA: 'ar_SA.UTF-8',
+};
+/**
+ * @deprecated Use LocaleEnum instead
+ */
+exports.Locale = exports.LocaleEnum;
+// ==================== Metadata Storage ====================
+/**
+ * Storage for collate metadata on classes and properties
+ */
+const collateMetadata = new Map();
+const databaseMetadata = new Map();
+const tableCollateMetadata = new Map();
+const orderByMetadata = new Map();
+// ==================== Decorators ====================
+/**
+ * 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;
+ */
+function SetCollate(collation) {
+    return function (target, propertyKey) {
+        if (propertyKey && typeof propertyKey === 'string') {
+            // Property decorator (column-level)
+            if (!collateMetadata.has(target.constructor)) {
+                collateMetadata.set(target.constructor, new Map());
+            }
+            const meta = typeof collation === 'string' ? { collate: collation } : collation;
+            collateMetadata.get(target.constructor).set(propertyKey, meta.collate);
+        }
+        else if (propertyKey === undefined) {
+            // Class decorator - store the collate for later use with @Column
+            if (!collateMetadata.has(target)) {
+                collateMetadata.set(target, new Map());
+            }
+        }
+    };
+}
+/**
+ * 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 {}
+ */
+function Database(options) {
+    return function (target) {
+        databaseMetadata.set(target, options);
+    };
+}
+/**
+ * Decorator to set table-level collation and options
+ *
+ * Usage:
+ *   @TableCollate({ collate: 'utf8mb4_spanish_ci', engine: 'InnoDB' })
+ *   class User extends Model {}
+ */
+function TableCollate(options) {
+    return function (target) {
+        tableCollateMetadata.set(target, options);
+    };
+}
+/**
+ * Decorator to specify order by with collation
+ *
+ * Usage:
+ *   @OrderBy('name', 'ASC', Collate.UTF8MB4_SPANISH_CI)
+ *   class User extends Model {}
+ */
+function OrderBy(column, direction = 'ASC', collate) {
+    return function (target) {
+        const existing = orderByMetadata.get(target) || [];
+        existing.push({ column, direction, collate });
+        orderByMetadata.set(target, existing);
+    };
+}
+// ==================== Helper Functions ====================
+/**
+ * Get collation metadata for a model class
+ */
+function getCollateMetadata(target) {
+    return collateMetadata.get(target) || new Map();
+}
+/**
+ * Get column collation from a model class and property
+ */
+function getColumnCollate(target, propertyKey) {
+    const classMeta = collateMetadata.get(target);
+    if (classMeta) {
+        return classMeta.get(propertyKey);
+    }
+    return undefined;
+}
+/**
+ * Get database options for a model class
+ */
+function getDatabaseOptions(target) {
+    return databaseMetadata.get(target);
+}
+/**
+ * Get table collation options for a model class
+ */
+function getTableCollateOptions(target) {
+    return tableCollateMetadata.get(target);
+}
+/**
+ * Get order by options for a model class
+ */
+function getOrderByOptions(target) {
+    return orderByMetadata.get(target) || [];
+}
+/**
+ * Clear all collate metadata (useful for testing)
+ */
+function clearCollateMetadata() {
+    collateMetadata.clear();
+    databaseMetadata.clear();
+    tableCollateMetadata.clear();
+    orderByMetadata.clear();
+}
+/**
+ * Generate SQL for creating a database with locale settings
+ */
+function generateCreateDatabaseSQL(options) {
+    const parts = [];
+    parts.push(`CREATE DATABASE ${options.name}`);
+    if (options.encoding) {
+        parts.push(`ENCODING = '${options.encoding}'`);
+    }
+    if (options.lcCollate) {
+        parts.push(`LC_COLLATE = '${options.lcCollate}'`);
+    }
+    if (options.lcCtype) {
+        parts.push(`LC_CTYPE = '${options.lcCtype}'`);
+    }
+    if (options.template) {
+        parts.push(`TEMPLATE = ${options.template}`);
+    }
+    if (options.tablespace) {
+        parts.push(`TABLESPACE = ${options.tablespace}`);
+    }
+    if (options.isTemplate !== undefined) {
+        parts.push(options.isTemplate ? 'IS_TEMPLATE = true' : 'IS_TEMPLATE = false');
+    }
+    if (options.collate) {
+        parts.push(`COLLATE = '${options.collate}'`);
+    }
+    return parts.join(' ');
+}
+/**
+ * Generate SQL for altering table collation
+ */
+function generateAlterTableCollateSQL(tableName, collate) {
+    return `ALTER TABLE ${tableName} CONVERT TO CHARACTER SET utf8mb4 COLLATE ${collate}`;
+}
+/**
+ * Generate SQL for column collation
+ */
+function generateColumnCollateSQL(columnName, collate) {
+    return `MODIFY ${columnName} VARCHAR(255) CHARACTER SET utf8mb4 COLLATE ${collate}`;
+}

package/dist/decorators/comment.js

@@ -0,0 +1,205 @@
+"use strict";
+/**
+ * @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;
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommentRegistry = void 0;
+exports.Comment = Comment;
+exports.getTableComment = getTableComment;
+exports.getFieldComment = getFieldComment;
+exports.getAllFieldComments = getAllFieldComments;
+exports.setIndexComment = setIndexComment;
+exports.getIndexComment = getIndexComment;
+exports.getAllIndexComments = getAllIndexComments;
+exports.setConstraintComment = setConstraintComment;
+exports.getConstraintComment = getConstraintComment;
+exports.getAllConstraintComments = getAllConstraintComments;
+exports.generateCommentSQL = generateCommentSQL;
+exports.generateIndexCommentSQL = generateIndexCommentSQL;
+exports.generateConstraintCommentSQL = generateConstraintCommentSQL;
+const TABLE_COMMENT_KEY = '__orm_table_comment__';
+const FIELD_COMMENTS_KEY = '__orm_field_comments__';
+const fieldCommentMap = new Map();
+const tableCommentMap = new Map();
+const indexCommentMap = new Map();
+const constraintCommentMap = new Map();
+function Comment(value) {
+    return function (target, propertyKey) {
+        const comment = value;
+        if (!propertyKey && typeof target === 'function') {
+            target[TABLE_COMMENT_KEY] = comment;
+            tableCommentMap.set(target, comment);
+            return;
+        }
+        if (propertyKey) {
+            const fieldName = String(propertyKey);
+            const constructor = typeof target === 'function' ? target : target.constructor;
+            if (!constructor[FIELD_COMMENTS_KEY]) {
+                constructor[FIELD_COMMENTS_KEY] = {};
+            }
+            constructor[FIELD_COMMENTS_KEY][fieldName] = comment;
+            if (!fieldCommentMap.has(constructor)) {
+                fieldCommentMap.set(constructor, new Map());
+            }
+            fieldCommentMap.get(constructor).set(fieldName, comment);
+        }
+    };
+}
+function getTableComment(target) {
+    return target[TABLE_COMMENT_KEY] ?? tableCommentMap.get(target);
+}
+function getFieldComment(target, fieldName) {
+    const fieldMap = target[FIELD_COMMENTS_KEY];
+    if (fieldMap) {
+        return fieldMap[fieldName];
+    }
+    return fieldCommentMap.get(target)?.get(fieldName);
+}
+function getAllFieldComments(target) {
+    const fieldMap = target[FIELD_COMMENTS_KEY];
+    if (fieldMap) {
+        return { ...fieldMap };
+    }
+    const map = fieldCommentMap.get(target);
+    return map ? Object.fromEntries(map) : {};
+}
+function setIndexComment(target, indexName, comment) {
+    if (!indexCommentMap.has(target)) {
+        indexCommentMap.set(target, new Map());
+    }
+    indexCommentMap.get(target).set(indexName, comment);
+}
+function getIndexComment(target, indexName) {
+    return indexCommentMap.get(target)?.get(indexName);
+}
+function getAllIndexComments(target) {
+    const map = indexCommentMap.get(target);
+    return map ? Object.fromEntries(map) : {};
+}
+function setConstraintComment(target, constraintName, comment) {
+    if (!constraintCommentMap.has(target)) {
+        constraintCommentMap.set(target, new Map());
+    }
+    constraintCommentMap.get(target).set(constraintName, comment);
+}
+function getConstraintComment(target, constraintName) {
+    return constraintCommentMap.get(target)?.get(constraintName);
+}
+function getAllConstraintComments(target) {
+    const map = constraintCommentMap.get(target);
+    return map ? Object.fromEntries(map) : {};
+}
+exports.CommentRegistry = {
+    getTableComment,
+    getFieldComment,
+    getAllFieldComments,
+    setIndexComment,
+    getIndexComment,
+    getAllIndexComments,
+    setConstraintComment,
+    getConstraintComment,
+    getAllConstraintComments,
+    clearComments(target) {
+        tableCommentMap.delete(target);
+        fieldCommentMap.delete(target);
+        indexCommentMap.delete(target);
+        constraintCommentMap.delete(target);
+        delete target[TABLE_COMMENT_KEY];
+        delete target[FIELD_COMMENTS_KEY];
+    },
+};
+function generateCommentSQL(target, tableName, dialect = 'mysql') {
+    const statements = [];
+    const table = tableName ?? target.name;
+    // SQLite has no COMMENT DDL of any kind — this is a genuine no-op.
+    if (dialect === 'sqlite') {
+        return statements;
+    }
+    const tableComment = getTableComment(target);
+    if (tableComment) {
+        const escapedComment = tableComment.replace(/'/g, "''");
+        switch (dialect) {
+            case 'postgres':
+                statements.push(`COMMENT ON TABLE "${table}" IS '${escapedComment}'`);
+                break;
+            case 'oracle':
+                statements.push(`COMMENT ON TABLE "${table}" IS '${escapedComment}'`);
+                break;
+            case 'mssql':
+                statements.push(`EXEC sp_addextendedproperty @name = N'MS_Description', @value = N'${escapedComment}', ` +
+                    `@level0type = N'SCHEMA', @level0name = N'dbo', ` +
+                    `@level1type = N'TABLE', @level1name = N'${table}'`);
+                break;
+            case 'mysql':
+            case 'mariadb':
+            default:
+                statements.push(`ALTER TABLE \`${table}\` COMMENT = '${escapedComment}'`);
+                break;
+        }
+    }
+    const fieldComments = getAllFieldComments(target);
+    for (const [fieldName, fieldComment] of Object.entries(fieldComments)) {
+        const escapedComment = fieldComment.replace(/'/g, "''");
+        switch (dialect) {
+            case 'postgres':
+                statements.push(`COMMENT ON COLUMN "${table}"."${fieldName}" IS '${escapedComment}'`);
+                break;
+            case 'oracle':
+                statements.push(`COMMENT ON COLUMN "${table}"."${fieldName}" IS '${escapedComment}'`);
+                break;
+            case 'mssql':
+                statements.push(`EXEC sp_addextendedproperty @name = N'MS_Description', @value = N'${escapedComment}', ` +
+                    `@level0type = N'SCHEMA', @level0name = N'dbo', ` +
+                    `@level1type = N'TABLE', @level1name = N'${table}', ` +
+                    `@level2type = N'COLUMN', @level2name = N'${fieldName}'`);
+                break;
+            case 'mysql':
+            case 'mariadb':
+            default:
+                statements.push(`ALTER TABLE \`${table}\` MODIFY \`${fieldName}\` COMMENT '${escapedComment}'`);
+                break;
+        }
+    }
+    return statements;
+}
+function generateIndexCommentSQL(target, tableName, dialect = 'mysql') {
+    const statements = [];
+    const indexComments = getAllIndexComments(target);
+    for (const [indexName, idxComment] of Object.entries(indexComments)) {
+        const escapedComment = idxComment.replace(/'/g, "''");
+        if (dialect === 'postgres') {
+            statements.push(`COMMENT ON INDEX "${indexName}" IS '${escapedComment}'`);
+        }
+    }
+    return statements;
+}
+function generateConstraintCommentSQL(target, tableName, dialect = 'mysql') {
+    const statements = [];
+    const constraintComments = getAllConstraintComments(target);
+    for (const [constraintName, constrComment] of Object.entries(constraintComments)) {
+        const escapedComment = constrComment.replace(/'/g, "''");
+        if (dialect === 'postgres') {
+            statements.push(`COMMENT ON CONSTRAINT "${constraintName}" ON "${tableName}" IS '${escapedComment}'`);
+        }
+    }
+    return statements;
+}