Skip to content
Color theme

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 a RunResult (workflowId).
  • runSync(WorkflowClass, args, options) — execute inline and await a SyncRunResult; 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 a key) if items were an array, otherwise a keyed record of entries; every entry carries a status, optional data, and optional error.
  • 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 a key) if items were an array, otherwise a keyed record of entries; every entry carries a status, optional data, and optional error.
  • 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';