@rytass/wms-module-graphql 0.4.0 → 0.6.0

package/README.md

@@ -88,6 +88,57 @@ The member-base adapter reuses everything `CasbinGuard` already put on the reque
 
 ➡️ **Full design & recipes: [`docs/authorization.md`](./docs/authorization.md)** (the problem, execution order, member-base / custom-JWT / no-guard recipes, the single coupling point, public API, FAQ).
 
+## Events & Hooks
+
+Intervene in and get notified about mutations. Every root mutation carries a typed **operation event** (`material.created`, `ship-inventory-order.shipped`, …) and fans out **stock domain events** (`stock.allocated`, `stock.shipped`, …) driven by the `ChangeType` state machine. Wire two opt-in hook points via `forRootAsync`:
+
+- **`beforeHooks`** run before any DB work — **throw to veto** the mutation (zero side effects).
+- **`afterListeners`** run **after the outermost transaction commits** — never notified about rolled-back changes.
+
+```ts
+import { memberBaseActorExtractor } from '@rytass/wms-module-graphql/adapters/member-base';
+
+WmsModuleGraphqlModule.forRootAsync({
+  ...coreOptions,
+
+  // (v2) populate payload.actor on every event — reads req.payload → { id, domain }
+  actorExtractor: memberBaseActorExtractor,
+
+  // (v2) append materialId/batchId/locationId/loaderId to stock event payloads
+  enrichStockEvents: true,
+
+  beforeHooks: {
+    'ship-inventory-order.shipped': async ({ args, actor }) => {
+      if (!allowed(args, actor)) throw new ForbiddenException('blocked');
+    },
+  },
+  afterListeners: {
+    // v2: payload.args carries items[]; payload.actor carries { id, domain }
+    'ship-inventory-order.shipped': async ({ payload }) => {
+      await erp.markShipped(payload.id, payload.result, payload.actor);
+    },
+    // v2 with enrichStockEvents: materialId/batchId/locationId/loaderId also available
+    'stock.allocated': async ({ payload }) => { await erp.reserve(payload); },
+  },
+});
+```
+
+**v2 payload enrichment** (upcoming minor — `core@0.3.0` / `graphql@0.6.0`):
+
+- Operation events gain `args` (the GraphQL input that triggered the mutation) and `actor`
+  (`WmsActor | null`). Nine action mutations return `boolean`; their real information is in
+  `args` and the stock events they fan out.
+- Stock events gain opt-in `materialId / batchId / locationId / loaderId` when
+  `enrichStockEvents: true` is set. **Caveat**: split / merge / reclassify order-items have
+  no `materialId` / `batchId` at the item level — only `locationId` / `loaderId` are
+  available for those three domains even with eager enrichment.
+- `WmsOperationResultMap` provides a per-event typed overlay so subscribers receive the
+  concrete DTO (`MaterialDto`, `ShipInventoryOrderDto`, …) instead of `unknown`.
+
+Post-commit delivery is guaranteed by an `AsyncLocalStorage` dispatch scope (events buffer during the request and flush only after commit). Prefer `@OnEvent`? Opt into the optional [`@nestjs/event-emitter`](https://docs.nestjs.com/techniques/events) bridge from `@rytass/wms-module-graphql/adapters/event-emitter` — every event also emits as `wms.<event>`. Nothing configured ⇒ no events, zero overhead.
+
+➡️ **Full design, the complete 56-event list & limitations: [`docs/events.md`](./docs/events.md)**.
+
 ## DataLoader context
 
 The module ships a `HelperModule` (auto-registered) that provides a singleton `LoaderService`. To avoid N+1 queries, the WMS resolvers expect a per-request DataLoader trio at `context.loaders`:
@@ -124,14 +175,16 @@ Full documentation is shipped inside this package under the `docs/` directory (a
 |---|---|
 | [`docs/integration-guide.md`](./docs/integration-guide.md) | Step-by-step wiring guide for NestJS + Next.js consumers |
 | [`docs/authorization.md`](./docs/authorization.md) | Complete resolver-authorization design & integration recipes (member-base / custom JWT / no-guard) |
+| [`docs/events.md`](./docs/events.md) | Mutation event/hook system — before-hooks (veto), post-commit after-listeners, complete event list, event-emitter bridge |
 | [`docs/api-reference.md`](./docs/api-reference.md) | Complete export catalog with signatures and usage examples |
 
 GitHub hosted links (always up-to-date):
 
-- [Integration Guide — §4 Backend setup](https://github.com/Rytass/WMS-Module/blob/main/docs/integration-guide.md#4-backend-setup-nestjs--graphql--typeorm)
-- [Integration Guide — §13.1 Existing GraphQLModule co-existence](https://github.com/Rytass/WMS-Module/blob/main/docs/integration-guide.md#13-integrating-into-an-existing-nestjs--nextjs-project)
+- [Integration Guide — §4 Backend setup](https://github.com/Rytass/WMS-Module/blob/main/libs/graphql/docs/integration-guide.md#4-backend-setup-nestjs--graphql--typeorm)
+- [Integration Guide — §13.1 Existing GraphQLModule co-existence](https://github.com/Rytass/WMS-Module/blob/main/libs/graphql/docs/integration-guide.md#13-integrating-into-an-existing-nestjs--nextjs-project)
 - [Authorization — design & recipes](https://github.com/Rytass/WMS-Module/blob/main/libs/graphql/docs/authorization.md)
-- [API Reference — @rytass/wms-module-graphql](https://github.com/Rytass/WMS-Module/blob/main/docs/api-reference.md#rytasswms-module-graphql)
+- [Events & Hooks — design & event list](https://github.com/Rytass/WMS-Module/blob/main/libs/graphql/docs/events.md)
+- [API Reference — @rytass/wms-module-graphql](https://github.com/Rytass/WMS-Module/blob/main/libs/graphql/docs/api-reference.md#rytasswms-module-graphql)
 
 ## License
 

package/adapters/event-emitter.d.ts

@@ -0,0 +1,29 @@
+import type { Provider } from '@nestjs/common';
+/**
+ * Bridges WMS domain events onto `@nestjs/event-emitter`'s `EventEmitter2`, so
+ * consumers can subscribe with `@OnEvent('wms.<event-name>')` instead of (or in
+ * addition to) the typed `afterListeners`.
+ *
+ * Pass this into `WmsModuleGraphqlModule.forRootAsync({ eventEmitterBridge })`.
+ * Importing this module is the only place `@nestjs/event-emitter` is referenced,
+ * keeping it an entirely optional peer dependency — the core graphql module
+ * never imports it.
+ *
+ * Prerequisite: register `EventEmitterModule.forRoot()` in your app so an
+ * `EventEmitter2` instance is available for injection.
+ *
+ * @example
+ * ```ts
+ * import { wmsEventEmitterBridgeProvider } from '@rytass/wms-module-graphql/adapters/event-emitter';
+ *
+ * WmsModuleGraphqlModule.forRootAsync({
+ *   ...coreOptions,
+ *   eventEmitterBridge: wmsEventEmitterBridgeProvider,
+ * });
+ *
+ * // elsewhere
+ * @OnEvent('wms.stock.allocated')
+ * handle(payload: WmsStockEventPayload) { ... }
+ * ```
+ */
+export declare const wmsEventEmitterBridgeProvider: Provider;

package/adapters/event-emitter.js

@@ -0,0 +1,41 @@
+import { EventEmitter2 } from '@nestjs/event-emitter';
+import { WMS_EVENT_EMITTER_BRIDGE } from '@rytass/wms-module-core';
+
+/**
+ * Bridges WMS domain events onto `@nestjs/event-emitter`'s `EventEmitter2`, so
+ * consumers can subscribe with `@OnEvent('wms.<event-name>')` instead of (or in
+ * addition to) the typed `afterListeners`.
+ *
+ * Pass this into `WmsModuleGraphqlModule.forRootAsync({ eventEmitterBridge })`.
+ * Importing this module is the only place `@nestjs/event-emitter` is referenced,
+ * keeping it an entirely optional peer dependency — the core graphql module
+ * never imports it.
+ *
+ * Prerequisite: register `EventEmitterModule.forRoot()` in your app so an
+ * `EventEmitter2` instance is available for injection.
+ *
+ * @example
+ * ```ts
+ * import { wmsEventEmitterBridgeProvider } from '@rytass/wms-module-graphql/adapters/event-emitter';
+ *
+ * WmsModuleGraphqlModule.forRootAsync({
+ *   ...coreOptions,
+ *   eventEmitterBridge: wmsEventEmitterBridgeProvider,
+ * });
+ *
+ * // elsewhere
+ * @OnEvent('wms.stock.allocated')
+ * handle(payload: WmsStockEventPayload) { ... }
+ * ```
+ */
+const wmsEventEmitterBridgeProvider = {
+    provide: WMS_EVENT_EMITTER_BRIDGE,
+    useFactory: (emitter) => ({
+        forward: (event) => {
+            emitter.emit(`wms.${event.name}`, event.payload);
+        },
+    }),
+    inject: [EventEmitter2],
+};
+
+export { wmsEventEmitterBridgeProvider };

package/adapters/member-base.d.ts

@@ -1,3 +1,4 @@
+import type { WmsActorExtractor } from '@rytass/wms-module-core';
 import type { WmsAuthChecker, WmsOperationRequirement } from '../lib/auth';
 /**
  * A Casbin `[subject, action]` tuple, e.g. `['wms:material', 'read']`.
@@ -33,3 +34,13 @@ export interface MemberBaseWmsAuthCheckerOptions {
  * (Apollo's default).
  */
 export declare const createMemberBaseWmsAuthChecker: (options: MemberBaseWmsAuthCheckerOptions) => WmsAuthChecker;
+/**
+ * A {@link WmsActorExtractor} for `@rytass/member-base-nestjs-module`. Reads the
+ * verified JWT payload that `CasbinGuard` attaches to the request and surfaces it
+ * as the event/hook `actor`. Returns `null` for unauthenticated requests.
+ *
+ * Pass to `WmsModuleGraphqlModule.forRootAsync({ actorExtractor })` so every
+ * operation event and before-hook carries `{ id, domain }`. Imports nothing from
+ * member-base — it only reads the runtime request fields.
+ */
+export declare const memberBaseActorExtractor: WmsActorExtractor;

package/adapters/member-base.js

@@ -43,5 +43,21 @@ const createMemberBaseWmsAuthChecker = (options) => {
         });
     };
 };
+/**
+ * A {@link WmsActorExtractor} for `@rytass/member-base-nestjs-module`. Reads the
+ * verified JWT payload that `CasbinGuard` attaches to the request and surfaces it
+ * as the event/hook `actor`. Returns `null` for unauthenticated requests.
+ *
+ * Pass to `WmsModuleGraphqlModule.forRootAsync({ actorExtractor })` so every
+ * operation event and before-hook carries `{ id, domain }`. Imports nothing from
+ * member-base — it only reads the runtime request fields.
+ */
+const memberBaseActorExtractor = (context) => {
+    const payload = extractRequest(context)?.payload;
+    if (!payload?.id) {
+        return null;
+    }
+    return { id: payload.id, domain: payload.domain, raw: payload };
+};
 
-export { createMemberBaseWmsAuthChecker };
+export { createMemberBaseWmsAuthChecker, memberBaseActorExtractor };

package/docs/README.md

@@ -8,6 +8,7 @@ Reference material for consumers of `@rytass/wms-module-{core,graphql,react}`.
 |------------------------------------------------|---------------------------------------------------------------------------------------------------|
 | [Integration Guide](./integration-guide.md)    | Step-by-step instructions for wiring the three packages into a new consumer project (NestJS + Next.js + PostgreSQL). Includes ready-to-paste `_app.tsx`, `app.module.ts`, `next.config.ts`, the 19 Pages Router shell pattern, AuthGuard stub, seed script template, deployment notes, and known issues. |
 | [Authorization](./authorization.md)            | Complete design of the resolver-level authorization protocol (`@WmsOperation` + `WmsAuthGuard` + `authChecker`). Explains the global deny-by-default guard pitfall, execution order, and integration recipes for member-base / Casbin, custom JWT / RBAC, and no-guard setups. Read this if any WMS query/mutation returns *forbidden*. |
+| [Events & Hooks](./events.md)                  | The mutation event/hook system — `beforeHooks` (veto before any DB work) and `afterListeners` (post-commit notify), the `AsyncLocalStorage` post-commit mechanism, the optional `@nestjs/event-emitter` bridge, and the complete list of 38 operation + 18 stock domain events with payloads. |
 | [API Reference](./api-reference.md)            | Complete export catalog for all three packages — every NestJS module, TypeORM entity, GraphQL resolver, DTO, React component, hook, and utility, organized by role with source paths and usage examples. Mirrors the actual `src/index.ts` barrel exports of `@rytass/wms-module-graphql@0.3.0` and `@rytass/wms-module-{core,react}@0.1.6`. |
 
 ## Quick links
@@ -26,6 +27,8 @@ Reference material for consumers of `@rytass/wms-module-{core,graphql,react}`.
 | Replace the `AuthGuard` stub with real auth             | [Integration Guide section 8.4](./integration-guide.md#84-real-auth-integration) |
 | Authorize WMS resolvers with member-base / Casbin / RBAC | [Authorization](./authorization.md)                                   |
 | Fix "every WMS query/mutation is forbidden"             | [Authorization section 1](./authorization.md#1-the-problem)            |
+| Hook into / get notified about mutations                | [Events & Hooks](./events.md)                                          |
+| See every event the system emits                        | [Events & Hooks section 5](./events.md#5-complete-event-list)          |
 | Decide between PostgreSQL and SQLite                    | [Integration Guide section 9](./integration-guide.md#9-database-support-matrix) |
 | Build a custom UI on top of the lib's GraphQL operations| [Integration Guide section 7.3](./integration-guide.md#73-graphql-operations--typed-hooks) |
 

package/docs/api-reference.md

@@ -449,6 +449,66 @@ The adapter imports nothing from member-base — it reads the `payload` / `enfor
 
 ---
 
+## Events & Hooks
+
+Opt-in `beforeHooks` (veto) and post-commit `afterListeners` for every mutation. Each root mutation carries `@WmsMutationEvent({ event })` (already applied); a per-mutation interceptor runs the before-hook, opens an `AsyncLocalStorage` dispatch scope, and flushes collected events after the transaction commits. Stock domain events are collected centrally by a TypeORM subscriber on `*_order_change` inserts. Full design & the complete event list: [`docs/events.md`](./events.md).
+
+### Root exports (`@rytass/wms-module-graphql`, re-exported from `@rytass/wms-module-core`)
+
+| Export                                                          | Kind      | Signature / shape                                                                                                                |
+|-----------------------------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------|
+| `WmsMutationEvent`                                              | decorator | `({ event: WmsOperationEventName, resolveId? }) => MethodDecorator`                                                              |
+| `WmsEventModuleOptions`                                         | type      | `{ beforeHooks?, afterListeners?, actorExtractor?, enrichStockEvents? }` — part of `forRootAsync` options                        |
+| `WmsBeforeHookMap`                                              | type      | `{ [N in WmsEventName]?: (ctx: WmsBeforeHookContext<N>) => void \| Promise<void> }`                                              |
+| `WmsAfterListenerMap`                                           | type      | `{ [N in WmsEventName]?: (ctx: WmsAfterEventContext<N>) => void \| Promise<void> }`                                              |
+| `WmsBeforeHookContext`                                          | type      | `{ event; args: Record<string, unknown>; executionContext: ExecutionContext; actor: WmsActor \| null }` (v2 adds `actor`)         |
+| `WmsAfterEventContext`                                          | type      | `{ event; payload: WmsEventPayloadMap[event] }`                                                                                  |
+| `WmsDomainEvent`                                                | type      | `{ name: WmsEventName; payload }`                                                                                                |
+| `WmsEventName` / `WmsOperationEventName` / `WmsStockEventName`  | type      | event-name unions (38 operation + 18 stock)                                                                                      |
+| `WmsEventPayloadMap`                                            | type      | event name → payload                                                                                                             |
+| `WmsOperationEventPayload`                                      | type      | v1: `{ id: string \| null; result: unknown }` — v2: `{ id; result; args: Readonly<Record<string, unknown>>; actor: WmsActor \| null }` |
+| `WmsStockEventPayload`                                          | type      | `{ orderId; itemId; quantityDelta; changeType: ChangeType \| null; inspectionResult? }` — v2 adds optional `materialId?`, `batchId?`, `locationId?`, `loaderId?` when `enrichStockEvents: true` |
+| `WmsActor`                                                      | type      | `{ readonly id: string; readonly domain?: string; readonly raw?: unknown }` — actor identity (v2)                                |
+| `WmsActorExtractor`                                             | type      | `(context: ExecutionContext) => WmsActor \| null` — injectable extractor (v2); token `WMS_ACTOR_EXTRACTOR`                       |
+| `WmsOperationResultMap`                                         | type      | Maps each `WmsOperationEventName` to its concrete `result` DTO (e.g. `'material.created' → MaterialDto`); powers typed listeners (v2) |
+
+### Adapter subpath (`@rytass/wms-module-graphql/adapters/event-emitter`)
+
+| Export                        | Kind       | Purpose                                                                                                                                  |
+|-------------------------------|------------|------------------------------------------------------------------------------------------------------------------------------------------|
+| `wmsEventEmitterBridgeProvider` | `Provider` | Pass to `forRootAsync({ eventEmitterBridge })`; fans every event onto `EventEmitter2` as `wms.<event>` for `@OnEvent`. Requires `@nestjs/event-emitter` (optional peer) + `EventEmitterModule.forRoot()`. |
+
+### Adapter subpath (`@rytass/wms-module-graphql/adapters/member-base`) — event extras (v2)
+
+| Export                      | Kind      | Purpose                                                                                                                             |
+|-----------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------|
+| `memberBaseActorExtractor`  | extractor | `WmsActorExtractor` that reads `GqlExecutionContext.create(ctx).getContext().req?.payload` → `{ id, domain }`. Pass to `forRootAsync({ actorExtractor })`. |
+
+```ts
+import { memberBaseActorExtractor } from '@rytass/wms-module-graphql/adapters/member-base';
+import { wmsEventEmitterBridgeProvider } from '@rytass/wms-module-graphql/adapters/event-emitter';
+
+WmsModuleGraphqlModule.forRootAsync({
+  ...coreOptions,
+  actorExtractor: memberBaseActorExtractor,   // v2: populates payload.actor
+  enrichStockEvents: true,                    // v2: appends ids to stock payloads
+  beforeHooks: {
+    'ship-inventory-order.shipped': async ({ args, actor }) => {
+      if (!ok(args, actor)) throw new ForbiddenException();
+    },
+  },
+  afterListeners: {
+    'stock.allocated': async ({ payload }) => { await sync(payload); },
+  },
+  // optional @OnEvent bridge:
+  // eventEmitterBridge: wmsEventEmitterBridgeProvider,
+});
+```
+
+`beforeHooks` / `afterListeners` are **not** part of the GraphQL schema — they are runtime hooks. With none configured the interceptor passes through with zero overhead. All v2 options (`actorExtractor`, `enrichStockEvents`) are fully optional; omitting them preserves the v1 behaviour exactly.
+
+---
+
 ## Resolvers（`@Resolver()` decorator class）
 
 以下 Resolver 類別處理 GraphQL `@ResolveField`，解析關聯欄位（防止 N+1）：