@flusys/nestjs-shared 6.4.1 → 7.0.0-beta.1

package/classes/disabled-event-bus.class.d.ts

@@ -0,0 +1,6 @@
+import { DomainEventHandler, IDomainEvent, IEventBus } from '../interfaces/event-bus.interface';
+export declare class DisabledEventBus implements IEventBus {
+    publish<T>(_event: IDomainEvent<T>): Promise<void>;
+    subscribe<T>(_pattern: string, _handler: DomainEventHandler<T>): Promise<void>;
+    close(): Promise<void>;
+}

package/classes/domain-event.publisher.d.ts

@@ -0,0 +1,14 @@
+import { DomainEventActionName, IDomainEvent, IDomainEventPayload, IEventBus, ILoggedUserInfo } from '../interfaces';
+export declare const DOMAIN_EVENT_VERSION = 1;
+export interface IPublishDomainEventInput<T = Record<string, unknown>> {
+    module: string;
+    entity: string;
+    action: DomainEventActionName;
+    ids?: string[];
+    data?: T | T[];
+    metadata?: Record<string, unknown>;
+    user?: ILoggedUserInfo | null;
+    eventBus?: IEventBus;
+}
+export declare function buildDomainEvent<T>(input: IPublishDomainEventInput<T>): IDomainEvent<IDomainEventPayload<T>>;
+export declare function publishDomainEvent<T>(input: IPublishDomainEventInput<T>): Promise<void>;

package/classes/event-bus.registry.d.ts

@@ -0,0 +1,14 @@
+import { DomainEventActionName, IEventBus, IModuleEventsConfig } from '../interfaces/event-bus.interface';
+export declare class EventBusRegistry {
+    private static bus?;
+    private static moduleConfigs;
+    private static defaultConfig;
+    static setBus(bus: IEventBus): void;
+    static getBus(): IEventBus | undefined;
+    static setDefaultModuleEvents(config: IModuleEventsConfig): void;
+    static configureModule(moduleName: string, config?: IModuleEventsConfig): void;
+    static getModuleConfig(moduleName?: string): IModuleEventsConfig;
+    static isEnabled(moduleName: string | undefined, entity: string, action: DomainEventActionName): boolean;
+    static shouldIncludePayload(moduleName?: string): boolean;
+    static reset(): void;
+}

package/classes/event-transports/event-transport.registry.d.ts

@@ -0,0 +1,10 @@
+import { IEventTransport } from '../../interfaces/event-bus.interface';
+export type EventTransportFactory = (config: Record<string, unknown>) => IEventTransport;
+export declare class EventTransportRegistry {
+    private static transports;
+    static register(name: string, factory: EventTransportFactory): void;
+    static get(name: string): EventTransportFactory | undefined;
+    static has(name: string): boolean;
+    static getAll(): string[];
+    static clear(): void;
+}

package/classes/event-transports/index.d.ts

@@ -0,0 +1,2 @@
+export * from './event-transport.registry';
+export * from './memory-transport';

package/classes/event-transports/kafka-transport.optional.d.ts

@@ -0,0 +1,21 @@
+import { DomainEventHandler, IDomainEvent, IEventTransport, IKafkaTransportConfig } from '../../interfaces/event-bus.interface';
+export declare class KafkaTransport implements IEventTransport {
+    private readonly config;
+    readonly name = "kafka";
+    private readonly logger;
+    private readonly handlers;
+    private readonly boundPatterns;
+    private client;
+    private producer;
+    private consumer;
+    private running;
+    constructor(config?: IKafkaTransportConfig);
+    connect(): Promise<void>;
+    publish(event: IDomainEvent): Promise<void>;
+    bind(pattern: string): Promise<void>;
+    onMessage(handler: DomainEventHandler): void;
+    close(): Promise<void>;
+    isReady(): boolean;
+    private get topic();
+    private startConsuming;
+}

package/classes/event-transports/memory-transport.d.ts

@@ -0,0 +1,13 @@
+import { DomainEventHandler, IDomainEvent, IEventTransport } from '../../interfaces/event-bus.interface';
+export declare class MemoryTransport implements IEventTransport {
+    readonly name = "memory";
+    private readonly emitter;
+    private ready;
+    constructor(maxListeners?: number);
+    connect(): Promise<void>;
+    publish(event: IDomainEvent): Promise<void>;
+    bind(_pattern: string): Promise<void>;
+    onMessage(handler: DomainEventHandler): void;
+    close(): Promise<void>;
+    isReady(): boolean;
+}

package/classes/event-transports/rabbitmq-transport.optional.d.ts

@@ -0,0 +1,27 @@
+import { DomainEventHandler, IDomainEvent, IEventTransport, IRabbitMqTransportConfig } from '../../interfaces/event-bus.interface';
+export declare class RabbitMqTransport implements IEventTransport {
+    private readonly config;
+    readonly name = "rabbitmq";
+    private readonly logger;
+    private readonly handlers;
+    private readonly boundPatterns;
+    private connection;
+    private channel;
+    private consuming;
+    private closed;
+    private reconnectTimer?;
+    constructor(config?: IRabbitMqTransportConfig);
+    connect(): Promise<void>;
+    publish(event: IDomainEvent): Promise<void>;
+    bind(pattern: string): Promise<void>;
+    onMessage(handler: DomainEventHandler): void;
+    close(): Promise<void>;
+    isReady(): boolean;
+    private get exchange();
+    private get queue();
+    private get durable();
+    private toRoutingKey;
+    private startConsuming;
+    private scheduleReconnect;
+    private teardown;
+}

package/classes/hybrid-event-bus.class.d.ts

@@ -0,0 +1,32 @@
+import { DomainEventHandler, EventTransportLabel, IDomainEvent, IEventBus, IEventBusModuleOptions } from '../interfaces/event-bus.interface';
+export declare class HybridEventBus implements IEventBus {
+    private readonly options;
+    private readonly logger;
+    private readonly subscriptions;
+    private readonly transports;
+    private readonly seenIds;
+    private readonly seenOrder;
+    private readonly label;
+    private readonly dedupeSize;
+    private memory?;
+    private connecting?;
+    private connected;
+    constructor(options?: IEventBusModuleOptions);
+    getTransportLabel(): EventTransportLabel;
+    getActiveTransports(): string[];
+    connect(): Promise<void>;
+    publish<T>(event: IDomainEvent<T>): Promise<void>;
+    subscribe<T>(pattern: string, handler: DomainEventHandler<T>): Promise<void>;
+    close(): Promise<void>;
+    private ensureConnected;
+    private resolveLabelFromEnv;
+    private buildTransports;
+    private createBrokerTransport;
+    private resolveHybridBrokerName;
+    private loadOptionalTransport;
+    private getTransportConfig;
+    private parseBrokers;
+    private registerTransport;
+    private dispatch;
+    private isDuplicate;
+}

package/classes/index.d.ts

@@ -1,6 +1,11 @@
 export * from './api-controller.class';
 export * from './api-service.class';
+export * from './disabled-event-bus.class';
+export * from './domain-event.publisher';
+export * from './event-bus.registry';
+export * from './event-transports';
 export * from './handle-custome-db';
 export * from './hybrid-cache.class';
+export * from './hybrid-event-bus.class';
 export * from './winston.logger.class';
 export * from '../constants/permissions';

package/constants/index.d.ts

@@ -1,11 +1,17 @@
 export declare const IS_PUBLIC_KEY = "isPublic";
 export declare const PERMISSIONS_KEY = "permissions";
+export declare const DOMAIN_EVENT_HANDLER_KEY = "domainEventHandler";
 export declare const CACHE_INSTANCE = "CACHE_INSTANCE";
 export declare const PERMISSION_GUARD_CONFIG = "PERMISSION_GUARD_CONFIG";
+export declare const EVENT_BUS_INSTANCE = "EVENT_BUS_INSTANCE";
+export declare const EVENT_BUS_MODULE_OPTIONS = "EVENT_BUS_MODULE_OPTIONS";
 export declare const IDEMPOTENCY_KEY_HEADER = "x-idempotency-key";
 export declare const REQUEST_ID_HEADER = "x-request-id";
 export declare const CLIENT_TYPE_HEADER = "x-client-type";
 export declare const PERMISSIONS_CACHE_PREFIX = "my-permissions";
 export declare const IDEMPOTENCY_CACHE_PREFIX = "idempotency";
+export declare const DEFAULT_EVENT_EXCHANGE = "flusys.events";
+export declare const DEFAULT_EVENT_TOPIC = "flusys.domain-events";
+export declare const DEFAULT_EVENT_SERVICE_NAME = "flusys";
 export * from './permissions';
 export * from './message-keys';

package/decorators/index.d.ts

@@ -1,5 +1,6 @@
 export * from './api-response.decorator';
 export * from './current-user.decorator';
 export * from './log-action.decorator';
+export * from './on-domain-event.decorator';
 export * from './public.decorator';
 export * from './require-permission.decorator';

package/decorators/on-domain-event.decorator.d.ts

@@ -0,0 +1 @@
+export declare const OnDomainEvent: (...patterns: string[]) => MethodDecorator;

package/enums/event-action.enum.d.ts

@@ -0,0 +1,7 @@
+export declare enum EventAction {
+    CREATED = "created",
+    UPDATED = "updated",
+    DELETED = "deleted",
+    RESTORED = "restored",
+    PURGED = "purged"
+}

package/enums/index.d.ts

@@ -1,3 +1,4 @@
+export * from './event-action.enum';
 export * from './notification-type.enum';
 export * from './participant-status.enum';
 export * from './recurrence-type.enum';

package/fesm/classes/api-service.class.js

@@ -25,9 +25,23 @@ import { EntityTarget, In } from 'typeorm';
 import { ERROR_MESSAGES, SYSTEM_MESSAGES } from '../constants';
 import { LogAction } from '../decorators/log-action.decorator';
 import { DeleteDto } from '../dtos';
+import { EventAction } from '../enums/event-action.enum';
 import { IDataSourceProvider } from '../interfaces';
 import { UtilsService } from '../modules/utils/utils.service';
+import { publishDomainEvent } from './domain-event.publisher';
 import { HybridCache } from './hybrid-cache.class';
+const DEFAULT_EVENT_MODULE = 'app';
+const OPERATION_EVENT_ACTIONS = {
+    insert: EventAction.CREATED,
+    insertMany: EventAction.CREATED,
+    update: EventAction.UPDATED,
+    updateMany: EventAction.UPDATED,
+    bulkUpsert: EventAction.UPDATED
+};
+const DELETE_EVENT_ACTIONS = {
+    delete: EventAction.DELETED,
+    restore: EventAction.RESTORED
+};
 export class ApiService {
     resolveEntity() {
         return this._entity;
@@ -64,7 +78,7 @@ export class ApiService {
                 saved,
                 returnFirst: true
             };
-        });
+        }, user);
     }
     async insertMany(dtos, user) {
         return this.executeInTransaction('insertMany', async (qr)=>{
@@ -76,7 +90,7 @@ export class ApiService {
                 saved,
                 returnFirst: false
             };
-        });
+        }, user);
     }
     async update(dto, user) {
         return this.executeInTransaction('update', async (qr)=>{
@@ -88,7 +102,7 @@ export class ApiService {
                 saved,
                 returnFirst: true
             };
-        });
+        }, user);
     }
     async updateMany(dtos, user) {
         return this.executeInTransaction('updateMany', async (qr)=>{
@@ -100,17 +114,22 @@ export class ApiService {
                 saved,
                 returnFirst: false
             };
-        });
+        }, user);
     }
     async bulkUpsert(toInsert, toUpdate, user) {
         return this.executeInTransaction('bulkUpsert', async (qr)=>{
             const allResults = [];
+            const eventGroups = [];
             if (toInsert.length > 0) {
                 await this.beforeInsertOperation(toInsert, user, qr);
                 const insertedEntities = await this.convertRequestDtoToEntity(toInsert, user);
                 const insertedSaved = await qr.manager.save(this.repository.target, insertedEntities);
                 await this.afterInsertOperation(this.ensureArray(insertedSaved), toInsert, user, qr);
                 allResults.push(...this.ensureArray(insertedSaved));
+                eventGroups.push({
+                    action: EventAction.CREATED,
+                    entities: this.ensureArray(insertedSaved)
+                });
             }
             if (toUpdate.length > 0) {
                 await this.beforeUpdateOperation(toUpdate, user, qr);
@@ -118,12 +137,17 @@ export class ApiService {
                 const updatedSaved = await qr.manager.save(this.repository.target, updatedEntities);
                 await this.afterUpdateOperation(this.ensureArray(updatedSaved), toUpdate, user, qr);
                 allResults.push(...this.ensureArray(updatedSaved));
+                eventGroups.push({
+                    action: EventAction.UPDATED,
+                    entities: this.ensureArray(updatedSaved)
+                });
             }
             return {
                 saved: allResults,
-                returnFirst: false
+                returnFirst: false,
+                eventGroups
             };
-        });
+        }, user);
     }
     async findByIds(ids, user, select) {
         await this.ensureDataSourceRepository();
@@ -325,6 +349,13 @@ export class ApiService {
                 this.clearCacheForAll(),
                 this.clearCacheForId(ids)
             ]);
+            await this.publishLifecycleEvents([
+                {
+                    action: DELETE_EVENT_ACTIONS[option.type] ?? EventAction.PURGED,
+                    entities: ids,
+                    idsOnly: true
+                }
+            ], user);
             return null;
         } catch (error) {
             await queryRunner.rollbackTransaction();
@@ -333,6 +364,32 @@ export class ApiService {
             await queryRunner.release();
         }
     }
+    async publishLifecycleEvents(groups, user) {
+        for (const group of groups){
+            if (!group.entities.length) continue;
+            await publishDomainEvent({
+                module: this.moduleName ?? DEFAULT_EVENT_MODULE,
+                entity: this.entityName,
+                action: group.action,
+                ids: group.entities.map((entity)=>entity.id),
+                ...group.idsOnly ? {} : {
+                    data: group.entities
+                },
+                user
+            });
+        }
+    }
+    /**
+   * Publishes a domain action for this service's entity - anything past plain
+   * CRUD, such as a submission or a state transition.
+   */ async publishDomainAction(action, input = {}) {
+        await publishDomainEvent({
+            ...input,
+            module: this.moduleName ?? DEFAULT_EVENT_MODULE,
+            entity: this.entityName,
+            action
+        });
+    }
     async clearCacheForAll() {
         await this.utilsService.clearCache(this.entityName, this.cacheManager);
     }
@@ -353,13 +410,13 @@ export class ApiService {
             value
         ];
     }
-    async executeInTransaction(operation, fn) {
+    async executeInTransaction(operation, fn, user) {
         await this.ensureDataSourceRepository();
         const qr = this.repository.manager.connection.createQueryRunner();
         await qr.connect();
         await qr.startTransaction();
         try {
-            const { saved, returnFirst } = await fn(qr);
+            const { saved, returnFirst, eventGroups } = await fn(qr);
             await qr.commitTransaction();
             const savedArray = this.ensureArray(saved);
             if (this.isCacheable) {
@@ -368,6 +425,12 @@ export class ApiService {
                     this.clearCacheForId(savedArray)
                 ]);
             }
+            await this.publishLifecycleEvents(eventGroups ?? [
+                {
+                    action: OPERATION_EVENT_ACTIONS[operation],
+                    entities: savedArray
+                }
+            ], user ?? null);
             if (returnFirst) {
                 return this.convertEntityToResponseDto(savedArray[0], false);
             }

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

@@ -15,6 +15,8 @@ import { Logger, InternalServerErrorException, NotFoundException } from '@nestjs
 import { createMockRepository, createMockDataSourceProvider } from '@test-utils/mocks/repository.mock';
 import { buildMockUser } from '@test-utils/mocks/logged-user.mock';
 import { ApiService } from './api-service.class';
+import { EventBusRegistry } from './event-bus.registry';
+import { EventAction } from '../enums/event-action.enum';
 import { UtilsService } from '../modules/utils/utils.service';
 import { Identity } from '../entities';
 let TestEntity = class TestEntity extends Identity {
@@ -802,4 +804,222 @@ describe('ApiService', ()=>{
             expect(clearSpy).toHaveBeenCalledWith('test-entity', mockCache, 'b');
         });
     });
+    describe('domain events', ()=>{
+        let publish;
+        function makeEventService(moduleName = 'test-module') {
+            const dataSourceProvider = createMockDataSourceProvider(mockRepo);
+            return new TestApiService('test-entity', mockCache, utilsService, 'TestApiService', false, moduleName, TestEntity, dataSourceProvider);
+        }
+        beforeEach(()=>{
+            publish = jest.fn().mockResolvedValue(undefined);
+            EventBusRegistry.reset();
+            EventBusRegistry.setBus({
+                publish,
+                subscribe: jest.fn(),
+                close: jest.fn()
+            });
+            EventBusRegistry.configureModule('test-module', {
+                enabled: true
+            });
+        });
+        afterEach(()=>{
+            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: 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: 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([
+                EventAction.CREATED,
+                EventAction.UPDATED
+            ]);
+        });
+        it.each([
+            [
+                'delete',
+                EventAction.DELETED
+            ],
+            [
+                'restore',
+                EventAction.RESTORED
+            ],
+            [
+                'permanent',
+                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.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.configureModule('test-module', {
+                enabled: true,
+                actions: [
+                    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.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.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/fesm/classes/disabled-event-bus.class.js

@@ -0,0 +1,11 @@
+/**
+ * Stands in for HybridEventBus when the subsystem is switched off.
+ *
+ * Injecting `EVENT_BUS_INSTANCE` keeps working, so turning events off cannot
+ * break a provider's dependencies, but nothing here can ever open a broker
+ * connection or run a handler.
+ */ export class DisabledEventBus {
+    async publish(_event) {}
+    async subscribe(_pattern, _handler) {}
+    async close() {}
+}

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

@@ -0,0 +1,36 @@
+import { DisabledEventBus } from './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 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 DisabledEventBus();
+        await expect(bus.publish(event)).resolves.toBeUndefined();
+        await expect(bus.subscribe('**', jest.fn())).resolves.toBeUndefined();
+        await expect(bus.close()).resolves.toBeUndefined();
+    });
+});