@yarlisai/workflow-validation

Pure DAG validation primitives for visual workflow builders. Detects dangling cross-block references (<blockName.path>) and gates deploys on blocking errors. Zero runtime dependencies, no React or state-store coupling.

Install

bun add @yarlisai/workflow-validation@alpha

Concepts

A workflow graph is just Record<string, BlockLike> — every block has an id, a name, and (optionally) subBlocks whose values may contain references like <api1.body.foo>. The validator walks every string leaf inside every subBlock value and checks each reference's prefix against the set of known blocks.

A reference is <prefix.path>. The prefix is normalized via normalizeBlockName(name) (lowercase + whitespace stripped) so "<API 1.foo>" and "<api1.foo>" collapse to the same target.

A system prefix is always valid even if no block has that name:

• start, loop, parallel, variable — workflow control-flow / variables
• api, chat, manual, webhook, schedule — trigger aliases (configurable)

Usage

import {
  validateReferences,
  canDeploy,
  createValidator,
} from '@yarlisai/workflow-validation'

// Pure functional API
const { issues } = validateReferences(workflow.blocks)
const gate = canDeploy(issues)
if (!gate.ok) console.warn(gate.reason)

// Facade API (binds a graph)
const v = createValidator(workflow.blocks)
const result = v.validate()
const ok = v.canDeploy(result.issues).ok

Custom trigger aliases

validateReferences(blocks, {
  extraValidPrefixes: ['api', 'chat', 'manual', 'webhook', 'schedule', 'cron'],
})

Lower-level normalization helpers

Re-exported for callers that already had extractReferencePrefixes / normalizeBlockName in their codebase:

import {
  normalizeBlockName,
  extractReferencePrefixes,
  isLikelyReferenceSegment,
  SYSTEM_REFERENCE_PREFIXES,
} from '@yarlisai/workflow-validation'

normalizeBlockName('My API 1') // → 'myapi1'
extractReferencePrefixes('hello <api1.body.x> and <bad>') // → [{ raw: '<api1.body.x>', prefix: 'api1' }, ...]

Severity model

Today the reference validator only emits 'warning' severity, so deploys are never blocked by reference issues. The 'error' channel is plumbed through ValidationIssue.severity so future rules (cyclic deps, type mismatches) can gate deploy without changing the response shape — canDeploy already counts errors and surfaces a reason.

Build

bun install
cd packages/workflow-validation
bun run build

License

MIT