ts-prorm-orm 1.1.0

package/dist/audit/history-query.js

@@ -0,0 +1,180 @@
+"use strict";
+/**
+ * Audit History Query methods
+ * Provides model-level and instance-level methods for querying audit history
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setAuditLogger = setAuditLogger;
+exports.getAuditLogger = getAuditLogger;
+exports.addAuditHistoryToModel = addAuditHistoryToModel;
+exports.addAuditHistoryToInstance = addAuditHistoryToInstance;
+// Store reference to the AuditLogger instance
+let auditLoggerInstance = null;
+/**
+ * Set the global AuditLogger instance
+ * This should be called once when setting up audit logging
+ *
+ * @param logger - The AuditLogger instance
+ */
+function setAuditLogger(logger) {
+    auditLoggerInstance = logger;
+}
+/**
+ * Get the current AuditLogger instance
+ */
+function getAuditLogger() {
+    return auditLoggerInstance;
+}
+// ==================== Model-Level Methods ====================
+/**
+ * Add model-level audit history methods to a Model class
+ *
+ * @param model - The Model static (class) to add methods to
+ */
+function addAuditHistoryToModel(model) {
+    const tableName = model.tableName || model.name;
+    /**
+     * Get audit history for this model
+     *
+     * @param options - Query options
+     * @returns Promise resolving to array of AuditLog entries
+     *
+     * @example
+     * const history = await User.getAuditHistory({ limit: 10 });
+     */
+    model.getAuditHistory = async function (options) {
+        const logger = getAuditLogger();
+        if (!logger) {
+            throw new Error('AuditLogger not initialized. Call setAuditLogger() first.');
+        }
+        return logger.getHistory(tableName, undefined, options);
+    };
+    /**
+     * Get audit history for a specific record
+     *
+     * @param recordId - The record ID
+     * @param options - Query options
+     * @returns Promise resolving to array of AuditLog entries
+     *
+     * @example
+     * const history = await User.getAuditHistoryForRecord(123);
+     */
+    model.getAuditHistoryForRecord = async function (recordId, options) {
+        const logger = getAuditLogger();
+        if (!logger) {
+            throw new Error('AuditLogger not initialized. Call setAuditLogger() first.');
+        }
+        return logger.getHistory(tableName, recordId, options);
+    };
+    // Store table name for instance methods
+    model.__auditTableName__ = tableName;
+}
+/**
+ * Add instance-level audit history methods to a ModelInstance
+ *
+ * @param instance - The Model instance prototype
+ */
+function addAuditHistoryToInstance(instance) {
+    /**
+     * Get audit history for this specific record
+     *
+     * @param options - Query options
+     * @returns Promise resolving to array of AuditLog entries
+     *
+     * @example
+     * const user = await User.findById(123);
+     * const history = await user.getAuditHistory();
+     */
+    instance.getAuditHistory = async function (options) {
+        const logger = getAuditLogger();
+        if (!logger) {
+            throw new Error('AuditLogger not initialized. Call setAuditLogger() first.');
+        }
+        const model = this.constructor;
+        const tableName = model.tableName || model.name;
+        const recordId = this.id;
+        return logger.getHistory(tableName, recordId, options);
+    };
+    /**
+     * Get the previous value of a specific field
+     *
+     * @param fieldName - The name of the field
+     * @returns The previous value of the field, or undefined
+     *
+     * @example
+     * const user = await User.findById(123);
+     * await user.update({ name: 'John' });
+     * const previousName = user.getPreviousValue('name');
+     * console.log(previousName); // 'Jane'
+     */
+    instance.getPreviousValue = function (fieldName) {
+        const previousDataValues = this._previousDataValues;
+        if (!previousDataValues) {
+            return undefined;
+        }
+        return previousDataValues[fieldName];
+    };
+    /**
+     * Get all previous values
+     *
+     * @returns Object containing previous field values
+     *
+     * @example
+     * const user = await User.findById(123);
+     * await user.update({ name: 'John', email: 'john@example.com' });
+     * const previousValues = user.getPreviousValues();
+     */
+    instance.getPreviousValues = function () {
+        return this._previousDataValues ? { ...this._previousDataValues } : {};
+    };
+    /**
+     * Check if a field was changed
+     *
+     * @param fieldName - The name of the field
+     * @returns True if the field was changed
+     *
+     * @example
+     * const user = await User.findById(123);
+     * await user.update({ name: 'John' });
+     * console.log(user.wasChanged('name')); // true
+     */
+    instance.wasChanged = function (fieldName) {
+        const previousDataValues = this._previousDataValues;
+        if (!previousDataValues) {
+            return false;
+        }
+        return previousDataValues[fieldName] !== undefined;
+    };
+    /**
+     * Get changes between previous and current values
+     *
+     * @returns Object with changed fields and their old/new values
+     *
+     * @example
+     * const user = await User.findById(123);
+     * await user.update({ name: 'John', email: 'john@example.com' });
+     * const changes = user.getChanges();
+     * // { name: { old: 'Jane', new: 'John' }, ... }
+     */
+    instance.getChanges = function () {
+        const changes = {};
+        const previousDataValues = this._previousDataValues || {};
+        const currentValues = this.dataValues || {};
+        const allKeys = new Set([...Object.keys(previousDataValues), ...Object.keys(currentValues)]);
+        for (const key of allKeys) {
+            const oldVal = previousDataValues[key];
+            const newVal = currentValues[key];
+            if (oldVal !== newVal) {
+                changes[key] = { old: oldVal, new: newVal };
+            }
+        }
+        return changes;
+    };
+}
+// ==================== Default Export ====================
+exports.default = {
+    setAuditLogger,
+    getAuditLogger,
+    addAuditHistoryToModel,
+    addAuditHistoryToInstance,
+};

package/dist/audit/index.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Audit Module
+ * Provides audit logging capabilities for tracking model changes
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addAuditHistoryToInstance = exports.addAuditHistoryToModel = exports.getAuditLogger = exports.setAuditLogger = exports.AuditLogger = void 0;
+var logger_1 = require("./logger");
+Object.defineProperty(exports, "AuditLogger", { enumerable: true, get: function () { return logger_1.AuditLogger; } });
+var history_query_1 = require("./history-query");
+Object.defineProperty(exports, "setAuditLogger", { enumerable: true, get: function () { return history_query_1.setAuditLogger; } });
+Object.defineProperty(exports, "getAuditLogger", { enumerable: true, get: function () { return history_query_1.getAuditLogger; } });
+Object.defineProperty(exports, "addAuditHistoryToModel", { enumerable: true, get: function () { return history_query_1.addAuditHistoryToModel; } });
+Object.defineProperty(exports, "addAuditHistoryToInstance", { enumerable: true, get: function () { return history_query_1.addAuditHistoryToInstance; } });
+const logger_2 = require("./logger");
+const history_query_2 = require("./history-query");
+exports.default = {
+    AuditLogger: logger_2.AuditLogger,
+    setAuditLogger: history_query_2.setAuditLogger,
+    getAuditLogger: history_query_2.getAuditLogger,
+    addAuditHistoryToModel: history_query_2.addAuditHistoryToModel,
+    addAuditHistoryToInstance: history_query_2.addAuditHistoryToInstance,
+};

package/dist/audit/logger.js

@@ -0,0 +1,236 @@
+"use strict";
+/**
+ * Audit Logger for the TypeScript ORM
+ * Provides persistent audit logging for model changes with database storage
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuditLogger = void 0;
+const data_types_1 = require("../models/data-types");
+// ==================== AuditLogger Class ====================
+/**
+ * AuditLogger - Provides persistent audit logging for model changes
+ *
+ * @example
+ * const auditLogger = new AuditLogger(prorm);
+ * await auditLogger.setupHooks();
+ *
+ * // Manually log an action
+ * await auditLogger.logAction('CREATE', 'User', 1, {}, { name: 'John' });
+ *
+ * // Get audit history
+ * const history = await auditLogger.getHistory('User', 1);
+ */
+class AuditLogger {
+    /**
+     * Create a new AuditLogger instance
+     *
+     * @param prorm - The Prorm instance
+     * @param options - Optional configuration options
+     */
+    constructor(prorm, options) {
+        this.auditModel = null;
+        this.hookedModels = new Set();
+        this.prorm = prorm;
+        this.options = {
+            tableName: options?.tableName ?? 'AuditLogs',
+            userIdGetter: options?.userIdGetter ?? (() => undefined),
+            ipAddressGetter: options?.ipAddressGetter ?? (() => undefined),
+            modelName: options?.modelName ?? 'AuditLog',
+        };
+    }
+    /**
+     * Get the audit model
+     */
+    getModel() {
+        return this.auditModel;
+    }
+    /**
+     * Get the current user ID
+     */
+    getUserId() {
+        return this.options.userIdGetter();
+    }
+    /**
+     * Get the current IP address
+     */
+    getIpAddress() {
+        return this.options.ipAddressGetter();
+    }
+    /**
+     * Define and create the audit log model
+     */
+    async ensureAuditModel() {
+        if (this.auditModel) {
+            return this.auditModel;
+        }
+        const { tableName, modelName } = this.options;
+        // Check if model already exists using prorm.model()
+        const existingModel = this.prorm.model(modelName);
+        if (existingModel) {
+            this.auditModel = existingModel;
+            return existingModel;
+        }
+        // Define the audit log model
+        const AuditLogModel = this.prorm.define(modelName, {
+            id: {
+                type: data_types_1.DataTypes.INTEGER(),
+                primaryKey: true,
+                autoIncrement: true,
+            },
+            tableName: {
+                type: data_types_1.DataTypes.STRING(255),
+                allowNull: false,
+            },
+            action: {
+                type: data_types_1.DataTypes.ENUM('CREATE', 'UPDATE', 'DELETE'),
+                allowNull: false,
+            },
+            recordId: {
+                type: data_types_1.DataTypes.STRING(255),
+                allowNull: false,
+            },
+            oldValues: {
+                type: data_types_1.DataTypes.JSON(),
+                allowNull: true,
+            },
+            newValues: {
+                type: data_types_1.DataTypes.JSON(),
+                allowNull: true,
+            },
+            userId: {
+                type: data_types_1.DataTypes.STRING(255),
+                allowNull: true,
+            },
+            timestamp: {
+                type: data_types_1.DataTypes.DATE(),
+                allowNull: false,
+                defaultValue: data_types_1.DataTypes.NOW(),
+            },
+            ipAddress: {
+                type: data_types_1.DataTypes.STRING(45),
+                allowNull: true,
+            },
+        }, {
+            tableName,
+            timestamps: false,
+            underscored: true,
+        });
+        this.auditModel = AuditLogModel;
+        return AuditLogModel;
+    }
+    /**
+     * Log an audit action
+     *
+     * @param action - The type of action (CREATE, UPDATE, DELETE)
+     * @param tableName - The name of the table
+     * @param recordId - The primary key of the record
+     * @param oldValues - The previous values (for UPDATE/DELETE)
+     * @param newValues - The new values (for CREATE/UPDATE)
+     */
+    async logAction(action, tableName, recordId, oldValues, newValues) {
+        const auditModel = await this.ensureAuditModel();
+        await auditModel.create({
+            tableName,
+            action,
+            recordId: String(recordId),
+            oldValues: oldValues ?? null,
+            newValues: newValues ?? null,
+            userId: this.getUserId() ?? null,
+            timestamp: new Date(),
+            ipAddress: this.getIpAddress() ?? null,
+        });
+    }
+    /**
+     * Get audit history for a table and optional record
+     *
+     * @param tableName - The name of the table
+     * @param recordId - Optional record ID to filter by
+     * @param options - Query options
+     */
+    async getHistory(tableName, recordId, options) {
+        const auditModel = await this.ensureAuditModel();
+        const where = {
+            tableName,
+        };
+        if (recordId !== undefined) {
+            where.recordId = String(recordId);
+        }
+        if (options?.startDate || options?.endDate) {
+            where.timestamp = {};
+            if (options.startDate) {
+                where.timestamp[Symbol.for('gte')] = options.startDate;
+            }
+            if (options.endDate) {
+                where.timestamp[Symbol.for('lte')] = options.endDate;
+            }
+        }
+        const results = await auditModel.findAll({
+            where,
+            order: [['timestamp', 'DESC']],
+            limit: options?.limit ?? 100,
+            offset: options?.offset ?? 0,
+        });
+        return results.map((r) => ({
+            id: r.id,
+            tableName: r.tableName,
+            action: r.action,
+            recordId: r.recordId,
+            oldValues: r.oldValues,
+            newValues: r.newValues,
+            userId: r.userId,
+            timestamp: r.timestamp,
+            ipAddress: r.ipAddress,
+        }));
+    }
+    /**
+     * Setup hooks for all models to automatically log changes
+     *
+     * This method iterates through all registered models and adds
+     * beforeCreate, beforeUpdate, and beforeDestroy hooks
+     */
+    setupHooks() {
+        const models = this.prorm.getModels();
+        for (const [, model] of models) {
+            this.addHooksToModel(model);
+        }
+    }
+    /**
+     * Add audit hooks to a specific model
+     *
+     * @param model - The model to add hooks to
+     */
+    addHooksToModel(model) {
+        if (this.hookedModels.has(model)) {
+            return;
+        }
+        const tableName = model.tableName || model.name;
+        // beforeCreate hook
+        model.hook('beforeCreate', async (instance) => {
+            const newValues = instance.toJSON ? instance.toJSON() : { ...instance.dataValues };
+            await this.logAction('CREATE', tableName, instance.id, undefined, newValues);
+        });
+        // beforeUpdate hook
+        model.hook('beforeUpdate', async (instance) => {
+            const oldValues = instance._previousDataValues ? { ...instance._previousDataValues } : {};
+            const newValues = instance.toJSON ? instance.toJSON() : { ...instance.dataValues };
+            await this.logAction('UPDATE', tableName, instance.id, oldValues, newValues);
+        });
+        // beforeDestroy hook
+        model.hook('beforeDestroy', async (instance) => {
+            const oldValues = instance.toJSON ? instance.toJSON() : { ...instance.dataValues };
+            await this.logAction('DELETE', tableName, instance.id, oldValues, undefined);
+        });
+        this.hookedModels.add(model);
+    }
+    /**
+     * Check if a model has audit hooks
+     *
+     * @param model - The model to check
+     */
+    hasHooks(model) {
+        return this.hookedModels.has(model);
+    }
+}
+exports.AuditLogger = AuditLogger;
+// ==================== Default Export ====================
+exports.default = AuditLogger;

package/dist/cache/cache-manager.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * Cache Manager - Abstract CacheBackend interface
+ *
+ * Defines the contract for cache backends used in query result caching.
+ * Supports L1 (in-memory) and L2 (distributed) caching layers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbstractCacheManager = void 0;
+/**
+ * Abstract cache manager with L1/L2 support
+ */
+class AbstractCacheManager {
+    constructor(options = {}) {
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            l1Hits: 0,
+            l2Hits: 0,
+            keys: 0,
+            hitRate: 0,
+        };
+        this.options = this.normalizeOptions(options);
+    }
+    /**
+     * Normalize and set default options
+     */
+    normalizeOptions(options) {
+        return {
+            l1: {
+                enabled: options.l1?.enabled ?? true,
+                maxEntries: options.l1?.maxEntries ?? 1000,
+                ttl: options.l1?.ttl ?? 60,
+            },
+            l2: {
+                enabled: options.l2?.enabled ?? true,
+                defaultTtl: options.l2?.defaultTtl ?? 3600,
+            },
+            key: {
+                prefix: options.key?.prefix ?? 'orm:cache:',
+                separator: options.key?.separator ?? ':',
+            },
+            readFromReplicas: options.readFromReplicas ?? false,
+            clusterNodes: options.clusterNodes ?? [],
+            clusterOptions: options.clusterOptions ?? {},
+            maxConnections: options.maxConnections ?? 10,
+            connectTimeout: options.connectTimeout ?? 10000,
+            commandTimeout: options.commandTimeout ?? 5000,
+            retryStrategy: options.retryStrategy ?? null,
+            db: options.db ?? 0,
+            enableKeyspaceNotifications: options.enableKeyspaceNotifications ?? false,
+        };
+    }
+    /**
+     * Build a full cache key with prefix
+     */
+    buildKey(key) {
+        return `${this.options.key.prefix}${key}`;
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        const total = this.stats.hits + this.stats.misses;
+        return {
+            ...this.stats,
+            hitRate: total > 0 ? this.stats.hits / total : 0,
+        };
+    }
+    /**
+     * Reset cache statistics
+     */
+    resetStats() {
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            l1Hits: 0,
+            l2Hits: 0,
+            keys: 0,
+            hitRate: 0,
+        };
+    }
+}
+exports.AbstractCacheManager = AbstractCacheManager;

package/dist/cache/index.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * Cache Module
+ *
+ * Provides caching functionality for query results using Redis Cluster
+ * with L1 (in-memory) and L2 (distributed Redis) cache layers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRedisClusterCache = exports.RedisClusterCache = exports.AbstractCacheManager = void 0;
+// Re-export cache manager types
+var cache_manager_1 = require("./cache-manager");
+Object.defineProperty(exports, "AbstractCacheManager", { enumerable: true, get: function () { return cache_manager_1.AbstractCacheManager; } });
+// Re-export Redis cluster cache
+var redis_cluster_cache_1 = require("./redis-cluster-cache");
+Object.defineProperty(exports, "RedisClusterCache", { enumerable: true, get: function () { return redis_cluster_cache_1.RedisClusterCache; } });
+Object.defineProperty(exports, "createRedisClusterCache", { enumerable: true, get: function () { return redis_cluster_cache_1.createRedisClusterCache; } });