@flusys/nestjs-shared 6.4.1 → 7.0.0

package/cjs/classes/api-service.class.spec.js

@@ -6,6 +6,8 @@ const _common = require("@nestjs/common");
 const _repositorymock = require("@test-utils/mocks/repository.mock");
 const _loggedusermock = require("@test-utils/mocks/logged-user.mock");
 const _apiserviceclass = require("./api-service.class");
+const _eventbusregistry = require("./event-bus.registry");
+const _eventactionenum = require("../enums/event-action.enum");
 const _utilsservice = require("../modules/utils/utils.service");
 const _entities = require("../entities");
 function _define_property(obj, key, value) {
@@ -806,4 +808,222 @@ describe('ApiService', ()=>{
             expect(clearSpy).toHaveBeenCalledWith('test-entity', mockCache, 'b');
         });
     });
+    describe('domain events', ()=>{
+        let publish;
+        function makeEventService(moduleName = 'test-module') {
+            const dataSourceProvider = (0, _repositorymock.createMockDataSourceProvider)(mockRepo);
+            return new TestApiService('test-entity', mockCache, utilsService, 'TestApiService', false, moduleName, TestEntity, dataSourceProvider);
+        }
+        beforeEach(()=>{
+            publish = jest.fn().mockResolvedValue(undefined);
+            _eventbusregistry.EventBusRegistry.reset();
+            _eventbusregistry.EventBusRegistry.setBus({
+                publish,
+                subscribe: jest.fn(),
+                close: jest.fn()
+            });
+            _eventbusregistry.EventBusRegistry.configureModule('test-module', {
+                enabled: true
+            });
+        });
+        afterEach(()=>{
+            _eventbusregistry.EventBusRegistry.reset();
+        });
+        it('should publish a created event after insert commits', async ()=>{
+            const service = makeEventService();
+            mockQueryRunner.manager.save.mockResolvedValue({
+                id: 'new-1',
+                name: 'Widget'
+            });
+            await service.insert({
+                name: 'Widget'
+            }, mockUser);
+            expect(publish).toHaveBeenCalledTimes(1);
+            expect(publish).toHaveBeenCalledWith(expect.objectContaining({
+                name: 'test-module.test-entity.created',
+                module: 'test-module',
+                entity: 'test-entity',
+                action: _eventactionenum.EventAction.CREATED,
+                payload: expect.objectContaining({
+                    ids: [
+                        'new-1'
+                    ]
+                })
+            }));
+        });
+        it('should carry the acting user on the envelope', async ()=>{
+            const service = makeEventService();
+            mockQueryRunner.manager.save.mockResolvedValue({
+                id: 'new-1',
+                name: 'Widget'
+            });
+            await service.insert({
+                name: 'Widget'
+            }, mockUser);
+            expect(publish.mock.calls[0][0].actor).toEqual(expect.objectContaining({
+                userId: mockUser.id
+            }));
+        });
+        it('should publish an updated event after update commits', async ()=>{
+            const service = makeEventService();
+            mockRepo.findOne.mockResolvedValue({
+                id: '1',
+                name: 'Old'
+            });
+            mockQueryRunner.manager.save.mockResolvedValue({
+                id: '1',
+                name: 'New'
+            });
+            await service.update({
+                id: '1',
+                name: 'New'
+            }, mockUser);
+            expect(publish.mock.calls[0][0]).toEqual(expect.objectContaining({
+                action: _eventactionenum.EventAction.UPDATED
+            }));
+        });
+        it('should publish created and updated separately for a bulk upsert', async ()=>{
+            const service = makeEventService();
+            mockRepo.findOne.mockResolvedValue({
+                id: '1',
+                name: 'Old'
+            });
+            mockQueryRunner.manager.save.mockResolvedValueOnce([
+                {
+                    id: 'new-1',
+                    name: 'A'
+                }
+            ]).mockResolvedValueOnce([
+                {
+                    id: '1',
+                    name: 'B'
+                }
+            ]);
+            await service.bulkUpsert([
+                {
+                    name: 'A'
+                }
+            ], [
+                {
+                    id: '1',
+                    name: 'B'
+                }
+            ], mockUser);
+            expect(publish.mock.calls.map(([event])=>event.action)).toEqual([
+                _eventactionenum.EventAction.CREATED,
+                _eventactionenum.EventAction.UPDATED
+            ]);
+        });
+        it.each([
+            [
+                'delete',
+                _eventactionenum.EventAction.DELETED
+            ],
+            [
+                'restore',
+                _eventactionenum.EventAction.RESTORED
+            ],
+            [
+                'permanent',
+                _eventactionenum.EventAction.PURGED
+            ]
+        ])('should publish %s as the %s action', async (type, action)=>{
+            const service = makeEventService();
+            await service.delete({
+                id: '1',
+                type
+            }, mockUser);
+            expect(publish.mock.calls[0][0]).toEqual(expect.objectContaining({
+                action
+            }));
+        });
+        it('should carry only the ids for a delete, with no row data to duplicate them', async ()=>{
+            const service = makeEventService();
+            await service.delete({
+                id: '1',
+                type: 'delete'
+            }, mockUser);
+            expect(publish.mock.calls[0][0].payload).toEqual({
+                ids: [
+                    '1'
+                ]
+            });
+        });
+        it('should not publish when the module has events disabled', async ()=>{
+            _eventbusregistry.EventBusRegistry.configureModule('test-module', {
+                enabled: false
+            });
+            const service = makeEventService();
+            mockQueryRunner.manager.save.mockResolvedValue({
+                id: 'new-1',
+                name: 'Widget'
+            });
+            await service.insert({
+                name: 'Widget'
+            }, mockUser);
+            expect(publish).not.toHaveBeenCalled();
+        });
+        it('should not publish for an action the module excluded', async ()=>{
+            _eventbusregistry.EventBusRegistry.configureModule('test-module', {
+                enabled: true,
+                actions: [
+                    _eventactionenum.EventAction.DELETED
+                ]
+            });
+            const service = makeEventService();
+            mockQueryRunner.manager.save.mockResolvedValue({
+                id: 'new-1',
+                name: 'Widget'
+            });
+            await service.insert({
+                name: 'Widget'
+            }, mockUser);
+            expect(publish).not.toHaveBeenCalled();
+        });
+        it('should omit the row data when the module opts out of payloads', async ()=>{
+            _eventbusregistry.EventBusRegistry.configureModule('test-module', {
+                enabled: true,
+                includePayload: false
+            });
+            const service = makeEventService();
+            mockQueryRunner.manager.save.mockResolvedValue({
+                id: 'new-1',
+                name: 'Widget'
+            });
+            await service.insert({
+                name: 'Widget'
+            }, mockUser);
+            expect(publish.mock.calls[0][0].payload).toEqual({
+                ids: [
+                    'new-1'
+                ]
+            });
+        });
+        it('should not fail the write when publishing throws', async ()=>{
+            publish.mockRejectedValue(new Error('broker down'));
+            const service = makeEventService();
+            mockQueryRunner.manager.save.mockResolvedValue({
+                id: 'new-1',
+                name: 'Widget'
+            });
+            await expect(service.insert({
+                name: 'Widget'
+            }, mockUser)).resolves.toEqual({
+                id: 'new-1',
+                name: 'Widget'
+            });
+        });
+        it('should do nothing when no bus is registered', async ()=>{
+            _eventbusregistry.EventBusRegistry.reset();
+            const service = makeEventService();
+            mockQueryRunner.manager.save.mockResolvedValue({
+                id: 'new-1',
+                name: 'Widget'
+            });
+            await expect(service.insert({
+                name: 'Widget'
+            }, mockUser)).resolves.toBeDefined();
+            expect(publish).not.toHaveBeenCalled();
+        });
+    });
 });

package/cjs/classes/disabled-event-bus.class.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "DisabledEventBus", {
+    enumerable: true,
+    get: function() {
+        return DisabledEventBus;
+    }
+});
+let DisabledEventBus = class DisabledEventBus {
+    async publish(_event) {}
+    async subscribe(_pattern, _handler) {}
+    async close() {}
+};

package/cjs/classes/disabled-event-bus.class.spec.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+const _disabledeventbusclass = require("./disabled-event-bus.class");
+describe('DisabledEventBus', ()=>{
+    const event = {
+        id: 'e1',
+        name: 'auth.session.logged-in',
+        module: 'auth',
+        entity: 'session',
+        action: 'logged-in',
+        payload: {
+            ids: [
+                'u1'
+            ]
+        },
+        actor: {
+            userId: 'u1',
+            companyId: null,
+            tenantId: null,
+            requestId: null
+        },
+        occurredAt: new Date().toISOString(),
+        version: 1
+    };
+    it('should never deliver an event to a subscriber', async ()=>{
+        const bus = new _disabledeventbusclass.DisabledEventBus();
+        const handler = jest.fn();
+        await bus.subscribe('**', handler);
+        await bus.publish(event);
+        expect(handler).not.toHaveBeenCalled();
+    });
+    it('should resolve without throwing so callers need no special case', async ()=>{
+        const bus = new _disabledeventbusclass.DisabledEventBus();
+        await expect(bus.publish(event)).resolves.toBeUndefined();
+        await expect(bus.subscribe('**', jest.fn())).resolves.toBeUndefined();
+        await expect(bus.close()).resolves.toBeUndefined();
+    });
+});

package/cjs/classes/domain-event.publisher.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get DOMAIN_EVENT_VERSION () {
+        return DOMAIN_EVENT_VERSION;
+    },
+    get buildDomainEvent () {
+        return buildDomainEvent;
+    },
+    get publishDomainEvent () {
+        return publishDomainEvent;
+    }
+});
+const _crypto = require("crypto");
+const _loggermiddleware = require("../middlewares/logger.middleware");
+const _eventpatternutil = require("../utils/event-pattern.util");
+const _eventbusregistry = require("./event-bus.registry");
+const DOMAIN_EVENT_VERSION = 1;
+function buildDomainEvent(input) {
+    const rows = input.data === undefined ? [] : toArray(input.data);
+    const ids = input.ids ?? collectIds(rows);
+    return {
+        id: (0, _crypto.randomUUID)(),
+        name: `${input.module}.${input.entity}.${input.action}`,
+        module: input.module,
+        entity: input.entity,
+        action: input.action,
+        payload: {
+            ids,
+            ...rows.length && _eventbusregistry.EventBusRegistry.shouldIncludePayload(input.module) ? {
+                data: (0, _eventpatternutil.sanitizeEventPayload)(rows)
+            } : {},
+            ...input.metadata ? {
+                metadata: (0, _eventpatternutil.sanitizeEventPayload)(input.metadata)
+            } : {}
+        },
+        actor: {
+            userId: input.user?.id ?? null,
+            companyId: input.user?.companyId ?? (0, _loggermiddleware.getCompanyId)() ?? null,
+            tenantId: (0, _loggermiddleware.getTenantId)() ?? null,
+            requestId: (0, _loggermiddleware.getRequestId)() ?? null
+        },
+        occurredAt: new Date().toISOString(),
+        version: DOMAIN_EVENT_VERSION
+    };
+}
+async function publishDomainEvent(input) {
+    const bus = input.eventBus ?? _eventbusregistry.EventBusRegistry.getBus();
+    if (!bus) return;
+    if (!_eventbusregistry.EventBusRegistry.isEnabled(input.module, input.entity, input.action)) return;
+    try {
+        await bus.publish(buildDomainEvent(input));
+    } catch  {
+    // Events must never break the operation that produced them
+    }
+}
+function toArray(value) {
+    return Array.isArray(value) ? value : [
+        value
+    ];
+}
+function collectIds(rows) {
+    return rows.reduce((ids, row)=>{
+        const id = row?.id;
+        if (id) ids.push(id);
+        return ids;
+    }, []);
+}

package/cjs/classes/domain-event.publisher.spec.js

@@ -0,0 +1,234 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+const _domaineventpublisher = require("./domain-event.publisher");
+const _eventbusregistry = require("./event-bus.registry");
+const user = {
+    id: 'user-1',
+    email: 'ada@example.com',
+    companyId: 'company-1'
+};
+describe('buildDomainEvent', ()=>{
+    beforeEach(()=>{
+        _eventbusregistry.EventBusRegistry.reset();
+        _eventbusregistry.EventBusRegistry.configureModule('form-builder', {
+            enabled: true
+        });
+    });
+    afterEach(()=>{
+        _eventbusregistry.EventBusRegistry.reset();
+    });
+    it('should name the event <module>.<entity>.<action>', ()=>{
+        const event = (0, _domaineventpublisher.buildDomainEvent)({
+            module: 'form-builder',
+            entity: 'form_result',
+            action: 'submitted'
+        });
+        expect(event.name).toBe('form-builder.form_result.submitted');
+        expect(event.version).toBe(1);
+        expect(event.id).toEqual(expect.any(String));
+    });
+    it('should derive ids from the supplied rows when none are given', ()=>{
+        const event = (0, _domaineventpublisher.buildDomainEvent)({
+            module: 'form-builder',
+            entity: 'form_result',
+            action: 'submitted',
+            data: [
+                {
+                    id: 'a'
+                },
+                {
+                    id: 'b'
+                }
+            ]
+        });
+        expect(event.payload.ids).toEqual([
+            'a',
+            'b'
+        ]);
+    });
+    it('should prefer explicitly supplied ids', ()=>{
+        const event = (0, _domaineventpublisher.buildDomainEvent)({
+            module: 'form-builder',
+            entity: 'form_result',
+            action: 'submitted',
+            ids: [
+                'explicit'
+            ],
+            data: {
+                id: 'ignored'
+            }
+        });
+        expect(event.payload.ids).toEqual([
+            'explicit'
+        ]);
+    });
+    it('should attach metadata regardless of the includePayload setting', ()=>{
+        _eventbusregistry.EventBusRegistry.configureModule('form-builder', {
+            enabled: true,
+            includePayload: false
+        });
+        const event = (0, _domaineventpublisher.buildDomainEvent)({
+            module: 'form-builder',
+            entity: 'form_result',
+            action: 'submitted',
+            data: {
+                id: 'a',
+                answer: 'secret-ish'
+            },
+            metadata: {
+                formId: 'form-1',
+                isDraft: false
+            }
+        });
+        expect(event.payload.data).toBeUndefined();
+        expect(event.payload.metadata).toEqual({
+            formId: 'form-1',
+            isDraft: false
+        });
+    });
+    it('should redact credential-like fields from data and metadata', ()=>{
+        const event = (0, _domaineventpublisher.buildDomainEvent)({
+            module: 'form-builder',
+            entity: 'form_result',
+            action: 'submitted',
+            data: {
+                id: 'a',
+                password: 'hunter2'
+            },
+            metadata: {
+                token: 'abc'
+            }
+        });
+        expect(event.payload.data).toEqual([
+            {
+                id: 'a',
+                password: '[REDACTED]'
+            }
+        ]);
+        expect(event.payload.metadata).toEqual({
+            token: '[REDACTED]'
+        });
+    });
+    it('should record the acting user', ()=>{
+        const event = (0, _domaineventpublisher.buildDomainEvent)({
+            module: 'form-builder',
+            entity: 'form_result',
+            action: 'submitted',
+            user
+        });
+        expect(event.actor).toEqual(expect.objectContaining({
+            userId: 'user-1',
+            companyId: 'company-1'
+        }));
+    });
+});
+describe('publishDomainEvent', ()=>{
+    let publish;
+    beforeEach(()=>{
+        publish = jest.fn().mockResolvedValue(undefined);
+        _eventbusregistry.EventBusRegistry.reset();
+        _eventbusregistry.EventBusRegistry.setBus({
+            publish,
+            subscribe: jest.fn(),
+            close: jest.fn()
+        });
+    });
+    afterEach(()=>{
+        _eventbusregistry.EventBusRegistry.reset();
+    });
+    it('should publish when the module has events enabled', async ()=>{
+        _eventbusregistry.EventBusRegistry.configureModule('auth', {
+            enabled: true
+        });
+        await (0, _domaineventpublisher.publishDomainEvent)({
+            module: 'auth',
+            entity: 'session',
+            action: 'logged-in'
+        });
+        expect(publish).toHaveBeenCalledWith(expect.objectContaining({
+            name: 'auth.session.logged-in'
+        }));
+    });
+    it('should stay silent when the module has events disabled', async ()=>{
+        _eventbusregistry.EventBusRegistry.configureModule('auth', {
+            enabled: false
+        });
+        await (0, _domaineventpublisher.publishDomainEvent)({
+            module: 'auth',
+            entity: 'session',
+            action: 'logged-in'
+        });
+        expect(publish).not.toHaveBeenCalled();
+    });
+    it('should honour an action allowlist that names a domain action', async ()=>{
+        _eventbusregistry.EventBusRegistry.configureModule('auth', {
+            enabled: true,
+            actions: [
+                'logged-in'
+            ]
+        });
+        await (0, _domaineventpublisher.publishDomainEvent)({
+            module: 'auth',
+            entity: 'session',
+            action: 'logged-in'
+        });
+        await (0, _domaineventpublisher.publishDomainEvent)({
+            module: 'auth',
+            entity: 'session',
+            action: 'logged-out'
+        });
+        expect(publish).toHaveBeenCalledTimes(1);
+    });
+    it('should publish through an explicitly supplied bus instead of the registered one', async ()=>{
+        const directPublish = jest.fn().mockResolvedValue(undefined);
+        _eventbusregistry.EventBusRegistry.configureModule('auth', {
+            enabled: true
+        });
+        await (0, _domaineventpublisher.publishDomainEvent)({
+            module: 'auth',
+            entity: 'session',
+            action: 'logged-in',
+            eventBus: {
+                publish: directPublish
+            }
+        });
+        expect(directPublish).toHaveBeenCalled();
+        expect(publish).not.toHaveBeenCalled();
+    });
+    it('should still respect the module switch when a bus is supplied explicitly', async ()=>{
+        const directPublish = jest.fn().mockResolvedValue(undefined);
+        _eventbusregistry.EventBusRegistry.configureModule('auth', {
+            enabled: false
+        });
+        await (0, _domaineventpublisher.publishDomainEvent)({
+            module: 'auth',
+            entity: 'session',
+            action: 'logged-in',
+            eventBus: {
+                publish: directPublish
+            }
+        });
+        expect(directPublish).not.toHaveBeenCalled();
+    });
+    it('should do nothing when no bus is registered', async ()=>{
+        _eventbusregistry.EventBusRegistry.reset();
+        await expect((0, _domaineventpublisher.publishDomainEvent)({
+            module: 'auth',
+            entity: 'session',
+            action: 'logged-in'
+        })).resolves.toBeUndefined();
+    });
+    it('should swallow a broker failure', async ()=>{
+        _eventbusregistry.EventBusRegistry.configureModule('auth', {
+            enabled: true
+        });
+        publish.mockRejectedValue(new Error('broker down'));
+        await expect((0, _domaineventpublisher.publishDomainEvent)({
+            module: 'auth',
+            entity: 'session',
+            action: 'logged-in'
+        })).resolves.toBeUndefined();
+    });
+});

package/cjs/classes/event-bus.registry.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "EventBusRegistry", {
+    enumerable: true,
+    get: function() {
+        return EventBusRegistry;
+    }
+});
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+const DISABLED = {
+    enabled: false
+};
+let EventBusRegistry = class EventBusRegistry {
+    static setBus(bus) {
+        this.bus = bus;
+    }
+    static getBus() {
+        return this.bus;
+    }
+    static setDefaultModuleEvents(config) {
+        this.defaultConfig = config ?? DISABLED;
+    }
+    /** Called by each feature module with the `events` block from its own config */ static configureModule(moduleName, config) {
+        this.moduleConfigs.set(moduleName, config ?? DISABLED);
+    }
+    static getModuleConfig(moduleName) {
+        if (!moduleName) return this.defaultConfig;
+        return this.moduleConfigs.get(moduleName) ?? this.defaultConfig;
+    }
+    /**
+   * Answers only "is this module configured to publish this" - whether a bus
+   * exists is the publisher's concern, so an explicitly supplied bus is still
+   * held to the module's own on/off switch.
+   */ static isEnabled(moduleName, entity, action) {
+        const config = this.getModuleConfig(moduleName);
+        if (!config.enabled) return false;
+        if (config.excludeEntities?.includes(entity)) return false;
+        if (config.entities?.length && !config.entities.includes(entity)) return false;
+        // Without an explicit allowlist, CRUD lifecycle actions and every domain
+        // action a package defines are all published.
+        if (!config.actions?.length) return true;
+        return config.actions.includes(action);
+    }
+    static shouldIncludePayload(moduleName) {
+        return this.getModuleConfig(moduleName).includePayload ?? true;
+    }
+    static reset() {
+        this.bus = undefined;
+        this.moduleConfigs.clear();
+        this.defaultConfig = DISABLED;
+    }
+};
+_define_property(EventBusRegistry, "bus", void 0);
+_define_property(EventBusRegistry, "moduleConfigs", new Map());
+_define_property(EventBusRegistry, "defaultConfig", DISABLED);