API: @loopstack/core
Classes
FanOutWorkflow
Workflow that launches N sub-workflows in parallel, awaits all of them, and fires a single aggregated callback to the parent.
Sub-workflows are referenced by their canonical name (string) — set via @Workflow({ name })
or auto-derived from the class name. Items may be passed as an array or a keyed record.
Modes:
'all'(default) — first failure cancels in-flight siblings; the callback fires once every child has settled (canceled siblings also send callbacks).'allSettled'— every child runs to completion; the callback aggregates all results.
import { FanOutWorkflow } from '@loopstack/core';Provided by: LoopCoreModule
export class FanOutWorkflow extends BaseWorkflow<FanOutArgs, FanOutInput> { constructor(orchestrator: WorkflowOrchestrator, registry: WorkflowRegistryService); start(state: FanOutState, ctx: RunContext<FanOutArgs>): Promise<void>; onChildComplete( state: FanOutState, input: TransitionInput< unknown, { key?: string; } >, ctx: RunContext<FanOutArgs>, ): Promise<void>; done(state: FanOutState): void;}SequenceWorkflow
Workflow that runs N sub-workflows one at a time, awaits each, and fires a single aggregated callback to the parent.
Sub-workflows are referenced by their canonical name (string) — set via @Workflow({ name })
or auto-derived from the class name. Items may be passed as an array or a keyed record.
Modes:
'all'(default) — first failure aborts the sequence; remaining items are marked as'skipped'in the result.'allSettled'— every item runs regardless of prior failures.
import { SequenceWorkflow } from '@loopstack/core';Provided by: LoopCoreModule
export class SequenceWorkflow extends BaseWorkflow<SequenceArgs, SequenceInput> { constructor(orchestrator: WorkflowOrchestrator, registry: WorkflowRegistryService); start(state: SequenceState, ctx: RunContext<SequenceArgs>): Promise<void>; onChildComplete(state: SequenceState, input: TransitionInput, ctx: RunContext<SequenceArgs>): Promise<void>; done(state: SequenceState): void;}WorkflowRunner
Service for starting workflows from code (API requests, webhooks, cron jobs,
delayed timeouts, batch fan-out) instead of the Studio “Run” button. Inject it
anywhere — it is globally available once LoopstackModule.forRoot() is imported.
run(WorkflowClass, args, options)— enqueue on BullMQ and return aRunResult(workflowId).runSync(WorkflowClass, args, options)— execute inline and await aSyncRunResult; pass{ stateless: true }to skip persistence.execute(workflow, payload, options)— controller-facing entry that starts, resumes, or retries based on the payload.runById(workflowId, userId, options)— resume/re-run an existing workflow by id.
import { WorkflowRunner } from '@loopstack/core';export class WorkflowRunner { constructor( configService: ConfigService, createWorkflowService: CreateWorkflowService, workspaceService: WorkspaceService, workflowService: WorkflowService, taskSchedulerService: TaskSchedulerService, rootProcessorService: RootProcessorService, workflowRegistryService: WorkflowRegistryService, orchestrator: WorkflowOrchestrator, ); execute<TArgs>( workflow: Type<BaseWorkflow<TArgs>> | string, payload: WorkflowPayload<TArgs>, options: { userId: string; appName: string; labels?: string[]; }, ): Promise<WorkflowRunResult>; run<W extends BaseWorkflow>( workflow: Type<W>, args: WorkflowArgs<W>, options: WorkflowRunnerOptions, ): Promise<RunResult>; runSync<W extends BaseWorkflow>( workflow: Type<W>, args: WorkflowArgs<W>, options: WorkflowRunnerSyncOptions, ): Promise<SyncRunResult | StatelessRunResult>; runById( workflowId: string, userId: string, payload?: { transition?: { id?: string; workflowId?: string; payload?: unknown; }; }, ): Promise<RunResult>; cancel(workflowId: string, userId: string): Promise<void>;}Interfaces
WorkflowSettledEvent
Emitted once a run has reached a state it will not leave by itself: completed, failed, or canceled. The
counterpart of workspace.deleted / workflow.deleted, for the end of a run rather than the end of its
record — so a host application can release what it was holding for that run (a claimed resource, a
reserved slot) without polling for it.
Emitted after the run’s own persistence has committed, and for sub-workflows as well as root runs — a
consumer that only cares about root runs checks parentId.
A consumer must be idempotent: there is no guarantee the event arrives exactly once per run, and a process that dies before its listener ran will never see it at all. Anything whose correctness depends on it should reconcile against the run’s status instead, and treat the event as what makes that prompt.
import { WorkflowSettledEvent } from '@loopstack/core';export interface WorkflowSettledEvent { id: string; workspaceId: string; workflowName: string; parentId?: string; status: SettledWorkflowState; user: string;}Type Aliases
FanOutArgs
Validated/persisted args for FanOutWorkflow (the parsed form of FanOutInput).
import { FanOutArgs } from '@loopstack/core';export type FanOutArgs = z.output<typeof FanOutArgsSchema>;FanOutInput
Call-site input for FanOutWorkflow.run() — the workflow to fan out, the items
(array or keyed record), and the mode ('all' | 'allSettled').
import { FanOutInput } from '@loopstack/core';export type FanOutInput = z.input<typeof FanOutArgsSchema>;SequenceArgs
Validated/persisted args for SequenceWorkflow (the parsed form of SequenceInput).
import { SequenceArgs } from '@loopstack/core';export type SequenceArgs = z.output<typeof SequenceArgsSchema>;SequenceInput
Call-site input for SequenceWorkflow.run() — the workflow to run, the items
(array or keyed record), and the mode ('all' | 'allSettled').
import { SequenceInput } from '@loopstack/core';export type SequenceInput = z.input<typeof SequenceArgsSchema>;Variables
FanOutResultSchema
Zod schema for the aggregated FanOutWorkflow result delivered as the data field of the
TransitionInput in a parent’s callback.
Fields:
results— an array of entries (each with akey) if items were an array, otherwise a keyed record of entries; every entry carries astatus, optionaldata, and optionalerror.hasErrors— true when any child did not complete successfully.errorCount— number of children that did not complete successfully.
import { FanOutResultSchema } from '@loopstack/core';FanOutResultSchema: z.ZodObject< { results: z.ZodUnion< readonly [ z.ZodArray< z.ZodObject< { status: z.ZodEnum<{ completed: 'completed'; failed: 'failed'; canceled: 'canceled'; }>; data: z.ZodOptional<z.ZodUnknown>; error: z.ZodOptional<z.ZodString>; key: z.ZodString; }, z.core.$strip > >, z.ZodRecord< z.ZodString, z.ZodObject< { status: z.ZodEnum<{ completed: 'completed'; failed: 'failed'; canceled: 'canceled'; }>; data: z.ZodOptional<z.ZodUnknown>; error: z.ZodOptional<z.ZodString>; }, z.core.$strip > >, ] >; hasErrors: z.ZodBoolean; errorCount: z.ZodNumber; }, z.core.$strip>;SequenceResultSchema
Zod schema for the aggregated SequenceWorkflow result delivered as the data field of the
TransitionInput in a parent’s callback.
Fields:
results— an array of entries (each with akey) if items were an array, otherwise a keyed record of entries; every entry carries astatus, optionaldata, and optionalerror.hasErrors— true when any item did not complete successfully.errorCount— number of items that did not complete successfully.
import { SequenceResultSchema } from '@loopstack/core';SequenceResultSchema: z.ZodObject< { results: z.ZodUnion< readonly [ z.ZodArray< z.ZodObject< { status: z.ZodEnum<{ completed: 'completed'; failed: 'failed'; canceled: 'canceled'; skipped: 'skipped'; }>; data: z.ZodOptional<z.ZodUnknown>; error: z.ZodOptional<z.ZodString>; key: z.ZodString; }, z.core.$strip > >, z.ZodRecord< z.ZodString, z.ZodObject< { status: z.ZodEnum<{ completed: 'completed'; failed: 'failed'; canceled: 'canceled'; skipped: 'skipped'; }>; data: z.ZodOptional<z.ZodUnknown>; error: z.ZodOptional<z.ZodString>; }, z.core.$strip > >, ] >; hasErrors: z.ZodBoolean; errorCount: z.ZodNumber; }, z.core.$strip>;WORKFLOW_SETTLED
In-process event name for WorkflowSettledEvent.
import { WORKFLOW_SETTLED } from '@loopstack/core';WORKFLOW_SETTLED = 'workflow.settled';