cloudflare--workers-sdk/packages/workflows-shared/CHANGELOG.md

@cloudflare/workflows-shared

0.12.0

Minor Changes

• #14465 2fedb1f Thanks @vaishnav-mk! - Add rollback support when terminating Workflow instances

  WorkflowInstance.terminate({ rollback: true }) now runs registered rollback handlers before marking a local Workflow instance as terminated. Wrangler also supports this via wrangler workflows instances terminate --rollback, including local mode.

  The rollback option is only sent for terminate operations and is rejected by the Local Explorer API for pause, resume, and restart actions.

0.11.2

Patch Changes

• #14318 f32e9c1 Thanks @vaishnav-mk! - Add step context to Workflows rollback handlers

  Rollback handlers now receive the original step context under ctx, making ctx.step.name, ctx.step.count, ctx.attempt, and the resolved step config available during rollback. The legacy stepName field remains available and is equivalent to ${ctx.step.name}-${ctx.step.count}.

  rollbackConfig is now limited to retry and timeout settings, matching the behavior supported by rollback handlers.

• #14314 5c3bb11 Thanks @harryzcy! - Bump esbuild to 0.28.1

  This update includes several bug fixes from esbuild versions 0.27.3 through 0.28.1. See the esbuild changelog for details.

0.11.1

Patch Changes

• #14134 262dfc2 Thanks @matingathani! - Fix wrangler dev Workflows crashing with SQLITE_TOOBIG when a step returns a large Uint8Array

  JSON.stringify encodes each byte of a Uint8Array as a separate numeric key ({"0":1,"1":2,...}), producing a string ~10× larger than the array's byte length. A 200 KB Uint8Array became a ~2 MB JSON string that exceeded SQLite's blob limit, crashing the Workflow step. The same bytes returned as an ArrayBuffer succeeded because JSON.stringify(ArrayBuffer) → {}.

  The step log metadata (used by the local Workflows explorer) now stores a human-readable description for TypedArray and ArrayBuffer outputs ([Uint8Array(200000 bytes)]) instead of attempting to JSON-serialise the raw bytes. The actual step value is unaffected — it is preserved in Durable Object key-value storage via structured clone for replay by subsequent steps.

0.11.0

Minor Changes

• #13983 9803586 Thanks @vaishnav-mk! - Add rollback support for local Workflows development

  Workflow steps can now register a compensation callback with trailing rollback options: step.do(name, fn, { rollback }) and step.do(name, config, fn, { rollback, rollbackConfig }). When the workflow fails, the local engine runs every registered rollback in reverse step-start order (LIFO), giving steps the opportunity to undo their side effects.

  Each rollback executes through an internal rollback-scoped Context.do, so it inherits the existing retry / timeout / attempt-tracking machinery. rollbackConfig lets users override the per-rollback config.

  Note: the public rollback option type lands with workerd's workflows_step_rollback compat flag. Until that ships, the trailing rollback options only flow through when called through the StepPromise wrapper from a worker that has the flag enabled.

0.10.0

Minor Changes

• #13565 b04eedf Thanks @vaishnav-mk! - Add restart from step support for local Workflows development

  Workflow instances can now be restarted from a specific step in local development. When restarting from a step, all earlier steps preserve their cached results and replay instantly, while the target step and everything after it re-execute.

  The WorkflowInstance.restart() method now accepts an optional { from: { name, count?, type? } } parameter to specify which step to restart from.

0.9.1

Patch Changes

• #13560 7567ef7 Thanks @vaishnav-mk! - Preserve NonRetryableError message and name when the workflows_preserve_non_retryable_error_message compatibility flag is enabled, instead of replacing it with a generic error message.

0.9.0

Minor Changes

• #13351 3788983 Thanks @pombosilva! - Add step and config properties to the workflow step context

  The callback passed to step.do() now receives ctx.step (with name and count) and ctx.config (the fully resolved step configuration with defaults merged in), in addition to the existing ctx.attempt.

0.8.0

Minor Changes

• #13145 5b60405 Thanks @Caio-Nogueira! - Add support for ReadableStream on workflow steps. This allows users to overcome the 1MB limit per step output.

  ReadableStream<Uint8Array> is already serializable on the workers platform. This feature makes it native to workflows as well by persisting each chunk and replaying it if needed

0.7.2

Patch Changes

• #13086 d4c6158 Thanks @pombosilva! - Add Workflows support to the local explorer UI.

  The local explorer (/cdn-cgi/explorer/) now includes a full Workflows dashboard for viewing and managing workflow instances during local development.

  UI features:

  • Workflow instance list with status badges, creation time, action buttons, and pagination
  • Status summary bar with instance counts per status
  • Status filter dropdown and search
  • Instance detail page with step history, params/output cards, error display, and expandable step details
  • Create instance dialog with optional ID and JSON params

0.7.1

Patch Changes

• #12985 17a57e6 Thanks @pombosilva! - Fix waitForEvent delivering events to stale waiters after timeout.

  When a step.waitForEvent() call timed out, its resolver was not removed from the workflow's internal waiters map. This meant the next step.waitForEvent() for the same event type would have its incoming event consumed by the dead resolver instead of the live one, causing the workflow to hang indefinitely.

0.7.0

Minor Changes

• #12881 8729f3d Thanks @pombosilva! - Workflow instances now support pause, resume, restart, and terminate in local dev.

  const instance = await env.MY_WORKFLOW.create({
    id: "my-instance",
  });
  
  await instance.pause(); // pauses after the current step completes
  await instance.resume(); // resumes from where it left off
  await instance.restart(); // restarts the workflow from the beginning
  await instance.terminate(); // terminates the workflow immediately
  

0.6.0

Minor Changes

• #11970 f235827 Thanks @pombosilva! - Adds step context with attempt count to step.do() callbacks.

  Workflow step callbacks now receive a context object containing the current attempt number (1-indexed). This allows developers to access which retry attempt is currently executing.

  Example:

  await step.do("my-step", async (ctx) => {
    // ctx.attempt is 1 on first try, 2 on first retry, etc.
    console.log(`Attempt ${ctx.attempt}`);
  });
  

0.5.0

Minor Changes

• #12622 bf9cb3d Thanks @LuisDuarte1! - Add configurable step limits for Workflows

  You can now set a maximum number of steps for a Workflow instance via the limits.steps configuration in your Wrangler config. When a Workflow instance exceeds this limit, it will fail with an error indicating the limit was reached.

  // wrangler.jsonc
  {
    "workflows": [
      {
        "binding": "MY_WORKFLOW",
        "name": "my-workflow",
        "class_name": "MyWorkflow",
        "limits": {
          "steps": 5000
        }
      }
    ]
  }
  

  The steps value must be an integer between 1 and 25,000. If not specified, the default limit of 10,000 steps is used. Step limits are also enforced in local development via wrangler dev.

0.4.0

Minor Changes

• #11648 eac5cf7 Thanks @pombosilva! - Add Workflows test handlers in vitest-pool-workers to get the Workflow instance output and error:

  • getOutput(): Returns the output of the successfully completed Workflow instance.
  • getError(): Returns the error information of the errored Workflow instance.

  Example:

  // First wait for the workflow instance to complete:
  await expect(
    instance.waitForStatus({ status: "complete" })
  ).resolves.not.toThrow();
  
  // Then, get its output
  const output = await instance.getOutput();
  
  // Or for errored workflow instances, get their error:
  await expect(
    instance.waitForStatus({ status: "errored" })
  ).resolves.not.toThrow();
  const error = await instance.getError();
  

0.3.9

Patch Changes

• #11448 2b4813b Thanks @edmundhung! - Builds package with esbuild v0.27.0

0.3.8

Patch Changes

• #10919 ca6c010 Thanks @Caio-Nogueira! - migrate workflow to use a wrapped binding

0.3.7

Patch Changes

• #10813 545afe5 Thanks @pombosilva! - Workflows are now created if the Request gets redirected after creation

0.3.6

Patch Changes

• #10785 d09cab3 Thanks @pombosilva! - Workflows names and instance IDs are now properly validated with production limits.

0.3.5

Patch Changes

• #10219 28494f4 Thanks @dario-piotrowicz! - fix NonRetryableError thrown with an empty error message not stopping workflow retries locally

0.3.4

Patch Changes

• #9367 2e12e6e Thanks @Caio-Nogueira! - Fix instance hydration after abort. Some use cases were causing instances to not be properly rehydrated after server shutdown, which would cause the instance to be lost.

0.3.3

Patch Changes

• #9033 2c50115 Thanks @dario-piotrowicz! - chore: convert wrangler.toml files into wrangler.jsonc ones

0.3.2

Patch Changes

• #8775 ec7e621 Thanks @LuisDuarte1! - Add waitForEvent and sendEvent support for local dev

0.3.1

Patch Changes

• #8606 18edbc2 Thanks @LuisDuarte1! - Implement local dev for createBatch

0.3.0

Minor Changes

• #7334 869ec7b Thanks @penalosa! - Packages in Workers SDK now support the versions of Node that Node itself supports (Current, Active, Maintenance). Currently, that includes Node v18, v20, and v22.

0.2.3

Patch Changes

• #8123 7f565c5 Thanks @LuisDuarte1! - Make NonRetryableError work and cache errored steps

0.2.2

Patch Changes

• #7575 7216835 Thanks @LuisDuarte1! - Make Instance.status() return type the same as production

0.2.1

Patch Changes

• #7520 805ad2b Thanks @bruxodasilva! - Fixed a bug in local development where fetching a Workflow instance by ID would return a Workflow status, even if that instance did not exist. This only impacted the get() method on the Worker bindings.

0.2.0

Minor Changes

• #7286 563439b Thanks @LuisDuarte1! - Add proper engine persistance in .wrangler and fix multiple workflows in miniflare

0.1.2

Patch Changes

• #7225 bb17205 Thanks @bruxodasilva! - - Fix workflows binding to create a workflow without arguments
  • Fix workflows instance.id not working the same way in wrangler local dev as it does in production

0.1.1

Patch Changes

• #7045 5ef6231 Thanks @RamIdeas! - Add preliminary support for Workflows in wrangler dev