Workflow API

Core types for defining and executing workflows in Strategos.

Workflow<TState>

Entry point for fluent workflow definitions. Creates a workflow builder for the specified state type.

Methods

Method	Returns	Description
Create(string name)	IWorkflowBuilder<TState>	Creates a new workflow with the given name

Example

Workflow<OrderState>.Create("process-order")
    .StartWith<ValidateOrderStep>()
    .Then<ProcessPaymentStep>()
    .Finally<FulfillOrderStep>();

---

IWorkflowStep<TState>

Interface for implementing workflow steps. Each step receives state, executes logic, and returns updated state.

Methods

Method	Parameters	Returns	Description
ExecuteAsync	TState state, StepContext context, CancellationToken ct	Task<StepResult<TState>>	Executes the step logic

Example

public class ValidateOrderStep : IWorkflowStep<OrderState>
{
    public async Task<StepResult<OrderState>> ExecuteAsync(
        OrderState state,
        StepContext context,
        CancellationToken ct)
    {
        var isValid = await ValidateAsync(state.Order, ct);

        return state
            .With(s => s.IsValid, isValid)
            .AsResult();
    }
}

---

IWorkflowDefinition<TState>

Interface for workflow definition classes. Implemented by generated partial classes.

Properties

Property	Type	Description
Definition	WorkflowDefinition<TState>	The complete workflow definition

Example

[Workflow("process-order")]
public static partial class ProcessOrderWorkflow : IWorkflowDefinition<OrderState>
{
    public static WorkflowDefinition<OrderState> Definition =>
        Workflow<OrderState>.Create("process-order")
            .StartWith<ValidateOrderStep>()
            .Finally<CompleteOrderStep>();
}

---

StepResult<TState>

Result type returned from step execution. Contains the updated state and optional routing information.

Properties

Property	Type	Description
State	TState	The updated workflow state
BranchValue	object?	Optional value for branch routing
IsComplete	bool	Whether workflow should terminate

Creation Methods

Method	Description
state.AsResult()	Creates result with updated state
state.AsResult(branchValue)	Creates result with branch routing
StepResult<TState>.Complete(state)	Creates terminal result

Example

// Simple state update
return state.With(s => s.Status, "Validated").AsResult();

// With branch routing
return state.AsResult(state.OrderType);  // Routes based on OrderType

// Terminal result
return StepResult<OrderState>.Complete(state);

---

StepContext

Execution context passed to every step. Contains metadata about the current execution.

Properties

Property	Type	Description
WorkflowId	Guid	Unique identifier for this workflow instance
CorrelationId	string	Correlation ID for tracing
Timestamp	DateTimeOffset	When the step execution started
Phase	string	Current workflow phase name
StepName	string	Current step name
Metadata	IReadOnlyDictionary<string, object>	Additional context data

Example

public async Task<StepResult<OrderState>> ExecuteAsync(
    OrderState state,
    StepContext context,
    CancellationToken ct)
{
    _logger.LogInformation(
        "Processing order {WorkflowId} at phase {Phase}",
        context.WorkflowId,
        context.Phase);

    // Step logic...
}

---

State Attributes

Attributes that control how state properties are merged between steps.

[WorkflowState]

Marks a record as workflow state. Required for source generator to produce state reducers.

[WorkflowState]
public record OrderState
{
    public Guid OrderId { get; init; }
    public string Status { get; init; }
}

[Append]

Merge lists by appending new items to existing items.

Constraint	Value
Valid On	Collection properties (List<T>, IList<T>, etc.)
Behavior	Combines source and target lists

[WorkflowState]
public record OrderState
{
    [Append]
    public List<string> AuditLog { get; init; } = new();
}

Merge Behavior:

// Before: AuditLog = ["Created", "Validated"]
// Update: AuditLog = ["Payment processed"]
// After:  AuditLog = ["Created", "Validated", "Payment processed"]

[Merge]

Merge dictionaries. New values overwrite existing keys.

Constraint	Value
Valid On	Dictionary properties (Dictionary<TKey, TValue>)
Behavior	Combines dictionaries, newer values win

[WorkflowState]
public record OrderState
{
    [Merge]
    public Dictionary<string, decimal> LinePrices { get; init; } = new();
}

Merge Behavior:

// Before: LinePrices = {"item1": 10.00, "item2": 20.00}
// Update: LinePrices = {"item2": 25.00, "item3": 30.00}
// After:  LinePrices = {"item1": 10.00, "item2": 25.00, "item3": 30.00}

---

Fluent Builder Methods

Methods available on the workflow builder for constructing workflow definitions.

Flow Control

Method	Description
StartWith<TStep>()	First step in workflow (required)
Then<TStep>()	Sequential step
Finally<TStep>()	Terminal step (recommended)

Branching

Method	Description
Branch(selector, cases...)	Route based on state value
BranchCase<TValue>(value, builder)	Define branch case
Otherwise(builder)	Default branch case

Parallel Execution

Method	Description
Fork(paths...)	Execute paths in parallel
Join<TStep>()	Merge parallel results

Loops

Method	Description
RepeatUntil(condition, name, builder)	Loop until condition is true

Human-in-the-Loop

Method	Description
AwaitApproval<TStep>()	Pause for human approval

Example

Workflow<OrderState>.Create("process-order")
    .StartWith<ValidateOrderStep>()
    .Branch(s => s.OrderType,
        BranchCase<OrderType>(OrderType.Standard, path => path
            .Then<ProcessStandardStep>()),
        BranchCase<OrderType>(OrderType.Express, path => path
            .Then<ProcessExpressStep>()),
        Otherwise(path => path
            .Then<ProcessCustomStep>()))
    .Fork(
        path => path.Then<NotifyCustomerStep>(),
        path => path.Then<UpdateInventoryStep>())
    .Join<AggregateResultsStep>()
    .AwaitApproval<ShipmentApprovalStep>()
    .Finally<FulfillOrderStep>();