hierarchical-approval 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -7,6 +7,38 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 _Nothing yet._
 
+## [1.9.0] - 2026-09-04
+
+### Added — `getWorkload()`
+
+- **Reports who currently owes a decision, and how overdue they are.**
+  `getStatistics()` answers how the tenant is doing; nothing answered who is
+  holding it up — the question behind rebalancing a queue, spotting the approver
+  who has been on leave for a week, or deciding whom to `transferApprovals()` a
+  departing colleague's work to.
+
+  ```ts
+  await engine.getWorkload({ documentType: 'purchase_order' });
+  // [{ approverId: 'alice', pending: 12, instances: 11, overdue: 3, onHold: 1,
+  //    oldestPendingAt: …, oldestAgeMs: 604800000 }, …]
+  ```
+
+  Sorted busiest first. `pending` counts open **levels** while `instances`
+  counts distinct documents — they differ when one person holds several branches
+  of a parallel group. `overdue` measures against each level's escalation
+  deadline, and `onHold` counts work paused by a clarification request.
+
+- **An approver who has already voted is not counted**, even while the level
+  stays open collecting other votes: they owe nothing more, and counting them
+  would overstate the queue of every quorum and weighted level.
+
+- Computed from pending instances rather than a dedicated index, so it works on
+  any storage adapter with no new adapter methods. That means it reads every
+  pending instance in the tenant — fine for the volumes an approval queue
+  reaches, but it is a reporting call, not something for a hot path.
+
+  New export: `ApproverWorkload`.
+
 ## [1.8.0] - 2026-09-04
 
 ### Added — `transferApprovals()`

package/README.md

@@ -399,6 +399,30 @@ engine.registerConditionOperator('between', (actual, expected) => {
 });
 ```
 
+### Who is holding things up
+
+`getStatistics()` answers how the tenant is doing; `getWorkload()` answers who
+is holding it up — the question behind rebalancing a queue or deciding whom to
+hand a departing colleague's work to:
+
+```ts
+const workload = await engine.getWorkload({ documentType: 'purchase_order' });
+// [
+//   { approverId: 'alice', pending: 12, instances: 11, overdue: 3, onHold: 1,
+//     oldestPendingAt: 2026-01-02T…, oldestAgeMs: 604800000 },
+//   ...
+// ]
+```
+
+Busiest queue first. `pending` counts open **levels**, `instances` counts
+distinct documents — they differ when one person holds several branches of a
+parallel group. An approver who has already voted on a level that is still
+collecting other votes owes nothing more and is not counted.
+
+Computed from pending instances rather than a dedicated index, so it works on
+any adapter with no new adapter methods — but it reads every pending instance in
+the tenant. It is a reporting call, not something for a hot path.
+
 ### Transferring a person's queue
 
 Someone leaves, changes team, or goes on long-term leave, and their open

package/dist/{ApprovalEngine-cI4LP2Mx.d.cts → ApprovalEngine-BDI4r_KB.d.cts}

@@ -284,6 +284,27 @@ interface TransferResult {
     /** True when nothing was written. */
     dryRun: boolean;
 }
+/**
+ * What one approver currently owes a decision on.
+ *
+ * Durations are milliseconds. An approver appears only while they hold at least
+ * one open level.
+ */
+interface ApproverWorkload {
+    approverId: string;
+    /** Open levels assigned to them. One instance can contribute several across parallel branches. */
+    pending: number;
+    /** Distinct documents involved — usually, but not always, equal to {@link pending}. */
+    instances: number;
+    /** Open levels already past their escalation deadline. */
+    overdue: number;
+    /** Open levels currently paused by a clarification request. */
+    onHold: number;
+    /** When the oldest of their open items was submitted. */
+    oldestPendingAt?: Date;
+    /** Age of that oldest item. `0` when they hold nothing. */
+    oldestAgeMs: number;
+}
 interface ApprovalStatistics {
     /** Total instances matching the filter (across all statuses). */
     total: number;
@@ -607,6 +628,27 @@ declare class ApprovalEngine {
      * submittedBy, date range) — `status` is ignored since every status is counted.
      * Adapter-agnostic: issues one cheap count query per status plus an overdue scan.
      */
+    /**
+     * Who currently owes a decision, and how overdue they are.
+     *
+     * `getStatistics()` answers how the tenant is doing; this answers who is
+     * holding it up — the question behind rebalancing a queue, spotting the
+     * approver who has been on leave for a week, or deciding whom to
+     * {@link transferApprovals} a departing colleague's work to.
+     *
+     * Computed from pending instances rather than a dedicated index, so it works
+     * on any storage adapter with no new adapter methods. That means it reads
+     * every pending instance in the tenant: fine for the operational volumes an
+     * approval queue reaches, but it is a reporting call, not something to put on
+     * a hot path.
+     *
+     * Rows are sorted by {@link ApproverWorkload.pending} descending, so the
+     * busiest queue is first.
+     *
+     * @param filter - Optional scoping; `status` is ignored, since only pending work counts.
+     * @returns One row per approver holding at least one open level.
+     */
+    getWorkload(filter?: Omit<InstanceFilter, 'status'>): Promise<ApproverWorkload[]>;
     getStatistics(filter?: Omit<InstanceFilter, 'status'>): Promise<ApprovalStatistics>;
     shutdown(): Promise<void>;
     /**
@@ -704,4 +746,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 TransferResult as T, 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 ProvideInfoOptions as n, type RejectOptions as o, type RequestInfoOptions as p, type ResubmitOptions as q, type RetryPolicy as r, defaultIdGenerator as s, 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 TransferResult as T, 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 ApproverWorkload as f, type BusinessCalendar as g, type CancelOptions as h, type ConditionOperatorFn as i, type CycleTimeStats as j, type IdempotencyKeyFn as k, type OutOfOfficeProvider as l, type OverrideOptions as m, type PreviewResult as n, type ProvideInfoOptions as o, type RejectOptions as p, type RequestInfoOptions as q, type ResubmitOptions as r, type RetryPolicy as s, defaultIdGenerator as t, toComparableNumber as u, validateConditionExpression as v, weekendCalendar as w };

package/dist/{ApprovalEngine-CElfKXOA.d.ts → ApprovalEngine-a1jXglT3.d.ts}

@@ -284,6 +284,27 @@ interface TransferResult {
     /** True when nothing was written. */
     dryRun: boolean;
 }
+/**
+ * What one approver currently owes a decision on.
+ *
+ * Durations are milliseconds. An approver appears only while they hold at least
+ * one open level.
+ */
+interface ApproverWorkload {
+    approverId: string;
+    /** Open levels assigned to them. One instance can contribute several across parallel branches. */
+    pending: number;
+    /** Distinct documents involved — usually, but not always, equal to {@link pending}. */
+    instances: number;
+    /** Open levels already past their escalation deadline. */
+    overdue: number;
+    /** Open levels currently paused by a clarification request. */
+    onHold: number;
+    /** When the oldest of their open items was submitted. */
+    oldestPendingAt?: Date;
+    /** Age of that oldest item. `0` when they hold nothing. */
+    oldestAgeMs: number;
+}
 interface ApprovalStatistics {
     /** Total instances matching the filter (across all statuses). */
     total: number;
@@ -607,6 +628,27 @@ declare class ApprovalEngine {
      * submittedBy, date range) — `status` is ignored since every status is counted.
      * Adapter-agnostic: issues one cheap count query per status plus an overdue scan.
      */
+    /**
+     * Who currently owes a decision, and how overdue they are.
+     *
+     * `getStatistics()` answers how the tenant is doing; this answers who is
+     * holding it up — the question behind rebalancing a queue, spotting the
+     * approver who has been on leave for a week, or deciding whom to
+     * {@link transferApprovals} a departing colleague's work to.
+     *
+     * Computed from pending instances rather than a dedicated index, so it works
+     * on any storage adapter with no new adapter methods. That means it reads
+     * every pending instance in the tenant: fine for the operational volumes an
+     * approval queue reaches, but it is a reporting call, not something to put on
+     * a hot path.
+     *
+     * Rows are sorted by {@link ApproverWorkload.pending} descending, so the
+     * busiest queue is first.
+     *
+     * @param filter - Optional scoping; `status` is ignored, since only pending work counts.
+     * @returns One row per approver holding at least one open level.
+     */
+    getWorkload(filter?: Omit<InstanceFilter, 'status'>): Promise<ApproverWorkload[]>;
     getStatistics(filter?: Omit<InstanceFilter, 'status'>): Promise<ApprovalStatistics>;
     shutdown(): Promise<void>;
     /**
@@ -704,4 +746,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 TransferResult as T, 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 ProvideInfoOptions as n, type RejectOptions as o, type RequestInfoOptions as p, type ResubmitOptions as q, type RetryPolicy as r, defaultIdGenerator as s, 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 TransferResult as T, 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 ApproverWorkload as f, type BusinessCalendar as g, type CancelOptions as h, type ConditionOperatorFn as i, type CycleTimeStats as j, type IdempotencyKeyFn as k, type OutOfOfficeProvider as l, type OverrideOptions as m, type PreviewResult as n, type ProvideInfoOptions as o, type RejectOptions as p, type RequestInfoOptions as q, type ResubmitOptions as r, type RetryPolicy as s, defaultIdGenerator as t, toComparableNumber as u, validateConditionExpression as v, weekendCalendar as w };

package/dist/index.cjs

@@ -2914,6 +2914,66 @@ var ApprovalEngine = class _ApprovalEngine {
    * submittedBy, date range) — `status` is ignored since every status is counted.
    * Adapter-agnostic: issues one cheap count query per status plus an overdue scan.
    */
+  /**
+   * Who currently owes a decision, and how overdue they are.
+   *
+   * `getStatistics()` answers how the tenant is doing; this answers who is
+   * holding it up — the question behind rebalancing a queue, spotting the
+   * approver who has been on leave for a week, or deciding whom to
+   * {@link transferApprovals} a departing colleague's work to.
+   *
+   * Computed from pending instances rather than a dedicated index, so it works
+   * on any storage adapter with no new adapter methods. That means it reads
+   * every pending instance in the tenant: fine for the operational volumes an
+   * approval queue reaches, but it is a reporting call, not something to put on
+   * a hot path.
+   *
+   * Rows are sorted by {@link ApproverWorkload.pending} descending, so the
+   * busiest queue is first.
+   *
+   * @param filter - Optional scoping; `status` is ignored, since only pending work counts.
+   * @returns One row per approver holding at least one open level.
+   */
+  async getWorkload(filter = {}) {
+    const pending = await this.fetchAllByFilter({ ...filter, status: "pending" });
+    const now = this.clock.now();
+    const byApprover = /* @__PURE__ */ new Map();
+    for (const instance of pending) {
+      const submittedAt = new Date(instance.createdAt).getTime();
+      const held = Boolean(instance.infoRequest);
+      for (const level of instance.levels) {
+        if (level.status !== "pending") continue;
+        const isOverdue = level.escalationDueAt !== void 0 && new Date(level.escalationDueAt) <= now;
+        for (const approverId of level.approverIds) {
+          if (level.approvedBy.includes(approverId) || level.rejectedBy.includes(approverId)) {
+            continue;
+          }
+          const row = byApprover.get(approverId) ?? {
+            pending: 0,
+            instances: /* @__PURE__ */ new Set(),
+            overdue: 0,
+            onHold: 0,
+            oldest: Number.POSITIVE_INFINITY
+          };
+          row.pending++;
+          row.instances.add(instance.id);
+          if (isOverdue) row.overdue++;
+          if (held) row.onHold++;
+          row.oldest = Math.min(row.oldest, submittedAt);
+          byApprover.set(approverId, row);
+        }
+      }
+    }
+    return [...byApprover.entries()].map(([approverId, row]) => ({
+      approverId,
+      pending: row.pending,
+      instances: row.instances.size,
+      overdue: row.overdue,
+      onHold: row.onHold,
+      oldestPendingAt: Number.isFinite(row.oldest) ? new Date(row.oldest) : void 0,
+      oldestAgeMs: Number.isFinite(row.oldest) ? now.getTime() - row.oldest : 0
+    })).sort((a, b) => b.pending - a.pending || a.approverId.localeCompare(b.approverId));
+  }
   async getStatistics(filter = {}) {
     const statuses = [
       "pending",