@flusys/nestjs-shared 7.0.2 → 8.0.0-beta.1

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

@@ -1,11 +0,0 @@
-/**
- * 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

@@ -1,36 +0,0 @@
-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();
-    });
-});

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

@@ -1,63 +0,0 @@
-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

@@ -1,230 +0,0 @@
-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

@@ -1,64 +0,0 @@
-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;
-}
-import { matchEventPattern } from '../utils/event-pattern.util';
-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;
-        // 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.some((entry)=>entry.includes('.') ? matchEventPattern(entry, `${entity}.${action}`) : matchEventPattern(entry, 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

@@ -1,137 +0,0 @@
-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', 'created')).toBe(true);
-    });
-    it('should report disabled for a module that never registered a config', ()=>{
-        expect(EventBusRegistry.isEnabled('storage', 'folder', 'created')).toBe(false);
-    });
-    it('should enable every action of an enabled module by default', ()=>{
-        EventBusRegistry.configureModule('storage', {
-            enabled: true
-        });
-        expect(EventBusRegistry.isEnabled('storage', 'folder', 'created')).toBe(true);
-        expect(EventBusRegistry.isEnabled('storage', 'folder', 'deleted')).toBe(true);
-    });
-    it('should honour an action allowlist', ()=>{
-        EventBusRegistry.configureModule('storage', {
-            enabled: true,
-            actions: [
-                'created'
-            ]
-        });
-        expect(EventBusRegistry.isEnabled('storage', 'folder', 'created')).toBe(true);
-        expect(EventBusRegistry.isEnabled('storage', 'folder', 'updated')).toBe(false);
-    });
-    it('should honour an allowlist that mixes CRUD lifecycle and domain actions', ()=>{
-        EventBusRegistry.configureModule('auth', {
-            enabled: true,
-            actions: [
-                'created',
-                'logged-in'
-            ]
-        });
-        expect(EventBusRegistry.isEnabled('auth', 'appuser', 'created')).toBe(true);
-        expect(EventBusRegistry.isEnabled('auth', 'session', 'logged-in')).toBe(true);
-        expect(EventBusRegistry.isEnabled('auth', 'appuser', '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', 'created')).toBe(false);
-    });
-    it('should scope an action to one entity when the entry names it', ()=>{
-        EventBusRegistry.configureModule('iam', {
-            enabled: true,
-            actions: [
-                'created',
-                'role.updated'
-            ]
-        });
-        expect(EventBusRegistry.isEnabled('iam', 'role', 'updated')).toBe(true);
-        expect(EventBusRegistry.isEnabled('iam', 'action', 'updated')).toBe(false);
-        expect(EventBusRegistry.isEnabled('iam', 'action', 'created')).toBe(true);
-    });
-    it('should treat a scoped entry as a routing pattern', ()=>{
-        EventBusRegistry.configureModule('iam', {
-            enabled: true,
-            actions: [
-                'role.*',
-                '*.purged'
-            ]
-        });
-        expect(EventBusRegistry.isEnabled('iam', 'role', 'updated')).toBe(true);
-        expect(EventBusRegistry.isEnabled('iam', 'role', 'permissions-assigned')).toBe(true);
-        expect(EventBusRegistry.isEnabled('iam', 'action', 'purged')).toBe(true);
-        expect(EventBusRegistry.isEnabled('iam', 'action', 'updated')).toBe(false);
-    });
-    it('should publish only the entity and action pairs an app lists', ()=>{
-        EventBusRegistry.configureModule('auth', {
-            enabled: true,
-            actions: [
-                'company.created',
-                'company.updated',
-                'session.logged-in'
-            ]
-        });
-        expect(EventBusRegistry.isEnabled('auth', 'company', 'created')).toBe(true);
-        expect(EventBusRegistry.isEnabled('auth', 'company', 'updated')).toBe(true);
-        expect(EventBusRegistry.isEnabled('auth', 'company', 'purged')).toBe(false);
-        expect(EventBusRegistry.isEnabled('auth', 'appuser', 'created')).toBe(false);
-        expect(EventBusRegistry.isEnabled('auth', 'session', 'logged-in')).toBe(true);
-        expect(EventBusRegistry.isEnabled('auth', 'session', 'logged-out')).toBe(false);
-    });
-    it('should fall back to the default config for unregistered modules', ()=>{
-        EventBusRegistry.setDefaultModuleEvents({
-            enabled: true
-        });
-        expect(EventBusRegistry.isEnabled('unknown-module', 'thing', '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

@@ -1,35 +0,0 @@
-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

@@ -1,27 +0,0 @@
-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

@@ -1,6 +0,0 @@
-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';