@servicenow/sdk-build-plugins 4.6.1 → 4.7.0

package/dist/flow/utils/flow-stage-processor.d.ts

@@ -0,0 +1,138 @@
+import { CallExpressionShape, type Diagnostics, type Factory, ObjectShape, Record, Shape, type Source } from '@servicenow/sdk-build-core';
+/**
+ * Converts a `Duration({...})` CallExpressionShape from the Fluent API into the
+ * `YYYY-MM-DD HH:MM:SS` string stored in `sys_hub_flow_stage.duration`.
+ *
+ * `Duration()` is an identity function — ObjectShape.get() resolves it with
+ * resolve=true by default, but CallExpressionShape.resolve() returns itself
+ * (can't evaluate the body). We therefore read with resolve=false to get the
+ * raw CallExpressionShape, then delegate to DurationShape for formatting.
+ * Falls back to zero duration when absent or not a Duration() call.
+ */
+export declare function stageDurationToString(stageConfig: ObjectShape): string;
+/**
+ * Reads the `stages: {}` config object from the Flow/Subflow first argument
+ * and creates `sys_hub_flow_stage` records for each declared stage.
+ *
+ * Records are created WITHOUT `component_indexes` — those are computed by
+ * `finalizeStageRecords` after the body loop has determined which actions
+ * each stage covers.
+ *
+ * `stage_id` is derived from the record's own coalesce-based sys_id (which the
+ * factory makes stable from `flow + value`), so it is deterministic across
+ * builds without requiring a separate hash.
+ *
+ * @returns Map keyed by the stages object property name (e.g. `'triage'`).
+ */
+export declare function processHeaderStages(flowConfiguration: ObjectShape, flowDefinitionRecord: Record, factory: Factory): Promise<Map<string, Record>>;
+/**
+ * Scans `relatedRecords` for subflow instances with `show_stages=true` and
+ * creates a separate `sys_hub_flow_stage` record with `type:'subflow'` for each.
+ *
+ * These differ from developer-declared stages:
+ *  - `type`             = `'subflow'` (not `'standard'`)
+ *  - `value`            = the subflow instance's `ui_id` (UUID)
+ *  - `label`            = the subflow definition's name (resolved via `subflowDefNames` map)
+ *  - `component_indexes`= empty — the platform links via `value` (the UUID)
+ *
+ * @param pendingStagesLength  Number of developer-declared stages — subflow stages
+ *                             are ordered after them.
+ * @param subflowDefNames      Map of subflow definition sys_id → name, built by the
+ *                             caller from the original shapes.
+ */
+export declare function createSubflowStageRecords(relatedRecords: Record[], pendingStagesLength: number, flowDefinitionRecord: Record, factory: Factory, subflowDefNames: Map<string, string>): Promise<Record[]>;
+/**
+ * Extracts the stage key from a `wfa.stage(params.stages.<key>)` call.
+ * Returns `undefined` when the argument is not a PropertyAccessShape.
+ */
+export declare function extractStageKey(callExpr: CallExpressionShape): string | undefined;
+/** Unwrap a statement to the underlying CallExpressionShape if applicable. */
+export declare function unwrapCall(stmt: Shape): CallExpressionShape | undefined;
+/**
+ * Collects subflow definition name from a `wfa.subflow(defRecord, ...)` call
+ * and stores it in the provided map.
+ */
+export declare function collectSubflowDefName(callExpr: CallExpressionShape, subflowDefNames: Map<string, string>): void;
+/**
+ * Resolves nested stage indexes inline during the main instance loop.
+ *
+ * Called when a flow logic instance (if/elseIf/else) is encountered.
+ * Builds a local NowIdKey → order map from the flat records (whose orders
+ * are known: `baseOrder + index`), then recursively scans the body for
+ * `wfa.stage()` calls and pushes resolved entries directly into `pendingStages`.
+ *
+ * Also collects subflow definition names from nested `wfa.subflow()` calls.
+ */
+export declare function resolveNestedStagesInline(callExpr: CallExpressionShape, flatRecords: Record[], baseOrder: number, headerStageRecords: Map<string, Record>, pendingStages: Array<{
+    startActionIndex: number;
+    key: string;
+}>, subflowDefNames: Map<string, string>, diagnostics: Diagnostics): void;
+/**
+ * Resolves nested stages inside a `tryCatch(config, { try, catch })` call.
+ * Scans both the `try` and `catch` arrow function bodies for `wfa.stage()` calls.
+ */
+export declare function resolveNestedStagesForTryCatch(callExpr: CallExpressionShape, flatRecords: Record[], baseOrder: number, headerStageRecords: Map<string, Record>, pendingStages: Array<{
+    startActionIndex: number;
+    key: string;
+}>, subflowDefNames: Map<string, string>, diagnostics: Diagnostics): void;
+/**
+ * Computes `component_indexes` for each developer-declared stage and merges it
+ * onto the pre-created header record.
+ *
+ * Matching is by **key name**: the `key` stored in each `pendingStage` entry is
+ * looked up in `headerStageRecords`. This is correct even when the order of
+ * `wfa.stage()` calls in the body differs from the declaration order in the
+ * stages config header.
+ *
+ * A stage may appear multiple times in `pendingStages` (e.g. inside both an
+ * `if` and an `elseIf` body).  All indexes for the same key are collected and
+ * joined with `,` into a single `component_indexes` value on one record.
+ *
+ * @returns Array of finalised stage records ready to be added to `relatedRecords`.
+ */
+export declare function finalizeStageRecords(pendingStages: Array<{
+    startActionIndex: number;
+    key: string;
+}>, headerStageRecords: Map<string, Record>): Record[];
+/**
+ * Converts a stage `value` string (which may contain spaces, dots, underscores
+ * etc.) into a valid camelCase JavaScript identifier suitable for use as an
+ * object property key and in `params.stages.<key>` property-access expressions.
+ *
+ * Examples:
+ *   "Request Cancelled" → "requestCancelled"
+ *   "Dept. Head Approval" → "deptHeadApproval"
+ *   "CIO Approval"        → "cioApproval"
+ *   "manager_approval"    → "managerApproval"
+ *   "triage"              → "triage"
+ */
+export declare function toSafeIdentifier(value: string): string;
+/**
+ * Builds `FlowStage()` CallExpressionShapes from `sys_hub_flow_stage` records
+ * for the header `stages: {}` config property.
+ *
+ * Only standard stages are included (type='subflow' stages are skipped).
+ *
+ * @returns Plain object keyed by stage `value` — e.g. `{ triage: FlowStage({...}) }`.
+ */
+export declare function buildStageShapes(stageRecords: Record[]): globalThis.Record<string, CallExpressionShape>;
+/**
+ * Parses `component_indexes` from stage records and builds a map from
+ * action record order to the stage key(s) that should be inserted before it.
+ *
+ * component_index N means the stage belongs before the record with order = N + 1.
+ */
+export declare function buildStageInsertionMap(stageRecords: Record[]): Map<number, string[]>;
+/**
+ * Creates a `wfa.stage(params.stages.<key>)` CallExpressionShape.
+ */
+export declare function createStageCallShape(stageKey: string, paramName: string, source: Source): CallExpressionShape;
+/**
+ * Walks through an array of body shapes and mutates flow logic bodies
+ * (if/elseIf/else/tryCatch) to insert `wfa.stage()` calls at positions identified
+ * by `stageInsertionMap`.
+ *
+ * Matched entries are removed from the map so they aren't inserted twice.
+ * Call this AFTER top-level stages have been handled.
+ */
+export declare function insertNestedStageShapes(shapes: Shape[], stageInsertionMap: Map<number, string[]>, paramName: string, orderFn: (rec: Record) => number): void;