@rytass/bpm-core-nestjs-module 0.22.0 → 0.24.0

package/src/lib/workflow-engine/dto/reassign-member-tasks.input.js.map

@@ -1 +1 @@
-{"version":3,"file":"reassign-member-tasks.input.js","sourceRoot":"","sources":["../../../../../../../libs/bpm-core/src/lib/workflow-engine/dto/reassign-member-tasks.input.ts"],"names":[],"mappings":";;;;AAAA,6CAAmD;AACnD,qDAAkE;AAG3D,IAAM,wBAAwB,GAA9B,MAAM,wBAAwB;CAkBpC,CAAA;AAlBY,4DAAwB;AAGnC;IAFC,IAAA,eAAK,GAAE;IACP,IAAA,0BAAQ,GAAE;;8DACW;AAItB;IAFC,IAAA,eAAK,GAAE;IACP,IAAA,0BAAQ,GAAE;;4DACS;AAIpB;IAFC,IAAA,eAAK,GAAE;IACP,IAAA,0BAAQ,GAAE;;wDACK;AAMhB;IAHC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACxC,IAAA,4BAAU,GAAE;IACZ,IAAA,2BAAS,GAAE;;wDACY;mCAjBb,wBAAwB;IADpC,IAAA,mBAAS,GAAE;GACC,wBAAwB,CAkBpC"}
+{"version":3,"file":"reassign-member-tasks.input.js","sourceRoot":"","sources":["../../../../../../../libs/bpm-core/src/lib/workflow-engine/dto/reassign-member-tasks.input.ts"],"names":[],"mappings":";;;;AAAA,6CAAuD;AACvD,qDAOyB;AAGlB,IAAM,wBAAwB,GAA9B,MAAM,wBAAwB;CA0BpC,CAAA;AA1BY,4DAAwB;AAGnC;IAFC,IAAA,eAAK,GAAE;IACP,IAAA,0BAAQ,GAAE;;8DACW;AAItB;IAFC,IAAA,eAAK,GAAE;IACP,IAAA,0BAAQ,GAAE;;4DACS;AAIpB;IAFC,IAAA,eAAK,GAAE;IACP,IAAA,0BAAQ,GAAE;;wDACK;AAMhB;IAHC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACxC,IAAA,4BAAU,GAAE;IACZ,IAAA,2BAAS,GAAE;;wDACY;AAQxB;IALC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,CAAC,YAAE,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACrC,IAAA,4BAAU,GAAE;IACZ,IAAA,yBAAO,GAAE;IACT,IAAA,+BAAa,GAAE;IACf,IAAA,wBAAM,EAAC,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;;yDACJ;mCAzBf,wBAAwB;IADpC,IAAA,mBAAS,GAAE;GACC,wBAAwB,CA0BpC"}

package/src/lib/workflow-engine/index.d.ts

@@ -5,6 +5,7 @@ export * from './approval-instance-page-info.object';
 export * from './approval-instance.entity';
 export * from './dto/adhoc-notification.input';
 export * from './dto/adhoc-target.input';
+export * from './dto/admin-cancel-approval-instance.input';
 export * from './dto/cancel-approval-instance.input';
 export * from './dto/decide-task.input';
 export * from './dto/dry-run-approval-workflow.input';
@@ -13,9 +14,11 @@ export * from './dto/reassign-task.input';
 export * from './dto/resubmit-approval-instance.input';
 export * from './dto/submit-approval-instance.input';
 export * from './initiator-custom-fields-resolver.token';
+export * from './instance-guard.token';
 export * from './task-candidate.entity';
 export * from './task-decision.entity';
 export * from './task.entity';
+export * from './stuck-approval-instance.object';
 export * from './task-reassignment.object';
 export * from './workflow-condition-evaluator';
 export * from './workflow-dry-run.object';

package/src/lib/workflow-engine/index.js

@@ -8,6 +8,7 @@ tslib_1.__exportStar(require("./approval-instance-page-info.object"), exports);
 tslib_1.__exportStar(require("./approval-instance.entity"), exports);
 tslib_1.__exportStar(require("./dto/adhoc-notification.input"), exports);
 tslib_1.__exportStar(require("./dto/adhoc-target.input"), exports);
+tslib_1.__exportStar(require("./dto/admin-cancel-approval-instance.input"), exports);
 tslib_1.__exportStar(require("./dto/cancel-approval-instance.input"), exports);
 tslib_1.__exportStar(require("./dto/decide-task.input"), exports);
 tslib_1.__exportStar(require("./dto/dry-run-approval-workflow.input"), exports);
@@ -16,9 +17,11 @@ tslib_1.__exportStar(require("./dto/reassign-task.input"), exports);
 tslib_1.__exportStar(require("./dto/resubmit-approval-instance.input"), exports);
 tslib_1.__exportStar(require("./dto/submit-approval-instance.input"), exports);
 tslib_1.__exportStar(require("./initiator-custom-fields-resolver.token"), exports);
+tslib_1.__exportStar(require("./instance-guard.token"), exports);
 tslib_1.__exportStar(require("./task-candidate.entity"), exports);
 tslib_1.__exportStar(require("./task-decision.entity"), exports);
 tslib_1.__exportStar(require("./task.entity"), exports);
+tslib_1.__exportStar(require("./stuck-approval-instance.object"), exports);
 tslib_1.__exportStar(require("./task-reassignment.object"), exports);
 tslib_1.__exportStar(require("./workflow-condition-evaluator"), exports);
 tslib_1.__exportStar(require("./workflow-dry-run.object"), exports);

package/src/lib/workflow-engine/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/workflow-engine/index.ts"],"names":[],"mappings":";;;AAAA,gEAAsC;AACtC,mEAAyC;AACzC,wDAA8B;AAC9B,+EAAqD;AACrD,qEAA2C;AAC3C,yEAA+C;AAC/C,mEAAyC;AACzC,+EAAqD;AACrD,kEAAwC;AACxC,gFAAsD;AACtD,4EAAkD;AAClD,oEAA0C;AAC1C,iFAAuD;AACvD,+EAAqD;AACrD,mFAAyD;AACzD,kEAAwC;AACxC,iEAAuC;AACvC,wDAA8B;AAC9B,qEAA2C;AAC3C,yEAA+C;AAC/C,oEAA0C;AAC1C,8EAAoD;AACpD,kEAAwC;AACxC,mEAAyC;AACzC,oEAA0C;AAC1C,mEAAyC;AACzC,mFAAyD;AACzD,kEAAwC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/workflow-engine/index.ts"],"names":[],"mappings":";;;AAAA,gEAAsC;AACtC,mEAAyC;AACzC,wDAA8B;AAC9B,+EAAqD;AACrD,qEAA2C;AAC3C,yEAA+C;AAC/C,mEAAyC;AACzC,qFAA2D;AAC3D,+EAAqD;AACrD,kEAAwC;AACxC,gFAAsD;AACtD,4EAAkD;AAClD,oEAA0C;AAC1C,iFAAuD;AACvD,+EAAqD;AACrD,mFAAyD;AACzD,iEAAuC;AACvC,kEAAwC;AACxC,iEAAuC;AACvC,wDAA8B;AAC9B,2EAAiD;AACjD,qEAA2C;AAC3C,yEAA+C;AAC/C,oEAA0C;AAC1C,8EAAoD;AACpD,kEAAwC;AACxC,mEAAyC;AACzC,oEAA0C;AAC1C,mEAAyC;AACzC,mFAAyD;AACzD,kEAAwC"}

package/src/lib/workflow-engine/instance-advance-failure.d.ts

@@ -0,0 +1,28 @@
+import type { HttpException } from '@nestjs/common';
+/** Which public operation tried to move the instance on. */
+export type InstanceAdvanceFailureKind = 'DECISION' | 'RESUBMIT';
+/** What the `ADVANCE_FAILED` activity row says about the attempt. */
+export interface InstanceAdvanceFailureContext {
+    readonly action: 'APPROVED' | 'RETURNED' | null;
+    /** The person who acted; for an SLA timeout, the member it acted as. */
+    readonly actorMemberId: string;
+    readonly automatic: 'SLA_AUTO_APPROVE' | null;
+    readonly instanceId: string;
+    readonly kind: InstanceAdvanceFailureKind;
+    /** The node the decision was made on; `null` for a resubmission. */
+    readonly nodeId: string | null;
+    /** The decided task; `null` for a resubmission. */
+    readonly taskId: string | null;
+}
+/**
+ * Carries a failed attempt to move an instance on from the call site that saw
+ * it, through the rolled-back transaction, to the public method that records
+ * it. It exists only for that trip: the public method records it and throws
+ * {@link InstanceAdvanceFailure.originalError} instead, so no caller ever sees
+ * this class. Deliberately not exported from the library index.
+ */
+export declare class InstanceAdvanceFailure extends Error {
+    readonly context: InstanceAdvanceFailureContext;
+    readonly originalError: HttpException;
+    constructor(originalError: HttpException, context: InstanceAdvanceFailureContext);
+}

package/src/lib/workflow-engine/instance-advance-failure.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InstanceAdvanceFailure = void 0;
+/**
+ * Carries a failed attempt to move an instance on from the call site that saw
+ * it, through the rolled-back transaction, to the public method that records
+ * it. It exists only for that trip: the public method records it and throws
+ * {@link InstanceAdvanceFailure.originalError} instead, so no caller ever sees
+ * this class. Deliberately not exported from the library index.
+ */
+class InstanceAdvanceFailure extends Error {
+    constructor(originalError, context) {
+        super(originalError.message);
+        this.name = 'InstanceAdvanceFailure';
+        this.context = context;
+        this.originalError = originalError;
+    }
+}
+exports.InstanceAdvanceFailure = InstanceAdvanceFailure;
+//# sourceMappingURL=instance-advance-failure.js.map

package/src/lib/workflow-engine/instance-advance-failure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-advance-failure.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/workflow-engine/instance-advance-failure.ts"],"names":[],"mappings":";;;AAmBA;;;;;;GAMG;AACH,MAAa,sBAAuB,SAAQ,KAAK;IAK/C,YACE,aAA4B,EAC5B,OAAsC;QAEtC,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QAE7B,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACrC,CAAC;CACF;AAfD,wDAeC"}

package/src/lib/workflow-engine/instance-guard.runner.d.ts

@@ -0,0 +1,19 @@
+import type { BPMInstanceGuard, BPMInstanceGuardInput } from './instance-guard.token';
+/** Default for `instanceGuardTimeoutMs` (ADR 27 §2.2). */
+export declare const BPM_INSTANCE_GUARD_DEFAULT_TIMEOUT_MS = 5000;
+export declare const BPM_INSTANCE_GUARD_TIMEOUT_CODE = "BPM_INSTANCE_GUARD_TIMEOUT";
+export declare const BPM_INSTANCE_GUARD_FAILED_CODE = "BPM_INSTANCE_GUARD_FAILED";
+export declare function isInstanceGuardError(error: unknown): boolean;
+/**
+ * Runs the host guard for one engine path and throws if the path must stop.
+ *
+ * Returns normally only when the guard answered with an empty list in time.
+ * Call it inside the engine transaction, after the case lock is taken, so a
+ * throw rolls the whole change back.
+ *
+ * - non-empty issues: 400 `createFormDataBadRequest`
+ * - no answer within `timeoutMs`: 503 `BPM_INSTANCE_GUARD_TIMEOUT` (fail closed)
+ * - a thrown `HttpException`: rethrown unchanged
+ * - any other error, or a malformed answer: 503 `BPM_INSTANCE_GUARD_FAILED`
+ */
+export declare function runInstanceGuard(guard: BPMInstanceGuard, input: BPMInstanceGuardInput, timeoutMs: number): Promise<void>;

package/src/lib/workflow-engine/instance-guard.runner.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BPM_INSTANCE_GUARD_FAILED_CODE = exports.BPM_INSTANCE_GUARD_TIMEOUT_CODE = exports.BPM_INSTANCE_GUARD_DEFAULT_TIMEOUT_MS = void 0;
+exports.isInstanceGuardError = isInstanceGuardError;
+exports.runInstanceGuard = runInstanceGuard;
+const common_1 = require("@nestjs/common");
+const form_data_issue_1 = require("../form/form-data-issue");
+/** Default for `instanceGuardTimeoutMs` (ADR 27 §2.2). */
+exports.BPM_INSTANCE_GUARD_DEFAULT_TIMEOUT_MS = 5000;
+exports.BPM_INSTANCE_GUARD_TIMEOUT_CODE = 'BPM_INSTANCE_GUARD_TIMEOUT';
+exports.BPM_INSTANCE_GUARD_FAILED_CODE = 'BPM_INSTANCE_GUARD_FAILED';
+/**
+ * Every error the guard path raises: the 400 for refused issues, the 503 for a
+ * timeout or a failing guard, and an `HttpException` the host threw itself.
+ * Lets a caller tell a guard refusal apart from any other failure without
+ * matching on messages.
+ */
+const instanceGuardErrors = new WeakSet();
+function markInstanceGuardError(error) {
+    instanceGuardErrors.add(error);
+    return error;
+}
+function isInstanceGuardError(error) {
+    return typeof error === 'object' && error !== null
+        ? instanceGuardErrors.has(error)
+        : false;
+}
+function createGuardUnavailable(code, message) {
+    return markInstanceGuardError(new common_1.ServiceUnavailableException({
+        code,
+        error: 'Service Unavailable',
+        message,
+        statusCode: 503,
+    }));
+}
+function isGuardIssue(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const issue = value;
+    return (typeof issue.message === 'string' &&
+        typeof issue.path === 'string' &&
+        issue.reason === 'HOST_RULE' &&
+        (issue.code === undefined || typeof issue.code === 'string'));
+}
+function readIssueFormDataErrors(issues) {
+    return issues.map((issue) => ({
+        message: issue.message,
+        path: issue.path,
+        reason: issue.reason,
+        ...(issue.code === undefined ? {} : { code: issue.code }),
+    }));
+}
+/**
+ * Runs the host guard for one engine path and throws if the path must stop.
+ *
+ * Returns normally only when the guard answered with an empty list in time.
+ * Call it inside the engine transaction, after the case lock is taken, so a
+ * throw rolls the whole change back.
+ *
+ * - non-empty issues: 400 `createFormDataBadRequest`
+ * - no answer within `timeoutMs`: 503 `BPM_INSTANCE_GUARD_TIMEOUT` (fail closed)
+ * - a thrown `HttpException`: rethrown unchanged
+ * - any other error, or a malformed answer: 503 `BPM_INSTANCE_GUARD_FAILED`
+ */
+async function runInstanceGuard(guard, input, timeoutMs) {
+    const timeoutError = markInstanceGuardError(new Error(`BPM_INSTANCE_GUARD_TIMEOUT_${timeoutMs}MS`));
+    let timer;
+    let issues;
+    try {
+        issues = await Promise.race([
+            Promise.resolve().then(() => guard.check(input)),
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => {
+                    reject(timeoutError);
+                }, timeoutMs);
+            }),
+        ]);
+    }
+    catch (error) {
+        if (error === timeoutError) {
+            throw createGuardUnavailable(exports.BPM_INSTANCE_GUARD_TIMEOUT_CODE, `Instance guard did not answer within ${timeoutMs} ms`);
+        }
+        if (error instanceof common_1.HttpException) {
+            markInstanceGuardError(error);
+            throw error;
+        }
+        throw createGuardUnavailable(exports.BPM_INSTANCE_GUARD_FAILED_CODE, 'Instance guard failed');
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!Array.isArray(issues) || !issues.every(isGuardIssue)) {
+        throw createGuardUnavailable(exports.BPM_INSTANCE_GUARD_FAILED_CODE, 'Instance guard returned an answer of the wrong shape');
+    }
+    if (issues.length === 0) {
+        return;
+    }
+    const formDataErrors = readIssueFormDataErrors(issues);
+    throw markInstanceGuardError((0, form_data_issue_1.createFormDataBadRequest)((0, form_data_issue_1.readFormDataIssueMessage)(formDataErrors), formDataErrors));
+}
+//# sourceMappingURL=instance-guard.runner.js.map

package/src/lib/workflow-engine/instance-guard.runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-guard.runner.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/workflow-engine/instance-guard.runner.ts"],"names":[],"mappings":"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"}

package/src/lib/workflow-engine/instance-guard.token.d.ts

@@ -0,0 +1,101 @@
+import { InjectionToken } from '@nestjs/common';
+import type { WorkflowNode } from '@rytass/bpm-core-shared';
+import type { EntityManager } from 'typeorm';
+import type { BPMAuthContext } from '../bpm-auth';
+import type { ApprovalInstanceEntity } from './approval-instance.entity';
+import type { TaskEntity } from './task.entity';
+import type { ApprovalTemplateVersionEntity } from '../template/approval-template-version.entity';
+/**
+ * Which engine path is asking the guard: a case being submitted, a returned
+ * case being resubmitted, or a task being decided.
+ */
+export type BPMInstanceGuardKind = 'DECIDE' | 'RESUBMIT' | 'SUBMIT';
+/**
+ * What the engine hands the guard. The guard runs inside the engine
+ * transaction, after the case lock is taken, so every value here is the state
+ * the engine is about to commit.
+ *
+ * Treat every object as read-only. The guard decides, it does not write:
+ * whatever it writes through `manager` is committed or rolled back together
+ * with the decision, and a timed-out guard cannot take it back.
+ */
+export interface BPMInstanceGuardInput {
+    /** The member who triggered the path, or `null` for a system action. */
+    readonly actorMemberId: string | null;
+    /**
+     * Set only for a decision made by the engine itself (SLA auto-approve). The
+     * guard may treat it differently, for example to skip an approver-facing
+     * rule. `null` for every other decision.
+     */
+    readonly automatic: 'SLA_AUTO_APPROVE' | null;
+    /** The caller's auth context, when the path has one. */
+    readonly authContext: BPMAuthContext | null;
+    /** The decision action (`APPROVE`, `REJECT`, ...). `null` unless `kind` is `DECIDE`. */
+    readonly action: string | null;
+    /**
+     * The keys of `formData` the request changed, sorted. For `SUBMIT` every
+     * submitted key counts; for `RESUBMIT` the keys whose value differs from the
+     * stored form data, including keys the resubmission drops; for `DECIDE` the
+     * approver-filled fields whose value really changes.
+     */
+    readonly changedFieldKeys: readonly string[];
+    /**
+     * The case as it will be committed. For `SUBMIT` this is the entity the
+     * engine has just built and not yet saved (no `id` yet).
+     */
+    readonly instance: Readonly<ApprovalInstanceEntity>;
+    readonly kind: BPMInstanceGuardKind;
+    /** The merged form data the case will hold after this path. */
+    readonly formData: Readonly<Record<string, unknown>>;
+    /** The node being decided. `null` unless `kind` is `DECIDE`. */
+    readonly node: WorkflowNode | null;
+    /** The task being decided. `null` unless `kind` is `DECIDE`. */
+    readonly task: Readonly<TaskEntity> | null;
+    /** The published template version the case runs on. */
+    readonly templateVersion: Readonly<ApprovalTemplateVersionEntity>;
+    /**
+     * The engine's transaction manager, for reads that must see the same
+     * snapshot the decision is made on. Do not write through it (see above).
+     */
+    readonly manager: EntityManager;
+}
+/**
+ * One rule the guard refuses on. A non-empty list is returned to the caller as
+ * a 400 `createFormDataBadRequest` carrying `formDataErrors`.
+ *
+ * - `path` is the form field the rule is about, or `''` for the whole case.
+ * - `reason` is always `HOST_RULE` for guard issues.
+ * - `code` is an optional host error code, passed through unchanged.
+ *
+ * A guard returns issues only. It cannot return a patch to `formData`: a
+ * patch would bypass the approver-fill permissions and the signature coverage.
+ */
+export interface BPMInstanceGuardIssue {
+    readonly code?: string;
+    readonly message: string;
+    readonly path: string;
+    readonly reason: 'HOST_RULE';
+}
+/**
+ * Host hook that can refuse a case before the engine commits a state change.
+ *
+ * The engine calls `check` on three paths: submit, resubmit and decide. It is
+ * called inside the transaction, so a refusal rolls the whole change back. An
+ * empty array means pass; a non-empty array becomes a 400. A thrown
+ * `HttpException` is returned to the caller unchanged; any other error and a
+ * timeout become a 503 (`BPM_INSTANCE_GUARD_FAILED` /
+ * `BPM_INSTANCE_GUARD_TIMEOUT`). The default timeout is 5000 ms
+ * (`instanceGuardTimeoutMs`).
+ *
+ * Keep `check` fast and side-effect free. A call that is still running when
+ * the timeout fires keeps running; if it has external side effects, the host
+ * must make them idempotent itself.
+ */
+export interface BPMInstanceGuard {
+    check(input: BPMInstanceGuardInput): Promise<readonly BPMInstanceGuardIssue[]>;
+}
+/**
+ * Optional host binding for {@link BPMInstanceGuard}. Without one, the three
+ * engine paths behave exactly as before the guard existed.
+ */
+export declare const BPM_INSTANCE_GUARD: InjectionToken<BPMInstanceGuard>;

package/src/lib/workflow-engine/instance-guard.token.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BPM_INSTANCE_GUARD = void 0;
+/**
+ * Optional host binding for {@link BPMInstanceGuard}. Without one, the three
+ * engine paths behave exactly as before the guard existed.
+ */
+exports.BPM_INSTANCE_GUARD = Symbol('BPM_INSTANCE_GUARD');
+//# sourceMappingURL=instance-guard.token.js.map

package/src/lib/workflow-engine/instance-guard.token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-guard.token.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/workflow-engine/instance-guard.token.ts"],"names":[],"mappings":";;;AAkHA;;;GAGG;AACU,QAAA,kBAAkB,GAAqC,MAAM,CACxE,oBAAoB,CACrB,CAAC"}

package/src/lib/workflow-engine/missing-form-fields.d.ts

@@ -0,0 +1,12 @@
+import { FormDefinitionSchema } from '@rytass/bpm-core-shared';
+/**
+ * The form data an expression reads when the host turns on
+ * `expressionMissingFormFieldsAsNull` (ADR 27 §3): every top-level field of
+ * the schema that the data has no key for is added, as `[]` for a table and
+ * `null` for anything else. A key that is present is never touched, and the
+ * columns inside table rows are not filled.
+ *
+ * The result is a copy used for evaluation only; it is never written back to
+ * `form_data`.
+ */
+export declare function fillMissingFormFields(formData: Readonly<Record<string, unknown>>, schema: FormDefinitionSchema): Readonly<Record<string, unknown>>;

package/src/lib/workflow-engine/missing-form-fields.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fillMissingFormFields = fillMissingFormFields;
+/**
+ * The form data an expression reads when the host turns on
+ * `expressionMissingFormFieldsAsNull` (ADR 27 §3): every top-level field of
+ * the schema that the data has no key for is added, as `[]` for a table and
+ * `null` for anything else. A key that is present is never touched, and the
+ * columns inside table rows are not filled.
+ *
+ * The result is a copy used for evaluation only; it is never written back to
+ * `form_data`.
+ */
+function fillMissingFormFields(formData, schema) {
+    const missing = schema.fields.filter((field) => !Object.prototype.hasOwnProperty.call(formData, field.fieldKey));
+    if (missing.length === 0) {
+        return formData;
+    }
+    return {
+        ...Object.fromEntries(missing.map((field) => [
+            field.fieldKey,
+            field.type === 'table' ? [] : null,
+        ])),
+        ...formData,
+    };
+}
+//# sourceMappingURL=missing-form-fields.js.map

package/src/lib/workflow-engine/missing-form-fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"missing-form-fields.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/workflow-engine/missing-form-fields.ts"],"names":[],"mappings":";;AAYA,sDAsBC;AAhCD;;;;;;;;;GASG;AACH,SAAgB,qBAAqB,CACnC,QAA2C,EAC3C,MAA4B;IAE5B,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAClC,CAAC,KAAK,EAAW,EAAE,CACjB,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,CAClE,CAAC;IAEF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,OAAO;QACL,GAAG,MAAM,CAAC,WAAW,CACnB,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAA8B,EAAE,CAAC;YACjD,KAAK,CAAC,QAAQ;YACd,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI;SACnC,CAAC,CACH;QACD,GAAG,QAAQ;KACZ,CAAC;AACJ,CAAC"}

package/src/lib/workflow-engine/stuck-approval-instance.object.d.ts

@@ -0,0 +1,22 @@
+import { StuckApprovalInstanceKindEnum } from './workflow-engine.enums';
+/**
+ * An approval instance that could not move on to its next stage, as the
+ * administrator's stuck-instances screen lists it: one row per instance, from
+ * its latest unresolved failure.
+ */
+export declare class StuckApprovalInstanceObject {
+    instanceId: string;
+    instanceTitle: string;
+    templateId: string;
+    templateName: string | null;
+    initiatorMemberId: string;
+    kind: StuckApprovalInstanceKindEnum;
+    nodeId: string | null;
+    nodeLabel: string | null;
+    taskId: string | null;
+    pendingActorMemberIds: string[];
+    failedActorMemberId: string | null;
+    automatic: string | null;
+    message: string;
+    failedAt: Date;
+}

package/src/lib/workflow-engine/stuck-approval-instance.object.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StuckApprovalInstanceObject = void 0;
+const tslib_1 = require("tslib");
+const graphql_1 = require("@nestjs/graphql");
+const workflow_engine_enums_1 = require("./workflow-engine.enums");
+/**
+ * An approval instance that could not move on to its next stage, as the
+ * administrator's stuck-instances screen lists it: one row per instance, from
+ * its latest unresolved failure.
+ */
+let StuckApprovalInstanceObject = class StuckApprovalInstanceObject {
+};
+exports.StuckApprovalInstanceObject = StuckApprovalInstanceObject;
+tslib_1.__decorate([
+    (0, graphql_1.Field)(() => graphql_1.ID, { description: 'The stuck instance.' }),
+    tslib_1.__metadata("design:type", String)
+], StuckApprovalInstanceObject.prototype, "instanceId", void 0);
+tslib_1.__decorate([
+    (0, graphql_1.Field)({ description: 'Title of the stuck instance.' }),
+    tslib_1.__metadata("design:type", String)
+], StuckApprovalInstanceObject.prototype, "instanceTitle", void 0);
+tslib_1.__decorate([
+    (0, graphql_1.Field)(() => graphql_1.ID, { description: 'The template the instance was filed from.' }),
+    tslib_1.__metadata("design:type", String)
+], StuckApprovalInstanceObject.prototype, "templateId", void 0);
+tslib_1.__decorate([
+    (0, graphql_1.Field)(() => String, {
+        description: 'Name of that template; null when it can no longer be read.',
+        nullable: true,
+    }),
+    tslib_1.__metadata("design:type", Object)
+], StuckApprovalInstanceObject.prototype, "templateName", void 0);
+tslib_1.__decorate([
+    (0, graphql_1.Field)({ description: 'Who filed the instance.' }),
+    tslib_1.__metadata("design:type", String)
+], StuckApprovalInstanceObject.prototype, "initiatorMemberId", void 0);
+tslib_1.__decorate([
+    (0, graphql_1.Field)(() => workflow_engine_enums_1.StuckApprovalInstanceKindEnum, {
+        description: 'DECISION: a decision on a task could not move the instance on. ' +
+            'RESUBMIT: the initiator resubmitted a returned instance and it could not start.',
+    }),
+    tslib_1.__metadata("design:type", String)
+], StuckApprovalInstanceObject.prototype, "kind", void 0);
+tslib_1.__decorate([
+    (0, graphql_1.Field)(() => String, {
+        description: 'The node the failed decision was made on; null for RESUBMIT.',
+        nullable: true,
+    }),
+    tslib_1.__metadata("design:type", Object)
+], StuckApprovalInstanceObject.prototype, "nodeId", void 0);
+tslib_1.__decorate([
+    (0, graphql_1.Field)(() => String, {
+        description: 'Display name of that node, read from the instance workflow snapshot; ' +
+            'null for RESUBMIT or when the node carries no label.',
+        nullable: true,
+    }),
+    tslib_1.__metadata("design:type", Object)
+], StuckApprovalInstanceObject.prototype, "nodeLabel", void 0);
+tslib_1.__decorate([
+    (0, graphql_1.Field)(() => graphql_1.ID, {
+        description: 'The task the failed decision was made on; null for RESUBMIT.',
+        nullable: true,
+    }),
+    tslib_1.__metadata("design:type", Object)
+], StuckApprovalInstanceObject.prototype, "taskId", void 0);
+tslib_1.__decorate([
+    (0, graphql_1.Field)(() => [String], {
+        description: 'Who has to press again now, read when the list is loaded. DECISION: ' +
+            'the members whose seat on the task is PENDING or CLAIMED (WAITING ' +
+            'seats are not their turn yet), or the assignee of a task that has no ' +
+            'candidate rows at all; it follows a later reassignment. RESUBMIT: the ' +
+            'initiator only.',
+    }),
+    tslib_1.__metadata("design:type", Array)
+], StuckApprovalInstanceObject.prototype, "pendingActorMemberIds", void 0);
+tslib_1.__decorate([
+    (0, graphql_1.Field)(() => String, {
+        description: 'The member the failed attempt was made as. For an automatic approval ' +
+            'this is the holder the system picked, who did not press anything: ' +
+            'read `automatic` first.',
+        nullable: true,
+    }),
+    tslib_1.__metadata("design:type", Object)
+], StuckApprovalInstanceObject.prototype, "failedActorMemberId", void 0);
+tslib_1.__decorate([
+    (0, graphql_1.Field)(() => String, {
+        description: "'SLA_AUTO_APPROVE' when the failed attempt was the system approving " +
+            'an overdue task, null when a person pressed the button.',
+        nullable: true,
+    }),
+    tslib_1.__metadata("design:type", Object)
+], StuckApprovalInstanceObject.prototype, "automatic", void 0);
+tslib_1.__decorate([
+    (0, graphql_1.Field)({
+        description: 'Why the instance could not move on, as the operator saw it.',
+    }),
+    tslib_1.__metadata("design:type", String)
+], StuckApprovalInstanceObject.prototype, "message", void 0);
+tslib_1.__decorate([
+    (0, graphql_1.Field)({ description: 'When the failed attempt was recorded.' }),
+    tslib_1.__metadata("design:type", Date)
+], StuckApprovalInstanceObject.prototype, "failedAt", void 0);
+exports.StuckApprovalInstanceObject = StuckApprovalInstanceObject = tslib_1.__decorate([
+    (0, graphql_1.ObjectType)('StuckApprovalInstance')
+], StuckApprovalInstanceObject);
+//# sourceMappingURL=stuck-approval-instance.object.js.map

package/src/lib/workflow-engine/stuck-approval-instance.object.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stuck-approval-instance.object.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/workflow-engine/stuck-approval-instance.object.ts"],"names":[],"mappings":";;;;AAAA,6CAAwD;AACxD,mEAAwE;AAExE;;;;GAIG;AAEI,IAAM,2BAA2B,GAAjC,MAAM,2BAA2B;CAiFvC,CAAA;AAjFY,kEAA2B;AAEtC;IADC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,YAAE,EAAE,EAAE,WAAW,EAAE,qBAAqB,EAAE,CAAC;;+DACpC;AAGpB;IADC,IAAA,eAAK,EAAC,EAAE,WAAW,EAAE,8BAA8B,EAAE,CAAC;;kEAChC;AAGvB;IADC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,YAAE,EAAE,EAAE,WAAW,EAAE,2CAA2C,EAAE,CAAC;;+DAC1D;AAMpB;IAJC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,MAAM,EAAE;QACnB,WAAW,EAAE,4DAA4D;QACzE,QAAQ,EAAE,IAAI;KACf,CAAC;;iEAC2B;AAG7B;IADC,IAAA,eAAK,EAAC,EAAE,WAAW,EAAE,yBAAyB,EAAE,CAAC;;sEACvB;AAO3B;IALC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,qDAA6B,EAAE;QAC1C,WAAW,EACT,iEAAiE;YACjE,iFAAiF;KACpF,CAAC;;yDACmC;AAOrC;IALC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,MAAM,EAAE;QACnB,WAAW,EACT,8DAA8D;QAChE,QAAQ,EAAE,IAAI;KACf,CAAC;;2DACqB;AAQvB;IANC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,MAAM,EAAE;QACnB,WAAW,EACT,uEAAuE;YACvE,sDAAsD;QACxD,QAAQ,EAAE,IAAI;KACf,CAAC;;8DACwB;AAM1B;IAJC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,YAAE,EAAE;QACf,WAAW,EAAE,8DAA8D;QAC3E,QAAQ,EAAE,IAAI;KACf,CAAC;;2DACqB;AAUvB;IARC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE;QACrB,WAAW,EACT,sEAAsE;YACtE,oEAAoE;YACpE,uEAAuE;YACvE,wEAAwE;YACxE,iBAAiB;KACpB,CAAC;;0EAC+B;AASjC;IAPC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,MAAM,EAAE;QACnB,WAAW,EACT,uEAAuE;YACvE,oEAAoE;YACpE,yBAAyB;QAC3B,QAAQ,EAAE,IAAI;KACf,CAAC;;wEACkC;AAQpC;IANC,IAAA,eAAK,EAAC,GAAG,EAAE,CAAC,MAAM,EAAE;QACnB,WAAW,EACT,sEAAsE;YACtE,yDAAyD;QAC3D,QAAQ,EAAE,IAAI;KACf,CAAC;;8DACwB;AAK1B;IAHC,IAAA,eAAK,EAAC;QACL,WAAW,EAAE,6DAA6D;KAC3E,CAAC;;4DACe;AAGjB;IADC,IAAA,eAAK,EAAC,EAAE,WAAW,EAAE,uCAAuC,EAAE,CAAC;sCACrD,IAAI;6DAAC;sCAhFL,2BAA2B;IADvC,IAAA,oBAAU,EAAC,uBAAuB,CAAC;GACvB,2BAA2B,CAiFvC"}

package/src/lib/workflow-engine/stuck-approval-instance.query.d.ts

@@ -0,0 +1,22 @@
+import { EntityManager } from 'typeorm';
+import { ActivityLogEntity } from './activity-log.entity';
+import { ApprovalInstanceEntity } from './approval-instance.entity';
+import { TaskStatusEnum } from './workflow-engine.enums';
+/**
+ * The rule above for one instance, given its `ADVANCE_FAILED` and
+ * `INSTANCE_RESUBMITTED` rows in `seq` order and the ids of the tasks among
+ * them that are still open.
+ */
+export declare function readUnresolvedInstanceFailures(instance: ApprovalInstanceEntity, logs: readonly ActivityLogEntity[], openTaskIds: ReadonlySet<string>): readonly ActivityLogEntity[];
+/**
+ * One page of stuck instances, as the ids of the failure that describes each:
+ * its latest unresolved `ADVANCE_FAILED` (highest `seq`). Newest failure first:
+ * `created_at` is the transaction start, so `seq` breaks a tie within one
+ * transaction, and the instance id any tie left after that.
+ */
+export declare function readStuckFailurePage(manager: EntityManager, openTaskStatuses: readonly TaskStatusEnum[], page: {
+    readonly offset: number;
+    readonly limit: number;
+}): Promise<readonly string[]>;
+/** How many instances {@link readStuckFailurePage} pages through. */
+export declare function countStuckInstances(manager: EntityManager, openTaskStatuses: readonly TaskStatusEnum[]): Promise<number>;