Workflow Decorators
Declare durable, resumable TypeScript workflows with AxilJS: tWorkflow marks a workflow class and tResume marks where execution restarts after failure.
On this page7
AxilJS workflow decorators describe long-running, multi-step processes that must survive failures and restarts.
They add explicit lifecycle semantics to a class: which class is a workflow, which version it is, whether it can be resumed, and which method is the entry point when it is. The individual steps, checkpoints and compensations are declared with the distributed decorators tStep, tCheckpoint and tCompensate.
The workflow decorators are:
@tWorkflow@tResume
Both belong to the Workflow category (axil decorator list --category Workflow).
@tWorkflow
Declares a class as a durable, resumable workflow.
1import { tWorkflow, tStep } from '@axiljs/decorator'
2
3@tWorkflow('document-processing')
4class DocumentWorkflow {
5 @tStep('extract', { order: 1 })
6 async extract(documentId: string) {}
7
8 @tStep('classify', { order: 2 })
9 async classify(documentId: string) {}
10
11 @tStep('index', { order: 3 })
12 async index(documentId: string) {}
13}tWorkflow(name: string, options: TWorkflowOptions = {}) is a class decorator. It records { name, ...options } as class metadata on the constructor, so the name and the options are flattened into one object.
Options
| Option | Type | Description |
|---|---|---|
version | string | Workflow definition version |
resumable | boolean | Whether an interrupted run may resume, not restart |
Both options are optional and have no default. @tWorkflow('x') records exactly { name: 'x' }; resumable is not assumed to be true unless you pass it.
A version matters once runs outlive deployments: a workflow engine needs to know which definition an in-flight run started under before replaying or resuming it.
When to use: on classes representing multi-step durable processes.
Composes with: tStep, tCheckpoint, tResume, tCompensate.
Warning
tWorkflow targets classes only. Its handler ignores the property key, so if you put it on a method it silently records class-level metadata on the prototype instead of throwing. axil decorator check only inspects method blocks and will not catch this.
@tResume
Declares a method as the entry point when a workflow run is resumed.
1import { tWorkflow, tStep, tCheckpoint, tResume } from '@axiljs/decorator'
2
3@tWorkflow('document-processing', { version: '2', resumable: true })
4class DocumentWorkflow {
5 @tStep('extract', { order: 1 })
6 async extract(documentId: string) {}
7
8 @tStep('index', { order: 2 })
9 @tCheckpoint('after-index')
10 async index(documentId: string) {}
11
12 @tResume({ from: 'after-index' })
13 async resumeAfterIndex(documentId: string) {}
14}tResume(options: TResumeOptions = {}) is a method decorator and stores the options object as-is under the tResume key.
Options
| Option | Type | Description |
|---|---|---|
from | string | Name of the checkpoint the run resumes from |
from is optional and has no default. @tResume() records {}, which a consumer can treat as "resume from the last checkpoint reached". The decorator does not check that a tCheckpoint with that name exists.
When to use: on workflow steps that may be resumed after failure. Explicit resume points are necessary for durable execution.
Composes with: tWorkflow, tCheckpoint.
Composing Workflow Semantics
A complete workflow combines the class-level declaration with steps, checkpoints, compensation, resume points and reliability limits.
1import {
2 tWorkflow,
3 tStep,
4 tCheckpoint,
5 tCompensate,
6 tResume,
7 tRetry,
8 tTimeout,
9} from '@axiljs/decorator'
10
11@tWorkflow('video-processing', { version: '3', resumable: true })
12class VideoPipeline {
13 @tStep('transcode', { order: 1 })
14 @tTimeout(600_000)
15 @tCheckpoint('after-transcode')
16 async transcode(videoId: string) {}
17
18 @tStep('analyze', { order: 2 })
19 @tRetry({ attempts: 3, backoff: 'exponential' })
20 @tCheckpoint('after-analysis')
21 async analyze(videoId: string) {}
22
23 @tStep('publish', { order: 3 })
24 async publish(videoId: string) {}
25
26 @tCompensate('publish')
27 async unpublish(videoId: string) {}
28
29 @tResume({ from: 'after-analysis' })
30 async resumeFromAnalysis(videoId: string) {}
31}The resulting metadata describes:
- A versioned, resumable workflow named
video-processing. - Three ordered steps: transcode, analyze, publish.
- A ten-minute limit on transcoding and three attempts for analysis.
- Checkpoints after transcoding and after analysis.
- A compensating action that reverses publication.
- A resume entry point that skips the work already checkpointed.
None of the workflow decorators declare a conflictsWith relationship.
Note
Workflow decorators only record metadata. Their catalog entries name a "Workflow Engine" as the consumer, and AxilJS does not ship one: nothing reads tWorkflow, tResume, tStep, tCheckpoint or tCompensate today. @axiljs/runtime executes only tAudit, tRetry and tTimeout and applies tRedact / tSensitive redaction, so in the example above the tRetry and tTimeout on individual steps do run when the class is wired with wire() / wireAll(), while ordering, checkpointing and resuming are up to your own orchestrator. Read the declarations with getMetadata() or inspect them with the axil decorator commands. See Runtime.
Reading Workflow Metadata
tWorkflow is stored on the constructor; tResume is stored per method on the prototype.
1import {
2 getMetadata,
3 getDecoratedMethods,
4 type TWorkflowOptions,
5 type TResumeOptions,
6} from '@axiljs/decorator'
7
8const workflow = getMetadata<TWorkflowOptions & { name: string }>('tWorkflow', VideoPipeline)
9// { name: 'video-processing', version: '3', resumable: true }
10
11const resumePoint = getDecoratedMethods(VideoPipeline.prototype).find(
12 (method) => getMetadata('tResume', VideoPipeline.prototype, method) !== undefined,
13)
14// 'resumeFromAnalysis'
15
16const resume = getMetadata<TResumeOptions>('tResume', VideoPipeline.prototype, resumePoint!)
17// { from: 'after-analysis' }An orchestrator can combine this with the tStep metadata (sorted by order) and the tCheckpoint names to decide which steps to skip on resume.
Workflow Decorator Reference
| Decorator | Targets | Records | Purpose |
|---|---|---|---|
@tWorkflow | class | { name, version?, resumable? } | Declares a durable, resumable workflow |
@tResume | method | { from? } | Declares the resume entry point |
Related decorators from the Distributed category:
| Decorator | Purpose |
|---|---|
@tStep | Defines an ordered workflow step |
@tCheckpoint | Defines a resumable workflow point |
@tCompensate | Defines compensation for a workflow step |
Design Principle
Workflow decorators describe the lifecycle of a long-running process, not the engine that runs it.
For example:
@tWorkflow('document-processing', { resumable: true })
class DocumentWorkflow {}does not persist state, schedule steps or replay history. It declares that the class is a durable workflow and how it may be resumed, so that a database-backed orchestrator, a state machine or a hosted workflow service can execute the same definition. See the decorator overview for how metadata is stored and consumed.
Was this page helpful?