@flowget/graph-validation

Isomorphic, zero-runtime-dependency static validator for Flowget workflow graphs.

This is the single source of validation logic shared by the Flowget builder (design-time, pre-submit) and the Flowget worker (host-side, pre-flight). Because both call the exact same pure functions over the exact same (graph, catalog) input, the builder's verdict and the worker's verdict are equal by construction — a graph the builder accepts is a graph the worker accepts.

Contingency. "Equal by construction" holds given both consumers feed catalogs derived from the same node-definition source. Catalog outputFields / triggerPayload / options can be factory functions — code, not data — so this package guarantees the validation function is identical, not that the two sides' catalog inputs are. Keeping those definitions in sync is the job of the shared registry and the compareFieldCoherence boot check, not of this validator.

What it does:

• Template-grammar classifier — parses {{ … }} template strings into the @flowget/types TemplateAst (v2-step / v1-reserved / v1-step operands, ?? fallback chains). ReDoS-safe on untrusted input.
• Reference existence + reachability — every {{ steps.<id>.output.<key> }} token must name a real upstream node and a declared output.
• Nested fields via dotted keys — a . in an OutputField / trigger-payload key is the path separator (matching the template grammar, which has no bracket form). A flat list of payment.id / payment.amount reconstructs a payment object so {{ trigger.payment.amount }} resolves at leaf granularity. An undeclared nested child is an advisory warning (the runtime payload may still carry it); a key declared as both a scalar and an object parent is a hard error.
• Coarse value-type lattice — isAssignable(producer, consumer) over the FieldValueType set; permissive on unknown / object / array so a "valid" verdict never lies (zero false positives).
• Declarative field rules — required, coarse type, enum membership, min / max / pattern.
• validateGraphStatic(graph, catalog) — the aggregator, returning a flat ValidationIssue[].
• validateTriggerInputs(graph, catalog, input) — a run-input gate: flags every {{ trigger.<path> }} the graph references that the run input (the builder's test input, or the worker's real event payload) does not provide, path-aware and false-positive-free. Config traversal is bounded (a stack-overflow-DoS guard); a reference nested deeper than the bound is left to the runtime resolver's non-retryable throw rather than pre-checked.

Install

npm install @flowget/graph-validation

@flowget/types is a peer dependency (>=0.5.0 <1.0.0) — install it too if it is not already in your tree.

Usage

import { validateGraphStatic } from "@flowget/graph-validation";

const issues = validateGraphStatic(graph, catalog);

const blocking = issues.filter((i) => i.severity === "error");
if (blocking.length > 0) {
  // builder: disable the Run button; worker: refuse the pre-flight
}

graph is a @flowget/types WorkflowGraph; catalog is the list of node definitions (structurally a subset of NodeMetadata<BuilderHints>), fed identically by both consumers.

⚠️ 0.x is unstable

This package is on the 0.x line. The surface may change in breaking ways between 0.x minors until 1.0.0 (0.x semver: minor = breaking, patch = additive). Pin a caret range and read the CHANGELOG before upgrading.

Links

• Docs: https://docs.flowget.io
• Contract types: @flowget/types