@tanstack/workflow-runtime 0.0.1

package/dist/types.d.ts

@@ -0,0 +1,375 @@
+import { AnyWorkflowDefinition, ApprovalResult, DeleteReason, RunState, RunStatus, RunStore, SerializedError, SignalDelivery, WorkflowEvent } from "@tanstack/workflow-core";
+
+//#region src/types.d.ts
+type WorkflowId = string;
+type WorkflowVersion = string;
+type RunId = string;
+type ScheduleId = string;
+type ScheduleBucketId = string;
+type LeaseOwner = string;
+type WorkflowExecutionStatus = RunStatus | 'queued';
+interface WorkflowLease {
+  owner: LeaseOwner;
+  expiresAt: number;
+}
+interface WorkflowExecution {
+  runId: RunId;
+  workflowId: WorkflowId;
+  workflowVersion?: WorkflowVersion;
+  status: WorkflowExecutionStatus;
+  input: unknown;
+  output?: unknown;
+  error?: SerializedError;
+  waitingFor?: RunState['waitingFor'];
+  pendingApproval?: RunState['pendingApproval'];
+  wakeAt?: number;
+  lease?: WorkflowLease;
+  createdAt: number;
+  updatedAt: number;
+}
+interface StoredWorkflowEvent {
+  runId: RunId;
+  eventIndex: number;
+  eventType: WorkflowEvent['type'];
+  stepId?: string;
+  event: WorkflowEvent;
+  createdAt: number;
+}
+interface LoadedExecution {
+  run: WorkflowExecution;
+  events: ReadonlyArray<StoredWorkflowEvent>;
+}
+interface CreateRunArgs {
+  runId: RunId;
+  workflowId: WorkflowId;
+  workflowVersion?: WorkflowVersion;
+  input: unknown;
+  now: number;
+}
+type CreateRunResult = {
+  kind: 'created';
+  run: WorkflowExecution;
+} | {
+  kind: 'existing';
+  run: WorkflowExecution;
+};
+interface ReadEventsArgs {
+  runId: RunId;
+  fromIndex?: number;
+}
+interface AppendEventsArgs {
+  runId: RunId;
+  expectedNextIndex: number;
+  events: ReadonlyArray<WorkflowEvent>;
+}
+interface AppendEventsResult {
+  nextIndex: number;
+}
+interface ClaimRunArgs {
+  runId: RunId;
+  leaseOwner: LeaseOwner;
+  leaseMs: number;
+  now: number;
+}
+type ClaimRunResult = {
+  kind: 'claimed';
+  run: WorkflowExecution;
+} | {
+  kind: 'not-found';
+} | {
+  kind: 'not-claimable';
+  run: WorkflowExecution;
+};
+interface HeartbeatRunLeaseArgs {
+  runId: RunId;
+  leaseOwner: LeaseOwner;
+  leaseMs: number;
+  now: number;
+}
+interface ReleaseRunLeaseArgs {
+  runId: RunId;
+  leaseOwner: LeaseOwner;
+}
+interface MarkRunPausedArgs {
+  runId: RunId;
+  waitingFor?: RunState['waitingFor'];
+  pendingApproval?: RunState['pendingApproval'];
+  wakeAt?: number;
+  now: number;
+}
+interface MarkRunFinishedArgs {
+  runId: RunId;
+  output: unknown;
+  now: number;
+}
+interface MarkRunErroredArgs {
+  runId: RunId;
+  error: SerializedError;
+  code: string;
+  now: number;
+}
+interface ScheduleTimerArgs {
+  runId: RunId;
+  workflowId: WorkflowId;
+  workflowVersion?: WorkflowVersion;
+  wakeAt: number;
+  signalId: string;
+  now: number;
+}
+interface ClaimDueTimersArgs {
+  now: number;
+  limit: number;
+  leaseOwner: LeaseOwner;
+  leaseMs: number;
+}
+interface TimerWakeup {
+  runId: RunId;
+  workflowId: WorkflowId;
+  workflowVersion?: WorkflowVersion;
+  wakeAt: number;
+  signalId: string;
+}
+interface DeliverSignalArgs<TPayload = unknown> {
+  runId: RunId;
+  delivery: SignalDelivery<TPayload>;
+  now: number;
+}
+type DeliverSignalResult = {
+  kind: 'delivered';
+  run: WorkflowExecution;
+} | {
+  kind: 'duplicate';
+  run: WorkflowExecution;
+} | {
+  kind: 'not-waiting';
+  run: WorkflowExecution;
+} | {
+  kind: 'not-found';
+};
+interface DeliverApprovalArgs {
+  runId: RunId;
+  approval: ApprovalResult;
+  now: number;
+}
+type DeliverApprovalResult = {
+  kind: 'delivered';
+  run: WorkflowExecution;
+} | {
+  kind: 'duplicate';
+  run: WorkflowExecution;
+} | {
+  kind: 'not-waiting';
+  run: WorkflowExecution;
+} | {
+  kind: 'not-found';
+};
+type WorkflowOverlapPolicy = 'skip' | 'allow' | 'buffer-one' | 'cancel-previous' | 'terminate-previous';
+type WorkflowScheduleSpec = {
+  kind: 'cron';
+  expression: string;
+  timezone?: string;
+} | {
+  kind: 'interval';
+  everyMs: number;
+  timezone?: string;
+};
+interface WorkflowScheduleDefinition {
+  id?: ScheduleId;
+  schedule: WorkflowScheduleSpec;
+  overlapPolicy?: WorkflowOverlapPolicy;
+  input?: unknown | (() => unknown | Promise<unknown>);
+  enabled?: boolean;
+}
+interface UpsertScheduleArgs {
+  scheduleId: ScheduleId;
+  workflowId: WorkflowId;
+  workflowVersion?: WorkflowVersion;
+  schedule: WorkflowScheduleSpec;
+  overlapPolicy: WorkflowOverlapPolicy;
+  input?: unknown;
+  nextFireAt?: number;
+  enabled: boolean;
+  now: number;
+}
+interface ClaimDueScheduleBucketsArgs {
+  now: number;
+  limit: number;
+  leaseOwner: LeaseOwner;
+  leaseMs: number;
+}
+interface ScheduleBucket {
+  scheduleId: ScheduleId;
+  bucketId: ScheduleBucketId;
+  workflowId: WorkflowId;
+  workflowVersion?: WorkflowVersion;
+  runId: RunId;
+  fireAt: number;
+  input: unknown;
+  overlapPolicy: WorkflowOverlapPolicy;
+}
+interface MarkScheduleBucketStartedArgs {
+  scheduleId: ScheduleId;
+  bucketId: ScheduleBucketId;
+  runId: RunId;
+  now: number;
+}
+interface ClaimStaleRunsArgs {
+  now: number;
+  limit: number;
+  leaseOwner: LeaseOwner;
+  leaseMs: number;
+}
+interface RunClaim {
+  run: WorkflowExecution;
+  lease: WorkflowLease;
+}
+interface ListRunsArgs {
+  workflowId?: WorkflowId;
+  status?: WorkflowExecutionStatus;
+  limit: number;
+  cursor?: string;
+}
+interface RunSummary {
+  runId: RunId;
+  workflowId: WorkflowId;
+  workflowVersion?: WorkflowVersion;
+  status: WorkflowExecutionStatus;
+  waitingFor?: RunState['waitingFor'];
+  pendingApproval?: RunState['pendingApproval'];
+  wakeAt?: number;
+  createdAt: number;
+  updatedAt: number;
+}
+interface RunTimeline {
+  run: WorkflowExecution;
+  events: ReadonlyArray<StoredWorkflowEvent>;
+}
+interface SaveRunStateArgs {
+  state: RunState;
+}
+interface WorkflowRunStoreAdapterStore {
+  loadRunState: (runId: RunId) => Promise<RunState | undefined>;
+  saveRunState: (args: SaveRunStateArgs) => Promise<void>;
+  deleteRun: (runId: RunId, reason: DeleteReason) => Promise<void>;
+  appendEvents: (args: AppendEventsArgs) => Promise<AppendEventsResult>;
+  readEvents: (args: ReadEventsArgs) => Promise<ReadonlyArray<StoredWorkflowEvent>>;
+  subscribeEvents?: (runId: RunId, fromIndex: number, onEvent: (event: WorkflowEvent, index: number) => void) => () => void;
+}
+type WorkflowRunStoreAdapter = RunStore;
+interface WorkflowExecutionStore extends WorkflowRunStoreAdapterStore {
+  createRun: (args: CreateRunArgs) => Promise<CreateRunResult>;
+  loadRun: (runId: RunId) => Promise<WorkflowExecution | undefined>;
+  loadExecution: (runId: RunId) => Promise<LoadedExecution | undefined>;
+  claimRun: (args: ClaimRunArgs) => Promise<ClaimRunResult>;
+  heartbeatRunLease: (args: HeartbeatRunLeaseArgs) => Promise<void>;
+  releaseRunLease: (args: ReleaseRunLeaseArgs) => Promise<void>;
+  markRunPaused: (args: MarkRunPausedArgs) => Promise<void>;
+  markRunFinished: (args: MarkRunFinishedArgs) => Promise<void>;
+  markRunErrored: (args: MarkRunErroredArgs) => Promise<void>;
+  scheduleTimer: (args: ScheduleTimerArgs) => Promise<void>;
+  claimDueTimers: (args: ClaimDueTimersArgs) => Promise<ReadonlyArray<TimerWakeup>>;
+  deliverSignal: <TPayload = unknown>(args: DeliverSignalArgs<TPayload>) => Promise<DeliverSignalResult>;
+  deliverApproval: (args: DeliverApprovalArgs) => Promise<DeliverApprovalResult>;
+  upsertSchedule: (args: UpsertScheduleArgs) => Promise<void>;
+  claimDueScheduleBuckets: (args: ClaimDueScheduleBucketsArgs) => Promise<ReadonlyArray<ScheduleBucket>>;
+  markScheduleBucketStarted: (args: MarkScheduleBucketStartedArgs) => Promise<void>;
+  claimStaleRuns: (args: ClaimStaleRunsArgs) => Promise<ReadonlyArray<RunClaim>>;
+  listRuns: (args: ListRunsArgs) => Promise<ReadonlyArray<RunSummary>>;
+  getRunTimeline: (runId: RunId) => Promise<RunTimeline | undefined>;
+}
+type WorkflowLoaderResult<TWorkflow extends AnyWorkflowDefinition = AnyWorkflowDefinition> = TWorkflow | {
+  default: TWorkflow;
+} | {
+  workflow: TWorkflow;
+};
+type WorkflowLoader<TWorkflow extends AnyWorkflowDefinition = AnyWorkflowDefinition> = () => Promise<WorkflowLoaderResult<TWorkflow>>;
+interface WorkflowRegistration<TWorkflow extends AnyWorkflowDefinition = AnyWorkflowDefinition> {
+  load: WorkflowLoader<TWorkflow>;
+  version?: WorkflowVersion;
+  previousVersions?: Record<WorkflowVersion, WorkflowLoader>;
+  schedules?: ReadonlyArray<WorkflowScheduleDefinition>;
+}
+type WorkflowRegistrationMap = Record<string, WorkflowRegistration>;
+interface WorkflowRuntimeConfig<TWorkflows extends WorkflowRegistrationMap = WorkflowRegistrationMap> {
+  workflows: TWorkflows;
+  store: WorkflowExecutionStore;
+  defaultLeaseMs?: number;
+}
+interface WorkflowRuntimeDefinition<TWorkflows extends WorkflowRegistrationMap = WorkflowRegistrationMap> extends WorkflowRuntimeConfig<TWorkflows> {
+  __kind: 'workflow-runtime';
+  startRun: (args: WorkflowRuntimeStartRunArgs) => Promise<WorkflowRuntimeRunResult>;
+  deliverSignal: <TPayload = unknown>(args: WorkflowRuntimeDeliverSignalArgs<TPayload>) => Promise<WorkflowRuntimeRunResult>;
+  deliverApproval: (args: WorkflowRuntimeDeliverApprovalArgs) => Promise<WorkflowRuntimeRunResult>;
+  sweep: (args?: WorkflowRuntimeSweepArgs) => Promise<WorkflowRuntimeSweepResult>;
+}
+interface WorkflowRuntimeStartRunArgs {
+  workflowId: WorkflowId;
+  runId: RunId;
+  input: unknown;
+  now?: number;
+  leaseOwner?: LeaseOwner;
+  leaseMs?: number;
+  threadId?: string;
+  includeEvents?: boolean;
+  maxEvents?: number;
+}
+interface WorkflowRuntimeDeliverSignalArgs<TPayload = unknown> {
+  runId: RunId;
+  signalId: string;
+  name: string;
+  payload: TPayload;
+  now?: number;
+  leaseOwner?: LeaseOwner;
+  leaseMs?: number;
+  threadId?: string;
+  includeEvents?: boolean;
+  maxEvents?: number;
+}
+interface WorkflowRuntimeDeliverApprovalArgs {
+  runId: RunId;
+  approval: ApprovalResult;
+  now?: number;
+  leaseOwner?: LeaseOwner;
+  leaseMs?: number;
+  threadId?: string;
+  includeEvents?: boolean;
+  maxEvents?: number;
+}
+type WorkflowRuntimeRunResultKind = 'completed' | 'paused' | 'errored' | 'running' | 'not-found' | 'not-claimable' | 'not-waiting' | 'duplicate';
+interface WorkflowRuntimeRunResult {
+  kind: WorkflowRuntimeRunResultKind;
+  runId: RunId;
+  workflowId?: WorkflowId;
+  run?: WorkflowExecution;
+  events: ReadonlyArray<WorkflowEvent>;
+  eventCount: number;
+  eventsTruncated?: boolean;
+}
+interface WorkflowRuntimeSweepArgs {
+  now?: number;
+  limit?: number;
+  maxScheduledRuns?: number;
+  maxTimers?: number;
+  maxDurationMs?: number;
+  leaseOwner?: LeaseOwner;
+  leaseMs?: number;
+  includeEvents?: boolean;
+  maxEvents?: number;
+}
+interface WorkflowRuntimeSweepResult {
+  scheduled: ReadonlyArray<WorkflowRuntimeRunResult>;
+  timers: ReadonlyArray<WorkflowRuntimeRunResult>;
+  summary: WorkflowRuntimeSweepSummary;
+  deadlineReached: boolean;
+  remainingMayExist: boolean;
+}
+type WorkflowRuntimeRunKindCounts = Partial<Record<WorkflowRuntimeRunResultKind, number>>;
+interface WorkflowRuntimeSweepSummary {
+  scheduled: WorkflowRuntimeRunKindCounts;
+  timers: WorkflowRuntimeRunKindCounts;
+  eventCount: number;
+  returnedEventCount: number;
+}
+//#endregion
+export { AppendEventsArgs, AppendEventsResult, ClaimDueScheduleBucketsArgs, ClaimDueTimersArgs, ClaimRunArgs, ClaimRunResult, ClaimStaleRunsArgs, CreateRunArgs, CreateRunResult, DeliverApprovalArgs, DeliverApprovalResult, DeliverSignalArgs, DeliverSignalResult, HeartbeatRunLeaseArgs, LeaseOwner, ListRunsArgs, LoadedExecution, MarkRunErroredArgs, MarkRunFinishedArgs, MarkRunPausedArgs, MarkScheduleBucketStartedArgs, ReadEventsArgs, ReleaseRunLeaseArgs, RunClaim, RunId, RunSummary, RunTimeline, SaveRunStateArgs, ScheduleBucket, ScheduleBucketId, ScheduleId, ScheduleTimerArgs, StoredWorkflowEvent, TimerWakeup, UpsertScheduleArgs, WorkflowExecution, WorkflowExecutionStatus, WorkflowExecutionStore, WorkflowId, WorkflowLease, WorkflowLoader, WorkflowLoaderResult, WorkflowOverlapPolicy, WorkflowRegistration, WorkflowRegistrationMap, WorkflowRunStoreAdapter, WorkflowRunStoreAdapterStore, WorkflowRuntimeConfig, WorkflowRuntimeDefinition, WorkflowRuntimeDeliverApprovalArgs, WorkflowRuntimeDeliverSignalArgs, WorkflowRuntimeRunKindCounts, WorkflowRuntimeRunResult, WorkflowRuntimeRunResultKind, WorkflowRuntimeStartRunArgs, WorkflowRuntimeSweepArgs, WorkflowRuntimeSweepResult, WorkflowRuntimeSweepSummary, WorkflowScheduleDefinition, WorkflowScheduleSpec, WorkflowVersion };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1 @@
+export {  };

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@tanstack/workflow-runtime",
+  "version": "0.0.1",
+  "description": "Runtime contracts for scheduling, durable execution stores, leases, timers, signals, and host adapters for TanStack Workflow.",
+  "author": "Tanner Linsley",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/workflow.git",
+    "directory": "packages/workflow-runtime"
+  },
+  "homepage": "https://tanstack.com/workflow",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
+  "keywords": [
+    "tanstack",
+    "workflow",
+    "durable-execution",
+    "runtime",
+    "typescript"
+  ],
+  "scripts": {
+    "clean": "premove ./build ./dist",
+    "lint": "eslint ./src",
+    "lint:fix": "eslint ./src --fix",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc",
+    "build": "tsdown"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./types": {
+      "import": "./dist/types.js",
+      "require": "./dist/types.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist/",
+    "src"
+  ],
+  "dependencies": {
+    "@tanstack/workflow-core": "workspace:*"
+  }
+}

package/src/define-runtime.ts

@@ -0,0 +1,46 @@
+import { createRuntimeDriver } from './runtime-driver'
+import type {
+  WorkflowRegistrationMap,
+  WorkflowRuntimeConfig,
+  WorkflowRuntimeDefinition,
+  WorkflowScheduleSpec,
+} from './types'
+
+export function defineWorkflowRuntime<
+  const TWorkflows extends WorkflowRegistrationMap,
+>(
+  config: WorkflowRuntimeConfig<TWorkflows>,
+): WorkflowRuntimeDefinition<TWorkflows> {
+  const driver = createRuntimeDriver(config)
+  return {
+    __kind: 'workflow-runtime',
+    ...config,
+    ...driver,
+  }
+}
+
+export function cron(
+  expression: string,
+  options: { timezone?: string } = {},
+): WorkflowScheduleSpec {
+  return {
+    kind: 'cron',
+    expression,
+    timezone: options.timezone,
+  }
+}
+
+export const every = {
+  milliseconds(everyMs: number): WorkflowScheduleSpec {
+    return { kind: 'interval', everyMs }
+  },
+  seconds(seconds: number): WorkflowScheduleSpec {
+    return { kind: 'interval', everyMs: seconds * 1000 }
+  },
+  minutes(minutes: number): WorkflowScheduleSpec {
+    return { kind: 'interval', everyMs: minutes * 60 * 1000 }
+  },
+  hours(hours: number): WorkflowScheduleSpec {
+    return { kind: 'interval', everyMs: hours * 60 * 60 * 1000 }
+  },
+}