@workglow/task-graph 0.2.13 → 0.2.15

package/dist/task-graph/__tests__/transforms/string-casts.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};
+//# sourceMappingURL=string-casts.test.d.ts.map

package/dist/task-graph/__tests__/transforms/string-casts.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string-casts.test.d.ts","sourceRoot":"","sources":["../../../../src/task-graph/__tests__/transforms/string-casts.test.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/task-graph/autoConnect.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ITask } from "../task/ITask";
+import type { TaskGraph } from "./TaskGraph";
+/**
+ * Auto-connects two tasks based on their schemas.
+ * Uses multiple matching strategies:
+ * 1. Match by type AND port name (highest priority)
+ * 2. Match by specific type only (format, $id) for unmatched ports
+ * 3. Look back through earlier tasks for unmatched required inputs
+ *
+ * @param graph - The task graph to add dataflows to
+ * @param sourceTask - The source task to connect from
+ * @param targetTask - The target task to connect to
+ * @param options - Optional configuration for the auto-connect operation
+ * @returns Result containing matches made, any errors, and unmatched required inputs
+ */
+export declare function autoConnect(graph: TaskGraph, sourceTask: ITask, targetTask: ITask, options?: {
+    /** Keys of inputs that are already provided and don't need connection */
+    readonly providedInputKeys?: Set<string>;
+    /** Keys of inputs that are already connected via dataflow (e.g., from rename) and must not be re-matched */
+    readonly connectedInputKeys?: Set<string>;
+    /** Earlier tasks to search for unmatched required inputs (in reverse chronological order) */
+    readonly earlierTasks?: readonly ITask[];
+    /**
+     * When true, skip `graph.addDataflow(...)` side effects and return matches
+     * only. Used by callers (e.g. the builder's proximity auto-connect) that
+     * need to know what *would* be connected without mutating the graph.
+     */
+    readonly dryRun?: boolean;
+}): {
+    readonly matches: Map<string, string>;
+    readonly error?: string;
+    readonly unmatchedRequired: readonly string[];
+};
+//# sourceMappingURL=autoConnect.d.ts.map

package/dist/task-graph/autoConnect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoConnect.d.ts","sourceRoot":"","sources":["../../src/task-graph/autoConnect.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAI3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,EAChB,UAAU,EAAE,KAAK,EACjB,UAAU,EAAE,KAAK,EACjB,OAAO,CAAC,EAAE;IACR,yEAAyE;IACzE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzC,4GAA4G;IAC5G,QAAQ,CAAC,kBAAkB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1C,6FAA6F;IAC7F,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,KAAK,EAAE,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B,GACA;IACD,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/C,CA0aA"}

package/dist/task-graph/transforms/coalesce.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @license Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ITransformDef } from "../TransformTypes";
+interface CoalesceParams {
+    readonly defaultValue: unknown;
+}
+export declare const coalesceTransform: ITransformDef<CoalesceParams>;
+export {};
+//# sourceMappingURL=coalesce.d.ts.map

package/dist/task-graph/transforms/coalesce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coalesce.d.ts","sourceRoot":"","sources":["../../../src/task-graph/transforms/coalesce.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,UAAU,cAAc;IACtB,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AAaD,eAAO,MAAM,iBAAiB,EAAE,aAAa,CAAC,cAAc,CAW3D,CAAC"}

package/dist/task-graph/transforms/date-conversions.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @license Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ITransformDef } from "../TransformTypes";
+interface UnixUnit {
+    readonly unit: "s" | "ms";
+}
+export declare const unixToIsoDateTransform: ITransformDef<UnixUnit>;
+export declare const isoDateToUnixTransform: ITransformDef<{}>;
+export {};
+//# sourceMappingURL=date-conversions.d.ts.map

package/dist/task-graph/transforms/date-conversions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"date-conversions.d.ts","sourceRoot":"","sources":["../../../src/task-graph/transforms/date-conversions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,UAAU,QAAQ;IAChB,QAAQ,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,CAAC;CAC3B;AAUD,eAAO,MAAM,sBAAsB,EAAE,aAAa,CAAC,QAAQ,CAwB1D,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,aAAa,CAAC,EAAE,CAapD,CAAC"}

package/dist/task-graph/transforms/index-access.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @license Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ITransformDef } from "../TransformTypes";
+interface IndexParams {
+    readonly index: number;
+}
+export declare const indexTransform: ITransformDef<IndexParams>;
+export {};
+//# sourceMappingURL=index-access.d.ts.map

package/dist/task-graph/transforms/index-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-access.d.ts","sourceRoot":"","sources":["../../../src/task-graph/transforms/index-access.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,UAAU,WAAW;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAQD,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC,WAAW,CA8BrD,CAAC"}

package/dist/task-graph/transforms/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { pickTransform } from "./pick";
+import { indexTransform } from "./index-access";
+import { coalesceTransform } from "./coalesce";
+import { uppercaseTransform, lowercaseTransform, truncateTransform, substringTransform } from "./string-casts";
+import { unixToIsoDateTransform, isoDateToUnixTransform } from "./date-conversions";
+import { numberToStringTransform, toBooleanTransform, stringifyTransform, parseJsonTransform } from "./scalar-conversions";
+export { pickTransform, indexTransform, coalesceTransform, uppercaseTransform, lowercaseTransform, truncateTransform, substringTransform, unixToIsoDateTransform, isoDateToUnixTransform, numberToStringTransform, toBooleanTransform, stringifyTransform, parseJsonTransform, };
+/**
+ * Registers all MVP built-in transforms. Separate from registerBaseTasks so
+ * consumers can opt in independently (tests may want transforms without
+ * task registration and vice versa).
+ */
+export declare function registerBuiltInTransforms(): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/task-graph/transforms/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/task-graph/transforms/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,GACnB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAiBhD"}

package/dist/task-graph/transforms/pick.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @license Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ITransformDef } from "../TransformTypes";
+interface PickParams {
+    readonly path: string;
+}
+export declare const pickTransform: ITransformDef<PickParams>;
+export {};
+//# sourceMappingURL=pick.d.ts.map

package/dist/task-graph/transforms/pick.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pick.d.ts","sourceRoot":"","sources":["../../../src/task-graph/transforms/pick.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,UAAU,UAAU;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AA0BD,eAAO,MAAM,aAAa,EAAE,aAAa,CAAC,UAAU,CAiCnD,CAAC"}

package/dist/task-graph/transforms/scalar-conversions.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @license Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ITransformDef } from "../TransformTypes";
+export declare const numberToStringTransform: ITransformDef<{}>;
+export declare const toBooleanTransform: ITransformDef<{}>;
+export declare const stringifyTransform: ITransformDef<{}>;
+export declare const parseJsonTransform: ITransformDef<{}>;
+//# sourceMappingURL=scalar-conversions.d.ts.map

package/dist/task-graph/transforms/scalar-conversions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scalar-conversions.d.ts","sourceRoot":"","sources":["../../../src/task-graph/transforms/scalar-conversions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAKvD,eAAO,MAAM,uBAAuB,EAAE,aAAa,CAAC,EAAE,CAerD,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,aAAa,CAAC,EAAE,CAYhD,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,aAAa,CAAC,EAAE,CAWhD,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,aAAa,CAAC,EAAE,CAOhD,CAAC"}

package/dist/task-graph/transforms/string-casts.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ITransformDef } from "../TransformTypes";
+export declare const uppercaseTransform: ITransformDef<{}>;
+export declare const lowercaseTransform: ITransformDef<{}>;
+interface TruncateParams {
+    readonly max: number;
+}
+export declare const truncateTransform: ITransformDef<TruncateParams>;
+interface SubstringParams {
+    readonly start: number;
+    readonly end: number | undefined;
+}
+export declare const substringTransform: ITransformDef<SubstringParams>;
+export {};
+//# sourceMappingURL=string-casts.d.ts.map

package/dist/task-graph/transforms/string-casts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string-casts.d.ts","sourceRoot":"","sources":["../../../src/task-graph/transforms/string-casts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAIvD,eAAO,MAAM,kBAAkB,EAAE,aAAa,CAAC,EAAE,CAOhD,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,aAAa,CAAC,EAAE,CAOhD,CAAC;AAEF,UAAU,cAAc;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,iBAAiB,EAAE,aAAa,CAAC,cAAc,CAW3D,CAAC;AAEF,UAAU,eAAe;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED,eAAO,MAAM,kBAAkB,EAAE,aAAa,CAAC,eAAe,CAc7D,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@workglow/task-graph",
   "type": "module",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "repository": {
     "type": "git",
     "url": "https://github.com/workglow-dev/workglow.git",
@@ -51,9 +51,9 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@workglow/job-queue": "0.2.13",
-    "@workglow/storage": "0.2.13",
-    "@workglow/util": "0.2.13"
+    "@workglow/job-queue": "0.2.15",
+    "@workglow/storage": "0.2.15",
+    "@workglow/util": "0.2.15"
   },
   "peerDependenciesMeta": {
     "@workglow/job-queue": {
@@ -67,8 +67,8 @@
     }
   },
   "devDependencies": {
-    "@workglow/job-queue": "0.2.13",
-    "@workglow/storage": "0.2.13",
-    "@workglow/util": "0.2.13"
+    "@workglow/job-queue": "0.2.15",
+    "@workglow/storage": "0.2.15",
+    "@workglow/util": "0.2.15"
   }
 }

package/src/EXECUTION_MODEL.md

@@ -288,6 +288,12 @@ This ensures:
 
 ## Key Invariants
 
+### 0. Cycle Guarantees
+
+- `TaskGraph` is a `DirectedAcyclicGraph`. The underlying `TaskGraphDAG` extends `DirectedAcyclicGraph` from `@workglow/util/graph`.
+- `TaskGraph.addDataflow` throws `CycleError` **synchronously** whenever the new edge would close a cycle. Detection runs inside `DirectedAcyclicGraph.addEdge` via `wouldAddingEdgeCreateCycle`, so no graph can ever reach a cyclic state — cycles are rejected at the construction call, not at run time.
+- Loop tasks (`WhileTask`, `IteratorTask`, `MapTask`, `ReduceTask`) achieve repetition by re-running an internally-acyclic subgraph once per iteration, never by adding back-edges. Each subgraph is its own `TaskGraph` and inherits the same invariant. `GraphAsTask.validateAcyclic()` re-asserts the invariant when the subgraph is finalized, so any direct `_dag` manipulation is caught before execution.
+
 ### 1. COMPLETED Tasks Are Immutable
 
 Once a task's `run()` completes and status becomes `COMPLETED`: