Decorators provide a declarative way to define workflows and event handlers in NestflowJS.

@Workflow

Marks a class as a workflow definition.

Signature

@Workflow<T, Event, State>(definition: IWorkflowDefinition<T, Event, State>)

Parameters

definition: Workflow definition object containing:
- name: Unique name for the workflow
- states: State configuration
  - finals: Array of final states
  - idles: Array of idle states
  - failed: Failed state
- transitions: Array of transition definitions
- entityService: Injection token for entity service

Example

@Workflow({
  name: 'OrderWorkflow',
  states: {
    finals: [OrderStatus.Completed, OrderStatus.Failed],
    idles: [OrderStatus.Pending],
    failed: OrderStatus.Failed,
  },
  transitions: [
    {
      from: [OrderStatus.Pending],
      to: OrderStatus.Processing,
      event: 'order.submit',
    },
  ],
  entityService: 'entity.order',
})
export class OrderWorkflow {}

@OnEvent

Defines an event handler for a specific event.

Signature

@OnEvent(event: string)

Parameters

event: The event name that triggers this handler

Example

@OnEvent('order.submit')
async onSubmit(@Entity() entity: Order, @Payload() data: any) {
  // Handle the event
  return entity;
}

@OnDefault

Defines a fallback handler for unhandled events.

Signature

@OnDefault

Example

@OnDefault
async fallback(entity: Order, event: string, payload?: any) {
  console.warn(`Unhandled event: ${event}`);
  return entity;
}

@Entity

Injects the entity being processed into the handler method.

Signature

@Entity()

Example

@OnEvent('order.submit')
async onSubmit(@Entity() entity: Order) {
  console.log('Processing order:', entity.id);
  return entity;
}

@Payload

Injects the event payload into the handler method. Optionally accepts a DTO class for validation.

Signature

@Payload(dto?: Class)

Parameters

dto?: Optional DTO class for payload validation and transformation

Example

@OnEvent('order.submit')
async onSubmit(
  @Entity() entity: Order,
  @Payload(SubmitOrderDto) data: SubmitOrderDto
) {
  // data is validated and transformed
  return entity;
}

@WithRetry

Adds retry logic to event handlers.

import { WithRetry, RetryStrategy } from 'nestflow-js/core';

Signature

@WithRetry(config: IBackoffRetryConfig)

Parameters

config: Retry configuration object:
- handler: Name of the handler method (required)
- maxAttempts: Maximum number of retry attempts
- strategy?: Backoff strategy (RetryStrategy.FIXED | RetryStrategy.EXPONENTIAL | RetryStrategy.EXPONENTIAL_JITTER). Defaults to RetryStrategy.EXPONENTIAL_JITTER
- initialDelay?: Base delay in milliseconds (default 1000)
- backoffMultiplier?: Multiplier per attempt (default 2)
- maxDelay?: Upper bound in milliseconds (default 60000)
- jitter?: true for full jitter, 0-1 for partial jitter

Example

@OnEvent('order.payment')
@WithRetry({
  handler: 'processPayment',
  maxAttempts: 3,
  strategy: RetryStrategy.EXPONENTIAL,
  initialDelay: 1000,
  maxDelay: 30000,
})
async processPayment(@Entity() entity: Order) {
  // Will retry up to 3 times with exponential backoff
  return entity;
}

Usage Example

@Workflow({
  name: 'OrderWorkflow',
  states: {
    finals: [OrderStatus.Completed],
    idles: [OrderStatus.Pending],
    failed: OrderStatus.Failed,
  },
  transitions: [
    {
      from: [OrderStatus.Pending],
      to: OrderStatus.Processing,
      event: 'order.submit',
    },
  ],
  entityService: 'entity.order',
})
export class OrderWorkflow {
  @OnEvent('order.submit')
  @WithRetry({ handler: 'onSubmit', maxAttempts: 3, strategy: RetryStrategy.EXPONENTIAL })
  async onSubmit(
    @Entity() entity: Order,
    @Payload(SubmitOrderDto) data: SubmitOrderDto
  ) {
    // Process order
    return entity;
  }

  @OnDefault
  async fallback(entity: Order, event: string, payload?: any) {
    console.warn(`Unhandled event: ${event}`);
    return entity;
  }
}

Decorators

On this page