@sera4/essentia 3.0.11 → 3.0.13-rc.1

package/dist/paper-trail/index.js

@@ -0,0 +1,662 @@
+import * as jsdiff from 'diff';
+import _ from 'lodash';
+import helpers from './helpers.js';
+import paginator from "../paginator/sql-pagination.js";
+import { utils } from "../ts/utils/index.js";
+const censorText = "**********";
+let failHard = false;
+let Sequelize = null;
+const paperTrail = {};
+paperTrail.init = (sequelize, sequelizePackage, optionsArg) => {
+    Sequelize = sequelizePackage;
+    // In case that options is being parsed as a readonly attribute.
+    // Or it is not passed at all
+    const optsArg = _.cloneDeep(optionsArg || {});
+    const defaultOptions = {
+        debug: false,
+        log: null,
+        exclude: [
+            'id',
+            'createdAt',
+            'updatedAt',
+            'deletedAt',
+            'created_at',
+            'updated_at',
+            'deleted_at',
+            'audit_source',
+            'revision',
+        ],
+        // additional fields to exclude on a global basis
+        excludeExtras: [],
+        excludeVirtualAttributes: true, // by default do not record these
+        censor: ["password", "password_salt", "temp_secret", "mfa_totp_secret"],
+        revisionAttribute: 'revision',
+        revisionModel: 'Revision',
+        revisionChangeModel: 'RevisionChange',
+        enableRevisionChangeModel: false,
+        UUID: false,
+        // does this project use int's and UUIDs for some references (postgres)
+        mixedDocumentReference: false,
+        underscored: false,
+        underscoredAttributes: false,
+        // always store these keys in a reference value if seen
+        includeReferences: [],
+        defaultAttributes: {
+            documentId: 'documentId',
+            revisionId: 'revisionId',
+            autoGenerated: 'autoGenerated'
+        },
+        als: null,
+        userModel: false,
+        userModelAttribute: 'userId',
+        tenantModel: false,
+        tenantModelAttribute: 'tenantId',
+        enableCompression: false,
+        enableMigration: false,
+        enableStrictDiff: true,
+        continuationNamespace: null,
+        continuationKey: 'userId',
+        continuationTenantKey: 'tenantId',
+        metaDataFields: null,
+        metaDataContinuationKey: 'metaData',
+        mysql: false,
+    };
+    if (optsArg.mixedDocumentReference)
+        defaultOptions.defaultAttributes.documentUuid = "documentUuid";
+    if (optsArg.underscoredAttributes) {
+        helpers.toUnderscored(defaultOptions.defaultAttributes);
+    }
+    // deals with not wanting to overwrite the initial ones, just add some
+    if (optsArg.excludeExtras) {
+        if (optsArg.exclude) {
+            optsArg.exclude = [...optsArg.exclude, ...optsArg.excludeExtras];
+        }
+        else {
+            optsArg.exclude = [...defaultOptions.exclude, ...optsArg.excludeExtras];
+        }
+    }
+    const options = _.defaults(optsArg, defaultOptions);
+    const log = options.log || console.log;
+    function createBeforeHook(operation) {
+        const beforeHook = function beforeHook(instance, opt) {
+            if (options.debug) {
+                log('beforeHook called');
+                log('instance:', instance);
+                log('opt:', opt);
+            }
+            if (opt.noPaperTrail) {
+                if (options.debug) {
+                    log('noPaperTrail opt: is true, not logging');
+                }
+                return;
+            }
+            const destroyOperation = operation === 'destroy';
+            const restoreOperation = operation === 'restore';
+            let previousVersion = _.cloneDeep(instance._previousDataValues);
+            let currentVersion = _.cloneDeep(instance.dataValues);
+            if (!destroyOperation && options.enableCompression) {
+                _.forEach(opt.fields, a => {
+                    previousVersion[a] = instance._previousDataValues[a];
+                    currentVersion[a] = instance.dataValues[a];
+                });
+            }
+            else {
+                previousVersion = instance._previousDataValues;
+                currentVersion = instance.dataValues;
+            }
+            const excludes = options.exclude.concat([...this.extraRevisionAttributesExclude]);
+            // Supported nested models, allowing JSONB objects.
+            previousVersion = _.omitBy(previousVersion, i => i != null && typeof i === 'object' && !(i instanceof Date || _.isPlainObject(i)));
+            previousVersion = _.omit(previousVersion, excludes);
+            currentVersion = _.omitBy(currentVersion, i => i != null && typeof i === 'object' && !(i instanceof Date || _.isPlainObject(i)));
+            currentVersion = _.omit(currentVersion, excludes);
+            // Disallow change of revision
+            instance.set(options.revisionAttribute, instance._previousDataValues[options.revisionAttribute]);
+            // Get diffs
+            const delta = helpers.calcDelta(previousVersion, currentVersion, options.exclude, options.enableStrictDiff);
+            const currentRevisionId = instance.get(options.revisionAttribute);
+            if (failHard && !currentRevisionId && opt.type === 'UPDATE') {
+                throw new Error('Revision Id was undefined');
+            }
+            if (options.debug) {
+                log('delta:', delta);
+                log('revisionId', currentRevisionId);
+            }
+            // Check if all required fields have been provided to the opts / ALS
+            if (options.metaDataFields) {
+                // get all required field keys as an array
+                const requiredFields = _.keys(_.pickBy(options.metaDataFields, function isMetaDataFieldRequired(required) {
+                    return required;
+                }));
+                if (requiredFields && requiredFields.length) {
+                    const store = options.als && options.als.getStore();
+                    const metaData = (store && store.get(metaDataContinuationKey)) || opt.metaData;
+                    const requiredFieldsProvided = _.filter(requiredFields, function isMetaDataFieldNonUndefined(field) {
+                        return metaData[field] !== undefined;
+                    });
+                    if (requiredFieldsProvided.length !== requiredFields.length) {
+                        log('Required fields: ', options.metaDataFields, requiredFields);
+                        log('Required fields provided: ', metaData, requiredFieldsProvided);
+                        throw new Error('Not all required fields are provided to paper trail!');
+                    }
+                }
+            }
+            if (destroyOperation || restoreOperation || (delta && delta.length > 0)) {
+                const revisionId = (currentRevisionId || 0) + 1;
+                instance.set(options.revisionAttribute, revisionId);
+                if (!instance.context) {
+                    instance.context = {};
+                }
+                instance.context.delta = delta;
+            }
+            if (options.debug) {
+                log('end of beforeHook');
+            }
+        };
+        return beforeHook;
+    }
+    function createAfterHook(operation) {
+        const afterHook = function afterHook(instance, opt) {
+            const store = options.als && options.als.getStore();
+            if (options.debug) {
+                log('afterHook called');
+                log('instance:', instance);
+                log('opt:', opt);
+                if (store) {
+                    log(`ALS ${options.continuationKey}:`, store.get(options.continuationKey));
+                }
+            }
+            const destroyOperation = operation === 'destroy';
+            const createOperation = operation === 'create';
+            const restoreOperation = operation === 'restore';
+            if (instance.context &&
+                ((instance.context.delta &&
+                    instance.context.delta.length > 0) ||
+                    destroyOperation || restoreOperation)) {
+                const Revision = sequelize.model(options.revisionModel);
+                let RevisionChange;
+                if (options.enableRevisionChangeModel) {
+                    RevisionChange = sequelize.model(options.revisionChangeModel);
+                }
+                const { delta } = instance.context;
+                let previousVersion = {};
+                let currentVersion = {};
+                if (!destroyOperation && options.enableCompression) {
+                    opt.fields = opt.fields || instance._options.attributes;
+                    _.forEach(opt.fields, a => {
+                        previousVersion[a] = instance._previousDataValues[a];
+                        currentVersion[a] = instance.dataValues[a];
+                    });
+                }
+                else {
+                    previousVersion = instance._previousDataValues;
+                    currentVersion = instance.dataValues;
+                }
+                // we need to support nested Objects in a different way
+                // if the type of change is a nested object, we need to lookat the deltas and join the path with periods
+                // to get and show the differences.
+                // Supported nested models.
+                previousVersion = _.omitBy(previousVersion, value => {
+                    if (value == null)
+                        return false; // keep null/undefined
+                    if (value instanceof Date)
+                        return false; // keep Dates
+                    if (_.isPlainObject(value))
+                        return false; // keep plain objects (including nested objects)
+                    return typeof value === 'object'; // omit if it's an object that's not plain or a Date
+                });
+                previousVersion = _.omit(previousVersion, options.exclude);
+                currentVersion = _.omitBy(currentVersion, value => {
+                    if (value == null)
+                        return false;
+                    if (value instanceof Date)
+                        return false;
+                    if (_.isPlainObject(value))
+                        return false;
+                    return typeof value === 'object';
+                });
+                currentVersion = _.omit(currentVersion, options.exclude);
+                const store = options.als && options.als.getStore();
+                if (store && !store.has(options.continuationKey)) {
+                    if (failHard)
+                        throw new Error(`The ALS continuationKey ${options.continuationKey} was not defined.`);
+                }
+                let objectsChanged = new Set();
+                // if the previous version or new version contain objects; push them onto this list
+                _.forEach(previousVersion, (value, key) => {
+                    if (typeof (value) === 'object') {
+                        objectsChanged.add(key);
+                        // blank it so we can set it equal to ONLY the values changed in the next segment
+                        previousVersion[key] = {};
+                    }
+                });
+                _.forEach(currentVersion, (value, key) => {
+                    if (typeof (value) === 'object') {
+                        objectsChanged.add(key);
+                        currentVersion[key] = {};
+                    }
+                });
+                // we don't want to see a full object; we want to see only
+                // x.y.z -> value
+                if (delta && objectsChanged.size > 0) {
+                    // the format of these are A,E,D,N (added, edited, deleted, new) for the kind
+                    // the array is either the key or key + subkeys ['options','subkey','subkey2'] etc.
+                    // {kind: 'E', path: Array(2), lhs: false, rhs: true}
+                    for (const difference of delta) {
+                        // blank the currentVersion[difference.path[0]]
+                        // and previousVersion[difference.path[0]]
+                        _.set(currentVersion, difference.path, difference.rhs);
+                        _.set(previousVersion, difference.path, difference.lhs);
+                    }
+                    ;
+                }
+                let document;
+                if (destroyOperation) {
+                    document = { oldValues: currentVersion };
+                }
+                else if (createOperation || restoreOperation) {
+                    // we want to print out the entire object as values MAY have changed when restoring
+                    //  and for NEW objects, we want the initial state
+                    document = { newValues: currentVersion };
+                }
+                else {
+                    document = { oldValues: previousVersion, newValues: currentVersion };
+                }
+                const references = _.pick(instance.dataValues, options.includeReferences);
+                if (Object.keys(references).length) {
+                    document['references'] = references;
+                }
+                if (options.mysql) {
+                    document = JSON.stringify(document);
+                }
+                // Build revision
+                const query = {
+                    model: this.name,
+                    document,
+                    operation,
+                };
+                // Add all extra data fields to the query object
+                if (options.metaDataFields) {
+                    const metaData = (store && store.get(options.metaDataContinuationKey)) ||
+                        opt.metaData;
+                    if (metaData) {
+                        _.forEach(options.metaDataFields, function getMetaDataValues(required, field) {
+                            const value = metaData[field];
+                            if (options.debug) {
+                                log(`Adding metaData field to Revision - ${field} => ${value}`);
+                            }
+                            if (!(field in query)) {
+                                query[field] = value;
+                            }
+                            else if (options.debug) {
+                                log(`Revision object already has a value at ${field} => ${query[field]}`);
+                                log('Not overwriting the original value');
+                            }
+                        });
+                    }
+                }
+                query[options.defaultAttributes.autoGenerated] = opt.autoGenerated;
+                // in case of custom user models that are not 'userId'
+                query[options.userModelAttribute] =
+                    (store && store.get(options.continuationKey)) || opt.userId;
+                query[options.tenantModelAttribute] =
+                    (store && store.get(options.continuationTenantKey)) || opt.tenantId;
+                if (options.mixedDocumentReference && utils.isValidUuidV4(instance.id)) {
+                    query[options.defaultAttributes.documentUuid] = instance.id;
+                }
+                else {
+                    query[options.defaultAttributes.documentId] = instance.id;
+                }
+                const revision = Revision.build(query);
+                revision[options.revisionAttribute] = instance.get(options.revisionAttribute);
+                return revision
+                    .save({ transaction: opt.transaction })
+                    .then(objectRevision => {
+                    // Loop diffs and create a revision-diff for each
+                    if (options.enableRevisionChangeModel) {
+                        _.forEach(delta, difference => {
+                            const o = helpers.diffToString(difference.item
+                                ? difference.item.lhs
+                                : difference.lhs);
+                            const n = helpers.diffToString(difference.item
+                                ? difference.item.rhs
+                                : difference.rhs);
+                            // let document = difference;
+                            document = difference;
+                            let diff = o || n ? jsdiff.diffChars(o, n) : [];
+                            if (options.mysql) {
+                                document = JSON.stringify(document);
+                                diff = JSON.stringify(diff);
+                            }
+                            const d = RevisionChange.build({
+                                path: difference.path[0],
+                                document,
+                                diff,
+                                revisionId: objectRevision.id,
+                            });
+                            d.save({ transaction: opt.transaction })
+                                .then(savedD => {
+                                // Add diff to revision
+                                objectRevision[`add${helpers.capitalizeFirstLetter(options.revisionChangeModel)}`](savedD);
+                                return null;
+                            })
+                                .catch(err => {
+                                log('RevisionChange save error', err);
+                                throw err;
+                            });
+                        });
+                    }
+                    return null;
+                })
+                    .catch(err => {
+                    log('Revision save error', err);
+                    throw err;
+                });
+            }
+            if (options.debug) {
+                log('end of afterHook');
+            }
+            return null;
+        };
+        return afterHook;
+    }
+    // order in which sequelize processes the hooks
+    // (1)
+    // beforeBulkCreate(instances, options, fn)
+    // beforeBulkDestroy(instances, options, fn)
+    // beforeBulkUpdate(instances, options, fn)
+    // (2)
+    // beforeValidate(instance, options, fn)
+    // (-)
+    // validate
+    // (3)
+    // afterValidate(instance, options, fn)
+    // - or -
+    // validationFailed(instance, options, error, fn)
+    // (4)
+    // beforeCreate(instance, options, fn)
+    // beforeDestroy(instance, options, fn)
+    // beforeUpdate(instance, options, fn)
+    // beforeRestore(instance, options, fn)
+    // (-)
+    // create
+    // destroy
+    // update
+    // (5)
+    // afterCreate(instance, options, fn)
+    // afterDestroy(instance, options, fn)
+    // afterUpdate(instance, options, fn)
+    // afterRestore(instance, options, fn)
+    // (6)
+    // afterBulkCreate(instances, options, fn)
+    // afterBulkDestroy(instances, options, fn)
+    // afterBulkUpdate(instances, options, fn)
+    // Extend model prototype with "hasPaperTrail" function
+    // Call model.hasPaperTrail() to enable revisions for model
+    _.assignIn(Sequelize.Model, {
+        hasPaperTrail: function hasPaperTrail() {
+            if (options.debug) {
+                log('Enabling paper trail on', this.name);
+            }
+            this.rawAttributes[options.revisionAttribute] = {
+                type: Sequelize.INTEGER,
+                defaultValue: 0,
+            };
+            this.revisionable = true;
+            // not sure if we need this
+            this.refreshAttributes();
+            this.extraRevisionAttributesExclude = new Set();
+            if (options.excludeVirtualAttributes) {
+                for (const attribute in this.rawAttributes) {
+                    if (this.rawAttributes[attribute].type == "VIRTUAL") {
+                        this.extraRevisionAttributesExclude.add(attribute);
+                    }
+                }
+            }
+            if (options.enableMigration) {
+                const tableName = this.getTableName();
+                const queryInterface = sequelize.getQueryInterface();
+                queryInterface.describeTable(tableName).then(attributes => {
+                    if (!attributes[options.revisionAttribute]) {
+                        if (options.debug) {
+                            log('adding revision attribute to the database');
+                        }
+                        queryInterface
+                            .addColumn(tableName, options.revisionAttribute, {
+                            type: Sequelize.INTEGER,
+                            defaultValue: 0,
+                        })
+                            .then(() => null)
+                            .catch(err => {
+                            log('something went really wrong..', err);
+                            return null;
+                        });
+                    }
+                    return null;
+                });
+            }
+            this.addHook('beforeCreate', createBeforeHook('create'));
+            this.addHook('beforeDestroy', createBeforeHook('destroy'));
+            this.addHook('beforeUpdate', createBeforeHook('update'));
+            this.addHook('beforeRestore', createBeforeHook('restore'));
+            this.addHook('afterCreate', createAfterHook('create'));
+            this.addHook('afterDestroy', createAfterHook('destroy'));
+            this.addHook('afterUpdate', createAfterHook('update'));
+            this.addHook('afterRestore', createAfterHook('restore'));
+            // create association
+            if (options.mixedDocumentReference) {
+                this.hasMany(sequelize.models[options.revisionModel], {
+                    constraints: false,
+                    foreignKey: options.defaultAttributes.documentUuid,
+                });
+                this.hasMany(sequelize.models[options.revisionModel], {
+                    foreignKey: options.defaultAttributes.documentId,
+                    constraints: false,
+                    scope: {
+                        model: this.name,
+                    },
+                });
+            }
+            else {
+                return this.hasMany(sequelize.models[options.revisionModel], {
+                    foreignKey: options.defaultAttributes.documentId,
+                    constraints: false,
+                    scope: {
+                        model: this.name,
+                    },
+                });
+            }
+        },
+    });
+    return {
+        // TWS-1032 since ALS must be set after a .run()
+        //   invocation this CANNOT be set on init().  If you would
+        //   like to use ALS, set it after the first invocation of run()
+        setupALS: function (asyncLocalStorage) {
+            options.als = asyncLocalStorage;
+        },
+        alsEnabled: function () {
+            return (options.als === true);
+        },
+        defineModels: function defineModels(db) {
+            // Attributes for RevisionModel
+            let attributes = {
+                model: {
+                    type: Sequelize.TEXT,
+                    allowNull: false,
+                },
+                document: {
+                    type: Sequelize.JSONB,
+                    allowNull: false,
+                },
+                operation: Sequelize.STRING(7),
+            };
+            if (options.mysql) {
+                attributes.document.type = Sequelize.TEXT('MEDIUMTEXT');
+            }
+            attributes[options.defaultAttributes.documentId] = {
+                type: Sequelize.INTEGER,
+                allowNull: false,
+            };
+            attributes[options.defaultAttributes.autoGenerated] = {
+                type: Sequelize.BOOLEAN,
+                defaultValue: false,
+                allowNull: false,
+            };
+            attributes[options.revisionAttribute] = {
+                type: Sequelize.INTEGER,
+                allowNull: false,
+            };
+            attributes[options.userModelAttribute] = {
+                type: options.UUID ? Sequelize.UUID : Sequelize.INTEGER,
+                allowNull: true
+            };
+            attributes[options.tenantModelAttribute] = {
+                type: options.UUID ? Sequelize.UUID : Sequelize.INTEGER,
+                allowNull: true
+            };
+            if (options.UUID) {
+                attributes.id = {
+                    primaryKey: true,
+                    type: Sequelize.UUID,
+                    defaultValue: Sequelize.UUIDV4,
+                };
+                if (!options.mixedDocumentReference)
+                    attributes[options.defaultAttributes.documentId].type = Sequelize.UUID;
+                attributes[options.userModelAttribute].type = Sequelize.UUID;
+            }
+            if (options.mixedDocumentReference) {
+                attributes[options.defaultAttributes.documentId].allowNull = true;
+                attributes[options.defaultAttributes.documentUuid] = {
+                    type: Sequelize.UUID,
+                    allowNull: true
+                };
+            }
+            if (options.debug) {
+                log('attributes', attributes);
+            }
+            let indexes = [{
+                    name: "document_reference_id",
+                    fields: [options.defaultAttributes.documentId]
+                }];
+            if (options.userModel)
+                indexes.push({ fields: [options.userModelAttribute] });
+            if (options.tenantModel)
+                indexes.push({ fields: [options.tenantModelAttribute] });
+            if (options.mixedDocumentReference) {
+                indexes.push({
+                    name: "document_reference_uuid",
+                    fields: [options.defaultAttributes.documentUuid]
+                });
+            }
+            // Revision model
+            const Revision = sequelize.define(options.revisionModel, attributes, {
+                underscored: options.underscored,
+                tableName: options.tableName,
+                timestamps: true,
+                createdAt: options.underscored ? "created_at" : "createdAt",
+                updatedAt: options.underscored ? "updated_at" : "updatedAt",
+                indexes
+            });
+            // safely prune down values
+            Revision.prototype.toJSON = function () {
+                let values = this.get();
+                const excludedFields = ["updated_at"];
+                // ensure that we always reference the id as document_id
+                values.document_id = values.document_id || values.document_uuid;
+                delete values.document_uuid;
+                _.forEach(defaultOptions.censor, a => {
+                    if (!utils.isBlank(values.document.newValues) && !utils.isBlank(values.document.newValues[a])) {
+                        values.document.newValues[a] = censorText;
+                    }
+                    if (!utils.isBlank(values.document.oldValues) && !utils.isBlank(values.document.oldValues[a])) {
+                        values.document.oldValues[a] = censorText;
+                    }
+                });
+                return _.omitBy(values, function (value, key) {
+                    return (excludedFields.includes(key) || (value === null));
+                });
+            };
+            Revision.associate = function associate(models) {
+                if (options.debug) {
+                    log('models', models);
+                }
+                if (options.userModel) {
+                    Revision.belongsTo(sequelize.model(options.userModel), options.belongsToUserOptions);
+                }
+                if (options.tenantModel) {
+                    Revision.belongsTo(sequelize.model(options.tenantModel), options.belongsToTenantOptions);
+                }
+            };
+            if (options.enableRevisionChangeModel) {
+                // Attributes for RevisionChangeModel
+                attributes = {
+                    path: {
+                        type: Sequelize.TEXT,
+                        allowNull: false,
+                    },
+                    document: {
+                        type: Sequelize.JSONB,
+                        allowNull: false,
+                    },
+                    diff: {
+                        type: Sequelize.JSONB,
+                        allowNull: false,
+                    },
+                };
+                if (options.mysql) {
+                    attributes.document.type = Sequelize.TEXT('MEDIUMTEXT');
+                    attributes.diff.type = Sequelize.TEXT('MEDIUMTEXT');
+                }
+                if (options.UUID) {
+                    attributes.id = {
+                        primaryKey: true,
+                        type: Sequelize.UUID,
+                        defaultValue: Sequelize.UUIDV4,
+                    };
+                }
+                // RevisionChange model
+                const RevisionChange = sequelize.define(options.revisionChangeModel, attributes, {
+                    underscored: options.underscored,
+                });
+                // Set associations
+                Revision.hasMany(RevisionChange, {
+                    foreignKey: options.defaultAttributes.revisionId,
+                    constraints: false,
+                });
+                RevisionChange.belongsTo(Revision);
+                if (db)
+                    db[RevisionChange.name] = RevisionChange;
+            }
+            paginator.paginate(Revision);
+            if (db)
+                db[Revision.name] = Revision;
+            /*
+             * We could extract this to a separate function so that having a
+             * user model doesn't require different loading
+             *
+             * or perhaps we could omit this because we are creating the
+             * association through the associate call above.
+             */
+            if (options.userModel) {
+                Revision.belongsTo(sequelize.model(options.userModel), {
+                    as: "account",
+                    foreignKey: {
+                        fieldName: options.userModelAttribute
+                    },
+                    onDelete: "CASCADE"
+                });
+            }
+            return Revision;
+        },
+    };
+};
+/**
+ * Throw exceptions when the user identifier from ALS is not set or if the
+ * revisionAttribute was not loaded on the model.
+ */
+paperTrail.enableFailHard = () => {
+    failHard = true;
+};
+export default paperTrail;
+//# sourceMappingURL=index.js.map