ts-prorm-orm 1.1.0

package/dist/decorators/database-settings.js

@@ -0,0 +1,236 @@
+"use strict";
+/**
+ * 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);
+ *   });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ForeignKeyChecks = ForeignKeyChecks;
+exports.DatabaseSetting = DatabaseSetting;
+exports.getForeignKeyChecksSetting = getForeignKeyChecksSetting;
+exports.getDatabaseSettings = getDatabaseSettings;
+exports.isForeignKeyChecksDisabled = isForeignKeyChecksDisabled;
+exports.getAllDatabaseSettings = getAllDatabaseSettings;
+exports.generateSettingsSQL = generateSettingsSQL;
+exports.createSettingsContext = createSettingsContext;
+require("reflect-metadata");
+// ==================== Metadata Keys ====================
+const FOREIGN_KEY_CHECKS_KEY = Symbol('prorm:foreignKeyChecks');
+const DATABASE_SETTINGS_KEY = Symbol('prorm:databaseSettings');
+// ==================== Decorators ====================
+/**
+ * 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
+ */
+function ForeignKeyChecks(options = { enabled: true }) {
+    return function (target) {
+        Reflect.defineMetadata(FOREIGN_KEY_CHECKS_KEY, { enabled: options.enabled ?? true, description: options.description }, target);
+    };
+}
+/**
+ * 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
+ */
+function DatabaseSetting(name, value) {
+    return function (target) {
+        // Get existing settings
+        const settings = getDatabaseSettings(target.prototype) || {};
+        // Store the new setting
+        settings[name] = value;
+        Reflect.defineMetadata(DATABASE_SETTINGS_KEY, settings, target);
+    };
+}
+// ==================== Helper Functions ====================
+/**
+ * Get foreign key checks setting for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns The foreign key checks setting or undefined
+ */
+function getForeignKeyChecksSetting(target) {
+    const metadata = Reflect.getMetadata(FOREIGN_KEY_CHECKS_KEY, target);
+    return metadata?.enabled;
+}
+/**
+ * Get all database settings for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns The database settings object
+ */
+function getDatabaseSettings(target) {
+    return Reflect.getMetadata(DATABASE_SETTINGS_KEY, target);
+}
+/**
+ * Check if foreign key checks are disabled for a model.
+ *
+ * @param target - The target class or prototype
+ * @returns True if FK checks are disabled
+ */
+function isForeignKeyChecksDisabled(target) {
+    return getForeignKeyChecksSetting(target) === false;
+}
+/**
+ * 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
+ */
+function getAllDatabaseSettings(target) {
+    const result = {
+        additionalSettings: {},
+    };
+    // Collect from prototype chain
+    let current = target;
+    while (current && current !== Object.prototype) {
+        const settings = getDatabaseSettings(current);
+        if (settings) {
+            if (settings.foreignKeyChecks !== undefined) {
+                result.foreignKeyChecks = settings.foreignKeyChecks;
+            }
+            if (settings.uniqueChecks !== undefined) {
+                result.uniqueChecks = settings.uniqueChecks;
+            }
+            if (settings.autocommit !== undefined) {
+                result.autocommit = settings.autocommit;
+            }
+            if (settings.sqlMode !== undefined) {
+                result.sqlMode = settings.sqlMode;
+            }
+            if (settings.additionalSettings) {
+                result.additionalSettings = {
+                    ...result.additionalSettings,
+                    ...settings.additionalSettings,
+                };
+            }
+        }
+        const fkSetting = getForeignKeyChecksSetting(current);
+        if (fkSetting !== undefined) {
+            result.foreignKeyChecks = fkSetting;
+        }
+        current = Object.getPrototypeOf(current);
+    }
+    return result;
+}
+/**
+ * Generate SQL to apply database settings.
+ *
+ * @param settings - The database settings
+ * @returns Array of SQL statements to execute
+ */
+function generateSettingsSQL(settings) {
+    const statements = [];
+    if (settings.foreignKeyChecks !== undefined) {
+        statements.push(`SET FOREIGN_KEY_CHECKS = ${settings.foreignKeyChecks ? 1 : 0}`);
+    }
+    if (settings.uniqueChecks !== undefined) {
+        statements.push(`SET UNIQUE_CHECKS = ${settings.uniqueChecks ? 1 : 0}`);
+    }
+    if (settings.autocommit !== undefined) {
+        statements.push(`SET AUTOCOMMIT = ${settings.autocommit ? 1 : 0}`);
+    }
+    if (settings.sqlMode) {
+        statements.push(`SET SQL_MODE = '${settings.sqlMode}'`);
+    }
+    if (settings.additionalSettings) {
+        for (const [name, value] of Object.entries(settings.additionalSettings)) {
+            if (value !== null && value !== undefined) {
+                const valStr = typeof value === 'string' ? `'${value}'` : String(value);
+                statements.push(`SET ${name} = ${valStr}`);
+            }
+        }
+    }
+    return statements;
+}
+/**
+ * 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
+ */
+function createSettingsContext(settings) {
+    return {
+        async execute(fn) {
+            // Generate and execute SET statements before
+            const beforeSQL = generateSettingsSQL(settings);
+            // Note: In practice, these would be executed via prorm.query()
+            // For now, we just execute the function
+            try {
+                return await fn();
+            }
+            finally {
+                // Could restore original settings here if needed
+                const afterSQL = generateSettingsSQL({});
+                // Note: In practice, restore settings here
+            }
+        },
+    };
+}
+// ==================== Exports ====================
+// Types are exported inline with the interfaces/classes above

package/dist/decorators/default.js

@@ -0,0 +1,244 @@
+"use strict";
+/**
+ * Default Value Decorator for the ORM
+ *
+ * Provides a type-safe way to set column defaults without raw SQL.
+ * Supports static values, functions, sequences, and database functions.
+ *
+ * Usage:
+ *
+ *   // Static values
+ *   @Default(18)
+ *   age: number;
+ *
+ *   @Default(true)
+ *   isActive: boolean;
+ *
+ *   @Default('pending')
+ *   status: string;
+ *
+ *   // Function for dynamic default
+ *   @Default(() => new Date())
+ *   createdAt: Date;
+ *
+ *   // Auto-generate UUID
+ *   @Default(() => uuidv4())
+ *   id: string;
+ *
+ *   // For JSON columns
+ *   @Default({ role: 'user', verified: false })
+ *   preferences: object;
+ *
+ *   // For array columns
+ *   @Default(['admin'])
+ *   roles: string[];
+ *
+ *   // Auto-sequences (PostgreSQL)
+ *   @Default({ sequence: 'user_id_seq' })
+ *   id: number;
+ *
+ *   // Database functions
+ *   @Default({ fn: 'now' })
+ *   createdAt: Date;
+ *
+ *   @Default({ fn: 'upper', args: ['username'] })
+ *   username: string;
+ *
+ *   // Raw SQL only when needed
+ *   @Default({ literal: "CURRENT_TIMESTAMP" })
+ *   updatedAt: Date;
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultFields = getDefaultFields;
+exports.getDefaultForField = getDefaultForField;
+exports.toPrormDefault = toPrormDefault;
+exports.applyDefaultValues = applyDefaultValues;
+exports.applyDefaultHooks = applyDefaultHooks;
+exports.Default = Default;
+exports.uuidDefault = uuidDefault;
+exports.nowDefault = nowDefault;
+exports.randomIntDefault = randomIntDefault;
+exports.computedDefault = computedDefault;
+// ==================== Metadata Storage ====================
+const DEFAULT_FIELDS_KEY = '__orm_default_fields__';
+/**
+ * Get all default field metadata from a model class.
+ */
+function getDefaultFields(target) {
+    return target[DEFAULT_FIELDS_KEY] || [];
+}
+/**
+ * Get default value for a specific field.
+ */
+function getDefaultForField(target, field) {
+    const fields = getDefaultFields(target);
+    return fields.find((f) => f.field === field)?.options;
+}
+/**
+ * Convert @Default options to prorm column definition format.
+ * This is used when initializing the model.
+ */
+function toPrormDefault(options) {
+    // Handle static values
+    if (!isDefaultOptionsObject(options)) {
+        return { defaultValue: options };
+    }
+    // Handle function defaults
+    if ('fn' in options && typeof options.fn === 'function') {
+        return { defaultValue: options.fn() };
+    }
+    // Handle sequence (returns raw SQL for PostgreSQL)
+    if ('sequence' in options) {
+        return {
+            defaultValue: prorm_lite_literal(`nextval('${options.sequence}')`),
+        };
+    }
+    // Handle database function
+    if ('fn' in options) {
+        const fnName = options.fn;
+        const args = options.args || [];
+        const argsStr = args.map((a) => (typeof a === 'string' ? `'${a}'` : a)).join(', ');
+        return {
+            defaultValue: prorm_lite_literal(`${fnName}(${argsStr})`),
+        };
+    }
+    // Handle literal
+    if ('literal' in options) {
+        return { defaultValue: prorm_lite_literal(options.literal) };
+    }
+    return { defaultValue: undefined };
+}
+/**
+ * Check if value is a DefaultValueOptions object (not a primitive).
+ */
+function isDefaultOptionsObject(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        (('fn' in value && typeof value.fn === 'function') ||
+            'sequence' in value ||
+            'fn' in value ||
+            'literal' in value));
+}
+/**
+ * Create a prorm.literal() wrapper.
+ * This is detected by the ORM and handled appropriately.
+ */
+function prorm_lite_literal(sql) {
+    // Return a special object that gets handled by the query compiler
+    return { __orm_literal: sql };
+}
+/**
+ * Apply default values to a model instance.
+ * Call this in beforeCreate/beforeUpdate hooks.
+ *
+ * @param instance - The model instance
+ */
+function applyDefaultValues(instance) {
+    const ModelClass = instance.constructor;
+    const defaultFields = getDefaultFields(ModelClass);
+    for (const { field, options } of defaultFields) {
+        // Skip if value is already set
+        const currentValue = instance.getDataValue ? instance.getDataValue(field) : instance[field];
+        if (currentValue !== undefined && currentValue !== null) {
+            continue;
+        }
+        // Handle function defaults (dynamic values)
+        if (options &&
+            typeof options === 'object' &&
+            'fn' in options &&
+            typeof options.fn === 'function') {
+            const defaultValue = options.fn();
+            if (instance.setDataValue) {
+                instance.setDataValue(field, defaultValue);
+            }
+            else {
+                instance[field] = defaultValue;
+            }
+        }
+        // Handle static defaults
+        else if (!isDefaultOptionsObject(options)) {
+            if (instance.setDataValue) {
+                instance.setDataValue(field, options);
+            }
+            else {
+                instance[field] = options;
+            }
+        }
+        // Database functions and sequences are handled by the database,
+        // so we don't apply them at runtime
+    }
+}
+/**
+ * Register beforeCreate hook to automatically apply default values.
+ * Call once per model after Model.init().
+ *
+ * @param ModelClass - The model class
+ */
+function applyDefaultHooks(ModelClass) {
+    const fields = getDefaultFields(ModelClass);
+    if (fields.length === 0)
+        return;
+    if (typeof ModelClass.addHook === 'function') {
+        ModelClass.addHook('beforeCreate', 'orm:defaultValues', async (instance) => {
+            applyDefaultValues(instance);
+        });
+    }
+}
+// ==================== Decorator ====================
+/**
+ * Set a default value for a model field.
+ *
+ * Can be used as:
+ * - @Default(18) - static value
+ * - @Default(() => new Date()) - function for dynamic defaults
+ * - @Default({ sequence: 'user_id_seq' }) - database sequence
+ * - @Default({ fn: 'now' }) - database function
+ * - @Default({ literal: "CURRENT_TIMESTAMP" }) - raw SQL
+ *
+ * @param options - The default value or configuration
+ */
+function Default(options) {
+    return function (target, propertyKey) {
+        const field = propertyKey;
+        // Store on the prototype (class), not the instance
+        const Constructor = target.constructor;
+        if (!Constructor[DEFAULT_FIELDS_KEY]) {
+            Constructor[DEFAULT_FIELDS_KEY] = [];
+        }
+        Constructor[DEFAULT_FIELDS_KEY].push({ field, options });
+    };
+}
+// ==================== Utility Functions ====================
+/**
+ * Helper to create a UUID default.
+ * Usage: @Default(() => uuidv4())
+ */
+function uuidDefault() {
+    // Simple UUID v4 implementation
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+/**
+ * Helper to create a current timestamp default.
+ * Usage: @Default(() => new Date())
+ */
+function nowDefault() {
+    return new Date();
+}
+/**
+ * Helper to create a random integer default.
+ * Usage: @Default(() => Math.floor(Math.random() * 100))
+ */
+function randomIntDefault(min = 0, max = 100) {
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+/**
+ * Helper to create a default based on another field.
+ * Usage: @Default((instance) => instance.username?.toLowerCase())
+ */
+function computedDefault(computeFn) {
+    return { fn: computeFn };
+}