hierarchical-approval 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -7,6 +7,41 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 _Nothing yet._
 
+## [1.3.0] - 2026-09-04
+
+### Added — out-of-office cover
+
+- **`outOfOfficeProvider` swaps absent approvers for their stand-in.** An
+  approver on leave stalled the chain until somebody noticed and reassigned by
+  hand; `delegate()` needed the absent person to initiate it, and `reassign()`
+  needed an administrator to spot the problem first.
+
+  ```ts
+  new ApprovalEngine({
+    adapter,
+    outOfOfficeProvider: {
+      getDelegateFor: async (userId, at) => hr.coverFor(userId, at), // null when available
+    },
+  });
+  ```
+
+  Applied wherever approvers are resolved — at submit, when a level activates,
+  on escalation, and in `previewApprovalChain()`, so a preview cannot disagree
+  with what `submit()` goes on to do.
+
+  Kept as an injected provider rather than engine-owned state because absence
+  lives in the HR or directory system that already tracks leave; storing it here
+  too would guarantee the two disagree. The resolution time is passed to the
+  provider, so cover can be date-bound.
+
+- **Substitution is transitive but bounded.** An A→B→C chain of absences lands
+  on whoever is actually present, up to five hops. A cover *cycle* (A covers B
+  while B covers A) stops and leaves the original approver assigned — visible and
+  fixable, unlike a hang. A provider that throws is treated as "no cover known",
+  because an HR lookup failing must not stop an approval being routed at all.
+
+  New export: `OutOfOfficeProvider`.
+
 ## [1.2.0] - 2026-09-04
 
 ### Added — template inheritance

package/README.md

@@ -399,6 +399,33 @@ engine.registerConditionOperator('between', (actual, expected) => {
 });
 ```
 
+### Out-of-office cover
+
+Approvers go on leave, and a chain that waits on an absent person stalls.
+Configure a provider and absent approvers are swapped for their stand-in
+wherever approvers are resolved — at submit, when a level activates, on
+escalation, and in `previewApprovalChain()`:
+
+```ts
+const engine = new ApprovalEngine({
+  adapter,
+  outOfOfficeProvider: {
+    // Return the stand-in, or null when the approver is available.
+    getDelegateFor: async (userId, at) => hr.coverFor(userId, at),
+  },
+});
+```
+
+Absence lives in the HR or directory system that already tracks leave, so this
+is an injected provider rather than engine-owned state — duplicating that data
+here would guarantee the two disagree. The resolution time is passed in, so
+cover can be date-bound.
+
+Substitution is transitive (A away → B, B away → C lands on C) up to five hops.
+A cover *cycle* stops rather than looping, and a provider that throws is treated
+as "no cover known" — an HR lookup failing must not stop an approval being
+routed at all.
+
 ### Template inheritance
 
 ERP tenants run many near-identical workflows — one per region, entity or

package/dist/{ApprovalEngine-CdtOJOsu.d.cts → ApprovalEngine-CfySjeuy.d.cts}

@@ -136,6 +136,23 @@ interface OrgProvider {
     /** Optional: resolve users matching a custom attribute/value pair. */
     getUsersByAttribute?(attr: string, value: unknown, tenantId?: string): Promise<string[]> | string[];
 }
+/**
+ * Supplies out-of-office cover so an approver on leave does not stall a chain.
+ *
+ * Consulted whenever a level's approvers are resolved — at submit, when a level
+ * activates, and when a chain is previewed. Kept as an injected provider rather
+ * than engine-owned state because absence lives in the HR or directory system
+ * that already knows about leave; duplicating it here would guarantee the two
+ * disagree.
+ */
+interface OutOfOfficeProvider {
+    /**
+     * @param userId - The approver about to be assigned.
+     * @param at - The moment cover is being resolved for.
+     * @returns The user to stand in, or null/undefined when the approver is available.
+     */
+    getDelegateFor(userId: string, at: Date): Promise<string | null | undefined> | string | null | undefined;
+}
 type ApproverResolverFn = (config: Record<string, unknown>, ctx: {
     submittedBy: string;
     data: Record<string, unknown>;
@@ -296,6 +313,11 @@ interface ApprovalEngineOptions {
     adapter: IStorageAdapter;
     tenantId?: string;
     orgProvider?: OrgProvider;
+    /**
+     * Supplies stand-ins for approvers who are away, so leave does not stall a
+     * chain. Consulted every time approvers are resolved.
+     */
+    outOfOfficeProvider?: OutOfOfficeProvider;
     logger?: Logger;
     escalationPollIntervalMs?: number;
     /** Maximum number of instances allowed in a single bulk operation. Default: 200. */
@@ -546,4 +568,4 @@ declare class ApprovalEngine {
     private runExternalAudit;
 }
 
-export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type UpdateDataOptions as U, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type BusinessCalendar as f, type CancelOptions as g, type ConditionOperatorFn as h, type CycleTimeStats as i, type IdempotencyKeyFn as j, type OverrideOptions as k, type PreviewResult as l, type RejectOptions as m, type ResubmitOptions as n, type RetryPolicy as o, defaultIdGenerator as p, toComparableNumber as t, validateConditionExpression as v, weekendCalendar as w };
+export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type UpdateDataOptions as U, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type BusinessCalendar as f, type CancelOptions as g, type ConditionOperatorFn as h, type CycleTimeStats as i, type IdempotencyKeyFn as j, type OutOfOfficeProvider as k, type OverrideOptions as l, type PreviewResult as m, type RejectOptions as n, type ResubmitOptions as o, type RetryPolicy as p, defaultIdGenerator as q, toComparableNumber as t, validateConditionExpression as v, weekendCalendar as w };

package/dist/{ApprovalEngine-DRC-o30z.d.ts → ApprovalEngine-Dhu5mlCG.d.ts}

@@ -136,6 +136,23 @@ interface OrgProvider {
     /** Optional: resolve users matching a custom attribute/value pair. */
     getUsersByAttribute?(attr: string, value: unknown, tenantId?: string): Promise<string[]> | string[];
 }
+/**
+ * Supplies out-of-office cover so an approver on leave does not stall a chain.
+ *
+ * Consulted whenever a level's approvers are resolved — at submit, when a level
+ * activates, and when a chain is previewed. Kept as an injected provider rather
+ * than engine-owned state because absence lives in the HR or directory system
+ * that already knows about leave; duplicating it here would guarantee the two
+ * disagree.
+ */
+interface OutOfOfficeProvider {
+    /**
+     * @param userId - The approver about to be assigned.
+     * @param at - The moment cover is being resolved for.
+     * @returns The user to stand in, or null/undefined when the approver is available.
+     */
+    getDelegateFor(userId: string, at: Date): Promise<string | null | undefined> | string | null | undefined;
+}
 type ApproverResolverFn = (config: Record<string, unknown>, ctx: {
     submittedBy: string;
     data: Record<string, unknown>;
@@ -296,6 +313,11 @@ interface ApprovalEngineOptions {
     adapter: IStorageAdapter;
     tenantId?: string;
     orgProvider?: OrgProvider;
+    /**
+     * Supplies stand-ins for approvers who are away, so leave does not stall a
+     * chain. Consulted every time approvers are resolved.
+     */
+    outOfOfficeProvider?: OutOfOfficeProvider;
     logger?: Logger;
     escalationPollIntervalMs?: number;
     /** Maximum number of instances allowed in a single bulk operation. Default: 200. */
@@ -546,4 +568,4 @@ declare class ApprovalEngine {
     private runExternalAudit;
 }
 
-export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type UpdateDataOptions as U, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type BusinessCalendar as f, type CancelOptions as g, type ConditionOperatorFn as h, type CycleTimeStats as i, type IdempotencyKeyFn as j, type OverrideOptions as k, type PreviewResult as l, type RejectOptions as m, type ResubmitOptions as n, type RetryPolicy as o, defaultIdGenerator as p, toComparableNumber as t, validateConditionExpression as v, weekendCalendar as w };
+export { type AddCommentOptions as A, type BulkResult as B, type CanApproveResult as C, type DelegateOptions as D, type EscalateOptions as E, type HealthResult as H, type IdGeneratorFn as I, type OrgProvider as O, type PreviewChainLevel as P, type ReassignOptions as R, type SubmitOptions as S, type UpdateDataOptions as U, type ValidationResult as V, type WeekendCalendarOptions as W, ApprovalEngine as a, type ApprovalEngineOptions as b, type ApprovalStatistics as c, type ApproveOptions as d, type ApproverResolverFn as e, type BusinessCalendar as f, type CancelOptions as g, type ConditionOperatorFn as h, type CycleTimeStats as i, type IdempotencyKeyFn as j, type OutOfOfficeProvider as k, type OverrideOptions as l, type PreviewResult as m, type RejectOptions as n, type ResubmitOptions as o, type RetryPolicy as p, defaultIdGenerator as q, toComparableNumber as t, validateConditionExpression as v, weekendCalendar as w };

package/dist/index.cjs

@@ -331,6 +331,7 @@ var TemplateRegistry = class {
 };
 
 // src/engine/LevelResolver.ts
+var MAX_OOO_HOPS = 5;
 var LevelResolver = class {
   constructor() {
     this.resolvers = /* @__PURE__ */ new Map();
@@ -342,7 +343,7 @@ var LevelResolver = class {
   registerApproverType(typeName, fn) {
     this.approverTypes.set(typeName, fn);
   }
-  async resolveApprovers(approvers, submittedBy, data, orgProvider) {
+  async resolveApprovers(approvers, submittedBy, data, orgProvider, outOfOffice, at) {
     const resolved = [];
     for (const approver of approvers) {
       switch (approver.type) {
@@ -362,7 +363,9 @@ var LevelResolver = class {
           break;
         }
         case "dynamic": {
-          const fn = this.resolvers.get(approver.resolver);
+          const fn = this.resolvers.get(
+            approver.resolver
+          );
           if (!fn) {
             throw new Error(
               `No resolver registered for "${approver.resolver}". Call engine.registerResolver("${approver.resolver}", fn) first.`
@@ -379,7 +382,11 @@ var LevelResolver = class {
               `Unknown approver type "${approver.type}". Register it with engine.registerApproverType("${approver.type}", fn) first.`
             );
           }
-          const ids = await customFn(approver, { submittedBy, data, orgProvider });
+          const ids = await customFn(approver, {
+            submittedBy,
+            data,
+            orgProvider
+          });
           resolved.push(...ids);
           break;
         }
@@ -391,7 +398,40 @@ var LevelResolver = class {
         "No approvers resolved for this level. Check your approver configuration \u2014 role may have no members or dynamic resolver returned empty."
       );
     }
-    return result;
+    return this.applyOutOfOffice(result, outOfOffice, at);
+  }
+  /**
+   * Replace approvers who are away with their cover.
+   *
+   * Substitution is transitive up to {@link MAX_OOO_HOPS} so an A→B→C chain of
+   * absences still lands on someone present, but a cycle (A covers B while B
+   * covers A) simply stops rather than looping — leaving the original approver
+   * assigned, which is visible and fixable, unlike a hang.
+   *
+   * A provider that throws is treated as "no cover known": an HR lookup failing
+   * must not block an approval from being routed at all.
+   */
+  async applyOutOfOffice(userIds, provider, at) {
+    if (!provider) return userIds;
+    const asOf = at ?? /* @__PURE__ */ new Date();
+    const covered = [];
+    for (const original of userIds) {
+      let current = original;
+      const seen = /* @__PURE__ */ new Set([current]);
+      for (let hop = 0; hop < MAX_OOO_HOPS; hop++) {
+        let delegate;
+        try {
+          delegate = await provider.getDelegateFor(current, asOf);
+        } catch {
+          break;
+        }
+        if (!delegate || delegate === current || seen.has(delegate)) break;
+        seen.add(delegate);
+        current = delegate;
+      }
+      covered.push(current);
+    }
+    return [...new Set(covered)];
   }
 };
 
@@ -1149,7 +1189,9 @@ var ApprovalEngine = class _ApprovalEngine {
         lvl.approverConfigs,
         opts.submittedBy,
         opts.data,
-        this.opts.orgProvider
+        this.opts.orgProvider,
+        this.opts.outOfOfficeProvider,
+        now
       );
     }
     const auditEntry = {
@@ -2152,7 +2194,9 @@ var ApprovalEngine = class _ApprovalEngine {
           cfg.approvers,
           submittedBy,
           data,
-          this.opts.orgProvider
+          this.opts.orgProvider,
+          this.opts.outOfOfficeProvider,
+          this.clock.now()
         );
         levels.push({ level: cfg.level, name: cfg.name, resolvedApprovers, mode: cfg.mode });
       } catch {
@@ -2531,7 +2575,9 @@ var ApprovalEngine = class _ApprovalEngine {
         [escalationConfig.escalateTo],
         instance.submittedBy,
         instance.data,
-        this.opts.orgProvider
+        this.opts.orgProvider,
+        this.opts.outOfOfficeProvider,
+        this.clock.now()
       );
       const filteredApprovers = newApprovers.filter((id) => id !== instance.submittedBy);
       if (filteredApprovers.length === 0) {
@@ -2816,7 +2862,9 @@ var ApprovalEngine = class _ApprovalEngine {
         lvl.approverConfigs,
         instance.submittedBy,
         instance.data,
-        this.opts.orgProvider
+        this.opts.orgProvider,
+        this.opts.outOfOfficeProvider,
+        now
       );
       if (lvl.escalationAfterDays) {
         lvl.escalationDueAt = this.deadlineFrom(now, lvl.escalationAfterDays);