@lucaapp/service-utils 5.3.0 → 5.4.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './lib/api';
+export * from './lib/atomicAuditLog';
 export * from './lib/kafka';
 export * from './lib/serviceIdentity';
 export * from './lib/urlEncoded';

package/dist/index.js

@@ -15,6 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./lib/api"), exports);
+__exportStar(require("./lib/atomicAuditLog"), exports);
 __exportStar(require("./lib/kafka"), exports);
 __exportStar(require("./lib/serviceIdentity"), exports);
 __exportStar(require("./lib/urlEncoded"), exports);

package/dist/lib/atomicAuditLog/index.d.ts

@@ -0,0 +1,148 @@
+import type { Model, ModelStatic, Sequelize } from 'sequelize';
+import { DataTypes } from 'sequelize';
+/**
+ * Represents a partition table with its timestamp.
+ */
+export interface PartitionTable {
+    tableName: string;
+    timestamp: Date;
+}
+interface AddHistoryOptions {
+    exclude?: string[];
+}
+interface AtomicAuditLogOptions {
+    /**
+     * Name of the audit log table.
+     * Default: 'AuditLogs'
+     */
+    attributeRevisionModelTableName?: string;
+    /**
+     * Type of the primary key for the tracked models.
+     * Default: DataTypes.INTEGER
+     */
+    primaryKeyType?: typeof DataTypes.UUID | typeof DataTypes.INTEGER;
+    /**
+     * Number of partitions to include in the UNION ALL view.
+     * Default: 6 (current table + 5 archives = ~6 weeks of data)
+     */
+    viewPartitionCount?: number;
+}
+/**
+ * Result of a partition operation.
+ */
+export interface PartitionResult {
+    archiveTableName: string;
+    timestamp: Date;
+}
+/**
+ * AtomicAuditLog provides audit logging with atomic revision assignment.
+ *
+ * This is a drop-in replacement for sequelize-central-log that solves the
+ * race condition issue where concurrent updates could result in duplicate
+ * revision numbers.
+ *
+ * Key differences from sequelize-central-log:
+ * - Uses PostgreSQL advisory locks to serialize inserts per entity
+ * - Calculates revision using MAX(revision)+1 subquery for atomicity
+ * - Runs within the same transaction as entity updates (when transaction provided)
+ *
+ * @example
+ * ```typescript
+ * const auditLog = new AtomicAuditLog(sequelize, {
+ *   attributeRevisionModelTableName: 'StayReservationAuditLogs',
+ *   primaryKeyType: DataTypes.UUID,
+ * });
+ *
+ * await auditLog.addHistory(StayReservation, {
+ *   exclude: ['primaryGuest'],
+ * });
+ * ```
+ */
+export declare class AtomicAuditLog {
+    private sequelize;
+    private tableName;
+    private primaryKeyType;
+    private viewPartitionCount;
+    constructor(sequelize: Sequelize, options?: AtomicAuditLogOptions);
+    /**
+     * Gets the table name for this audit log.
+     */
+    getTableName(): string;
+    /**
+     * Gets the view name that combines all partitions.
+     */
+    getViewName(): string;
+    /**
+     * Adds audit logging hooks to a Sequelize model.
+     *
+     * @param model - The Sequelize model to track
+     * @param options - Configuration options
+     * @returns Promise that resolves when hooks are added
+     */
+    addHistory<T extends Model>(model: ModelStatic<T>, options?: AddHistoryOptions): Promise<void>;
+    /**
+     * Creates an audit log entry with atomically assigned revision number.
+     */
+    private createAuditLogEntry;
+    /**
+     * Creates an audit hook handler for a specific operation.
+     */
+    private createAuditHook;
+    /**
+     * Gets the last N partition tables for this audit log.
+     *
+     * Partition tables follow the naming pattern: `{tableName}_{YYYY_MM_DD}T{HH_MM_SS}`
+     *
+     * @param count - Number of partitions to retrieve (default: viewPartitionCount - 1)
+     * @returns Array of partition tables sorted by timestamp descending
+     */
+    getLastNPartitionTables(count?: number): Promise<PartitionTable[]>;
+    /**
+     * Partitions the audit log table by creating a new empty table and
+     * archiving the current data.
+     *
+     * This operation:
+     * 1. Creates a new table with the same schema (including indexes/constraints)
+     * 2. Renames the current table to an archive table with timestamp suffix
+     * 3. Renames the new table to the original table name
+     * 4. Recreates the UNION ALL view
+     *
+     * The entire operation runs in a transaction for atomicity.
+     *
+     * @returns The name of the archive table and timestamp
+     * @example
+     * ```typescript
+     * const result = await auditLog.partitionTable();
+     * console.log(`Archived to: ${result.archiveTableName}`);
+     * ```
+     */
+    partitionTable(): Promise<PartitionResult>;
+    /**
+     * Recreates the UNION ALL view that combines the current table with archive partitions.
+     *
+     * The view includes:
+     * - The current (active) table
+     * - The last N-1 archive tables (where N = viewPartitionCount)
+     *
+     * Each row includes a `partition_table` column indicating its source.
+     *
+     * @example
+     * ```typescript
+     * await auditLog.recreateView();
+     * // Creates view: StayReservationAuditLogs_View
+     * // Combining: StayReservationAuditLogs + last 5 archives
+     * ```
+     */
+    recreateView(): Promise<void>;
+    /**
+     * Drops old partition tables beyond the retention count.
+     *
+     * This is useful for cleaning up old audit data while maintaining
+     * the view with recent partitions.
+     *
+     * @param retentionCount - Number of archive partitions to keep (default: viewPartitionCount * 2)
+     * @returns Array of dropped table names
+     */
+    dropOldPartitions(retentionCount?: number): Promise<string[]>;
+}
+export {};

package/dist/lib/atomicAuditLog/index.js

@@ -0,0 +1,313 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AtomicAuditLog = void 0;
+const sequelize_1 = require("sequelize");
+/**
+ * Default columns to exclude from audit logging.
+ */
+const DEFAULT_EXCLUDE = [
+    'id',
+    'uuid',
+    'createdAt',
+    'updatedAt',
+    'deletedAt',
+    'revision',
+];
+const isValidValue = (value) => value !== undefined && value !== null;
+const computeCreateDiff = (currentValues, excludeSet) => {
+    const diff = [];
+    for (const [key, value] of Object.entries(currentValues)) {
+        if (!excludeSet.has(key) && isValidValue(value)) {
+            diff.push({ key, values: { new: value } });
+        }
+    }
+    return diff;
+};
+const computeDestroyDiff = (previousValues, excludeSet) => {
+    const diff = [];
+    for (const [key, value] of Object.entries(previousValues)) {
+        if (!excludeSet.has(key) && isValidValue(value)) {
+            diff.push({ key, values: { old: value } });
+        }
+    }
+    return diff;
+};
+const computeUpdateDiff = (instance, previousValues, currentValues, excludeSet) => {
+    const diff = [];
+    const changedKeys = instance.changed();
+    if (!changedKeys || !Array.isArray(changedKeys)) {
+        return diff;
+    }
+    for (const key of changedKeys) {
+        if (!excludeSet.has(key)) {
+            diff.push({
+                key,
+                values: { old: previousValues[key], new: currentValues[key] },
+            });
+        }
+    }
+    return diff;
+};
+const computeDiff = (instance, operation, exclude) => {
+    const previousValues = instance.previous();
+    const currentValues = instance.dataValues;
+    const excludeSet = new Set([...DEFAULT_EXCLUDE, ...exclude]);
+    if (operation === 'create') {
+        return computeCreateDiff(currentValues, excludeSet);
+    }
+    if (operation === 'destroy') {
+        return computeDestroyDiff(previousValues, excludeSet);
+    }
+    return computeUpdateDiff(instance, previousValues, currentValues, excludeSet);
+};
+/**
+ * AtomicAuditLog provides audit logging with atomic revision assignment.
+ *
+ * This is a drop-in replacement for sequelize-central-log that solves the
+ * race condition issue where concurrent updates could result in duplicate
+ * revision numbers.
+ *
+ * Key differences from sequelize-central-log:
+ * - Uses PostgreSQL advisory locks to serialize inserts per entity
+ * - Calculates revision using MAX(revision)+1 subquery for atomicity
+ * - Runs within the same transaction as entity updates (when transaction provided)
+ *
+ * @example
+ * ```typescript
+ * const auditLog = new AtomicAuditLog(sequelize, {
+ *   attributeRevisionModelTableName: 'StayReservationAuditLogs',
+ *   primaryKeyType: DataTypes.UUID,
+ * });
+ *
+ * await auditLog.addHistory(StayReservation, {
+ *   exclude: ['primaryGuest'],
+ * });
+ * ```
+ */
+class AtomicAuditLog {
+    constructor(sequelize, options = {}) {
+        this.sequelize = sequelize;
+        this.tableName = options.attributeRevisionModelTableName ?? 'AuditLogs';
+        this.primaryKeyType = options.primaryKeyType ?? sequelize_1.DataTypes.INTEGER;
+        this.viewPartitionCount = options.viewPartitionCount ?? 6;
+    }
+    /**
+     * Gets the table name for this audit log.
+     */
+    getTableName() {
+        return this.tableName;
+    }
+    /**
+     * Gets the view name that combines all partitions.
+     */
+    getViewName() {
+        return `${this.tableName}_View`;
+    }
+    /**
+     * Adds audit logging hooks to a Sequelize model.
+     *
+     * @param model - The Sequelize model to track
+     * @param options - Configuration options
+     * @returns Promise that resolves when hooks are added
+     */
+    async addHistory(model, options = {}) {
+        const { exclude = [] } = options;
+        const modelName = model.name;
+        const primaryKeyAttribute = model.primaryKeyAttribute || 'uuid';
+        const createHook = this.createAuditHook(modelName, primaryKeyAttribute, exclude, 'create');
+        const updateHook = this.createAuditHook(modelName, primaryKeyAttribute, exclude, 'update');
+        const destroyHook = this.createAuditHook(modelName, primaryKeyAttribute, exclude, 'destroy');
+        model.addHook('afterCreate', createHook);
+        model.addHook('afterUpdate', updateHook);
+        model.addHook('afterDestroy', destroyHook);
+    }
+    /**
+     * Creates an audit log entry with atomically assigned revision number.
+     */
+    async createAuditLogEntry(modelId, modelName, operation, diff, transaction) {
+        // Use advisory lock to serialize inserts for the same entity
+        // pg_advisory_xact_lock automatically releases at transaction end
+        const lockKey = `hashtext('${this.tableName}:${modelId}')`;
+        await this.sequelize.query(`SELECT pg_advisory_xact_lock(${lockKey})`, {
+            transaction,
+            type: sequelize_1.QueryTypes.SELECT,
+        });
+        // Insert with subquery for atomic revision assignment
+        const query = `
+      INSERT INTO "${this.tableName}" ("modelId", "model", "operation", "diff", "revision", "createdAt")
+      SELECT
+        :modelId,
+        :modelName,
+        :operation,
+        :diff::jsonb,
+        COALESCE(
+          (SELECT MAX("revision") + 1 FROM "${this.tableName}" WHERE "modelId" = :modelId),
+          0
+        ),
+        NOW()
+    `;
+        await this.sequelize.query(query, {
+            replacements: {
+                modelId,
+                modelName,
+                operation,
+                diff: JSON.stringify(diff),
+            },
+            type: sequelize_1.QueryTypes.INSERT,
+            transaction,
+        });
+    }
+    /**
+     * Creates an audit hook handler for a specific operation.
+     */
+    createAuditHook(modelName, primaryKeyAttribute, exclude, operation) {
+        return async (instance, options) => {
+            try {
+                const diff = computeDiff(instance, operation, exclude);
+                if (diff.length === 0) {
+                    return;
+                }
+                const modelId = instance.getDataValue(primaryKeyAttribute);
+                await this.createAuditLogEntry(modelId, modelName, operation, diff, options.transaction);
+            }
+            catch (error) {
+                // Log error but don't fail the main operation
+                // eslint-disable-next-line no-console
+                console.warn(`Error creating audit log entry for ${modelName}:`, error);
+            }
+        };
+    }
+    /**
+     * Gets the last N partition tables for this audit log.
+     *
+     * Partition tables follow the naming pattern: `{tableName}_{YYYY_MM_DD}T{HH_MM_SS}`
+     *
+     * @param count - Number of partitions to retrieve (default: viewPartitionCount - 1)
+     * @returns Array of partition tables sorted by timestamp descending
+     */
+    async getLastNPartitionTables(count) {
+        const partitionCount = count ?? this.viewPartitionCount - 1;
+        const archiveTables = await this.sequelize.query(`SELECT tablename FROM pg_tables
+       WHERE schemaname = 'public'
+       AND tablename LIKE $1
+       AND tablename != $2
+       ORDER BY tablename DESC`, {
+            type: sequelize_1.QueryTypes.SELECT,
+            bind: [`${this.tableName}_%`, this.tableName],
+        });
+        const partitionTables = [];
+        const timestampRegex = new RegExp(`${this.tableName}_(\\d{4}(?:_\\d{2}){5})`);
+        for (const table of archiveTables) {
+            const timestampMatch = table.tablename.match(timestampRegex);
+            if (timestampMatch) {
+                const timestampString = timestampMatch[1];
+                // Convert YYYY_MM_DD_HH_MM_SS to YYYY-MM-DD HH:MM:SS
+                const formattedTimestamp = timestampString
+                    .replaceAll('_', '-')
+                    .replace(/^(\d{4}-\d{2}-\d{2})-(\d{2})-(\d{2})-(\d{2})$/, '$1 $2:$3:$4');
+                const timestamp = new Date(formattedTimestamp);
+                if (!Number.isNaN(timestamp.getTime())) {
+                    partitionTables.push({
+                        tableName: table.tablename,
+                        timestamp,
+                    });
+                }
+            }
+        }
+        return partitionTables
+            .sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime())
+            .slice(0, partitionCount);
+    }
+    /**
+     * Partitions the audit log table by creating a new empty table and
+     * archiving the current data.
+     *
+     * This operation:
+     * 1. Creates a new table with the same schema (including indexes/constraints)
+     * 2. Renames the current table to an archive table with timestamp suffix
+     * 3. Renames the new table to the original table name
+     * 4. Recreates the UNION ALL view
+     *
+     * The entire operation runs in a transaction for atomicity.
+     *
+     * @returns The name of the archive table and timestamp
+     * @example
+     * ```typescript
+     * const result = await auditLog.partitionTable();
+     * console.log(`Archived to: ${result.archiveTableName}`);
+     * ```
+     */
+    async partitionTable() {
+        const now = new Date();
+        const timestamp = now.toISOString().replaceAll(/[.:-]/g, '_').slice(0, 19);
+        const archiveTableName = `${this.tableName}_${timestamp}`;
+        const newTableName = `${this.tableName}_New`;
+        await this.sequelize.transaction(async (transaction) => {
+            // Create a new empty table by copying the schema from the existing table
+            await this.sequelize.query(`CREATE TABLE "${newTableName}" (LIKE "${this.tableName}" INCLUDING ALL)`, { transaction });
+            // Rename current table to archive
+            await this.sequelize.query(`ALTER TABLE "${this.tableName}" RENAME TO "${archiveTableName}"`, { transaction });
+            // Rename new table to original name
+            await this.sequelize.query(`ALTER TABLE "${newTableName}" RENAME TO "${this.tableName}"`, { transaction });
+        });
+        // Recreate the view to include the new archive
+        await this.recreateView();
+        return { archiveTableName, timestamp: now };
+    }
+    /**
+     * Recreates the UNION ALL view that combines the current table with archive partitions.
+     *
+     * The view includes:
+     * - The current (active) table
+     * - The last N-1 archive tables (where N = viewPartitionCount)
+     *
+     * Each row includes a `partition_table` column indicating its source.
+     *
+     * @example
+     * ```typescript
+     * await auditLog.recreateView();
+     * // Creates view: StayReservationAuditLogs_View
+     * // Combining: StayReservationAuditLogs + last 5 archives
+     * ```
+     */
+    async recreateView() {
+        const viewName = this.getViewName();
+        const archiveTables = await this.getLastNPartitionTables();
+        const unionQueries = [
+            `SELECT *, '${this.tableName}' as partition_table FROM "${this.tableName}"`,
+        ];
+        for (const table of archiveTables) {
+            unionQueries.push(`SELECT *, '${table.tableName}' as partition_table FROM "${table.tableName}"`);
+        }
+        const viewQuery = `
+      CREATE OR REPLACE VIEW "${viewName}" AS
+      ${unionQueries.join('\nUNION ALL\n')}
+    `;
+        await this.sequelize.query(viewQuery, { type: sequelize_1.QueryTypes.RAW });
+    }
+    /**
+     * Drops old partition tables beyond the retention count.
+     *
+     * This is useful for cleaning up old audit data while maintaining
+     * the view with recent partitions.
+     *
+     * @param retentionCount - Number of archive partitions to keep (default: viewPartitionCount * 2)
+     * @returns Array of dropped table names
+     */
+    async dropOldPartitions(retentionCount) {
+        const keepCount = retentionCount ?? this.viewPartitionCount * 2;
+        // Get all partitions (more than we want to keep)
+        const allPartitions = await this.getLastNPartitionTables(keepCount + 100);
+        // Tables to drop are those beyond the retention count
+        const tablesToDrop = allPartitions.slice(keepCount);
+        const droppedTables = [];
+        for (const table of tablesToDrop) {
+            await this.sequelize.query(`DROP TABLE IF EXISTS "${table.tableName}"`, {
+                type: sequelize_1.QueryTypes.RAW,
+            });
+            droppedTables.push(table.tableName);
+        }
+        return droppedTables;
+    }
+}
+exports.AtomicAuditLog = AtomicAuditLog;

package/dist/lib/validation.d.ts

@@ -86,16 +86,16 @@ declare const z: {
             thumbprint: zod.ZodString;
             timestamp: zod.ZodString;
         }, "strip", zod.ZodTypeAny, {
-            kid: string;
             timestamp: string;
+            kid: string;
             signature: string;
             certificateType: string;
             country: string;
             rawData: string;
             thumbprint: string;
         }, {
-            kid: string;
             timestamp: string;
+            kid: string;
             signature: string;
             certificateType: string;
             country: string;
@@ -104,8 +104,8 @@ declare const z: {
         }>, "many">;
     }, "strip", zod.ZodTypeAny, {
         certificates: {
-            kid: string;
             timestamp: string;
+            kid: string;
             signature: string;
             certificateType: string;
             country: string;
@@ -114,8 +114,8 @@ declare const z: {
         }[];
     }, {
         certificates: {
-            kid: string;
             timestamp: string;
+            kid: string;
             signature: string;
             certificateType: string;
             country: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucaapp/service-utils",
-  "version": "5.3.0",
+  "version": "5.4.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [