Cloudflare - v1.3.0
    Preparing search index...

    Class WorkflowBinding<Params, E>

    Accessor for a Workflows binding.

    A Workflow is durable execution: a class of steps that survives restarts, retries a failed step without replaying the ones before it, and can sleep for a month between two of them. This accessor is the producer side — starting instances and reading them back. The steps themselves live in a WorkflowEntrypoint class the Worker exports, which this package neither provides nor wraps: a base class that must be exported from the Worker's own entry, and named in its own wrangler.json, has nothing an adapter can add.

    The method names mirror the platform's — create, createBatch, get — because an accessor that renames operations makes Cloudflare's documentation stop matching this one. status is the single addition, saving the two-step that reading an instance's state otherwise takes.

    Every binding here but this one and Browser Rendering has a capability service beside it, and the reason differs from Browser's. There the obstacle was a dependency; here it is that the kernel has no capability to implement. @bayudwiyansatria/core names a CacheStore, a DataStore, a MessageQueue — abstractions with more than one plausible provider. Durable execution has none yet, and inventing one to sit in front of a single implementation with no consumers would be ceremony rather than abstraction, which the binding guide says in as many words.

    That leaves nothing lost, because unlike Browser Rendering the binding's own operations cost no dependency: Workflow, WorkflowInstance and their options come from @cloudflare/workers-types, already a peer. A consumer gets the real surface here rather than a bare handle.

    const screens = new WorkflowBinding<ScreenRequest>()

    const run = await screens.create(env, { universe: 'IDX', filters })

    return ctx.json({ id: run.id })

    Bayu Dwiyan Satria

    1.0.0

    1.3.0

    Type Parameters

    Hierarchy (View Summary)

    Index
    constructor
    settings
    name
    create createBatch get isBound resolve status tryResolve withRetention
    settings: () => WorkflowSettings

    This accessor's settings, resolved on first read.

    • get name(): string

      The binding name this instance resolves.

      Returns string

      The binding name as declared in wrangler.json.

    • Starts an instance.

      Parameters

      • env: E

        The Worker environment.

      • Optionalparams: Params

        The event payload the instance is triggered with.

      • options: WorkflowInstanceCreateOptions<Params> = {}

        Creation options — an explicit id, or a retention policy overriding the configured one.

      Returns Promise<WorkflowInstance>

      A handle to the new instance.

      Returns as soon as the instance is accepted, not when it finishes — a Workflow that runs for an hour returns a handle in milliseconds. Read the outcome later with status.

      Supplying an id in options makes the start idempotent in the only sense Cloudflare offers: a second start under an id that already exists throws rather than producing a second run.

      MissingBindingError When the Workflow binding is absent.

    • Starts several instances in one call.

      Parameters

      • env: E

        The Worker environment.

      • batch: WorkflowInstanceCreateOptions<Params>[]

        Creation options, one entry per instance.

      Returns Promise<WorkflowInstance[]>

      Handles to the new instances, in the order they were given.

      Cloudflare caps a batch at 100 instances, or at 1 MiB of payload, whichever is reached first — so a caller fanning out over a large universe splits the work itself rather than relying on this to do it. Nothing here chunks on the caller's behalf, because the right chunk size depends on how big the payloads are and only the caller knows that.

      MissingBindingError When the Workflow binding is absent.

    • Reads back an instance started earlier.

      Parameters

      • env: E

        The Worker environment.

      • id: string

        The instance id.

      Returns Promise<WorkflowInstance>

      A handle to the instance, which can be paused, resumed, terminated or read.

      MissingBindingError When the Workflow binding is absent.

    • Checks whether the binding is available on the given environment.

      Use this to degrade gracefully when a binding is optional.

      Parameters

      • env: E

        The Worker environment.

      Returns boolean

      true when the binding is present.

    • Reads an instance's current status.

      Parameters

      • env: E

        The Worker environment.

      • id: string

        The instance id.

      Returns Promise<InstanceStatus>

      The instance's status, plus its output or error when it has one.

      The one method here without a counterpart on the binding, and the only one worth adding: reporting a run's progress is what a status endpoint does on every request, and it would otherwise take two awaits every time.

      A finished instance carries its result in output; a failed one carries error. Both disappear once retention lapses — see WorkflowSettings.

      MissingBindingError When the Workflow binding is absent.

    • Applies the configured retention policy to options that do not set one.

      Parameters

      • options: WorkflowInstanceCreateOptions<Params>

        The caller-supplied creation options.

      Returns WorkflowInstanceCreateOptions<Params>

      Creation options with the configured retention filled in.

      All or nothing, deliberately. A call that names retention at all owns both halves of it, so a caller asking for a longer error retention on one run does not silently inherit the configured success retention beside it.

    Settings
    Member Visibility

    On This Page
    Why there is no
    Constructors
    Properties
    Accessors
    Methods