@yieldstar/core

Base types, abstract classes, and the WorkflowRunner execution engine. This package defines the interfaces that runtime implementations (SQLite, Postgres) must satisfy.

Install

bun add @yieldstar/core

WorkflowRunner

Executes a workflow generator against the heap and scheduler. The runner advances the generator one step per invocation — it mediates between the invoker and the scheduling layer.

import { WorkflowRunner } from "@yieldstar/core";

const runner = new WorkflowRunner({
  router,
  heapClient,
  schedulerClient,
  logger,
});
Constructor paramTypeDescription
routerWorkflowRouterMap of workflow IDs to generators
heapClientHeapClientStep cache implementation
schedulerClientSchedulerClientTimer/wake-up implementation
loggerLoggerPino logger

HeapClient (abstract class)

Persistence layer for step results, indexed by (executionId, stepKey).

abstract readStep(params: {
  executionId: string;
  stepKey: string;
}): Promise<HeapRecord | null>;

abstract writeStep(params: {
  executionId: string;
  stepKey: string;
  stepAttempt: number;
  stepDone: boolean;
  stepResponseJson: string;
}): Promise<void>;

HeapRecord

type HeapRecord = {
  stepResponseJson: string;
  meta: { attempt: number; done: boolean };
};

SchedulerClient (interface)

interface SchedulerClient {
  requestWakeUp(event: WorkflowEvent, resumeIn?: number): Promise<void>;
}

WorkflowInvoker (type)

type WorkflowInvoker = {
  workflowEndEmitter: EventEmitter;
  execute(event: ExecutionEvent): Promise<void>;
};

EventProcessor (type)

type EventProcessor = (
  event: WorkflowEvent,
  logger: Logger
) => Promise<void | WorkflowResult<any>>;

Step response classes

ClassType stringDescription
StepKey"step-key"Cache key for the current step
StepCacheCheck"cache-check"Signals the runner to look up cached state
StepResult"step-result"Wraps a successful step return value
StepError"step-error"Wraps a caught error with optional retry policy
StepDelay"step-delay"Carries a resumeIn timestamp
StepInvalid"step-invalid"Protocol violation (e.g., missing yield*)
WorkflowResult"workflow-result"Wraps the workflow's return value
WorkflowDelay"workflow-delay"Emitted by the runner when a delay needs scheduling
WorkflowRestart"workflow-restart"Signals the runtime to re-invoke

Event types

type TriggerEvent<WorkflowId, Params> = {
  workflowId: WorkflowId;
  executionId?: string;
  params: Params;
  context?: Record<string, any>;
};

type ExecutionEvent<Params> = {
  workflowId: string;
  executionId: string;
  params: Params;
  context?: Record<string, any>;
};

type WorkflowEvent<Params, Context> = {
  workflowId: string;
  executionId: string;
  params: Params;
  context: Context;
};

Middleware types

type MiddlewareNext = () => Promise<Response>;

type MiddlewareFunction = (
  req: Request,
  event: MiddlewareEvent,
  next: MiddlewareNext,
  logger: Logger
) => Promise<Response>;