Question 1

What is hierarchical-approval?

Accepted Answer

hierarchical-approval is a TypeScript-first npm library that provides a complete approval workflow engine for ERP and enterprise systems. It handles multi-level sequential and parallel approval chains, conditional routing, optimistic locking, idempotency, immutable audit trails, SLA tracking, escalation, and delegation — without requiring BPMN, external orchestrators, or hand-rolled logic.

Question 2

Does hierarchical-approval support PostgreSQL?

Accepted Answer

Yes. The library ships a production-ready PostgresAdapter as a peer dependency. Call adapter.migrate() once to set up the schema. It also includes a MemoryAdapter for development and zero-I/O testing.

Question 3

How does optimistic locking work in hierarchical-approval?

Accepted Answer

Every ApprovalInstance carries a version counter. The storage adapter's updateInstance() method checks the stored version against the expected version before writing. If they differ (meaning another process modified the instance concurrently), it throws an ApprovalConflictError. The engine retries automatically up to maxAttempts times (default 3) with linear backoff (baseDelayMs times the attempt number) plus random jitter, which is on by default.

Question 4

Can I use hierarchical-approval without a real database in tests?

Accepted Answer

Yes. The ApprovalTestKit utility creates a pre-wired engine with MemoryAdapter and ManualClock. ManualClock.advanceDays(n) lets you test SLA breaches and escalation scheduling without real timers. ApprovalTestKit.fullyApprove() drives an instance through all levels in one call.

Question 5

Does hierarchical-approval ship built-in audit, metrics, and notification plug-ins?

Accepted Answer

Yes. The library ships seven production-grade plug-ins on dedicated import subpaths, each with zero runtime dependencies and fully tree-shakeable. plugins/audit provides a tamper-evident SHA-256 hash-chained audit adapter with a verify() method (detecting edits, deletions, reordering, and tail truncation) plus PII redaction. plugins/metrics provides a Prometheus scrape adapter and an in-memory snapshot adapter with p50/p95. plugins/resilience provides an RBAC default-deny authorization policy, token-bucket rate limiting, and structured logging middleware. plugins/notify provides a reliable outbox notification adapter with retry, exponential backoff, and a dead-letter queue for at-least-once delivery. plugins/tracing provides OpenTelemetry-shaped spans per approval operation without taking an OpenTelemetry dependency. plugins/webhook delivers lifecycle events over HTTP with HMAC-SHA256 request signing, jittered retry and Retry-After handling. plugins/scheduler lets escalation and SLA deadlines run on your own job runner (BullMQ, Temporal, cron) instead of an in-process timer.

Question 6

What approval modes does hierarchical-approval support?

Accepted Answer

Each approval level has a mode field: "any" (one approver is sufficient), "all" (every listed approver must act), or "majority" (more than half must approve). Modes are configured per-level in the template.

See an approval chain react — live.

This is a visual demo. Want the actual library?