docs(typescript): align step-interrupted contract#193
Merged
Conversation
Fixes #192. The TypeScript SDK does not throw StepInterruptedError from `await context.step(...)`. The SDK throws a StepError whose cause.name equals "StepInterruptedError". Update four files to reflect this. - errors.md: rewrite the StepInterruptedError prose paragraph in the "Exception types" TypeScript tab and relabel the SIE mermaid node. - step.md: update the TypeScript step() Throws note and the AtMostOncePerRetry semantics description. - step-interrupted.ts: detect interruption via err instanceof StepError && err.cause?.name === "StepInterruptedError". - exception-hierarchy.ts: rewrite the trailing comment block. Python and Java tabs remain accurate. Their SDKs raise or throw the language-specific class directly per their respective hierarchies. Context: aws/aws-durable-execution-sdk-js#576 fixes the metadata crash that masked this divergence on cold replay and codifies the wrapping contract via unit and e2e tests.
ParidelPooya
approved these changes
May 26, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #192.
Summary
The TypeScript tab of the Error handling: errors page tells customers to detect step interruption with
instanceof StepInterruptedError, but the JS SDK does not throwStepInterruptedErrorfromawait context.step(...). It throws aStepErrorwhosecause.nameequals"StepInterruptedError".The wrapping has always been the SDK's behaviour on this code path. A separate bug (aws-durable-execution-sdk-js#529) masked the divergence by crashing before the throw line; aws-durable-execution-sdk-js#576 fixes that crash and codifies the contract via unit and e2e tests.
Python and Java tabs remain accurate.
Changes
docs/sdk-reference/error-handling/errors.md: rewrite theStepInterruptedErrorprose paragraph in the "Exception types" TypeScript tab; relabel theSIEmermaid node so the diagram does not implyStepInterruptedErrorsurfaces as a thrown error.docs/sdk-reference/operations/step.md: update the TypeScriptstep()Throwsnote and theAtMostOncePerRetrysemantics description.examples/typescript/sdk-reference/error-handling/step-interrupted.ts: detect interruption viaerr instanceof StepError && err.cause?.name === "StepInterruptedError". Drop the emdash in thelogger.warnmessage.examples/typescript/sdk-reference/error-handling/exception-hierarchy.ts: rewrite the trailing comment block. KeepStepInterruptedErrorin the import/export list because it remains useful for typing theerrorargument of aretryStrategycallback.Verification
AT_MOST_ONCE_PER_RETRYpath:step-handler.tsthrowsDurableOperationError.fromErrorObject(createErrorObjectFromError(StepInterruptedError)).createErrorObjectFromErrorproduces{ ErrorType: "StepInterruptedError", ... }.DurableOperationError.fromErrorObjectfalls through itsswitchto thedefaultbranch and returns aStepErrorwhosecauseis a plainErrorwithname === "StepInterruptedError".StepError,DurableOperationError, andStepInterruptedErrorare all public exports of@aws/durable-execution-sdk-js.StepInterruptedErrormention across the docs (errors.md,step.md, the two example files). Python and Java mentions are correct as-is and untouched.~/.venvs/zensical/bin/mdformaton the modified Markdown files.~/.venvs/zensical/bin/zensical build --clean: build succeeds with no warnings.Out of scope
examples/typescript/sdk-reference/error-handling/step-interrupted-error.ts(currently a// Coming soon...placeholder).By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.