Documentation Index
Fetch the complete documentation index at: https://mintlify.com/eersnington/sideffect/llms.txt
Use this file to discover all available pages before exploring further.
Sideffect exports a rich set of TypeScript types for working with workflows, steps, and their contexts. All types are exported from sideffect.
Workflow Types
WorkflowDefinition<Payload, Env>
The object returned by Workflow.make(). Holds the workflow’s name, payload schema, and the toLayer() method that binds the definition to its implementation.
interface WorkflowDefinition<Payload, Env = DefaultCloudflareEnv> {
/** Runtime tag used by Sideffect to validate workflow definitions. */
readonly _tag: "WorkflowDefinition";
/** Cloudflare Workflow name. */
readonly name: string;
/** Schema used to decode incoming workflow event payloads. */
readonly payloadSchema: Schema.Schema<Payload>;
/**
* Binds a workflow definition to its implementation.
*
* The returned layer can be discovered by `withCloudflareWorkflows(...)` or
* passed manually to `WorkflowEntrypoints.make(...)`.
*/
toLayer<NextResult>(
run: WorkflowRun<Payload, NextResult, Env>,
): WorkflowLayer<Payload, NextResult, Env>;
}
WorkflowLayer<Payload, Result, Env>
The object returned by workflowDefinition.toLayer(). Pairs a WorkflowDefinition with its run implementation and is consumed by WorkflowEntrypoints.make() or withCloudflareWorkflows().
interface WorkflowLayer<Payload, Result = unknown, Env = DefaultCloudflareEnv> {
/** Runtime tag used by Sideffect to validate workflow layers. */
readonly _tag: "WorkflowLayer";
/** Workflow definition and payload schema. */
readonly workflow: WorkflowDefinition<Payload, Env>;
/** Workflow implementation. */
readonly run: WorkflowRun<Payload, Result, Env>;
}
WorkflowRun<Payload, Result, Env>
The run function signature for workflows. Receives the typed WorkflowContext and the SideffectStep façade as arguments.
type WorkflowRun<Payload, Result, Env = DefaultCloudflareEnv> = (
workflow: WorkflowContext<Payload, Env>,
step: SideffectStep<Env>,
) => MaybeEffect<Result>;
WorkflowContext<Payload, Env>
Passed as the first argument to a workflow run function. Provides the decoded payload, the original Cloudflare event metadata, Worker bindings, and the execution context.
interface WorkflowContext<Payload, Env = DefaultCloudflareEnv> {
/** Decoded workflow event payload. */
readonly payload: Payload;
/** Original Cloudflare event metadata with the decoded payload attached. */
readonly event: WorkflowEvent<Payload>;
/** Worker environment/bindings from the WorkflowEntrypoint instance. */
readonly env: Env;
/** Worker execution context from the WorkflowEntrypoint instance. */
readonly ctx: unknown;
}
WorkflowEvent<Payload>
Re-shapes CloudflareWorkflowEvent so payload is typed as Payload rather than unknown. Available as event in the WorkflowContext passed to every workflow run function.
type WorkflowEvent<Payload> =
Readonly<Omit<CloudflareWorkflowEvent<Payload>, "payload">> & {
readonly payload: Payload;
};
WorkflowConfigEntry
The Wrangler workflow binding config shape generated or merged by Sideffect when building wrangler.json / wrangler.toml entries.
interface WorkflowConfigEntry {
/** Worker binding name exposed on `env`. */
readonly binding: string;
/** Cloudflare Workflow name. */
readonly name: string;
/** JavaScript export/class name for the WorkflowEntrypoint. */
readonly class_name: string;
/** Optional external Worker script name for native Cloudflare workflow bindings. */
readonly script_name?: string;
readonly [key: string]: unknown;
}
Step Types
StepDefinition<Payload, Result, Env>
The object returned by Step.make(). Carries the step’s name, payload and result schemas, the user-supplied run function, and optional rollback configuration.
interface StepDefinition<Payload, Result, Env = DefaultCloudflareEnv> {
/** Runtime tag used by Sideffect to validate step-like values. */
readonly _tag: "StepDefinition";
/** Cloudflare step name used when the step is executed. */
readonly name: string;
/** Schema used to decode step payloads before `run` executes. */
readonly payloadSchema: Schema.Schema<Payload>;
/** Schema used to decode step results before they leave the step. */
readonly resultSchema: Schema.Schema<Result>;
/** User function that performs the step work. */
readonly run: (payload: Payload, context: StepContext<Env>) => MaybeEffect<Result>;
/** Optional rollback handler forwarded to Cloudflare's native rollback system. */
readonly rollback?: RollbackHandler<Payload, Result, Env>;
/** Optional Cloudflare rollback step configuration. */
readonly rollbackConfig?: WorkflowStepConfig;
/** Applies a transformation helper while preserving the step type. */
pipe<A>(fn: (self: StepDefinition<Payload, Result, Env>) => A): A;
}
StepOptions
Options passed as the optional third argument to step.do(step, payload, options?). Maps directly to the relevant fields of Cloudflare’s WorkflowStepConfig.
interface StepOptions {
/** Cloudflare retry configuration for the step. */
readonly retries?: WorkflowStepConfig["retries"];
/** Cloudflare timeout configuration for the step. */
readonly timeout?: WorkflowStepConfig["timeout"];
/** Whether Cloudflare should treat step logs/output as sensitive. */
readonly sensitive?: WorkflowStepConfig["sensitive"];
}
StepContext<Env>
Passed as the second argument to a step run function. Extends Cloudflare’s WorkflowStepContext (which provides attempt, step.name, and config) and adds the Worker environment, execution context, and the raw NativeWorkflowStep handle.
interface StepContext<Env = DefaultCloudflareEnv> extends WorkflowStepContext {
/** Worker environment/bindings from the WorkflowEntrypoint instance. */
readonly env: Env;
/** Worker execution context from the WorkflowEntrypoint instance. */
readonly ctx: unknown;
/** Raw Cloudflare WorkflowStep API object for advanced native operations. */
readonly workflowStep: NativeWorkflowStep;
}
SideffectStep<Env>
The step façade passed to workflow run functions. Provides a type-safe do method that validates payloads and results against their schemas, and forwards sleep, sleepUntil, and waitForEvent to the underlying Cloudflare step API.
interface SideffectStep<Env = DefaultCloudflareEnv> {
/**
* Runs a typed Sideffect step through Cloudflare's native step system.
*
* The payload and result are decoded with the step schemas, and failures to
* decode are converted to non-retryable workflow failures.
*/
do<const S extends StepDefinition<any, any, Env>>(
step: S,
payload: StepPayload<S>,
options?: StepOptions,
): Promise<StepResult<S>>;
/** Forwards to Cloudflare `step.sleep()`. */
sleep(name: string, duration: string | number): Promise<void>;
/** Forwards to Cloudflare `step.sleepUntil()`. */
sleepUntil(name: string, timestamp: Date | number): Promise<void>;
/** Forwards to Cloudflare `step.waitForEvent()`. */
waitForEvent<A = unknown>(
name: string,
options: { readonly type: string; readonly timeout?: string | number },
): Promise<WorkflowStepEvent<A>>;
}
NativeWorkflowStep
The underlying Cloudflare workflow step API exposed via ctx.workflowStep inside StepContext and RollbackContext. Use this for advanced operations that bypass Sideffect’s schema layer.
interface NativeWorkflowStep {
/** Runs a Cloudflare Workflow step. */
do<A>(name: string, callback: (context: WorkflowStepContext) => Promise<A> | A): Promise<A>;
/** Runs a Cloudflare Workflow step with native rollback options. */
do<A>(
name: string,
callback: (context: WorkflowStepContext) => Promise<A> | A,
rollbackOptions: WorkflowStepRollbackOptions<A>,
): Promise<A>;
/** Runs a configured Cloudflare Workflow step. */
do<A>(
name: string,
config: StepOptions,
callback: (context: WorkflowStepContext) => Promise<A> | A,
): Promise<A>;
/** Runs a configured Cloudflare Workflow step with native rollback options. */
do<A>(
name: string,
config: StepOptions,
callback: (context: WorkflowStepContext) => Promise<A> | A,
rollbackOptions: WorkflowStepRollbackOptions<A>,
): Promise<A>;
/** Pauses the workflow for a Cloudflare duration string or millisecond count. */
sleep(name: string, duration: string | number): Promise<void>;
/** Pauses the workflow until the given timestamp. */
sleepUntil(name: string, timestamp: Date | number): Promise<void>;
/** Waits for a Cloudflare Workflow event. */
waitForEvent<A = unknown>(
name: string,
options: { readonly type: string; readonly timeout?: string | number },
): Promise<WorkflowStepEvent<A>>;
}
Rollback Types
RollbackContext<Payload, Result, Env>
Context passed to rollback handlers defined on a StepDefinition. Provides access to the step’s original payload, the step’s output (if any), the failure that triggered the rollback, the Worker environment, and the native Cloudflare rollback context.
interface RollbackContext<Payload, Result, Env = DefaultCloudflareEnv> {
/** Worker environment/bindings from the WorkflowEntrypoint instance. */
readonly env: Env;
/** Worker execution context from the WorkflowEntrypoint instance. */
readonly ctx: unknown;
/** Raw Cloudflare WorkflowStep API object for advanced native operations. */
readonly workflowStep: NativeWorkflowStep;
/** Original step payload. */
readonly payload: Payload;
/** Step output from Cloudflare, or `undefined` if no output was available. */
readonly result: Result | undefined;
/** Failure that caused Cloudflare to invoke rollback. */
readonly failure: unknown;
/** Native Cloudflare rollback context. */
readonly native: WorkflowRollbackContext<Result>;
}
Utility Types
DefaultCloudflareEnv
typeof cloudflareEnv from cloudflare:workers. The default Worker environment type extended by wrangler types and Sideffect env generation. Used as the Env default throughout the library.
type DefaultCloudflareEnv = typeof cloudflareEnv;