packages/engine/workflowGenerator
Ticket 7.3 -- JSON state graph -> XState v5 workflow AST generator.
Engine, next. Source: packages/engine/workflowGenerator.mjs.
Variables#
STATE_UNION_MARKER#
constSTATE_UNION_MARKER:"// Generated by `construct generate workflow --state-union`."='// Generated by `construct generate workflow --state-union`.'
Defined in: packages/engine/workflowGenerator.mjs:323
First line of every emitted state-union file. It is the one signal
generateWorkflow trusts to tell "a file this block wrote, free to
regenerate" apart from "hand-written content, never overwrite".
Functions#
compileStateUnion()#
compileStateUnion(
descriptor,opts):object
Defined in: packages/engine/workflowGenerator.mjs:340
Compile a descriptor's states into a <Name>State discriminated union
(one { status: '<state>' } member per state, nothing else) plus an
exhaustive-match helper and an assertNever for switch statements.
Pure -- no filesystem access; byte-stable for the same descriptor.
Parameters#
descriptor
any
The same JSON state-graph descriptor compileWorkflow takes.
opts
name is the already-capitalized layer base name (e.g. "Checkout").
name
string
Returns#
object
The file text and the state names, in descriptor order.
source
source:
string
states
states:
string[]
compileWorkflow()#
compileWorkflow(
descriptor,opts):object
Defined in: packages/engine/workflowGenerator.mjs:254
Compile a JSON state-graph descriptor into an XState v5 workflow source file. Pure -- no filesystem access.
Parameters#
descriptor
any
{id?, initial, context?: {field: {type, default}}, guards?: {name: note}, states: {...}}.
guards is optional: each entry becomes a named stub in setup()'s guards: map that
returns false with a // TODO: <note> comment -- typically the req sentence the guard exists
to satisfy -- so a transition that names a guard always compiles against a real (if unimplemented)
predicate instead of a dangling string.
eventPayloads maps an event name to a TS type string whose members join { type } in
the event union; typeImports ([{from, names[]}]) adds import type lines for the names those
payload types (or context fields) refer to.
opts
name is the already-capitalized layer base name (e.g. "Checkout").
name
string
Returns#
object
contextFields
contextFields:
string[]
events
events:
string[]
source
source:
string
eventsToEnvelope()#
eventsToEnvelope(
eventNames):any
Defined in: packages/engine/workflowGenerator.mjs:130
Shape events (a list of event name strings) into the Context Envelope
(schemas/envelope.v1.json) events: [{type, payload}] array, for
downstream consumers such as Ticket 7.4's controller binder.
Parameters#
eventNames
any
Returns#
any
extractEventNames()#
extractEventNames(
statesJson):any[]
Defined in: packages/engine/workflowGenerator.mjs:119
Every distinct event name referenced across all states' on maps, in
first-appearance order (Object.entries preserves insertion order).
Parameters#
statesJson
any
Returns#
any[]
generateWorkflow()#
generateWorkflow(
root,name,feature,descriptor,options?):object
Defined in: packages/engine/workflowGenerator.mjs:393
Ingest a JSON state-graph descriptor as feature feature's <name>
workflow: writes features/<feature>/workflows/<Name>Workflow.tsx, then
re-validates via generators.mjs's shared selfCheck. With
{ stateUnion: true } it also writes <Name>WorkflowState.ts beside it
(see compileStateUnion); nothing at all is written if that file already
holds real content.
Parameters#
root
string
Project root.
name
string
Workflow name (turned into a valid identifier).
feature
string
Feature that owns the workflow.
descriptor
any
JSON state-graph descriptor.
options?
stateUnion also emits the typed state union and exhaustive matcher.
stateUnion?
boolean = false
Returns#
object
The written file(s) and what the machine exposes.
contextFields
contextFields:
string[]
events
events:
string[]
file
file:
string
stateFile?
optionalstateFile?:string
parseTypeString()#
parseTypeString(
typeStr):TypeNode
Defined in: packages/engine/workflowGenerator.mjs:48
Parse a standalone TS type string (e.g. "number", "string | null") into a real ts.TypeNode via
the compiler API's own parser -- so a hand-authored type string in a descriptor (a context field,
or 's function input/output types) prints back out exactly as valid TS, whatever its shape,
instead of being pasted in as unchecked text. Exported so other generators that accept the same
kind of free-form TS-type-as-string field (packages/core/research/specToCode.mjs's function
stubs) reuse this exact parse-and-reprint step instead of a second copy of it.
Parameters#
typeStr
string
A standalone TypeScript type expression (e.g. "string | null").
Returns#
TypeNode
The parsed type node, ready to print or splice into other AST.
Throws#
When typeStr is not a valid standalone TS type.