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

package/README.md

@@ -232,6 +232,443 @@ export class MyService {
 
 `CacheModule.forRoot(true)` connects to Redis automatically when `REDIS_URL` is set; otherwise uses in-memory only.
 
+## 8. Hybrid Event Bus
+
+The event counterpart of the hybrid cache: one wrapper, transport chosen by configuration.
+
+| `USE_EVENT_LABEL` | Behaviour                                              | Extra install    |
+| ----------------- | ------------------------------------------------------ | ---------------- |
+| `memory`          | In-process only (default)                              | none             |
+| `rabbitmq`        | Topic exchange, cross-service                          | `npm i amqplib`  |
+| `kafka`           | Single topic, cross-service                            | `npm i kafkajs`  |
+| `hybrid`          | Both layers, duplicate delivery suppressed by event id | broker of choice |
+
+### Registering
+
+`EventBusModule` is optional - register it only in an app that actually publishes or
+consumes events.
+
+```typescript
+import { EventBusModule } from '@flusys/nestjs-shared/modules';
+
+@Module({
+  imports: [EventBusModule.forRoot({ serviceName: 'flusysnest' })],
+})
+export class AppModule {}
+```
+
+Leave it out and nothing breaks: no package injects the bus as a hard dependency, and
+`publishDomainEvent` - including the calls `ApiService` makes for you - finds no bus and
+returns without doing anything. There is no placeholder registration to add just to keep
+DI happy. `forRoot({ enabled: false })` is for the other case: the app supports events but
+this deployment has them switched off, and you want that stated at startup.
+
+The one thing an unregistered app gives up is consumption - `@OnDomainEvent` methods are
+bound at bootstrap by an explorer that ships inside the module, so without it handlers
+never run and nothing warns about it.
+
+### Running against a real broker
+
+Both brokers need their driver installed - `npm i amqplib` or `npm i kafkajs`. The
+transports load it at runtime, so the package builds and boots without either.
+
+- **One delivery per service, not per replica.** RabbitMQ binds a single queue named
+  `<serviceName>.events` and Kafka joins one consumer group named `<serviceName>-events`,
+  so two replicas of the same service compete for each event and only one of them handles
+  it. Give a service that must see every event on every replica its own `queue` / `groupId`.
+- **A publisher consumes its own events.** In `rabbitmq` and `kafka` mode the local
+  handlers run off the broker round trip, which is what makes a single code path work
+  across services. In `hybrid` mode the in-process copy arrives first and the broker copy
+  is dropped by event id, so a handler still runs exactly once.
+- **RabbitMQ reconnects on its own.** A dropped connection *and* a channel killed by a
+  protocol error both schedule one reconnect (`reconnectDelay`, 5s by default), which
+  re-binds every pattern onto the fresh channel. While it is down, publishes are dropped
+  rather than queued - events must never fail the operation that produced them.
+- **Kafka's consumer is built on the first bind**, not at connect. A missing topic or an
+  unavailable group coordinator therefore fails consumption alone and leaves the producer
+  working, instead of taking the whole transport down to in-process delivery.
+
+### Publishing
+
+Every service extending `ApiService` publishes automatically once its module enables
+events — no per-service code. Turn it on in the module's own config:
+
+```typescript
+StorageModule.forRoot({
+  config: {
+    ...dbConfig,
+    events: { enabled: true, includePayload: true },
+  },
+});
+```
+
+#### Every `events` option
+
+| Option            | Type                        | Default | Effect                                                                 |
+| ----------------- | --------------------------- | ------- | ---------------------------------------------------------------------- |
+| `enabled`         | `boolean`                   | `false` | Master switch for the module. Everything else is ignored when off.     |
+| `actions`         | `(EventAction \| string)[]` | all     | Allowlist of action names. Omit to publish every action.               |
+| `entities`        | `string[]`                  | all     | Allowlist of entity names. Omit to publish every entity.               |
+| `excludeEntities` | `string[]`                  | `[]`    | Denylist, applied before `entities`.                                   |
+| `includePayload`  | `boolean`                   | `true`  | Attach the saved rows as `payload.data`. Ids and metadata always ride. |
+
+Three rules that decide what actually reaches a consumer:
+
+1. `actions` is **one allowlist covering CRUD and domain actions together**. Listing only
+   `['logged-in']` silences that module's `created`/`updated`/`deleted` too - name
+   everything you want kept, or omit `actions` entirely.
+2. `entities` matches the entity **in the event name**, which for a domain action is not
+   always the table you expect: `auth.session.logged-in` is filtered by `session`, not
+   `appuser`.
+3. Entity names are the ones the services register, so some are `snake_case`
+   (`form_result`, `file_manager`) and some are `camelCase` (`storageConfig`,
+   `emailConfig`, `translationKey`). The per-module tables below list them verbatim.
+
+Event names are always `<module>.<entity>.<action>`. CRUD lifecycle actions are
+`created`, `updated`, `deleted`, `restored`, `purged`. Events are published after the
+transaction commits and never fail the write that produced them.
+
+The module's own `events` block is the single authority on whether it publishes: passing
+an `eventBus` explicitly chooses _which_ bus to publish on, it never overrides the switch,
+so `enabled: false` silences the module everywhere. `delete` and `restore` carry ids only -
+there is no row left to attach.
+
+Payloads are walked before they leave the process: credential-like fields become
+`[REDACTED]`, a relation that loops back becomes `[CIRCULAR]`, anything past 8 levels deep
+becomes `[TRUNCATED]`, and a Buffer becomes `[BINARY]`. Saved TypeORM rows with
+bidirectional relations are therefore safe to publish.
+
+### Registering each module
+
+Every feature module takes the same `events` block in its own config, and every one of
+them also has a `forRootAsync` variant that returns the identical `config`. The blocks
+below spell out all options with that module's real entity and action names, so each is
+copy-pasteable. `EventAction` comes from `@flusys/nestjs-shared/enums`; the action and
+entity constants come from each package's own `config` entry point.
+
+In an application, keep the per-module blocks in one map rather than scattering them
+across registrations - `flusysnest/src/config/modules.config.ts` is the reference:
+
+```typescript
+const domainEventsEnabled = envConfig.getBoolean('ENABLE_DOMAIN_EVENTS', false);
+
+export const moduleEventsConfig: Record<FeatureModuleName, IModuleEventsConfig> = {
+  storage: {
+    enabled: domainEventsEnabled,
+    actions: [...CRUD_EVENT_ACTIONS, STORAGE_EVENT_ACTIONS.UPLOADED, STORAGE_EVENT_ACTIONS.REMOVED],
+    entities: [
+      STORAGE_EVENT_ENTITIES.FILE,
+      STORAGE_EVENT_ENTITIES.FOLDER,
+      STORAGE_EVENT_ENTITIES.STORAGE_CONFIG,
+    ],
+    excludeEntities: [STORAGE_EVENT_ENTITIES.STORAGE_CONFIG],
+    includePayload: true,
+  },
+  // ...one entry per feature module
+};
+
+export function getBaseModuleConfig(moduleName: FeatureModuleName) {
+  return { ...getDbConfig(), events: moduleEventsConfig[moduleName] };
+}
+
+AuthModule.forRoot({ config: { ...authConfig, ...getBaseModuleConfig('auth') } });
+```
+
+Spelling `actions` and `entities` out in full is the same as omitting them, and makes the
+file a readable inventory of what each module can publish - delete a line to stop
+publishing it. The trade-off is that a package gaining a new entity or action stays silent
+until it is added here, so keep a test asserting these lists cover each package's own
+`*_EVENT_ACTIONS` / `*_EVENT_ENTITIES` constants. One env flag still arms every module, but
+each keeps its own block, so narrowing one module never touches the others. Note the two `excludeEntities` entries that ship by
+default: `storageConfig` and `emailConfig` rows hold S3, Azure, SFTP and SMTP credentials
+in a `config` blob, so they stay off the bus entirely.
+
+#### auth
+
+```typescript
+import { AUTH_EVENT_ACTIONS, AUTH_EVENT_ENTITIES } from '@flusys/nestjs-auth/config';
+
+AuthModule.forRoot({
+  config: {
+    ...dbConfig,
+    events: {
+      enabled: true,
+      actions: [EventAction.CREATED, AUTH_EVENT_ACTIONS.LOGGED_IN],
+      entities: [AUTH_EVENT_ENTITIES.USER, AUTH_EVENT_ENTITIES.SESSION],
+      excludeEntities: ['company_branch'],
+      includePayload: false,
+    },
+  },
+});
+```
+
+| Entity                    | Actions it can publish                                                                                  |
+| ------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `appuser`                 | CRUD + `registered`, `password-changed`, `password-reset-requested`, `password-reset`, `email-verified` |
+| `company`                 | CRUD                                                                                                    |
+| `company_branch`          | CRUD                                                                                                    |
+| `session`                 | `logged-in`, `logged-out`, `token-refreshed`, `company-switched`                                        |
+| `user_company_permission` | `permission-granted`, `permission-revoked`                                                              |
+
+#### iam
+
+```typescript
+import { IAM_EVENT_ACTIONS, IAM_EVENT_ENTITIES } from '@flusys/nestjs-iam/config';
+
+IAMModule.forRoot({
+  config: {
+    ...dbConfig,
+    events: {
+      enabled: true,
+      actions: [EventAction.CREATED, EventAction.DELETED, IAM_EVENT_ACTIONS.PERMISSIONS_ASSIGNED],
+      entities: ['role', IAM_EVENT_ENTITIES.USER_ROLE],
+      excludeEntities: ['action'],
+      includePayload: true,
+    },
+  },
+});
+```
+
+| Entity                                                      | Actions it can publish |
+| ----------------------------------------------------------- | ---------------------- |
+| `action`, `role`                                            | CRUD                   |
+| `user_action`, `role_action`, `company_action`, `user_role` | `permissions-assigned` |
+
+#### storage
+
+```typescript
+import { STORAGE_EVENT_ACTIONS, STORAGE_EVENT_ENTITIES } from '@flusys/nestjs-storage/config';
+
+StorageModule.forRoot({
+  config: {
+    ...dbConfig,
+    events: {
+      enabled: true,
+      actions: [EventAction.CREATED, EventAction.DELETED, STORAGE_EVENT_ACTIONS.UPLOADED],
+      entities: [STORAGE_EVENT_ENTITIES.FILE, 'folder'],
+      excludeEntities: ['storageConfig'],
+      includePayload: true,
+    },
+  },
+});
+```
+
+| Entity          | Actions it can publish       |
+| --------------- | ---------------------------- |
+| `file_manager`  | CRUD + `uploaded`, `removed` |
+| `folder`        | CRUD                         |
+| `storageConfig` | CRUD                         |
+
+Uploads and removals report provider keys in `payload.ids`, with `location`,
+`storageConfigId`, `totalSize` and `count` in `payload.metadata`.
+
+#### form-builder
+
+```typescript
+import { FORM_BUILDER_EVENT_ACTIONS } from '@flusys/nestjs-form-builder/config';
+
+FormBuilderModule.forRoot({
+  config: {
+    ...dbConfig,
+    events: {
+      enabled: true,
+      actions: [FORM_BUILDER_EVENT_ACTIONS.SUBMITTED],
+      entities: ['form_result'],
+      excludeEntities: [],
+      includePayload: false,
+    },
+  },
+});
+```
+
+| Entity        | Actions it can publish            |
+| ------------- | --------------------------------- |
+| `form`        | CRUD                              |
+| `form_result` | CRUD + `submitted`, `draft-saved` |
+
+Submissions carry `formId`, `isDraft` and `schemaVersion` in `payload.metadata`, so an
+audit consumer can work with `includePayload: false` and never see answer data.
+
+#### email
+
+```typescript
+import { EMAIL_EVENT_ACTIONS, EMAIL_EVENT_ENTITIES } from '@flusys/nestjs-email/config';
+
+EmailModule.forRoot({
+  config: {
+    ...dbConfig,
+    events: {
+      enabled: true,
+      actions: [EMAIL_EVENT_ACTIONS.SENT, EMAIL_EVENT_ACTIONS.FAILED],
+      entities: [EMAIL_EVENT_ENTITIES.MESSAGE],
+      excludeEntities: ['emailConfig'],
+      includePayload: false,
+    },
+  },
+});
+```
+
+| Entity          | Actions it can publish |
+| --------------- | ---------------------- |
+| `emailConfig`   | CRUD                   |
+| `emailTemplate` | CRUD                   |
+| `email_message` | `sent`, `failed`       |
+
+#### event-manager
+
+```typescript
+import { EVENT_MANAGER_EVENT_ACTIONS } from '@flusys/nestjs-event-manager/config';
+
+EventManagerModule.forRoot({
+  config: {
+    ...dbConfig,
+    events: {
+      enabled: true,
+      actions: [EventAction.CREATED, EVENT_MANAGER_EVENT_ACTIONS.PARTICIPANT_STATUS_CHANGED],
+      entities: ['event'],
+      excludeEntities: [],
+      includePayload: true,
+    },
+  },
+});
+```
+
+| Entity  | Actions it can publish              |
+| ------- | ----------------------------------- |
+| `event` | CRUD + `participant-status-changed` |
+
+The participant event is keyed by the **event** id, with `participantId`,
+`participantUserId` and `status` in `payload.metadata`.
+
+#### notification
+
+```typescript
+import {
+  NOTIFICATION_EVENT_ACTIONS,
+  NOTIFICATION_EVENT_ENTITIES,
+} from '@flusys/nestjs-notification/config';
+
+NotificationModule.forRoot({
+  config: {
+    ...dbConfig,
+    enableRealtime: true,
+    events: {
+      enabled: true,
+      actions: [NOTIFICATION_EVENT_ACTIONS.SENT, NOTIFICATION_EVENT_ACTIONS.READ],
+      entities: [NOTIFICATION_EVENT_ENTITIES.NOTIFICATION],
+      excludeEntities: [],
+      includePayload: false,
+    },
+  },
+});
+```
+
+| Entity         | Actions it can publish            |
+| -------------- | --------------------------------- |
+| `notification` | CRUD + `sent`, `read`, `all-read` |
+
+Subscribing to `notification.**` while the notification module itself reacts to other
+modules' events is the usual way to fan a domain event out to users.
+
+#### localization
+
+```typescript
+import { LOCALIZATION_EVENT_ACTIONS } from '@flusys/nestjs-localization/config';
+
+LocalizationModule.forRoot({
+  config: {
+    ...dbConfig,
+    defaultLanguageCode: 'en',
+    events: {
+      enabled: true,
+      actions: [LOCALIZATION_EVENT_ACTIONS.BULK_UPDATED],
+      entities: ['translation'],
+      excludeEntities: ['translationKey'],
+      includePayload: false,
+    },
+  },
+});
+```
+
+| Entity           | Actions it can publish |
+| ---------------- | ---------------------- |
+| `language`       | CRUD                   |
+| `translationKey` | CRUD                   |
+| `translation`    | CRUD + `bulk-updated`  |
+
+`bulk-updated` carries every written id plus `count` in `payload.metadata`, and is not
+published when there was nothing to write - useful for cache busting a translation CDN.
+
+#### task-manager
+
+```typescript
+import { TASK_MANAGER_EVENT_ACTIONS } from '@flusys/nestjs-task-manager/config';
+
+TaskManagerModule.forRoot({
+  config: {
+    ...dbConfig,
+    events: {
+      enabled: true,
+      actions: [TASK_MANAGER_EVENT_ACTIONS.MOVED, TASK_MANAGER_EVENT_ACTIONS.ASSIGNED],
+      entities: ['task', 'task_list'],
+      excludeEntities: ['task_comment'],
+      includePayload: true,
+    },
+  },
+});
+```
+
+| Entity                                     | Actions it can publish     |
+| ------------------------------------------ | -------------------------- |
+| `task`                                     | CRUD + `moved`, `assigned` |
+| `task_list`                                | CRUD + `reordered`         |
+| `task_board`, `task_label`, `task_comment` | CRUD                       |
+
+`moved` carries `fromListId`/`toListId`; `assigned` carries the assignee ids. Domain
+events carry a `payload.metadata` descriptor that is attached even when `includePayload`
+is off.
+
+### Publishing your own
+
+```typescript
+import { publishDomainEvent } from '@flusys/nestjs-shared/classes';
+
+await publishDomainEvent({
+  module: 'billing',
+  entity: 'invoice',
+  action: 'settled',
+  ids: [invoice.id],
+  metadata: { amount: invoice.total },
+  user,
+});
+```
+
+Inside a service that already extends `ApiService`, call
+`this.publishDomainAction(action, { ... })` - it fills in the module and entity for you.
+
+### Consuming
+
+```typescript
+import { OnDomainEvent } from '@flusys/nestjs-shared/decorators';
+import { DomainEvent } from '@flusys/nestjs-shared/interfaces';
+
+@Injectable()
+export class AuditConsumer {
+  @OnDomainEvent('storage.*.created', 'auth.appuser.deleted')
+  async handle(event: DomainEvent) {
+    // event.payload.ids / .data / .metadata, event.actor, event.action
+  }
+}
+```
+
+`DomainEvent` is the standard envelope shape - it covers both CRUD lifecycle and domain
+actions, so one type fits every handler. `*` matches exactly one segment; `**` (or `#`)
+matches the rest. Handlers are discovered at bootstrap on any singleton provider or
+controller registered with Nest - a REQUEST-scoped provider has no instance at that point,
+so put consumers on singletons. Injecting `EVENT_BUS_INSTANCE` gives direct
+`publish` / `subscribe` access - mark it `@Optional()`, so the service still resolves in an
+app that never registers `EventBusModule`.
+
 ## License
 
 MIT © FLUSYS

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

@@ -13,8 +13,10 @@ const _typeorm = require("typeorm");
 const _constants = require("../constants");
 const _logactiondecorator = require("../decorators/log-action.decorator");
 const _dtos = require("../dtos");
+const _eventactionenum = require("../enums/event-action.enum");
 const _interfaces = require("../interfaces");
 const _utilsservice = require("../modules/utils/utils.service");
+const _domaineventpublisher = require("./domain-event.publisher");
 const _hybridcacheclass = require("./hybrid-cache.class");
 function _define_property(obj, key, value) {
     if (key in obj) {
@@ -38,6 +40,18 @@ function _ts_decorate(decorators, target, key, desc) {
 function _ts_metadata(k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
+const DEFAULT_EVENT_MODULE = 'app';
+const OPERATION_EVENT_ACTIONS = {
+    insert: _eventactionenum.EventAction.CREATED,
+    insertMany: _eventactionenum.EventAction.CREATED,
+    update: _eventactionenum.EventAction.UPDATED,
+    updateMany: _eventactionenum.EventAction.UPDATED,
+    bulkUpsert: _eventactionenum.EventAction.UPDATED
+};
+const DELETE_EVENT_ACTIONS = {
+    delete: _eventactionenum.EventAction.DELETED,
+    restore: _eventactionenum.EventAction.RESTORED
+};
 let ApiService = class ApiService {
     resolveEntity() {
         return this._entity;
@@ -74,7 +88,7 @@ let ApiService = class ApiService {
                 saved,
                 returnFirst: true
             };
-        });
+        }, user);
     }
     async insertMany(dtos, user) {
         return this.executeInTransaction('insertMany', async (qr)=>{
@@ -86,7 +100,7 @@ let ApiService = class ApiService {
                 saved,
                 returnFirst: false
             };
-        });
+        }, user);
     }
     async update(dto, user) {
         return this.executeInTransaction('update', async (qr)=>{
@@ -98,7 +112,7 @@ let ApiService = class ApiService {
                 saved,
                 returnFirst: true
             };
-        });
+        }, user);
     }
     async updateMany(dtos, user) {
         return this.executeInTransaction('updateMany', async (qr)=>{
@@ -110,17 +124,22 @@ let ApiService = 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: _eventactionenum.EventAction.CREATED,
+                    entities: this.ensureArray(insertedSaved)
+                });
             }
             if (toUpdate.length > 0) {
                 await this.beforeUpdateOperation(toUpdate, user, qr);
@@ -128,12 +147,17 @@ let ApiService = 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: _eventactionenum.EventAction.UPDATED,
+                    entities: this.ensureArray(updatedSaved)
+                });
             }
             return {
                 saved: allResults,
-                returnFirst: false
+                returnFirst: false,
+                eventGroups
             };
-        });
+        }, user);
     }
     async findByIds(ids, user, select) {
         await this.ensureDataSourceRepository();
@@ -335,6 +359,13 @@ let ApiService = class ApiService {
                 this.clearCacheForAll(),
                 this.clearCacheForId(ids)
             ]);
+            await this.publishLifecycleEvents([
+                {
+                    action: DELETE_EVENT_ACTIONS[option.type] ?? _eventactionenum.EventAction.PURGED,
+                    entities: ids,
+                    idsOnly: true
+                }
+            ], user);
             return null;
         } catch (error) {
             await queryRunner.rollbackTransaction();
@@ -343,6 +374,32 @@ let ApiService = class ApiService {
             await queryRunner.release();
         }
     }
+    async publishLifecycleEvents(groups, user) {
+        for (const group of groups){
+            if (!group.entities.length) continue;
+            await (0, _domaineventpublisher.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 (0, _domaineventpublisher.publishDomainEvent)({
+            ...input,
+            module: this.moduleName ?? DEFAULT_EVENT_MODULE,
+            entity: this.entityName,
+            action
+        });
+    }
     async clearCacheForAll() {
         await this.utilsService.clearCache(this.entityName, this.cacheManager);
     }
@@ -363,13 +420,13 @@ let ApiService = 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) {
@@ -378,6 +435,12 @@ let ApiService = 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);
             }