web / lib/services/stage-transition

lib/services/stage-transition

Provides atomic stage transition management for import jobs.

This service ensures that stage transitions and job queuing happen atomically to prevent race conditions and duplicate job creation. It manages the entire transition lifecycle including validation, queuing, and state tracking.

Key responsibilities:

Atomic stage transition processing
Prevention of duplicate job queuing
Stage transition validation
Centralized job queuing logic.

Classes

StageTransitionService

Service to handle stage transitions atomically.

Constructors

Constructor

new StageTransitionService(): StageTransitionService

Returns

StageTransitionService

Methods

validateStageTransition()

static validateStageTransition(fromStage, toStage): boolean

Validate stage transition.

Parameters

fromStage

string

toStage

string

Returns

boolean

processStageTransition()

static processStageTransition(payload, job, previousJob): Promise<StageTransitionResult>

Process stage transition and queue appropriate jobs atomically.

Parameters

payload

BasePayload

job

ImportJob

previousJob

undefined | ImportJob

Returns

Promise<StageTransitionResult>

isTransitioning()

static isTransitioning(jobId, fromStage?, toStage?): boolean

Check if a transition is currently being processed.

Parameters

jobId

string

fromStage?

string

toStage?

string

Returns

boolean

getTransitioningCount()

static getTransitioningCount(): number

Get currently transitioning job count (for monitoring).

Returns

number

clearTransitionLocks()

static clearTransitionLocks(): void

Force clear transition locks (for emergency situations).

Returns

void

cleanupOldLocks()

static cleanupOldLocks(): number

Clean up old transition locks (for transitions completed over 5 minutes ago).

Returns

number

cleanupTask()

static cleanupTask(): object

Cleanup task handler for Payload jobs This should be registered as a Payload task with a schedule.

Returns

object

output

output: object

output.cleaned

cleaned: number

Interfaces

StageTransitionResult

Properties

success

success: boolean

jobQueued?

optional jobQueued: boolean

queuedJobType?

optional queuedJobType: string

error?

optional error: string