hierarchical-approval 2.2.0 → 2.3.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-export { A as AddCommentOptions, a as ApprovalEngine, b as ApprovalEngineOptions, c as ApprovalStatistics, d as ApproveOptions, e as ApproverResolverFn, f as ApproverWorkload, B as BulkResult, g as BusinessCalendar, C as CanApproveResult, h as CancelOptions, i as ConditionOperatorFn, j as CycleTimeStats, D as DelegateOptions, E as EscalateOptions, H as HealthResult, I as IdGeneratorFn, k as IdempotencyKeyFn, l as ImportResult, O as OrgProvider, m as OutOfOfficeProvider, n as OverrideOptions, P as PreviewChainLevel, o as PreviewResult, p as ProvideInfoOptions, R as ReassignOptions, q as RejectOptions, r as RequestInfoOptions, s as ResubmitOptions, t as RetryPolicy, S as SubmitOptions, T as TEMPLATE_BUNDLE_VERSION, u as TemplateBundle, v as TransferResult, U as UpdateDataOptions, V as ValidationResult, W as WeekendCalendarOptions, w as defaultIdGenerator, x as toComparableNumber, y as validateConditionExpression, z as weekendCalendar } from './ApprovalEngine-CbFBAMlO.cjs';
-import { I as IStorageAdapter } from './IStorageAdapter-Bk7ybd3z.cjs';
-export { c as CursorPaginatedResult, C as CursorPaginationOpts, b as InstanceFilter, a as PaginatedResult, P as PaginationOpts } from './IStorageAdapter-Bk7ybd3z.cjs';
+export { A as AddCommentOptions, a as ApprovalEngine, b as ApprovalEngineOptions, c as ApprovalStatistics, d as ApproveOptions, e as ApproverResolverFn, f as ApproverWorkload, B as BulkResult, g as BusinessCalendar, C as CanApproveResult, h as CancelOptions, i as ConditionOperatorFn, j as CycleTimeStats, D as DelegateOptions, E as EscalateOptions, H as HealthResult, I as IdGeneratorFn, k as IdempotencyKeyFn, l as ImportResult, O as OrgProvider, m as OutOfOfficeProvider, n as OverrideOptions, P as PreviewChainLevel, o as PreviewResult, p as ProvideInfoOptions, q as PurgeResult, R as ReassignOptions, r as RejectOptions, s as RequestInfoOptions, t as ResubmitOptions, u as RetryPolicy, S as SubmitOptions, T as TEMPLATE_BUNDLE_VERSION, v as TemplateBundle, w as TransferResult, U as UpdateDataOptions, V as ValidationResult, W as WeekendCalendarOptions, x as defaultIdGenerator, y as toComparableNumber, z as validateConditionExpression, F as weekendCalendar } from './ApprovalEngine-C1dUPnLM.cjs';
+import { I as IStorageAdapter } from './IStorageAdapter-DdHO4Rf1.cjs';
+export { c as CursorPaginatedResult, C as CursorPaginationOpts, b as InstanceFilter, a as PaginatedResult, P as PaginationOpts } from './IStorageAdapter-DdHO4Rf1.cjs';
 import { L as Logger } from './Logger-BplhlU7l.cjs';
 export { n as noopLogger } from './Logger-BplhlU7l.cjs';
 import { C as Clock } from './Clock-3FnOczFJ.cjs';

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export { A as AddCommentOptions, a as ApprovalEngine, b as ApprovalEngineOptions, c as ApprovalStatistics, d as ApproveOptions, e as ApproverResolverFn, f as ApproverWorkload, B as BulkResult, g as BusinessCalendar, C as CanApproveResult, h as CancelOptions, i as ConditionOperatorFn, j as CycleTimeStats, D as DelegateOptions, E as EscalateOptions, H as HealthResult, I as IdGeneratorFn, k as IdempotencyKeyFn, l as ImportResult, O as OrgProvider, m as OutOfOfficeProvider, n as OverrideOptions, P as PreviewChainLevel, o as PreviewResult, p as ProvideInfoOptions, R as ReassignOptions, q as RejectOptions, r as RequestInfoOptions, s as ResubmitOptions, t as RetryPolicy, S as SubmitOptions, T as TEMPLATE_BUNDLE_VERSION, u as TemplateBundle, v as TransferResult, U as UpdateDataOptions, V as ValidationResult, W as WeekendCalendarOptions, w as defaultIdGenerator, x as toComparableNumber, y as validateConditionExpression, z as weekendCalendar } from './ApprovalEngine-B3ChZxS7.js';
-import { I as IStorageAdapter } from './IStorageAdapter-DjRvHUF0.js';
-export { c as CursorPaginatedResult, C as CursorPaginationOpts, b as InstanceFilter, a as PaginatedResult, P as PaginationOpts } from './IStorageAdapter-DjRvHUF0.js';
+export { A as AddCommentOptions, a as ApprovalEngine, b as ApprovalEngineOptions, c as ApprovalStatistics, d as ApproveOptions, e as ApproverResolverFn, f as ApproverWorkload, B as BulkResult, g as BusinessCalendar, C as CanApproveResult, h as CancelOptions, i as ConditionOperatorFn, j as CycleTimeStats, D as DelegateOptions, E as EscalateOptions, H as HealthResult, I as IdGeneratorFn, k as IdempotencyKeyFn, l as ImportResult, O as OrgProvider, m as OutOfOfficeProvider, n as OverrideOptions, P as PreviewChainLevel, o as PreviewResult, p as ProvideInfoOptions, q as PurgeResult, R as ReassignOptions, r as RejectOptions, s as RequestInfoOptions, t as ResubmitOptions, u as RetryPolicy, S as SubmitOptions, T as TEMPLATE_BUNDLE_VERSION, v as TemplateBundle, w as TransferResult, U as UpdateDataOptions, V as ValidationResult, W as WeekendCalendarOptions, x as defaultIdGenerator, y as toComparableNumber, z as validateConditionExpression, F as weekendCalendar } from './ApprovalEngine-Ci9urTDI.js';
+import { I as IStorageAdapter } from './IStorageAdapter-BU3sau5W.js';
+export { c as CursorPaginatedResult, C as CursorPaginationOpts, b as InstanceFilter, a as PaginatedResult, P as PaginationOpts } from './IStorageAdapter-BU3sau5W.js';
 import { L as Logger } from './Logger-BplhlU7l.js';
 export { n as noopLogger } from './Logger-BplhlU7l.js';
 import { C as Clock } from './Clock-3FnOczFJ.js';

package/dist/index.js

@@ -909,6 +909,7 @@ function computeTimingStats(samples) {
 
 // src/engine/ApprovalEngine.ts
 var MAX_SUBWORKFLOW_DEPTH = 5;
+var DEFAULT_PURGE_LIMIT = 1e3;
 var DEFAULT_MAX_REMINDERS = 3;
 var DEFAULT_MAX_ATTEMPTS = 3;
 var DEFAULT_BASE_DELAY_MS = 50;
@@ -3114,6 +3115,82 @@ var ApprovalEngine = class _ApprovalEngine {
     });
     return result;
   }
+  /**
+   * Permanently remove finished approvals older than a cut-off.
+   *
+   * Approval tables only grow, and data-minimisation rules eventually require
+   * old records to go. There was no way to remove one, so operators reached
+   * around the library and deleted rows directly — which is exactly where
+   * orphaned audit rows and half-deleted instances come from.
+   *
+   * **Only terminal instances are eligible.** A pending approval is live work;
+   * deleting one would strand a document with no way to finish and no record of
+   * why. Passing a non-terminal status is rejected rather than quietly ignored,
+   * because a caller who asked to purge pending work has misunderstood
+   * something and should hear about it.
+   *
+   * This is irreversible and removes the audit trail with the instance. In many
+   * deployments that trail *is* the compliance record, which is why the
+   * underlying `deleteInstance` is an optional adapter method: an adapter that
+   * does not implement it makes the whole operation unavailable, and this
+   * throws rather than reporting a successful purge of nothing.
+   *
+   * @param opts - Cut-off, optional status/type scoping, safety limit, dry run.
+   * @returns What was removed, or would be under `dryRun`.
+   */
+  async purgeInstances(opts) {
+    const dryRun = opts.dryRun ?? false;
+    const limit = opts.limit ?? DEFAULT_PURGE_LIMIT;
+    if (!(opts.olderThan instanceof Date) || Number.isNaN(opts.olderThan.getTime())) {
+      throw new ApprovalValidationError("purgeInstances requires a valid olderThan date.");
+    }
+    const requested = opts.statuses ?? [...TERMINAL_STATUSES];
+    const nonTerminal = requested.filter((st) => !TERMINAL_STATUSES.has(st));
+    if (nonTerminal.length > 0) {
+      throw new ApprovalValidationError(
+        `purgeInstances refuses non-terminal statuses (${nonTerminal.join(", ")}): a pending approval is live work, and removing it would strand the document it belongs to.`
+      );
+    }
+    const deleteInstance = this.opts.adapter.deleteInstance?.bind(this.opts.adapter);
+    if (!deleteInstance && !dryRun) {
+      throw new ApprovalValidationError(
+        "The configured storage adapter does not implement deleteInstance(), so instances cannot be purged."
+      );
+    }
+    const result = { purged: [], scanned: 0, dryRun };
+    for (const status of requested) {
+      if (result.purged.length >= limit) break;
+      const page = await this.opts.adapter.getInstancesByFilter(
+        this.tenantId,
+        {
+          status,
+          toDate: opts.olderThan,
+          ...opts.documentType ? { documentType: opts.documentType } : {}
+        },
+        { limit, offset: 0 }
+      );
+      for (const instance of page.items) {
+        if (result.purged.length >= limit) break;
+        result.scanned++;
+        if (!TERMINAL_STATUSES.has(instance.status)) continue;
+        if (new Date(instance.createdAt) > opts.olderThan) continue;
+        if (!dryRun) await deleteInstance(this.tenantId, instance.id);
+        result.purged.push({
+          instanceId: instance.id,
+          documentId: instance.documentId,
+          status: instance.status
+        });
+      }
+    }
+    this.logger.info("purgeInstances: sweep complete", {
+      tenantId: this.tenantId,
+      olderThan: opts.olderThan.toISOString(),
+      scanned: result.scanned,
+      purged: result.purged.length,
+      dryRun
+    });
+    return result;
+  }
   async getStatistics(filter = {}) {
     const statuses = [
       "pending",
@@ -4116,6 +4193,10 @@ var MemoryAdapter = class {
       return hasOverdueEscalation || isExpired || hasSLABreach || hasDelegationExpiry || hasDueReminder;
     }).map((i) => reviveDates(deepClone(i)));
   }
+  async deleteInstance(tenantId, id) {
+    const key = `${tenantId}:${id}`;
+    return this.instances.delete(key);
+  }
   async countInstances(tenantId, filter) {
     let count = 0;
     for (const instance of this.instances.values()) {