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

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

@@ -0,0 +1,63 @@
+import { randomUUID } from 'crypto';
+import { getCompanyId, getRequestId, getTenantId } from '../middlewares/logger.middleware';
+import { sanitizeEventPayload } from '../utils/event-pattern.util';
+import { EventBusRegistry } from './event-bus.registry';
+export const DOMAIN_EVENT_VERSION = 1;
+export function buildDomainEvent(input) {
+    const rows = input.data === undefined ? [] : toArray(input.data);
+    const ids = input.ids ?? collectIds(rows);
+    return {
+        id: randomUUID(),
+        name: `${input.module}.${input.entity}.${input.action}`,
+        module: input.module,
+        entity: input.entity,
+        action: input.action,
+        payload: {
+            ids,
+            ...rows.length && EventBusRegistry.shouldIncludePayload(input.module) ? {
+                data: sanitizeEventPayload(rows)
+            } : {},
+            ...input.metadata ? {
+                metadata: sanitizeEventPayload(input.metadata)
+            } : {}
+        },
+        actor: {
+            userId: input.user?.id ?? null,
+            companyId: input.user?.companyId ?? getCompanyId() ?? null,
+            tenantId: getTenantId() ?? null,
+            requestId: getRequestId() ?? null
+        },
+        occurredAt: new Date().toISOString(),
+        version: DOMAIN_EVENT_VERSION
+    };
+}
+/**
+ * Publishes a domain event for an operation that is not plain CRUD - a form
+ * submission, a login, a file upload. Honours the publishing module's own
+ * `events` config and never throws, so a broker outage cannot break the caller.
+ *
+ * Supplying `eventBus` chooses which bus to publish on; it never overrides the
+ * module's on/off switch, otherwise turning a module's events off would leave
+ * every service holding its own bus still publishing.
+ */ export async function publishDomainEvent(input) {
+    const bus = input.eventBus ?? EventBusRegistry.getBus();
+    if (!bus) return;
+    if (!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/fesm/classes/domain-event.publisher.spec.js

@@ -0,0 +1,230 @@
+import { buildDomainEvent, publishDomainEvent } from './domain-event.publisher';
+import { EventBusRegistry } from './event-bus.registry';
+const user = {
+    id: 'user-1',
+    email: 'ada@example.com',
+    companyId: 'company-1'
+};
+describe('buildDomainEvent', ()=>{
+    beforeEach(()=>{
+        EventBusRegistry.reset();
+        EventBusRegistry.configureModule('form-builder', {
+            enabled: true
+        });
+    });
+    afterEach(()=>{
+        EventBusRegistry.reset();
+    });
+    it('should name the event <module>.<entity>.<action>', ()=>{
+        const event = 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 = 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 = 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.configureModule('form-builder', {
+            enabled: true,
+            includePayload: false
+        });
+        const event = 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 = 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 = 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.reset();
+        EventBusRegistry.setBus({
+            publish,
+            subscribe: jest.fn(),
+            close: jest.fn()
+        });
+    });
+    afterEach(()=>{
+        EventBusRegistry.reset();
+    });
+    it('should publish when the module has events enabled', async ()=>{
+        EventBusRegistry.configureModule('auth', {
+            enabled: true
+        });
+        await 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.configureModule('auth', {
+            enabled: false
+        });
+        await 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.configureModule('auth', {
+            enabled: true,
+            actions: [
+                'logged-in'
+            ]
+        });
+        await publishDomainEvent({
+            module: 'auth',
+            entity: 'session',
+            action: 'logged-in'
+        });
+        await 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.configureModule('auth', {
+            enabled: true
+        });
+        await 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.configureModule('auth', {
+            enabled: false
+        });
+        await 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.reset();
+        await expect(publishDomainEvent({
+            module: 'auth',
+            entity: 'session',
+            action: 'logged-in'
+        })).resolves.toBeUndefined();
+    });
+    it('should swallow a broker failure', async ()=>{
+        EventBusRegistry.configureModule('auth', {
+            enabled: true
+        });
+        publish.mockRejectedValue(new Error('broker down'));
+        await expect(publishDomainEvent({
+            module: 'auth',
+            entity: 'session',
+            action: 'logged-in'
+        })).resolves.toBeUndefined();
+    });
+});

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

@@ -0,0 +1,65 @@
+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
+};
+/**
+ * Ambient access point for the event bus.
+ *
+ * ApiService is request scoped and is extended by every feature package, so the
+ * bus is resolved from here instead of being threaded through 20+ constructors.
+ * Services may still receive a bus explicitly - that instance wins.
+ */ export 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);

package/fesm/classes/event-bus.registry.spec.js

@@ -0,0 +1,112 @@
+import { EventAction } from '../enums/event-action.enum';
+import { EventBusRegistry } from './event-bus.registry';
+const bus = {
+    publish: jest.fn(),
+    subscribe: jest.fn(),
+    close: jest.fn()
+};
+describe('EventBusRegistry', ()=>{
+    beforeEach(()=>{
+        EventBusRegistry.reset();
+        EventBusRegistry.setBus(bus);
+    });
+    afterEach(()=>{
+        EventBusRegistry.reset();
+    });
+    it('should expose the registered bus', ()=>{
+        expect(EventBusRegistry.getBus()).toBe(bus);
+    });
+    it('should answer from the module config alone, independent of any registered bus', ()=>{
+        EventBusRegistry.reset();
+        EventBusRegistry.configureModule('storage', {
+            enabled: true
+        });
+        expect(EventBusRegistry.getBus()).toBeUndefined();
+        expect(EventBusRegistry.isEnabled('storage', 'folder', EventAction.CREATED)).toBe(true);
+    });
+    it('should report disabled for a module that never registered a config', ()=>{
+        expect(EventBusRegistry.isEnabled('storage', 'folder', EventAction.CREATED)).toBe(false);
+    });
+    it('should enable every action of an enabled module by default', ()=>{
+        EventBusRegistry.configureModule('storage', {
+            enabled: true
+        });
+        expect(EventBusRegistry.isEnabled('storage', 'folder', EventAction.CREATED)).toBe(true);
+        expect(EventBusRegistry.isEnabled('storage', 'folder', EventAction.DELETED)).toBe(true);
+    });
+    it('should honour an action allowlist', ()=>{
+        EventBusRegistry.configureModule('storage', {
+            enabled: true,
+            actions: [
+                EventAction.CREATED
+            ]
+        });
+        expect(EventBusRegistry.isEnabled('storage', 'folder', EventAction.CREATED)).toBe(true);
+        expect(EventBusRegistry.isEnabled('storage', 'folder', EventAction.UPDATED)).toBe(false);
+    });
+    it('should honour an allowlist that mixes CRUD lifecycle and domain actions', ()=>{
+        EventBusRegistry.configureModule('auth', {
+            enabled: true,
+            actions: [
+                EventAction.CREATED,
+                'logged-in'
+            ]
+        });
+        expect(EventBusRegistry.isEnabled('auth', 'appuser', EventAction.CREATED)).toBe(true);
+        expect(EventBusRegistry.isEnabled('auth', 'session', 'logged-in')).toBe(true);
+        expect(EventBusRegistry.isEnabled('auth', 'appuser', EventAction.UPDATED)).toBe(false);
+        expect(EventBusRegistry.isEnabled('auth', 'session', 'logged-out')).toBe(false);
+    });
+    it('should silence CRUD when the allowlist names only domain actions', ()=>{
+        EventBusRegistry.configureModule('auth', {
+            enabled: true,
+            actions: [
+                'logged-in'
+            ]
+        });
+        expect(EventBusRegistry.isEnabled('auth', 'session', 'logged-in')).toBe(true);
+        expect(EventBusRegistry.isEnabled('auth', 'appuser', EventAction.CREATED)).toBe(false);
+    });
+    it('should honour an entity allowlist and exclusion list', ()=>{
+        EventBusRegistry.configureModule('storage', {
+            enabled: true,
+            entities: [
+                'folder',
+                'file_manager'
+            ],
+            excludeEntities: [
+                'file_manager'
+            ]
+        });
+        expect(EventBusRegistry.isEnabled('storage', 'folder', EventAction.CREATED)).toBe(true);
+        expect(EventBusRegistry.isEnabled('storage', 'file_manager', EventAction.CREATED)).toBe(false);
+        expect(EventBusRegistry.isEnabled('storage', 'storageConfig', EventAction.CREATED)).toBe(false);
+    });
+    it('should fall back to the default config for unregistered modules', ()=>{
+        EventBusRegistry.setDefaultModuleEvents({
+            enabled: true
+        });
+        expect(EventBusRegistry.isEnabled('unknown-module', 'thing', EventAction.CREATED)).toBe(true);
+    });
+    it('should include the payload unless a module opts out', ()=>{
+        EventBusRegistry.configureModule('storage', {
+            enabled: true
+        });
+        EventBusRegistry.configureModule('auth', {
+            enabled: true,
+            includePayload: false
+        });
+        expect(EventBusRegistry.shouldIncludePayload('storage')).toBe(true);
+        expect(EventBusRegistry.shouldIncludePayload('auth')).toBe(false);
+    });
+    it('should clear everything on reset', ()=>{
+        EventBusRegistry.configureModule('storage', {
+            enabled: true
+        });
+        EventBusRegistry.reset();
+        expect(EventBusRegistry.getBus()).toBeUndefined();
+        expect(EventBusRegistry.getModuleConfig('storage')).toEqual({
+            enabled: false
+        });
+    });
+});

package/fesm/classes/event-transports/event-transport.registry.js

@@ -0,0 +1,35 @@
+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;
+}
+/**
+ * Static registry for event transports.
+ * Broker transports register themselves on import so nestjs-shared never has to
+ * depend on `amqplib` or `kafkajs` at build time.
+ */ export class EventTransportRegistry {
+    static register(name, factory) {
+        this.transports.set(name.toLowerCase(), factory);
+    }
+    static get(name) {
+        return this.transports.get(name.toLowerCase());
+    }
+    static has(name) {
+        return this.transports.has(name.toLowerCase());
+    }
+    static getAll() {
+        return Array.from(this.transports.keys());
+    }
+    static clear() {
+        this.transports.clear();
+    }
+}
+_define_property(EventTransportRegistry, "transports", new Map());

package/fesm/classes/event-transports/event-transport.registry.spec.js

@@ -0,0 +1,27 @@
+import { EventTransportRegistry } from './event-transport.registry';
+const stubTransport = {};
+describe('EventTransportRegistry', ()=>{
+    afterEach(()=>{
+        EventTransportRegistry.clear();
+    });
+    it('should register and resolve a transport factory', ()=>{
+        EventTransportRegistry.register('rabbitmq', ()=>stubTransport);
+        expect(EventTransportRegistry.get('rabbitmq')({})).toBe(stubTransport);
+    });
+    it('should resolve case insensitively', ()=>{
+        EventTransportRegistry.register('Kafka', ()=>stubTransport);
+        expect(EventTransportRegistry.has('kafka')).toBe(true);
+    });
+    it('should return undefined for an unknown transport', ()=>{
+        expect(EventTransportRegistry.get('nats')).toBeUndefined();
+        expect(EventTransportRegistry.has('nats')).toBe(false);
+    });
+    it('should list every registered transport', ()=>{
+        EventTransportRegistry.register('memory', ()=>stubTransport);
+        EventTransportRegistry.register('kafka', ()=>stubTransport);
+        expect(EventTransportRegistry.getAll().sort()).toEqual([
+            'kafka',
+            'memory'
+        ]);
+    });
+});

package/fesm/classes/event-transports/index.js

@@ -0,0 +1,6 @@
+export * from './event-transport.registry';
+// Built-in transport (no external dependencies)
+export * from './memory-transport'; // Note: Broker transports are loaded dynamically by HybridEventBus.
+ // Import them directly when registering manually:
+ // - import { RabbitMqTransport } from '@flusys/nestjs-shared/classes/event-transports/rabbitmq-transport.optional';
+ // - import { KafkaTransport } from '@flusys/nestjs-shared/classes/event-transports/kafka-transport.optional';

package/fesm/classes/event-transports/kafka-transport.optional.js

@@ -0,0 +1,144 @@
+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;
+}
+/**
+ * Optional Kafka event transport
+ * Requires: npm install kafkajs
+ */ import { InternalServerErrorException, Logger } from '@nestjs/common';
+import { DEFAULT_EVENT_SERVICE_NAME, DEFAULT_EVENT_TOPIC, SYSTEM_MESSAGES } from '../../constants';
+import { loadOptionalModule } from '../../utils/optional-module.util';
+import { EventTransportRegistry } from './event-transport.registry';
+const DEFAULT_BROKERS = [
+    'localhost:9092'
+];
+/**
+ * Every domain event lands on a single topic keyed by event name; pattern
+ * filtering happens in the bus, which keeps consumer group management trivial.
+ */ export class KafkaTransport {
+    async connect() {
+        let kafkajs;
+        try {
+            kafkajs = await loadOptionalModule('kafkajs');
+        } catch  {
+            throw new InternalServerErrorException({
+                message: 'kafkajs not found',
+                messageKey: SYSTEM_MESSAGES.SDK_NOT_INSTALLED,
+                messageVariables: {
+                    sdk: 'kafkajs'
+                }
+            });
+        }
+        const Kafka = kafkajs.Kafka ?? kafkajs.default.Kafka;
+        this.client = new Kafka({
+            clientId: this.config.clientId ?? DEFAULT_EVENT_SERVICE_NAME,
+            brokers: this.config.brokers ?? DEFAULT_BROKERS,
+            ssl: this.config.ssl,
+            sasl: this.config.sasl
+        });
+        this.producer = this.client.producer();
+        await this.producer.connect();
+        // The consumer is built on the first bind, never here: subscribing to a
+        // topic that does not exist yet, or a coordinator that is not ready, would
+        // otherwise fail the whole transport and take publishing down with it - and
+        // a service that only publishes would join a consumer group for nothing.
+        if (this.boundPatterns.size) await this.startConsuming();
+    }
+    async publish(event) {
+        if (!this.producer) return;
+        await this.producer.send({
+            topic: this.topic,
+            messages: [
+                {
+                    key: event.name,
+                    value: JSON.stringify(event),
+                    headers: {
+                        eventId: event.id,
+                        module: event.module,
+                        action: String(event.action)
+                    }
+                }
+            ]
+        });
+    }
+    async bind(pattern) {
+        if (this.boundPatterns.has(pattern)) return;
+        this.boundPatterns.add(pattern);
+        await this.startConsuming();
+    }
+    onMessage(handler) {
+        this.handlers.push(handler);
+    }
+    async close() {
+        await this.consumer?.disconnect().catch(()=>{});
+        await this.producer?.disconnect().catch(()=>{});
+        this.consumer = undefined;
+        this.producer = undefined;
+        this.client = undefined;
+        this.running = false;
+    }
+    isReady() {
+        return Boolean(this.producer);
+    }
+    get topic() {
+        return this.config.topic ?? DEFAULT_EVENT_TOPIC;
+    }
+    async startConsuming() {
+        if (this.running || !this.client) return;
+        this.running = true;
+        try {
+            this.consumer = this.client.consumer({
+                groupId: this.config.groupId ?? `${DEFAULT_EVENT_SERVICE_NAME}-events`
+            });
+            await this.consumer.connect();
+            await this.consumer.subscribe({
+                topic: this.topic,
+                fromBeginning: false
+            });
+            await this.consumer.run({
+                eachMessage: async ({ message })=>{
+                    // A compacted topic delivers tombstones with no value at all
+                    if (!message?.value) return;
+                    try {
+                        const event = JSON.parse(message.value.toString());
+                        await Promise.all(this.handlers.map((handler)=>handler(event)));
+                    } catch (error) {
+                        this.logger.error(error instanceof Error ? error.message : 'Failed to handle event');
+                    }
+                }
+            });
+        } catch (error) {
+            // Released so a later bind can try again; the producer stays usable
+            this.running = false;
+            this.consumer = undefined;
+            throw error;
+        }
+    }
+    constructor(config = {}){
+        _define_property(this, "config", void 0);
+        _define_property(this, "name", void 0);
+        _define_property(this, "logger", void 0);
+        _define_property(this, "handlers", void 0);
+        _define_property(this, "boundPatterns", void 0);
+        _define_property(this, "client", void 0);
+        _define_property(this, "producer", void 0);
+        _define_property(this, "consumer", void 0);
+        _define_property(this, "running", void 0);
+        this.config = config;
+        this.name = 'kafka';
+        this.logger = new Logger(KafkaTransport.name);
+        this.handlers = [];
+        this.boundPatterns = new Set();
+        this.running = false;
+    }
+}
+EventTransportRegistry.register('kafka', (config)=>new KafkaTransport(config));