API Reference: Step Methods (`Step`)

The Step class is the fundamental execution unit in Siglo. A step encapsulates an async action, parameter validation contracts, lifecycle hooks, structured retry policies, SLA deadlines, idempotency locks, caching, and saga compensations.

The 5-Phase Step Lifecycle
Instantiating Steps
- Step.create(name?, action)
Validation and Contracts
Lifecycle Hooks
Fault Tolerance and Resilience
Optimization and Deduplication
- step.idempotent(keyOrFn?, options?)
- step.cache(msOrOptions)
Dependency Injection
- step.withDependencies(deps)
- step.requireDependency(key)
Context Transformation
- step.reduce(field)
Network Egress Guardrails
Execution and Inspection
- step.run and step.execute
- step.toGraph, step.inspect, step.toMermaid
Static Methods and Configuration

The 5-Phase Step Lifecycle

Every step executes through five distinct, deterministic phases:

Validation: Enforces parameter constraints declared via .schema() or .spec(). Rejections throw ValidationException.
Pre-Execution Guard (onBefore): Evaluates whether the step should run. Returning false bypasses the action and triggers onSkip.
Action Execution: Runs the step action under the configured timeout, idempotent lock, and onFail retry strategy.
Post-Execution Transform (onAfter): Modifies or enriches the raw output before merging.
Context Merge: Merges step output into the accumulated workflow context (or assigns it to a target property if .reduce() was configured).

[!NOTE] Network Guardrails Across Lifecycle Phases: When .allowNetwork(), .allowUnixSockets(), .denyNetwork(), or .networkPolicy() is declared, the network egress policy governs phases 2 (onBefore/onSkip), 3 (action), 4 (onAfter), and onFail through Node’s AsyncLocalStorage. Any unauthorized outbound call triggers a NetworkPolicyViolationException tagged with the active phase (before, action, or after).

Instantiating Steps

`Step.create(name?, action)`

Instantiates a typed Step execution unit with input and output contracts.

Signatures

export type StepAction<TInput = any, TOutput = any> = (
    parameter: TInput,
    current?: any,
    index?: number,
) => TOutput | Promise<TOutput>;

export class Step<TInput = any, TOutput = any, TName extends string = string> {
    static create<TName extends string, TIn = any, TOut = any>(
        name: TName,
        action?: StepAction<TIn, TOut>,
    ): Step<TIn, TOut, TName>;

    static create<TIn = any, TOut = any>(action: StepAction<TIn, TOut> | Flow<TIn, TOut>): Step<TIn, TOut, string>;
}

Example

import { Step } from '@siglo/core';

interface UserInput {
    userId: string;
}

interface UserOutput {
    name: string;
    email: string;
}

export const fetchUser = Step.create('fetchUser', async (param: UserInput): Promise<UserOutput> => {
    return { name: 'Bob', email: '[email protected]' };
});

Validation and Contracts

`step.schema(schema)`

Validates the incoming execution context against standard schema validators supporting the Standard Schema specification (~standard), including Zod, Valibot, and ArkType.

Signature

step.schema<TSchema = any>(schemaObj: TSchema): Step<TInput, TOutput, TName>;

Example with Zod

import { Step } from '@siglo/core';
import { z } from 'zod';

const OrderInputSchema = z.object({
    orderId: z.string().min(1),
    amount: z.number().positive(),
    currency: z.enum(['USD', 'EUR', 'GBP']),
});

export const processPayment = Step.create('processPayment', async (param: z.infer<typeof OrderInputSchema>) => {
    return { paymentCaptured: true };
}).schema(OrderInputSchema);

If validation fails, a ValidationException is thrown before the step action executes, containing detailed issue descriptions in err.errors.

`step.spec(field, options)`

Declares granular parameter constraints, default values, transforms, and translations for a specific context field.

Signature

export interface SpecData {
    require?: boolean;
    requireMessage?: string;
    default?: any;
    validate?: (value: any) => boolean;
    transform?: (value: any) => any;
    translate?: string; // Rename field in context
    schema?: any;       // Standard schema for this field
}

step.spec(field: string, options: SpecData): Step<TInput, TOutput, TName>;

Example

const sanitizeInput = Step.create('sanitizeInput', async (param: any) => {
    return { cleanEmail: param.userEmail };
})
    .spec('email', {
        require: true,
        requireMessage: 'Customer email is mandatory.',
        validate: async (v: string) => v.includes('@'),
        transform: async (v: string) => v.trim().toLowerCase(),
        translate: async (param: any, value: string) => {
            param.userEmail = value;
        },
    })
    .spec('newsletterOptIn', {
        default: false,
    });

`step.strict()`

Enforces strict parameter filtering on incoming parameters, selecting only declared spec fields and filtering out undeclared properties before the action executes.

Signature

step.strict(): Step<TInput, TOutput, TName>;

Example

const strictStep = Step.create('createAccount', async (param: any) => {
    // Only declared spec fields ('username') are present in param; extra keys are filtered
    return { created: param.username, hasExtra: 'extraField' in param };
})
    .spec('username', { require: true })
    .strict();

const result = await strictStep.run({ username: 'alice', extraField: 'filtered out' } as any);
console.log(result.hasExtra); // false

Lifecycle Hooks

`step.onBefore(hook)`

Pre-execution guard hook. Evaluates the incoming parameter context before the action executes. If it returns false, step action execution is skipped and control transfers to onSkip (or context passes through unchanged).

Signature

export type OnBeforeAction<TInput = any> = (
    parameter: TInput
) => boolean | Promise<boolean>;

step.onBefore(hook: OnBeforeAction<TInput>): Step<TInput, TOutput, TName>;

Example

const sendInvoice = Step.create('sendInvoice', async (param: { amount: number }) => ({ invoiceSent: true })).onBefore(
    param => param.amount > 0,
); // Skip if amount is 0

`step.onSkip(hook)`

Fallback hook that executes if and only if onBefore returns false. Its returned value is merged into the context in place of the step action output.

Signature

export type OnSkipAction<TInput = any, TFallback = any> = (
    parameter: TInput
) => TFallback | Promise<TFallback>;

step.onSkip(hook: OnSkipAction<TInput>): Step<TInput, TOutput, TName>;

Example

const chargeSubscription = Step.create('charge', async () => ({ charged: true }))
    .onBefore((param: { isTrial: boolean }) => !param.isTrial)
    .onSkip(param => ({ charged: false, trialSkipped: true }));

`step.onAfter(hook)`

Post-execution transformation hook. Receives the raw output produced by the step action and the input parameters, returning an enriched or transformed output.

Signature

export type OnAfterAction<TOutput = any, TInput = any> = (
    output: TOutput,
    parameter: TInput
) => any | Promise<any>;

step.onAfter(hook: OnAfterAction<TOutput, TInput>): Step<TInput, TOutput, TName>;

Example

const calculateTax = Step.create('calcTax', async (param: { subtotal: number }) => ({
    tax: param.subtotal * 0.08,
})).onAfter((output, param) => ({
    ...output,
    totalWithTax: param.subtotal + output.tax,
}));

Fault Tolerance and Resilience

`step.timeout(ms)`

Enforces a per-step SLA deadline in milliseconds. If the step action takes longer than ms, the action is aborted via AbortSignal and throws a StepTimeoutException.

Signature

step.timeout(ms: number): Step<TInput, TOutput, TName>;

Example

import { Step, StepTimeoutException } from '@siglo/core';

const callExternalVendor = Step.create('vendorApi', async () => {
    const res = await fetch('https://api.vendor.com/data');
    return res.json();
}).timeout(2000); // 2-second timeout

`step.onFail(config)`

Configures structured retry policies or custom error fallback handlers when the step action throws.

Signatures

export interface RetryConfig {
    maxRetries?: number;
    delay?: number;
    backoff?: 'fixed' | 'linear' | 'exponential' | ((attempt: number) => number);
    jitter?: boolean | ((delay: number) => number);
    maxDelay?: number;
    retryIf?: (err: any, attempt: number) => boolean;
    onRetry?: (error: any, attempt: number, delayMs?: number) => void;
}

export type OnFailCallback = (
    error: any,
    retry: (fallback?: any) => void,
    reject: (err?: any) => void
) => any;

step.onFail(config: RetryConfig | OnFailCallback): Step<TInput, TOutput, TName>;

Example with Exponential Backoff & Jitter

const resilientFetch = Step.create('fetchData', async () => {
    return await externalService.call();
}).onFail({
    maxRetries: 3,
    delay: 500,
    backoff: 'exponential',
    jitter: true,
    maxDelay: 5000,
    retryIf: err => err.status >= 500, // Only retry 5xx server errors
    onRetry: (err, attempt) => console.warn(`Retry attempt ${attempt} due to ${err.message}`),
});

Example with OnFail Fallback

To provide a graceful fallback return value when errors occur, use the callback form:

const resilientFetchWithFallback = Step.create('fetchData', async () => {
    return await externalService.call();
}).onFail((err, retry, reject) => {
    if (err.status >= 500) {
        retry({ fallbackData: true }); // Resolves step with fallback data
    } else {
        reject(err);
    }
});

`step.compensate(handler, options?)`

Registers a saga compensation rollback handler. If downstream steps in the workflow fail, registered compensation handlers execute automatically in reverse order (LIFO).

Signature

export interface CompensationOptions {
    maxRetries?: number;
    delay?: number;
    retryIf?: (err: any, attempt: number) => boolean;
}

step.compensate(
    handler: (ctx: any) => Promise<void> | void,
    options?: CompensationOptions
): Step<TInput, TOutput, TName>;

Example

const bookFlight = Step.create('bookFlight', async (ctx: { flightNo: string }) => {
    const booking = await airlineApi.reserve(ctx.flightNo);
    return { flightReservationId: booking.id };
}).compensate(
    async ctx => {
        // Automatically called if payment or hotel booking fails downstream
        await airlineApi.cancelReservation(ctx.flightReservationId);
    },
    { maxRetries: 3, delay: 1000 },
);

Optimization and Deduplication

`step.idempotent(keyOrFn?, options?)`

Guarantees step deduplication and concurrent claim locking using deterministic idempotency keys and TTL storage.

Signature

step.idempotent(
    keyOrFn?: string | ((ctx: any) => string),
    options?: { ttlMs?: number; store?: IdempotencyStore }
): Step<TInput, TOutput, TName>;

Semantics

Claiming: Before execution, attempts to claim the key in the configured IdempotencyStore.
Conflict: If already in-progress, throws IdempotencyConflictException.
Cache Hit: If previously completed and within TTL, returns cached output without re-executing.
Completion: Upon successful execution, records output and marks status COMPLETED.

Example

const chargeCard = Step.create('chargeCard', async (ctx: { idempotencyToken: string; amount: number }) => {
    return await stripe.charges.create({ amount: ctx.amount });
}).idempotent(ctx => ctx.idempotencyToken, { ttlMs: 86400000 }); // 24-hour TTL

`step.cache(msOrOptions)`

Caches step output in memory or persistent storage (StorageAdapter) based on input parameters.

Signatures

export interface CacheOptions {
    ttl?: number;
    staleWhileRevalidate?: number;
    swr?: boolean | number;
    keySerializer?: (stepId: string, param: any, namespace?: string) => string;
    stampedeProtection?: boolean;
}

step.cache(cachedLastOrOptions?: number | CacheOptions): Step<TInput, TOutput, TName>;

Example

const getExchangeRates = Step.create('rates', async () => {
    return await fetchRates();
}).cache({ ttl: 60000 }); // Cache for 60 seconds

Dependency Injection

`step.withDependencies(deps)`

Attaches runtime dependencies and service repositories directly to the step.

Signature

step.withDependencies(dependencies: Record<string, any>): this;

`step.requireDependency(key)`

Retrieves a required injected dependency or throws a descriptive error if missing.

Signature

step.requireDependency<T = any>(key: string): T;

Example

interface DatabaseClient {
    query: (sql: string) => Promise<any>;
}

const saveUser = Step.create('saveUser', async (param: { name: string }) => {
    const db = saveUser.requireDependency<DatabaseClient>('db');
    await db.query(`INSERT INTO users (name) VALUES ('${param.name}')`);
    return { saved: true };
}).withDependencies({ db: myDbClient });

Context Transformation

`step.reduce(field)`

Assigns the step output directly to a designated field in the accumulated context instead of shallow-merging properties.

Signature

step.reduce(field: string): Step<TInput, TOutput, TName>;

Example

const countItems = Step.create('count', async () => 42).reduce('itemCount');

// Output context: { itemCount: 42 } rather than { value: 42 }

Network Egress Guardrails

Steps can declare granular network egress permissions enforced via Node’s AsyncLocalStorage (ASL). In flows with an outer network policy, the flow supersedes the step; steps can only narrow permissions within what the flow permits. By default, loopback addresses (localhost, 127.0.0.1, ::1, 0.0.0.0) and local Unix domain socket IPC are allowed.

Lifecycle Hook Governance

The network policy boundary wraps the entire step execution lifecycle via AsyncLocalStorage:

onBefore & onSkip: Pre-execution guards and fallback computations are governed by the step’s allowlist (violations tagged with phase: 'before').
action & reduce: The core step execution runs within the policy context (violations tagged with phase: 'action').
onAfter: Context enrichment and post-processing cannot bypass step network restrictions (violations tagged with phase: 'after').
onFail: Step-level retries and fallback error handlers adhere to the policy perimeter.
Global Plugins (executeBefore, executeAfter): Engine-level plugins execute outside this boundary to ensure system observability and metrics remain unaffected.
Compensations (step.compensate): Sagas rollback in an independent scope with their own execution perimeter.

`step.allowNetwork(hosts)`

Declares an allowlist of target hosts, wildcard subdomains, ports, or regular expressions permitted for network calls during this step.

Signatures

step.allowNetwork(hosts: (string | RegExp)[] | string | RegExp): this;

Parameters

hosts: (string | RegExp)[] — Array of hostnames ('api.stripe.com'), wildcard patterns ('*.stripe.com'), specific ports ('api.internal:8080'), or RegExps (/^api\.internal$/).

Example

const chargeStep = Step.create('charge', async ({ amount }) => {
    return await fetch('https://api.stripe.com/v1/charges', {/* ... */});
}).allowNetwork(['api.stripe.com', '*.stripe.network']);

`step.allowUnixSockets(sockets)`

Explicitly permits communication over specified local Unix domain sockets (IPC filesystem paths) during step execution.

Signature

step.allowUnixSockets(sockets: string | string[]): this;

Example

const dockerStep = Step.create('dockerInspect', async () => {
    // Connects to local Docker daemon Unix socket
    return await queryDockerDaemon('/var/run/docker.sock');
}).allowUnixSockets(['/var/run/docker.sock']);

`step.denyNetwork()`

Shorthand for .allowNetwork([]). Strictly denies all external outbound network access from the step’s lifecycle hooks and action.

Signature

step.denyNetwork(): this;

Example

const computeTax = Step.create('computeTax', ({ subtotal }) => {
    return { tax: subtotal * 0.08 };
}).denyNetwork(); // Disallows external network egress entirely

`step.networkPolicy(policy)`

Configures the complete network egress policy object for the step.

Signature

step.networkPolicy(policy: NetworkPolicyConfig): this;

Parameters

policy: NetworkPolicyConfig
- allowedHosts: (string | RegExp)[] (optional) — Allowed target host patterns.
- defaultPolicy: 'allow' | 'deny' (optional, default: 'deny') — Default fallback rule.
- allowLocalhost: boolean (optional, default: true) — Loopback exemption.
- allowUnixSockets: string[] (optional) — Allowed Unix domain socket paths.

Example

const syncStep = Step.create('sync', async () => {
    /* ... */
}).networkPolicy({
    allowedHosts: ['api.github.com'],
    defaultPolicy: 'deny',
    allowLocalhost: true,
    allowUnixSockets: ['/var/run/docker.sock'],
});

Execution and Inspection

`step.run and step.execute`

Runs the step directly as a standalone unit.

const output = await fetchUser.run({ userId: 'u_123' }, { pojo: true });

Graph and Export Methods

step.toGraph(): Returns a StepNode AST.
step.inspect(): Returns inspection metrics for this step.
step.toMermaid() / step.toDot() / step.toJSON(): Visual diagram and AST exports.

Static Methods and Configuration

The Step class exposes static utilities and orchestrator shortcuts:

Step.create(name, action): Primary factory method for step construction.
Step.flow(...steps) / Step.pipe(...steps): Shorthand alias to compose a sequential Flow.
Step.start(steps, param?, options?): Low-level executor entry point.
Step.config(props): Configures global runtime settings (logging, plugins, telemetry).
Step.useStorage(adapter): Registers the global StorageAdapter.
Step.checkpoint(stackId, options?): Captures an instantaneous checkpoint snapshot.
Step.restoreCheckpoint(data, options?): Restores stack state from a serialized snapshot.
Step.parallel(...), Step.all(...), Step.allSettled(...), Step.race(...): Combinator factories.
Step.when(...), Step.branch(...), Step.map(...): Branching and collection combinators.
Step.waitForEvent(...), Step.wait(...): Durable wait factories.

​API Reference: Step Methods (Step)

​Table of Contents

​The 5-Phase Step Lifecycle

​Instantiating Steps

​Step.create(name?, action)

​Signatures

​Example

​Validation and Contracts

​step.schema(schema)

​Signature

​Example with Zod

​step.spec(field, options)

​Signature

​Example

​step.strict()

​Signature

​Example

​Lifecycle Hooks

​step.onBefore(hook)

​Signature

​Example

​step.onSkip(hook)

​Signature

​Example

​step.onAfter(hook)

​Signature

​Example

​Fault Tolerance and Resilience

​step.timeout(ms)

​Signature

​Example

​step.onFail(config)

​Signatures

​Example with Exponential Backoff & Jitter

​Example with OnFail Fallback

​step.compensate(handler, options?)

​Signature

​Example

​Optimization and Deduplication

​step.idempotent(keyOrFn?, options?)

​Signature

​Semantics

​Example

​step.cache(msOrOptions)

​Signatures

​Example

​Dependency Injection

​step.withDependencies(deps)

​Signature

​step.requireDependency(key)

​Signature

​Example

​Context Transformation

​step.reduce(field)

​Signature

​Example

​Network Egress Guardrails

​Lifecycle Hook Governance

​step.allowNetwork(hosts)

​Signatures

​Parameters

​Example

​step.allowUnixSockets(sockets)

​Signature

​Example

​step.denyNetwork()

​Signature

​Example

​step.networkPolicy(policy)

​Signature

​Parameters

​Example

​Execution and Inspection

​step.run and step.execute

​Graph and Export Methods

​Static Methods and Configuration

​Related Topic Guides

API Reference: Step Methods (`Step`)

Table of Contents

The 5-Phase Step Lifecycle

Instantiating Steps

`Step.create(name?, action)`

Signatures

Example

Validation and Contracts

`step.schema(schema)`

Signature

Example with Zod

`step.spec(field, options)`

Signature

Example

`step.strict()`

Signature

Example

Lifecycle Hooks

`step.onBefore(hook)`

Signature

Example

`step.onSkip(hook)`

Signature

Example

`step.onAfter(hook)`

Signature

Example

Fault Tolerance and Resilience

`step.timeout(ms)`

Signature

Example

`step.onFail(config)`

Signatures

Example with Exponential Backoff & Jitter

Example with OnFail Fallback

`step.compensate(handler, options?)`

Signature

Example

Optimization and Deduplication

`step.idempotent(keyOrFn?, options?)`

Signature

Semantics

Example

`step.cache(msOrOptions)`

Signatures

Example

Dependency Injection

`step.withDependencies(deps)`

Signature

`step.requireDependency(key)`

Signature

Example

Context Transformation

`step.reduce(field)`

Signature

Example

Network Egress Guardrails

Lifecycle Hook Governance

`step.allowNetwork(hosts)`

Signatures

Parameters

Example

`step.allowUnixSockets(sockets)`

Signature

Example

`step.denyNetwork()`

Signature

Example

`step.networkPolicy(policy)`

Signature

Parameters

Example

Execution and Inspection

`step.run and step.execute`

Graph and Export Methods

Static Methods and Configuration

Related Topic Guides