@multiplier-labs/stepflow 0.3.1

package/dist/types-BlwFEGzj.d.ts

@@ -0,0 +1,276 @@
+import { R as RunStatus, W as WorkflowKind, S as StepStatus, a as WorkflowError } from './types-BVShq7zT.js';
+
+/**
+ * Storage interface types for the workflow engine.
+ * Implement StorageAdapter to use your preferred database.
+ */
+
+/**
+ * Extended status of a workflow run.
+ * Adds 'pending' and 'timeout' to the core statuses.
+ */
+type ExtendedRunStatus = "pending" | "queued" | "running" | "succeeded" | "failed" | "canceled" | "timeout";
+/**
+ * Extended status of a workflow step.
+ * Uses 'completed' instead of 'succeeded' for consistency.
+ */
+type ExtendedStepStatus = "pending" | "running" | "completed" | "failed" | "skipped" | "canceled";
+/**
+ * Stored representation of a workflow run.
+ */
+interface WorkflowRunRecord {
+    id: string;
+    kind: string;
+    status: RunStatus;
+    parentRunId?: string;
+    input: Record<string, unknown>;
+    context: Record<string, unknown>;
+    output?: Record<string, unknown>;
+    error?: {
+        code: string;
+        message: string;
+    };
+    metadata?: Record<string, unknown>;
+    priority?: number;
+    timeoutMs?: number;
+    createdAt: Date;
+    startedAt?: Date;
+    finishedAt?: Date;
+}
+/**
+ * Stored representation of a workflow step execution.
+ */
+interface WorkflowRunStepRecord {
+    id: string;
+    runId: string;
+    stepKey: string;
+    stepName: string;
+    status: StepStatus;
+    attempt: number;
+    result?: unknown;
+    error?: WorkflowError;
+    startedAt?: Date;
+    finishedAt?: Date;
+}
+/**
+ * Stored workflow event.
+ */
+interface WorkflowEventRecord {
+    id: string;
+    runId: string;
+    stepKey?: string;
+    eventType: string;
+    level: "info" | "warn" | "error";
+    payload?: unknown;
+    timestamp: Date;
+}
+/**
+ * Extended workflow run record with additional fields.
+ * Used by new WorkflowStorage implementations.
+ */
+interface ExtendedWorkflowRunRecord {
+    id: string;
+    kind: string;
+    status: ExtendedRunStatus;
+    input: Record<string, unknown>;
+    context: Record<string, unknown>;
+    output?: Record<string, unknown>;
+    error?: {
+        code: string;
+        message: string;
+    };
+    metadata?: Record<string, unknown>;
+    priority: number;
+    timeoutMs?: number;
+    createdAt: Date;
+    startedAt?: Date;
+    finishedAt?: Date;
+}
+/**
+ * Step result representation.
+ */
+interface StepResult {
+    id: string;
+    runId: string;
+    stepName: string;
+    status: ExtendedStepStatus;
+    output?: Record<string, unknown>;
+    error?: Record<string, unknown>;
+    attempt: number;
+    startedAt?: Date;
+    completedAt?: Date;
+}
+/**
+ * Step record for workflow steps.
+ */
+interface StepRecord {
+    stepKey: string;
+    stepName: string;
+    status: ExtendedStepStatus;
+    result?: Record<string, unknown>;
+    error?: Record<string, unknown>;
+    attempt: number;
+    startedAt?: Date;
+    finishedAt?: Date;
+}
+/**
+ * Input for creating a new workflow run.
+ */
+interface CreateRunInput {
+    id?: string;
+    kind: string;
+    status: ExtendedRunStatus;
+    parentRunId?: string;
+    input: Record<string, unknown>;
+    context?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    priority?: number;
+    timeoutMs?: number;
+}
+/**
+ * Input for updating a workflow run.
+ */
+interface UpdateRunInput {
+    status?: ExtendedRunStatus;
+    context?: Record<string, unknown>;
+    output?: Record<string, unknown>;
+    error?: {
+        code: string;
+        message: string;
+    };
+    startedAt?: Date;
+    finishedAt?: Date;
+}
+/**
+ * Options for listing runs.
+ */
+interface ListRunsOptions {
+    kind?: WorkflowKind;
+    status?: RunStatus | RunStatus[];
+    parentRunId?: string;
+    limit?: number;
+    offset?: number;
+    orderBy?: "createdAt" | "startedAt" | "finishedAt";
+    orderDirection?: "asc" | "desc";
+}
+/**
+ * Extended options for listing runs.
+ */
+interface ExtendedListRunsOptions {
+    kind?: string;
+    status?: ExtendedRunStatus | ExtendedRunStatus[];
+    limit?: number;
+    offset?: number;
+    orderBy?: "createdAt" | "startedAt" | "finishedAt";
+    orderDir?: "asc" | "desc";
+}
+/**
+ * Options for listing events.
+ */
+interface ListEventsOptions {
+    stepKey?: string;
+    level?: "info" | "warn" | "error";
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Paginated result wrapper.
+ */
+interface PaginatedResult<T> {
+    items: T[];
+    total: number;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * New storage interface for workflow persistence.
+ * Implement this interface for new implementations.
+ */
+interface WorkflowStorage {
+    createRun(run: CreateRunInput): Promise<ExtendedWorkflowRunRecord>;
+    getRun(id: string): Promise<ExtendedWorkflowRunRecord | null>;
+    updateRun(id: string, updates: UpdateRunInput): Promise<void>;
+    listRuns(options?: ExtendedListRunsOptions): Promise<PaginatedResult<ExtendedWorkflowRunRecord>>;
+    deleteRun(id: string): Promise<void>;
+    dequeueRun(workflowKinds: string[]): Promise<ExtendedWorkflowRunRecord | null>;
+    cleanupStaleRuns(defaultTimeoutMs?: number): Promise<number>;
+    markRunsAsFailed(runIds: string[], reason: string): Promise<void>;
+    getStepResult(runId: string, stepName: string): Promise<StepResult | undefined>;
+    getStepResults(runId: string): Promise<StepResult[]>;
+    getStepsForRun(runId: string): Promise<StepRecord[]>;
+    saveStepResult(result: Omit<StepResult, "id"> & {
+        id?: string;
+    }): Promise<void>;
+    initialize(): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * Abstract storage adapter interface.
+ * Implement this interface to use your preferred database.
+ */
+interface StorageAdapter {
+    createRun(run: Omit<WorkflowRunRecord, "id" | "createdAt">): Promise<WorkflowRunRecord>;
+    getRun(runId: string): Promise<WorkflowRunRecord | null>;
+    updateRun(runId: string, updates: Partial<WorkflowRunRecord>): Promise<void>;
+    listRuns(options?: ListRunsOptions): Promise<PaginatedResult<WorkflowRunRecord>>;
+    createStep(step: Omit<WorkflowRunStepRecord, "id">): Promise<WorkflowRunStepRecord>;
+    getStep(stepId: string): Promise<WorkflowRunStepRecord | null>;
+    updateStep(stepId: string, updates: Partial<WorkflowRunStepRecord>): Promise<void>;
+    getStepsForRun(runId: string): Promise<WorkflowRunStepRecord[]>;
+    saveEvent(event: Omit<WorkflowEventRecord, "id">): Promise<void>;
+    getEventsForRun(runId: string, options?: ListEventsOptions): Promise<WorkflowEventRecord[]>;
+    /**
+     * Optional transaction support.
+     * @deprecated Transaction support is deprecated and will be removed in a future release.
+     */
+    transaction?<T>(fn: (tx: StorageAdapter) => Promise<T>): Promise<T>;
+    deleteOldRuns?(olderThan: Date): Promise<number>;
+    initialize?(): Promise<void>;
+    close?(): void | Promise<void>;
+}
+/**
+ * Database table schema for workflow runs.
+ * Note: When used with Kysely, wrap auto-generated fields with Generated<T>.
+ */
+interface StepflowRunsTable {
+    id: string;
+    kind: string;
+    status: ExtendedRunStatus;
+    input: Record<string, unknown>;
+    context: Record<string, unknown>;
+    output: Record<string, unknown> | null;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+    metadata: Record<string, unknown> | null;
+    priority: number;
+    timeout_ms: number | null;
+    created_at: Date;
+    started_at: Date | null;
+    finished_at: Date | null;
+}
+/**
+ * Database table schema for step results.
+ * Note: When used with Kysely, wrap auto-generated fields with Generated<T>.
+ */
+interface StepflowStepResultsTable {
+    id: string;
+    run_id: string;
+    step_name: string;
+    status: ExtendedStepStatus;
+    output: Record<string, unknown> | null;
+    error: Record<string, unknown> | null;
+    attempt: number;
+    started_at: Date | null;
+    completed_at: Date | null;
+}
+/**
+ * Combined database schema for Stepflow.
+ */
+interface StepflowDatabase {
+    "stepflow.runs": StepflowRunsTable;
+    "stepflow.step_results": StepflowStepResultsTable;
+}
+
+export type { CreateRunInput as C, ExtendedListRunsOptions as E, ListEventsOptions as L, PaginatedResult as P, StepRecord as S, UpdateRunInput as U, WorkflowEventRecord as W, ExtendedRunStatus as a, ExtendedStepStatus as b, ExtendedWorkflowRunRecord as c, ListRunsOptions as d, StepResult as e, StepflowDatabase as f, StepflowRunsTable as g, StepflowStepResultsTable as h, StorageAdapter as i, WorkflowRunRecord as j, WorkflowRunStepRecord as k, WorkflowStorage as l };

package/dist/types-DzkEqnQJ.d.ts

@@ -0,0 +1,75 @@
+import { W as WorkflowKind } from './types-BVShq7zT.js';
+
+/**
+ * Event system types for the workflow engine.
+ */
+
+/**
+ * Built-in event types emitted by the workflow engine.
+ */
+type BuiltInEventType = "run.created" | "run.queued" | "run.dequeued" | "run.started" | "run.resumed" | "run.completed" | "run.failed" | "run.canceled" | "run.timeout" | "step.started" | "step.completed" | "step.failed" | "step.skipped" | "step.retry";
+/**
+ * Event types emitted by the workflow engine.
+ * Includes built-in types and allows custom events via string.
+ */
+type WorkflowEventType = BuiltInEventType | (string & {});
+/**
+ * Workflow event payload structure.
+ */
+interface WorkflowEvent {
+    /** Unique run identifier */
+    runId: string;
+    /** Workflow type */
+    kind: WorkflowKind;
+    /** Type of event */
+    eventType: WorkflowEventType;
+    /** Step key (for step-related events) */
+    stepKey?: string;
+    /** When the event occurred */
+    timestamp: Date;
+    /** Event-specific data */
+    payload?: unknown;
+}
+/**
+ * Callback function for handling workflow events.
+ */
+type EventCallback = (event: WorkflowEvent) => void;
+/**
+ * Unsubscribe function returned when subscribing to events.
+ */
+type Unsubscribe = () => void;
+/**
+ * Event transport interface.
+ * Implement this to customize how events are delivered.
+ */
+interface EventTransport {
+    /**
+     * Emit an event to all subscribers.
+     */
+    emit(event: WorkflowEvent): void;
+    /**
+     * Subscribe to events for a specific run.
+     * @returns Unsubscribe function
+     */
+    subscribe(runId: string, callback: EventCallback): Unsubscribe;
+    /**
+     * Subscribe to all events.
+     * @returns Unsubscribe function
+     */
+    subscribeAll(callback: EventCallback): Unsubscribe;
+    /**
+     * Optional: Filter events by type.
+     * @returns Unsubscribe function
+     */
+    subscribeToType?(eventType: WorkflowEventType, callback: EventCallback): Unsubscribe;
+    /**
+     * Optional: Persist event for later retrieval.
+     */
+    persist?(event: WorkflowEvent): Promise<void>;
+    /**
+     * Optional: Close/cleanup the transport.
+     */
+    close?(): void;
+}
+
+export type { BuiltInEventType as B, EventCallback as E, Unsubscribe as U, WorkflowEvent as W, EventTransport as a, WorkflowEventType as b };

package/docs/github-packages-setup.md

@@ -0,0 +1,97 @@
+# GitHub Packages Setup for @multiplier-labs/stepflow
+
+This document describes how to publish stepflow to GitHub Packages and how to install it in your projects.
+
+## Publishing (Maintainers)
+
+### Automated Publishing via Release
+
+1. Ensure your changes are merged to the main branch
+2. Go to **Releases** in the GitHub repository
+3. Click **Draft a new release**
+4. Create a tag matching the version in `package.json` (e.g., `v0.1.0`)
+5. Publish the release
+
+The GitHub Actions workflow (`.github/workflows/publish.yml`) automatically:
+- Installs dependencies
+- Builds the package
+- Publishes to GitHub Packages
+
+### Manual Publishing (if needed)
+
+```bash
+# Authenticate with GitHub Packages
+npm login --registry=https://npm.pkg.github.com
+# Username: your GitHub username
+# Password: Personal Access Token with write:packages scope
+
+# Build and publish
+npm run build
+npm publish
+```
+
+## Installing in Projects
+
+### Step 1: Configure npm for the @multiplier-labs scope
+
+Create or update `.npmrc` in your project root:
+
+```
+@multiplier-labs:registry=https://npm.pkg.github.com
+```
+
+### Step 2: Authenticate with GitHub Packages
+
+Generate a Personal Access Token (PAT):
+1. Go to GitHub → Settings → Developer settings → Personal access tokens
+2. Generate a token with `read:packages` scope
+3. Authenticate npm:
+
+```bash
+npm login --registry=https://npm.pkg.github.com
+# Username: your GitHub username
+# Password: your PAT
+# Email: your email
+```
+
+Alternatively, add to your `~/.npmrc` (for global auth):
+
+```
+//npm.pkg.github.com/:_authToken=YOUR_PAT_HERE
+```
+
+### Step 3: Install the package
+
+```bash
+npm install @multiplier-labs/stepflow
+```
+
+## Usage in CI/CD
+
+For GitHub Actions, use the built-in `GITHUB_TOKEN`:
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: '20'
+    registry-url: 'https://npm.pkg.github.com'
+    scope: '@multiplier-labs'
+
+- run: npm ci
+  env:
+    NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+For other CI systems, set `NODE_AUTH_TOKEN` environment variable to a PAT with `read:packages` scope.
+
+## Versioning
+
+Update the version in `package.json` before creating a release:
+
+```bash
+npm version patch  # 0.1.0 → 0.1.1
+npm version minor  # 0.1.0 → 0.2.0
+npm version major  # 0.1.0 → 1.0.0
+```
+
+Then push the tag and create a release on GitHub.