hierarchical-approval 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -3,6 +3,33 @@
 All notable changes to `hierarchical-approval` are documented here. This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-07-23
+
+### Added — NestJS integration
+
+- **`hierarchical-approval/nestjs`** — first-class NestJS support on its own
+  tree-shakeable subpath. `@nestjs/common` is an **optional peer dependency**.
+  - `HierarchicalApprovalModule.forRoot(options)` and `.forRootAsync(asyncOptions)`
+    provide a configured `ApprovalEngine` under the `APPROVAL_ENGINE` token, with
+    an `isGlobal` flag and `imports`/`inject`/`useFactory` async wiring.
+  - `@InjectApprovalEngine()` decorator for injecting the engine into services.
+  - The module stops the engine's escalation scheduler on application shutdown
+    via `onModuleDestroy`.
+
+### Added — adoption & discoverability
+
+- `examples/playground/` — a StackBlitz-ready, in-browser runnable demo of a
+  purchase-order approval chain, plus "Try it live" (RunKit + StackBlitz) links
+  in the README.
+- Expanded npm `keywords` for problem-based search (approval-workflow,
+  maker-checker, four-eyes, delegation, escalation, …).
+
+### Fixed
+
+- Replaced the non-standard `peerDependenciesOptional` field with the correct
+  `peerDependenciesMeta`, so `pg` (and now `@nestjs/common`) are properly marked
+  optional and no longer emit install-time peer warnings.
+
 ## [0.4.0] - 2026-07-23
 
 ### Added — per-template analytics

package/README.md

@@ -11,7 +11,7 @@ Multi-tenant · audit-ready · fully pluggable · zero runtime dependencies you
 [![types](https://img.shields.io/npm/types/hierarchical-approval.svg?logo=typescript&logoColor=white&color=3178c6)](https://www.typescriptlang.org/)
 [![minzipped size](https://img.shields.io/bundlephobia/minzip/hierarchical-approval?color=44cc11)](https://bundlephobia.com/package/hierarchical-approval)
 [![license](https://img.shields.io/npm/l/hierarchical-approval.svg?color=blue)](./LICENSE)
-[![tests](https://img.shields.io/badge/tests-195%20passing-44cc11.svg?logo=vitest&logoColor=white)](./tests)
+[![tests](https://img.shields.io/badge/tests-404%20passing-44cc11.svg?logo=vitest&logoColor=white)](./tests)
 
 [**Documentation**](https://hierarchical-approval.matthewswong.com) ·
 [**npm**](https://www.npmjs.com/package/hierarchical-approval) ·
@@ -28,6 +28,11 @@ npm install pg @types/pg
 
 > 📖 Full docs & live guides: **[hierarchical-approval.matthewswong.com](https://hierarchical-approval.matthewswong.com)**
 
+### ▶️ Try it live (no install)
+
+- **[Run in your browser on RunKit →](https://npm.runkit.com/hierarchical-approval)** — `require('hierarchical-approval')` in an instant notebook.
+- **[Open the interactive playground on StackBlitz →](https://stackblitz.com/github/matthews-wong/hierarchical-approval/tree/main/examples/playground)** — a full purchase-order approval chain running in-browser.
+
 <details>
 <summary><strong>Table of contents</strong></summary>
 
@@ -1069,6 +1074,65 @@ Every operation is wrapped in a span named `approval.<operation>` (e.g. `approva
 
 ---
 
+## NestJS integration
+
+First-class NestJS support ships as the `hierarchical-approval/nestjs` subpath. `@nestjs/common` is an **optional peer dependency** — you only pull it in if you use this module.
+
+```ts
+import { Module } from '@nestjs/common';
+import { HierarchicalApprovalModule } from 'hierarchical-approval/nestjs';
+import { MemoryAdapter } from 'hierarchical-approval/adapters/memory';
+
+@Module({
+  imports: [
+    HierarchicalApprovalModule.forRoot({
+      adapter: new MemoryAdapter(),
+      isGlobal: true, // inject ApprovalEngine anywhere without re-importing
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+Inject the configured engine with the `@InjectApprovalEngine()` decorator:
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { ApprovalEngine } from 'hierarchical-approval';
+import { InjectApprovalEngine } from 'hierarchical-approval/nestjs';
+
+@Injectable()
+export class InvoiceService {
+  constructor(@InjectApprovalEngine() private readonly approvals: ApprovalEngine) {}
+
+  submit(invoiceId: string, amount: number) {
+    return this.approvals.submit({
+      templateName: 'Invoice',
+      documentId: invoiceId,
+      documentType: 'invoice',
+      submittedBy: 'system',
+      data: { amount },
+    });
+  }
+}
+```
+
+Configure asynchronously from your `ConfigService` (or any provider) with `forRootAsync`:
+
+```ts
+HierarchicalApprovalModule.forRootAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    adapter: new PostgresAdapter({ connectionString: config.get('DATABASE_URL') }),
+  }),
+});
+```
+
+The module registers the engine under the `APPROVAL_ENGINE` token and stops its escalation scheduler on application shutdown via `onModuleDestroy` (call `app.enableShutdownHooks()` to activate Nest's shutdown lifecycle).
+
+---
+
 ## Custom storage adapter
 
 Implement `IStorageAdapter` to use any database: