ts-prorm-orm 1.1.0

package/dist/decorators/timezone.js

@@ -0,0 +1,512 @@
+"use strict";
+/**
+ * Timezone Decorator for the ORM
+ *
+ * Provides automatic timezone conversion for date/time columns.
+ * Supports column-level, table-level, and database-level timezone configuration.
+ *
+ * Usage:
+ *
+ * // Column-level timezone
+ * @Timezone('UTC')  // Store as UTC, convert on read/write
+ * createdAt: Date;
+ *
+ * @Timezone('America/New_York')  // Eastern time
+ * orderPlacedAt: Date;
+ *
+ * @Timezone('Europe/London')  // British time
+ * updatedAt: Date;
+ *
+ * // Auto-detect from user context
+ * @Timezone({ from: 'user' })
+ * lastLoginAt: Date;
+ *
+ * // With format options
+ * @Timezone({
+ *   zone: 'UTC',
+ *   format: 'ISO',  // 'ISO', 'DATE', 'DATETIME', 'TIMESTAMP'
+ *   storeAs: 'utc'  // 'utc', 'local', 'string'
+ * })
+ * timestamp: Date;
+ *
+ * // Table-level default timezone
+ * @Table({ timezone: 'America/Los_Angeles' })
+ * class WestCoastOrder extends Model {}
+ *
+ * // Database-level timezone setting
+ * @DatabaseSetting('timezone', 'UTC')
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimezoneEnum = void 0;
+exports.setTimezoneContext = setTimezoneContext;
+exports.getTimezoneContext = getTimezoneContext;
+exports.clearTimezoneContext = clearTimezoneContext;
+exports.resolveTimezoneFromContext = resolveTimezoneFromContext;
+exports.getTimezoneFields = getTimezoneFields;
+exports.getTimezoneForField = getTimezoneForField;
+exports.getTableTimezone = getTableTimezone;
+exports.getDefaultTimezone = getDefaultTimezone;
+exports.convertToTimezone = convertToTimezone;
+exports.convertFromTimezone = convertFromTimezone;
+exports.formatDateTimezone = formatDateTimezone;
+exports.parseDate = parseDate;
+exports.convertOnRead = convertOnRead;
+exports.convertOnWrite = convertOnWrite;
+exports.Timezone = Timezone;
+exports.applyTimezoneToQuery = applyTimezoneToQuery;
+exports.convertWhereToTimezone = convertWhereToTimezone;
+exports.getEffectiveTimezone = getEffectiveTimezone;
+exports.getAllTimezoneFields = getAllTimezoneFields;
+exports.convertInstanceOnRead = convertInstanceOnRead;
+exports.convertInstanceOnWrite = convertInstanceOnWrite;
+exports.applyTimezoneHooks = applyTimezoneHooks;
+require("reflect-metadata");
+// ==================== Constants ====================
+/**
+ * Common timezone constants for easy reference
+ */
+exports.TimezoneEnum = {
+    UTC: 'UTC',
+    US_EASTERN: 'America/New_York',
+    US_CENTRAL: 'America/Chicago',
+    US_MOUNTAIN: 'America/Denver',
+    US_PACIFIC: 'America/Los_Angeles',
+    EUROPE_LONDON: 'Europe/London',
+    EUROPE_PARIS: 'Europe/Paris',
+    EUROPE_BERLIN: 'Europe/Berlin',
+    ASIA_TOKYO: 'Asia/Tokyo',
+    ASIA_SHANGHAI: 'Asia/Shanghai',
+    ASIA_SINGAPORE: 'Asia/Singapore',
+    AUSTRALIA_SYDNEY: 'Australia/Sydney',
+};
+/**
+ * Metadata keys for storing timezone information
+ */
+const TIMEZONE_FIELDS_KEY = '__orm_timezone_fields__';
+const TABLE_TIMEZONE_KEY = '__orm_table_timezone__';
+const DEFAULT_TIMEZONE_KEY = '__orm_default_timezone__';
+// ==================== Context Management ====================
+/**
+ * Current timezone context (thread-local storage for request scope)
+ */
+let currentTimezoneContext = null;
+/**
+ * Set timezone context for current request/operation
+ *
+ * @param context - The timezone context
+ */
+function setTimezoneContext(context) {
+    currentTimezoneContext = context;
+}
+/**
+ * Get current timezone context
+ *
+ * @returns The current timezone context
+ */
+function getTimezoneContext() {
+    return currentTimezoneContext;
+}
+/**
+ * Clear timezone context
+ */
+function clearTimezoneContext() {
+    currentTimezoneContext = null;
+}
+/**
+ * Get timezone from context based on source configuration
+ *
+ * @param source - The timezone source configuration
+ * @returns The resolved timezone string
+ */
+function resolveTimezoneFromContext(source) {
+    if (typeof source === 'string') {
+        return source;
+    }
+    if (typeof source === 'object' && 'from' in source) {
+        const ctx = currentTimezoneContext;
+        if (!ctx)
+            return undefined;
+        switch (source.from) {
+            case 'user':
+                return ctx.timezone;
+            case 'request':
+            case 'context':
+                return ctx.timezone || ctx.request?.timezone || ctx.timezone;
+            default:
+                return undefined;
+        }
+    }
+    return undefined;
+}
+// ==================== Metadata Storage ====================
+/**
+ * Get all timezone field metadata from a model class
+ */
+function getTimezoneFields(target) {
+    return target[TIMEZONE_FIELDS_KEY] || [];
+}
+/**
+ * Get timezone metadata for a specific field
+ */
+function getTimezoneForField(target, field) {
+    const fields = getTimezoneFields(target);
+    return fields.find((f) => f.field === field);
+}
+/**
+ * Get table-level timezone configuration
+ */
+function getTableTimezone(target) {
+    return target[TABLE_TIMEZONE_KEY];
+}
+/**
+ * Get default timezone from class
+ */
+function getDefaultTimezone(target) {
+    return target[DEFAULT_TIMEZONE_KEY];
+}
+// ==================== Timezone Conversion ====================
+/**
+ * Convert date to specified timezone
+ *
+ * @param date - The date to convert
+ * @param targetZone - Target timezone (e.g., 'America/New_York')
+ * @returns Date adjusted to target timezone
+ */
+function convertToTimezone(date, targetZone) {
+    // Get offset for target timezone
+    const targetDate = new Date(date.toLocaleString('en-US', { timeZone: targetZone }));
+    const utcDate = new Date(date.toLocaleString('en-US', { timeZone: 'UTC' }));
+    const offsetMs = targetDate.getTime() - utcDate.getTime();
+    const result = new Date(date.getTime() + offsetMs);
+    return result;
+}
+/**
+ * Convert date from specified timezone to UTC
+ *
+ * @param date - The date to convert
+ * @param sourceZone - Source timezone (e.g., 'America/New_York')
+ * @returns Date in UTC
+ */
+function convertFromTimezone(date, sourceZone) {
+    // Create date as if it's in the source timezone
+    const str = date.toISOString();
+    const sourceDateStr = date.toLocaleString('en-US', { timeZone: sourceZone });
+    const sourceDate = new Date(sourceDateStr);
+    // Calculate the offset
+    const utcDate = new Date(date.toLocaleString('en-US', { timeZone: 'UTC' }));
+    const offsetMs = sourceDate.getTime() - utcDate.getTime();
+    return new Date(date.getTime() - offsetMs);
+}
+/**
+ * Format date according to specified format
+ *
+ * @param date - The date to format
+ * @param format - The format type
+ * @returns Formatted date string or timestamp
+ */
+function formatDateTimezone(date, format) {
+    switch (format) {
+        case 'ISO':
+            return date.toISOString();
+        case 'DATE':
+            return date.toISOString().split('T')[0];
+        case 'DATETIME':
+            return date.toISOString().replace('T', ' ').split('.')[0];
+        case 'TIMESTAMP':
+            return date.getTime();
+        default:
+            return date.toISOString();
+    }
+}
+/**
+ * Parse date from database storage format
+ *
+ * @param value - The value from database
+ * @param format - The expected format
+ * @returns Parsed Date object
+ */
+function parseDate(value, format) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (value instanceof Date) {
+        return value;
+    }
+    if (typeof value === 'number') {
+        // Timestamp
+        return new Date(value);
+    }
+    if (typeof value === 'string') {
+        return new Date(value);
+    }
+    return null;
+}
+// ==================== Field-Level Operations ====================
+/**
+ * Convert value when reading from database
+ *
+ * @param value - Raw value from database
+ * @param meta - Timezone metadata
+ * @returns Converted value
+ */
+function convertOnRead(value, meta) {
+    if (!meta.convertOnRead) {
+        return value;
+    }
+    const date = parseDate(value, meta.format);
+    if (!date) {
+        return value;
+    }
+    // Resolve actual timezone
+    let targetZone;
+    if (typeof meta.zone === 'string') {
+        targetZone = meta.zone;
+    }
+    else {
+        targetZone = resolveTimezoneFromContext(meta.zone);
+    }
+    if (!targetZone) {
+        return value;
+    }
+    // Convert to target timezone
+    const converted = convertToTimezone(date, targetZone);
+    // Return in requested format
+    if (meta.storeAs === 'string') {
+        return formatDateTimezone(converted, meta.format);
+    }
+    return converted;
+}
+/**
+ * Convert value when writing to database
+ *
+ * @param value - Value from application
+ * @param meta - Timezone metadata
+ * @returns Value ready for database
+ */
+function convertOnWrite(value, meta) {
+    if (!meta.convertOnWrite) {
+        return value;
+    }
+    if (value === null || value === undefined) {
+        return value;
+    }
+    const date = value instanceof Date ? value : new Date(value);
+    if (isNaN(date.getTime())) {
+        return value;
+    }
+    // Resolve source timezone
+    let sourceZone;
+    if (typeof meta.zone === 'string') {
+        sourceZone = meta.zone;
+    }
+    else {
+        sourceZone = resolveTimezoneFromContext(meta.zone);
+    }
+    // If storing as UTC, convert to UTC
+    if (meta.storeAs === 'utc') {
+        return date.toISOString();
+    }
+    // If storing as string with timezone info
+    if (meta.storeAs === 'string') {
+        return formatDateTimezone(date, meta.format);
+    }
+    // Store as local time
+    return date;
+}
+// ==================== Decorators ====================
+/**
+ * Column-level timezone decorator
+ *
+ * @param options - Timezone options or timezone string
+ */
+function Timezone(options = {}) {
+    return function (target, propertyKey) {
+        const field = propertyKey;
+        const column = typeof options === 'string' ? options : options.column || propertyKey;
+        const zone = typeof options === 'string' ? options : options.zone || 'UTC';
+        const format = typeof options === 'string' ? 'ISO' : options.format || 'ISO';
+        const storeAs = typeof options === 'string' ? 'utc' : options.storeAs || 'utc';
+        const convertOnRead = typeof options === 'string' ? true : (options.convertOnRead ?? true);
+        const convertOnWrite = typeof options === 'string' ? true : (options.convertOnWrite ?? true);
+        // Store on the prototype (class), not the instance
+        const Constructor = target.constructor;
+        if (!Constructor[TIMEZONE_FIELDS_KEY]) {
+            Constructor[TIMEZONE_FIELDS_KEY] = [];
+        }
+        Constructor[TIMEZONE_FIELDS_KEY].push({
+            field,
+            column,
+            zone,
+            format,
+            storeAs,
+            convertOnRead,
+            convertOnWrite,
+        });
+    };
+}
+// ==================== Query Helper ====================
+/**
+ * Apply timezone conversion to query options
+ *
+ * @param queryOptions - Original query options
+ * @param targetTimezone - Target timezone for conversion
+ * @returns Modified query options with timezone
+ */
+function applyTimezoneToQuery(queryOptions, targetTimezone) {
+    if (!queryOptions) {
+        return { timezone: targetTimezone };
+    }
+    return {
+        ...queryOptions,
+        timezone: targetTimezone,
+    };
+}
+/**
+ * Convert where clause dates to specified timezone
+ *
+ * @param where - Original where clause
+ * @param timezone - Target timezone
+ * @returns Modified where clause with timezone context
+ */
+function convertWhereToTimezone(where, timezone) {
+    if (!where) {
+        return where;
+    }
+    // Process each key in the where clause
+    const result = {};
+    for (const [key, value] of Object.entries(where)) {
+        if (value instanceof Date) {
+            // Convert date to target timezone
+            result[key] = convertToTimezone(value, timezone);
+        }
+        else if (typeof value === 'object' && value !== null) {
+            // Recursively process nested objects
+            result[key] = convertWhereToTimezone(value, timezone);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+// ==================== Model-Level Helpers ====================
+/**
+ * Get effective timezone for a field (column-level or table-level default)
+ *
+ * @param target - Model class
+ * @param field - Field name
+ * @returns Effective timezone or undefined
+ */
+function getEffectiveTimezone(target, field) {
+    // Check column-level first
+    const fieldMeta = getTimezoneForField(target, field);
+    if (fieldMeta) {
+        if (typeof fieldMeta.zone === 'string') {
+            return fieldMeta.zone;
+        }
+        return resolveTimezoneFromContext(fieldMeta.zone);
+    }
+    // Fall back to table-level default
+    const tableOptions = getTableTimezone(target);
+    if (tableOptions?.timezone) {
+        return tableOptions.timezone;
+    }
+    // Fall back to global default
+    return getDefaultTimezone(target);
+}
+/**
+ * Get all timezone metadata for a model including table defaults
+ *
+ * @param target - Model class
+ * @returns Array of timezone field metadata
+ */
+function getAllTimezoneFields(target) {
+    return getTimezoneFields(target);
+}
+/**
+ * Convert model instance field values based on timezone metadata
+ *
+ * @param instance - Model instance
+ * @param targetTimezone - Target timezone for conversion
+ * @returns Converted instance values
+ */
+function convertInstanceOnRead(instance, targetTimezone) {
+    const ModelClass = instance.constructor;
+    const timezoneFields = getTimezoneFields(ModelClass);
+    if (timezoneFields.length === 0) {
+        return instance;
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(instance.toJSON ? instance.toJSON() : instance)) {
+        const meta = timezoneFields.find((f) => f.field === key || f.column === key);
+        if (meta) {
+            result[key] = convertOnRead(value, {
+                ...meta,
+                zone: targetTimezone,
+            });
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Convert model instance field values before writing to database
+ *
+ * @param instance - Model instance
+ * @returns Converted values ready for database
+ */
+function convertInstanceOnWrite(instance) {
+    const ModelClass = instance.constructor;
+    const timezoneFields = getTimezoneFields(ModelClass);
+    if (timezoneFields.length === 0) {
+        return instance;
+    }
+    const result = {};
+    const data = instance.getDataValue
+        ? (() => {
+            const data = {};
+            for (const f of timezoneFields) {
+                data[f.column] = instance.getDataValue(f.field);
+            }
+            return data;
+        })()
+        : instance;
+    for (const [key, value] of Object.entries(data)) {
+        const meta = timezoneFields.find((f) => f.field === key || f.column === key);
+        if (meta) {
+            const converted = convertOnWrite(value, meta);
+            result[meta.column] = converted;
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+// ==================== Hook Registration ====================
+/**
+ * Register hooks for automatic timezone conversion
+ * Call this after Model.init()
+ *
+ * @param ModelClass - The model class
+ */
+function applyTimezoneHooks(ModelClass) {
+    const timezoneFields = getTimezoneFields(ModelClass);
+    if (timezoneFields.length === 0)
+        return;
+    // Before find hooks to set timezone context
+    if (typeof ModelClass.addHook === 'function') {
+        ModelClass.addHook('beforeFind', 'orm:timezone', async (instance) => {
+            // Set context based on query options if timezone specified
+            const timezone = instance._timezone || instance.timezone;
+            if (timezone) {
+                setTimezoneContext({ timezone });
+            }
+        });
+        ModelClass.addHook('afterFind', 'orm:timezone', async () => {
+            clearTimezoneContext();
+        });
+    }
+}

package/dist/decorators/trigger.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * @Trigger class decorator — declare a database trigger on a model class.
+ *
+ * Stores trigger metadata using plain class properties (no reflect-metadata
+ * dependency) consistent with the rest of this decorator suite.
+ *
+ * Example:
+ *
+ *   @Trigger({
+ *     name: 'trg_users_audit',
+ *     timing: 'AFTER',
+ *     event: 'INSERT',
+ *     body: `INSERT INTO audit_log(action, ts) VALUES ('INSERT', NOW())`,
+ *     forEach: 'ROW',
+ *   })
+ *   class User extends Model { ... }
+ *
+ *   // Retrieve trigger definitions:
+ *   const triggers = getTriggers(User);
+ *
+ *   // Generate DDL:
+ *   const sql = buildCreateTriggerSQL('users', triggers[0], 'mysql');
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Trigger = Trigger;
+exports.getTriggers = getTriggers;
+exports.buildCreateTriggerSQL = buildCreateTriggerSQL;
+// ==================== Metadata key ====================
+const TRIGGERS_KEY = '__orm_triggers__';
+// ==================== Decorator ====================
+/**
+ * Attach a trigger definition to a model class.
+ * Multiple @Trigger decorators may be stacked on the same class.
+ */
+function Trigger(options) {
+    return (target) => {
+        if (!target[TRIGGERS_KEY]) {
+            target[TRIGGERS_KEY] = [];
+        }
+        target[TRIGGERS_KEY] = [...target[TRIGGERS_KEY], options];
+    };
+}
+// ==================== Helpers ====================
+/**
+ * Return all trigger definitions registered on a class.
+ */
+function getTriggers(target) {
+    return target[TRIGGERS_KEY] || [];
+}
+/**
+ * Generate a CREATE TRIGGER DDL statement for the given dialect.
+ *
+ * Supported dialects: 'mysql' | 'mariadb' | 'postgres' | 'sqlite'
+ */
+function buildCreateTriggerSQL(tableName, trigger, dialect) {
+    const forEach = trigger.forEach ?? 'ROW';
+    const name = trigger.name;
+    switch (dialect) {
+        case 'postgres': {
+            // PostgreSQL requires a trigger function; we embed the body in a
+            // DO-style anonymous block as a convention for metadata purposes.
+            const fnName = `${name}_fn`;
+            const createFn = `CREATE OR REPLACE FUNCTION ${fnName}()\n` +
+                `RETURNS TRIGGER LANGUAGE plpgsql AS $$\n` +
+                `BEGIN\n  ${trigger.body}\n  RETURN NEW;\nEND;\n$$`;
+            const createTrg = `CREATE TRIGGER ${name}\n` +
+                `  ${trigger.timing} ${trigger.event}\n` +
+                `  ON "${tableName}"\n` +
+                `  FOR EACH ${forEach}\n` +
+                `  EXECUTE FUNCTION ${fnName}()`;
+            return `${createFn};\n\n${createTrg}`;
+        }
+        case 'sqlite': {
+            // SQLite does not support FOR EACH STATEMENT; always ROW-level implicitly.
+            return (`CREATE TRIGGER IF NOT EXISTS ${name}\n` +
+                `  ${trigger.timing} ${trigger.event}\n` +
+                `  ON \`${tableName}\`\n` +
+                `BEGIN\n  ${trigger.body};\nEND`);
+        }
+        // mysql / mariadb (default)
+        default: {
+            return (`CREATE TRIGGER \`${name}\`\n` +
+                `  ${trigger.timing} ${trigger.event}\n` +
+                `  ON \`${tableName}\`\n` +
+                `  FOR EACH ${forEach}\n` +
+                `BEGIN\n  ${trigger.body};\nEND`);
+        }
+    }
+}