hierarchical-approval 2.2.0 → 2.3.0

package/dist/index.cjs

@@ -915,6 +915,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;
@@ -3120,6 +3121,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",
@@ -4122,6 +4199,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()) {