@spfn/workflow 0.1.0-alpha.2

package/dist/index.d.ts

@@ -0,0 +1,545 @@
+import * as _sinclair_typebox from '@sinclair/typebox';
+import { TSchema, Static } from '@sinclair/typebox';
+import { JobDef, InferJobInput, InferJobOutput } from '@spfn/core/job';
+import { WorkflowExecution } from './entities/workflow-execution.js';
+export { NewWorkflowExecution, workflowExecutions } from './entities/workflow-execution.js';
+import { WorkflowStepExecution } from './entities/workflow-step-execution.js';
+export { NewWorkflowStepExecution, workflowStepExecutions } from './entities/workflow-step-execution.js';
+export { W as WorkflowStatus, a as WorkflowStepStatus } from './status-JJY5KGcN.js';
+import 'drizzle-orm/pg-core';
+
+/**
+ * Workflow Builder Types
+ */
+
+/**
+ * Workflow context passed to step mappers
+ */
+interface WorkflowContext<TInput, TResults extends Record<string, unknown>> {
+    /**
+     * Original workflow input
+     */
+    input: TInput;
+    /**
+     * Results from previous steps
+     */
+    results: TResults;
+    /**
+     * Execution metadata
+     */
+    execution: {
+        id: string;
+        workflowName: string;
+        startedAt: Date;
+    };
+}
+/**
+ * Step mapper function - maps workflow context to step input
+ */
+type StepMapper<TInput, TResults extends Record<string, unknown>, TStepInput> = (ctx: WorkflowContext<TInput, TResults>) => TStepInput;
+/**
+ * Step definition in a workflow
+ */
+interface WorkflowStepDef<TStepInput = unknown, TStepOutput = unknown> {
+    /**
+     * Step name (unique within workflow)
+     */
+    name: string;
+    /**
+     * Job definition
+     */
+    job: JobDef<TStepInput, TStepOutput>;
+    /**
+     * Input mapper function
+     */
+    mapper: StepMapper<unknown, Record<string, unknown>, TStepInput>;
+    /**
+     * Step type
+     */
+    type: 'sequential' | 'parallel';
+    /**
+     * Parallel group name (for parallel steps)
+     */
+    parallelGroup?: string;
+}
+/**
+ * Notification provider interface
+ */
+interface NotificationProvider {
+    name: string;
+    notify(event: WorkflowEvent): Promise<void>;
+}
+/**
+ * Workflow event types for notification
+ */
+type WorkflowEventType = 'started' | 'completed' | 'failed' | 'cancelled' | 'step.started' | 'step.completed' | 'step.failed';
+/**
+ * Workflow event for notifications
+ */
+interface WorkflowEvent {
+    type: WorkflowEventType;
+    workflowName: string;
+    executionId: string;
+    stepName?: string;
+    stepIndex?: number;
+    input?: unknown;
+    output?: unknown;
+    error?: string;
+    timestamp: Date;
+}
+/**
+ * Notification configuration
+ */
+interface NotifyConfig {
+    /**
+     * Events to notify on
+     */
+    on: WorkflowEventType[];
+    /**
+     * Condition for notification
+     */
+    when?: (event: WorkflowEvent) => boolean;
+    /**
+     * Notification providers
+     */
+    providers: NotificationProvider[];
+}
+/**
+ * Workflow definition
+ */
+interface WorkflowDef<TName extends string = string, TInput = unknown> {
+    /**
+     * Workflow name (unique identifier)
+     */
+    name: TName;
+    /**
+     * Input schema
+     */
+    inputSchema?: TSchema;
+    /**
+     * Steps in execution order
+     */
+    steps: WorkflowStepDef[];
+    /**
+     * Can resume from failure point
+     */
+    resumable: boolean;
+    /**
+     * Enable rollback on failure
+     */
+    rollbackEnabled: boolean;
+    /**
+     * Notification configurations
+     */
+    notifyConfigs: NotifyConfig[];
+    /**
+     * Type inference helper
+     */
+    _input: TInput;
+}
+/**
+ * Infer workflow input type
+ */
+type InferWorkflowInput<T> = T extends WorkflowDef<string, infer TInput> ? TInput : never;
+
+/**
+ * Workflow builder with fluent API and type inference
+ */
+declare class WorkflowBuilder<TName extends string, TInput = void, TResults extends Record<string, unknown> = Record<string, never>> {
+    private readonly _name;
+    private _inputSchema?;
+    private _steps;
+    private _resumable;
+    private _rollbackEnabled;
+    private _notifyConfigs;
+    constructor(name: TName);
+    /**
+     * Define input schema
+     */
+    input<TSchema extends _sinclair_typebox.TSchema>(schema: TSchema): WorkflowBuilder<TName, Static<TSchema>, TResults>;
+    /**
+     * Add a sequential step
+     */
+    pipe<TJob extends JobDef<any, any>, TStepName extends string = TJob['name']>(job: TJob, mapper: StepMapper<TInput, TResults, InferJobInput<TJob>>): WorkflowBuilder<TName, TInput, TResults & {
+        [K in TStepName]: InferJobOutput<TJob>;
+    }>;
+    /**
+     * Add parallel steps
+     */
+    parallel<TParallel extends Record<string, [JobDef<any, any>, StepMapper<TInput, TResults, any>]>>(steps: TParallel): WorkflowBuilder<TName, TInput, TResults & {
+        [K in keyof TParallel]: InferJobOutput<TParallel[K][0]>;
+    }>;
+    /**
+     * Enable/disable resumable (restart from failure point)
+     */
+    resumable(enabled?: boolean): this;
+    /**
+     * Enable/disable rollback on failure
+     */
+    rollback(enabled?: boolean): this;
+    /**
+     * Configure notifications (chainable — each call adds a separate config)
+     */
+    notify(config: NotifyConfig): this;
+    /**
+     * Build the workflow definition
+     */
+    build(): WorkflowDef<TName, TInput>;
+}
+/**
+ * Create a new workflow definition
+ *
+ * @example
+ * ```typescript
+ * const provisionTenant = workflow('provision-tenant')
+ *     .input(Type.Object({
+ *         tenantId: Type.String(),
+ *         plan: Type.String(),
+ *     }))
+ *     .resumable(true)
+ *     .pipe(createPodIdentity, (ctx) => ({
+ *         tenantId: ctx.input.tenantId,
+ *     }))
+ *     .parallel({
+ *         appRepo: [createAppRepo, (ctx) => ({ tenantId: ctx.input.tenantId })],
+ *         gitopsRepo: [createGitopsRepo, (ctx) => ({ tenantId: ctx.input.tenantId })],
+ *     })
+ *     .pipe(notifyComplete, (ctx) => ({
+ *         appRepoUrl: ctx.results.appRepo.repoUrl,
+ *         gitopsRepoUrl: ctx.results.gitopsRepo.repoUrl,
+ *     }))
+ *     .build();
+ * ```
+ */
+declare function workflow<TName extends string>(name: TName): WorkflowBuilder<TName>;
+
+/**
+ * Workflow Engine Types
+ */
+
+/**
+ * Logger interface for workflow engine
+ */
+interface WorkflowLogger {
+    info(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    debug(message: string, ...args: unknown[]): void;
+}
+/**
+ * Default console logger
+ */
+declare const defaultLogger: WorkflowLogger;
+/**
+ * Workflow engine configuration
+ */
+interface WorkflowEngineConfig {
+    /**
+     * Database instance (drizzle)
+     */
+    db: unknown;
+    /**
+     * Storage for large outputs (optional)
+     */
+    storage?: OutputStorage;
+    /**
+     * Large output threshold in bytes (default: 1MB)
+     */
+    largeOutputThreshold?: number;
+    /**
+     * Custom logger (optional, defaults to console)
+     */
+    logger?: WorkflowLogger;
+    /**
+     * Enable input schema validation (default: true)
+     */
+    validateInput?: boolean;
+}
+/**
+ * Output storage interface for large data
+ */
+interface OutputStorage {
+    /**
+     * Upload data and return URL reference
+     */
+    upload(data: unknown): Promise<string>;
+    /**
+     * Download data from URL reference
+     */
+    download(url: string): Promise<unknown>;
+}
+/**
+ * Execution result from start()
+ */
+interface ExecutionResult {
+    /**
+     * Execution ID
+     */
+    id: string;
+    /**
+     * Workflow name
+     */
+    workflowName: string;
+    /**
+     * Initial status
+     */
+    status: 'pending';
+}
+/**
+ * Execution status with details
+ */
+interface ExecutionStatus extends WorkflowExecution {
+    /**
+     * Step executions
+     */
+    steps: WorkflowStepExecution[];
+}
+/**
+ * Cancel options
+ */
+interface CancelOptions {
+    /**
+     * Execute rollback after cancel
+     */
+    rollback?: boolean;
+}
+/**
+ * List filter options
+ */
+interface ListOptions {
+    /**
+     * Filter by workflow name
+     */
+    workflowName?: string;
+    /**
+     * Filter by status
+     */
+    status?: string;
+    /**
+     * Limit results
+     */
+    limit?: number;
+    /**
+     * Offset for pagination
+     */
+    offset?: number;
+}
+/**
+ * Workflow engine interface
+ */
+interface WorkflowEngine<TWorkflows extends WorkflowDef<string, unknown>[]> {
+    /**
+     * Start a workflow execution
+     */
+    start<TName extends TWorkflows[number]['name']>(name: TName, input: ExtractWorkflowInput<TWorkflows, TName>): Promise<ExecutionResult>;
+    /**
+     * Get execution status
+     */
+    get(executionId: string): Promise<ExecutionStatus | null>;
+    /**
+     * Get step output
+     */
+    getStepOutput(executionId: string, stepName: string): Promise<unknown>;
+    /**
+     * List executions
+     */
+    list(options?: ListOptions): Promise<ExecutionStatus[]>;
+    /**
+     * Retry failed execution
+     */
+    retry(executionId: string): Promise<ExecutionResult>;
+    /**
+     * Cancel execution
+     */
+    cancel(executionId: string, options?: CancelOptions): Promise<void>;
+    /**
+     * Subscribe to execution events
+     */
+    subscribe(executionId: string, callback: (event: WorkflowEvent) => void): () => void;
+}
+/**
+ * Extract input type from workflow by name
+ */
+type ExtractWorkflowInput<TWorkflows extends WorkflowDef<string, unknown>[], TName extends string> = TWorkflows extends (infer W)[] ? W extends WorkflowDef<TName, infer TInput> ? TInput : never : never;
+
+/**
+ * Workflow Engine Implementation
+ *
+ * Orchestrates workflow execution using @spfn/core Job and Events
+ */
+
+/**
+ * Create a workflow engine
+ *
+ * @example
+ * ```typescript
+ * const engine = createWorkflowEngine({
+ *     workflows: [provisionTenant, deprovisionTenant],
+ *     db: database,
+ * });
+ *
+ * const execution = await engine.start('provision-tenant', {
+ *     tenantId: 'abc',
+ *     plan: 'pro',
+ * });
+ * ```
+ */
+declare function createWorkflowEngine<TWorkflows extends WorkflowDef<string, unknown>[]>(options: {
+    workflows: TWorkflows;
+} & WorkflowEngineConfig): WorkflowEngine<TWorkflows>;
+
+/**
+ * Built-in Notification Providers
+ *
+ * Only consoleProvider is provided by default.
+ * For email, SMS, Slack, etc., implement your own provider using @spfn/notification.
+ *
+ * @example
+ * ```typescript
+ * import { sendEmail } from '@spfn/notification/server';
+ * import type { NotificationProvider } from '@spfn/workflow';
+ *
+ * const emailProvider: NotificationProvider = {
+ *     name: 'email',
+ *     async notify(event) {
+ *         await sendEmail({
+ *             to: 'admin@example.com',
+ *             subject: `[Workflow] ${event.workflowName}: ${event.type}`,
+ *             text: formatEventAsText(event),
+ *         });
+ *     },
+ * };
+ * ```
+ */
+
+/**
+ * Console notification provider
+ *
+ * Logs workflow events to console. This is the only built-in provider.
+ *
+ * @example
+ * ```typescript
+ * workflow('provision')
+ *     .notify({
+ *         on: ['failed'],
+ *         providers: [consoleProvider],
+ *     });
+ * ```
+ */
+declare const consoleProvider: NotificationProvider;
+/**
+ * Helper: Format workflow event as plain text
+ *
+ * Use this when implementing custom notification providers.
+ *
+ * @example
+ * ```typescript
+ * import { formatEventAsText } from '@spfn/workflow';
+ * import { sendEmail } from '@spfn/notification/server';
+ *
+ * const emailProvider: NotificationProvider = {
+ *     name: 'email',
+ *     async notify(event) {
+ *         await sendEmail({
+ *             to: 'admin@example.com',
+ *             subject: `[Workflow] ${event.workflowName}: ${event.type}`,
+ *             text: formatEventAsText(event),
+ *         });
+ *     },
+ * };
+ * ```
+ */
+declare function formatEventAsText(event: WorkflowEvent): string;
+
+/**
+ * Workflow Router
+ *
+ * Defines a collection of workflows for server registration
+ */
+
+/**
+ * Workflow router configuration options
+ */
+interface WorkflowRouterConfig {
+    /**
+     * Large output threshold in bytes
+     * Outputs larger than this will be stored in external storage
+     * @default 1024 * 1024 (1MB)
+     */
+    largeOutputThreshold?: number;
+    /**
+     * Storage for large outputs (optional)
+     */
+    storage?: OutputStorage;
+    /**
+     * Custom logger (optional, defaults to console)
+     */
+    logger?: WorkflowLogger;
+    /**
+     * Enable input schema validation (default: true)
+     */
+    validateInput?: boolean;
+}
+/**
+ * Workflow router instance
+ *
+ * Contains workflow definitions and provides access to the engine
+ */
+interface WorkflowRouter<TWorkflows extends WorkflowDef[]> {
+    /**
+     * Registered workflows
+     */
+    readonly workflows: TWorkflows;
+    /**
+     * Internal workflows reference
+     */
+    readonly _workflows: TWorkflows;
+    /**
+     * Workflow engine instance (available after initialization)
+     */
+    readonly engine: WorkflowEngine<TWorkflows>;
+    /**
+     * Check if engine is initialized
+     */
+    readonly isInitialized: boolean;
+    /**
+     * Initialize the workflow engine
+     * Called internally by @spfn/core server
+     *
+     * @internal
+     */
+    _init: (db: WorkflowEngineConfig['db'], options?: WorkflowRouterConfig) => void;
+}
+/**
+ * Define a workflow router for server registration
+ *
+ * @example
+ * ```typescript
+ * import { workflow, defineWorkflowRouter } from '@spfn/workflow';
+ *
+ * const provisionTenant = workflow('provision-tenant')
+ *     .input(Type.Object({ tenantId: Type.String() }))
+ *     .pipe(createResources, ctx => ({ tenantId: ctx.input.tenantId }))
+ *     .build();
+ *
+ * export const workflowRouter = defineWorkflowRouter([
+ *     provisionTenant,
+ *     deprovisionTenant,
+ * ]);
+ *
+ * // In server.config.ts
+ * export default defineServerConfig()
+ *     .workflows(workflowRouter)
+ *     .build();
+ *
+ * // Usage
+ * await workflowRouter.engine.start('provision-tenant', { tenantId: 'abc' });
+ * ```
+ */
+declare function defineWorkflowRouter<TWorkflows extends WorkflowDef[]>(workflows: TWorkflows): WorkflowRouter<TWorkflows>;
+/**
+ * Type guard to check if value is a WorkflowRouter
+ */
+declare function isWorkflowRouter(value: unknown): value is WorkflowRouter<WorkflowDef[]>;
+
+export { type CancelOptions, type ExecutionResult, type ExecutionStatus, type InferWorkflowInput, type ListOptions, type NotificationProvider, type NotifyConfig, type OutputStorage, type StepMapper, WorkflowBuilder, type WorkflowContext, type WorkflowDef, type WorkflowEngine, type WorkflowEngineConfig, type WorkflowEvent, type WorkflowEventType, WorkflowExecution, type WorkflowLogger, type WorkflowRouter, type WorkflowRouterConfig, type WorkflowStepDef, WorkflowStepExecution, consoleProvider, createWorkflowEngine, defaultLogger, defineWorkflowRouter, formatEventAsText, isWorkflowRouter, workflow };