Decorators

Workflow Decorators

Declare durable, resumable TypeScript workflows with AxilJS: tWorkflow marks a workflow class and tResume marks where execution restarts after failure.

6 min readUpdated DocumentationEdit this page
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.

TypeScript
TS
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

OptionTypeDescription
versionstringWorkflow definition version
resumablebooleanWhether 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.

TypeScript
TS
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

OptionTypeDescription
fromstringName 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.

TypeScript
TS
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:

  1. A versioned, resumable workflow named video-processing.
  2. Three ordered steps: transcode, analyze, publish.
  3. A ten-minute limit on transcoding and three attempts for analysis.
  4. Checkpoints after transcoding and after analysis.
  5. A compensating action that reverses publication.
  6. 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.

TypeScript
TS
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

DecoratorTargetsRecordsPurpose
@tWorkflowclass{ name, version?, resumable? }Declares a durable, resumable workflow
@tResumemethod{ from? }Declares the resume entry point

Related decorators from the Distributed category:

DecoratorPurpose
@tStepDefines an ordered workflow step
@tCheckpointDefines a resumable workflow point
@tCompensateDefines 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:

TypeScript
TS
@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?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY