@aikirun/workflow 0.8.0 → 0.9.1

package/README.md

@@ -1,6 +1,6 @@
 # @aikirun/workflow
 
-Workflow SDK for Aiki durable execution platform - define durable workflows with tasks, sleeps, waits, and event handling.
+Workflow SDK for Aiki durable execution platform.
 
 ## Installation
 
@@ -10,150 +10,27 @@ npm install @aikirun/workflow
 
 ## Quick Start
 
-### Define a Workflow
-
 ```typescript
 import { workflow } from "@aikirun/workflow";
-import { markUserVerified, sendVerificationEmail } from "./tasks.ts";
+import { sendEmail, createProfile } from "./tasks.ts";
 
+// Define a workflow
 export const onboardingWorkflow = workflow({ name: "user-onboarding" });
 
 export const onboardingWorkflowV1 = onboardingWorkflow.v("1.0.0", {
 	async handler(run, input: { email: string }) {
-		run.logger.info("Starting onboarding", { email: input.email });
-
-		// Execute a task to send verification email
-		await sendVerificationEmail.start(run, { email: input.email });
-
-		// Execute task to mark user as verified
-		// (In a real scenario, this would be triggered by an external event)
-		await markUserVerified.start(run, { email: input.email });
-
-		// Sleep for 24 hours before sending tips
-		await run.sleep("onboarding-delay", { days: 1 });
-
-		// Send usage tips
-		await sendUsageTips.start(run, { email: input.email });
-
-		return { success: true, userId: input.email };
-	},
-});
-```
-
-## Features
-
-- **Durable Execution** - Automatically survives crashes and restarts
-- **Task Orchestration** - Coordinate multiple tasks in sequence
-- **Durable Sleep** - Sleep without consuming resources or blocking workers
-- **State Snapshots** - Automatically save state at each step
-- **Error Handling** - Built-in retry and recovery mechanisms
-- **Multiple Versions** - Run different workflow versions simultaneously
-- **Logging** - Built-in structured logging for debugging
-
-## Workflow Primitives
-
-### Execute Tasks
-
-```typescript
-const result = await createUserProfile.start(run, {
-	email: input.email,
-});
-```
-
-### Sleep for a Duration
-
-```typescript
-// Sleep requires a unique id for memoization
-await run.sleep("daily-delay", { days: 1 });
-await run.sleep("processing-delay", { hours: 2, minutes: 30 });
-await run.sleep("short-pause", { seconds: 30 });
-```
-
-### Sleep Cancellation
-
-Sleeps can be cancelled externally via the `wake()` method:
-
-```typescript
-const handle = await myWorkflow.start(client, input);
-await handle.wake(); // Wakes the workflow if sleeping
-```
-
-The sleep returns a result indicating whether it was cancelled:
-
-```typescript
-const { cancelled } = await run.sleep("wait-period", { hours: 1 });
-if (cancelled) {
-  // Handle early wake-up
-}
-```
-
-### Get Workflow State
-
-```typescript
-const { state } = await run.handle.getState();
-console.log("Workflow status:", state.status);
-```
-
-### Logging
-
-```typescript
-run.logger.info("Processing user", { email: input.email });
-run.logger.debug("User created", { userId: result.userId });
-```
-
-## Workflow Options
-
-### Delayed Trigger
-
-```typescript
-export const morningWorkflowV1 = morningWorkflow.v("1.0.0", {
-	// ... workflow definition
-	opts: {
-		trigger: {
-			type: "delayed",
-			delay: { seconds: 5 }, // or: delay: 5000
-		},
+		await sendEmail.start(run, { email: input.email });
+		await run.sleep("welcome-delay", { days: 1 });
+		await createProfile.start(run, { email: input.email });
+		return { success: true };
 	},
 });
 ```
 
-### Retry Strategy
-
-```typescript
-export const paymentWorkflowV1 = paymentWorkflow.v("1.0.0", {
-	// ... workflow definition
-	opts: {
-		retry: {
-			type: "exponential",
-			maxAttempts: 3,
-			baseDelayMs: 1000,
-			maxDelayMs: 10000,
-		},
-	},
-});
-```
-
-### Reference ID
-
-```typescript
-// Assign a reference ID for tracking and lookup
-const handle = await orderWorkflowV1
-	.with().opt("reference.id", `order-${orderId}`)
-	.start(client, { orderId });
-
-// Configure conflict handling: "error" (default) or "return_existing"
-const handle = await orderWorkflowV1
-	.with().opt("reference", { id: `order-${orderId}`, onConflict: "return_existing" })
-	.start(client, { orderId });
-```
-
-## Running Workflows
-
-With the client:
+Run with a client:
 
 ```typescript
 import { client } from "@aikirun/client";
-import { onboardingWorkflowV1 } from "./workflows.ts";
 
 const aikiClient = await client({
 	url: "http://localhost:9876",
@@ -164,99 +41,28 @@ const handle = await onboardingWorkflowV1.start(aikiClient, {
 	email: "user@example.com",
 });
 
-// Wait for completion
-const result = await handle.wait(
-	{ type: "status", status: "completed" },
-	{ maxDurationMs: 60 * 1000, pollIntervalMs: 5_000 },
-);
-
-if (result.success) {
-	console.log("Workflow completed!", result.state);
-} else {
-	console.log("Workflow did not complete:", result.cause);
-}
+const result = await handle.waitForStatus("completed");
 ```
 
-With a worker:
-
-```typescript
-import { worker } from "@aikirun/worker";
-
-const aikiWorker = worker({
-	name: "my-worker",
-	workflows: [onboardingWorkflowV1],
-	opts: {
-		maxConcurrentWorkflowRuns: 10,
-	},
-});
-
-await aikiWorker.spawn(aikiClient);
-```
-
-## Execution Context
-
-The `run` parameter provides access to:
-
-```typescript
-interface WorkflowRunContext<Input, Output> {
-	id: WorkflowRunId; // Unique run ID
-	name: WorkflowName; // Workflow name
-	versionId: WorkflowVersionId; // Version ID
-	options: WorkflowOptions; // Execution options (trigger, retry, reference)
-	handle: WorkflowRunHandle<Input, Output>; // Advanced state management
-	logger: Logger; // Logging (info, debug, warn, error, trace)
-	sleep(params: SleepParams): Promise<SleepResult>; // Durable sleep
-}
-```
-
-Sleep parameters:
-- `id` (required): Unique identifier for memoization
-- Duration fields: `days`, `hours`, `minutes`, `seconds`, `milliseconds`
-
-Example: `run.sleep("my-sleep", { days: 1, hours: 2 })`
-
-## Error Handling
-
-Workflows handle errors gracefully:
-
-```typescript
-try {
-	await risky.start(run, input);
-} catch (error) {
-	run.logger.error("Task failed", { error: error.message });
-	// Workflow can decide how to proceed
-}
-```
-
-Failed workflows transition to `awaiting_retry` state and are automatically retried by the server.
-
-### Expected Errors
-
-These errors are thrown during normal workflow execution and should not be caught in workflow code:
-
-- `WorkflowRunSuspendedError` - Thrown when a workflow suspends (e.g., during sleep or awaiting events). The worker catches this error and the workflow resumes when the condition is met.
+## Features
 
-- `WorkflowRunConflictError` - Thrown when another worker has already claimed the workflow execution. This prevents duplicate execution when workers race to process the same workflow.
+- **Durable Execution** - Workflows survive crashes and restarts
+- **Task Orchestration** - Coordinate multiple tasks
+- **Durable Sleep** - Sleep without blocking workers
+- **Event Handling** - Wait for external events with timeouts
+- **Child Workflows** - Compose workflows together
+- **Automatic Retries** - Configurable retry strategies
+- **Versioning** - Run multiple versions simultaneously
 
-## Best Practices
+## Documentation
 
-1. **Keep Workflows Deterministic** - Same input should always produce same output
-2. **Expect Replays** - Code may execute multiple times during retries
-3. **Use Descriptive Events** - Name events clearly for debugging
-4. **Handle Timeouts** - Always check `event.received` after waiting
-5. **Log Strategically** - Use logger to track workflow progress
-6. **Version Your Workflows** - Deploy new versions alongside old ones
+For comprehensive documentation including retry strategies, schema validation, child workflows, and best practices, see the [Workflows Guide](https://aiki.run/docs/core-concepts/workflows).
 
 ## Related Packages
 
 - [@aikirun/task](https://www.npmjs.com/package/@aikirun/task) - Define tasks
 - [@aikirun/client](https://www.npmjs.com/package/@aikirun/client) - Start workflows
 - [@aikirun/worker](https://www.npmjs.com/package/@aikirun/worker) - Execute workflows
-- [@aikirun/types](https://www.npmjs.com/package/@aikirun/types) - Type definitions
-
-## Changelog
-
-See the [CHANGELOG](https://github.com/aikirun/aiki/blob/main/CHANGELOG.md) for version history.
 
 ## License
 

package/dist/index.d.ts

@@ -281,6 +281,7 @@ declare class WorkflowVersionImpl<Input, Output, AppContext, TEventsDefinition e
     private handler;
     private tryExecuteWorkflow;
     private assertRetryAllowed;
+    private parse;
     private createFailedState;
     private createAwaitingRetryState;
 }

package/dist/index.js

@@ -878,19 +878,7 @@ var WorkflowVersionImpl = class _WorkflowVersionImpl {
     parentRunHandle[INTERNAL5].assertExecutionAllowed();
     const { client } = parentRunHandle[INTERNAL5];
     const inputRaw = isNonEmptyArray(args) ? args[0] : void 0;
-    let input = inputRaw;
-    if (this.params.schema?.input) {
-      try {
-        input = this.params.schema.input.parse(inputRaw);
-      } catch (error) {
-        await parentRunHandle[INTERNAL5].transitionState({
-          status: "failed",
-          cause: "self",
-          error: createSerializableError(error)
-        });
-        throw new WorkflowRunFailedError2(parentRun.id, parentRunHandle.run.attempts);
-      }
-    }
+    const input = await this.parse(parentRunHandle, this.params.schema?.input, inputRaw);
     const inputHash = await hashInput(input);
     const reference = this.params.opts?.reference;
     const path = getWorkflowRunPath(this.name, this.versionId, reference?.id ?? inputHash);
@@ -904,6 +892,9 @@ var WorkflowVersionImpl = class _WorkflowVersionImpl {
         parentRun.logger
       );
       const { run: existingRun } = await client.api.workflowRun.getByIdV1({ id: existingRunInfo.id });
+      if (existingRun.state.status === "completed") {
+        await this.parse(parentRunHandle, this.params.schema?.output, existingRun.state.output);
+      }
       const logger2 = parentRun.logger.child({
         "aiki.childWorkflowName": existingRun.name,
         "aiki.childWorkflowVersionId": existingRun.versionId,
@@ -985,29 +976,16 @@ var WorkflowVersionImpl = class _WorkflowVersionImpl {
     logger.info("Workflow complete");
   }
   async tryExecuteWorkflow(input, run, context, retryStrategy) {
+    const { handle } = run[INTERNAL5];
     while (true) {
       try {
         const outputRaw = await this.params.handler(run, input, context);
-        let output = outputRaw;
-        if (this.params.schema?.output) {
-          try {
-            output = this.params.schema.output.parse(outputRaw);
-          } catch (error) {
-            const { handle } = run[INTERNAL5];
-            await handle[INTERNAL5].transitionState({
-              status: "failed",
-              cause: "self",
-              error: createSerializableError(error)
-            });
-            throw new WorkflowRunFailedError2(run.id, handle.run.attempts);
-          }
-        }
+        const output = await this.parse(handle, this.params.schema?.output, outputRaw);
         return output;
       } catch (error) {
         if (error instanceof WorkflowRunSuspendedError4 || error instanceof WorkflowRunFailedError2 || error instanceof WorkflowRunConflictError5) {
           throw error;
         }
-        const { handle } = run[INTERNAL5];
         const attempts = handle.run.attempts;
         const retryParams = getRetryParams(attempts, retryStrategy);
         if (!retryParams.retriesLeft) {
@@ -1052,6 +1030,21 @@ var WorkflowVersionImpl = class _WorkflowVersionImpl {
       throw error;
     }
   }
+  async parse(handle, schema, data) {
+    if (!schema) {
+      return data;
+    }
+    try {
+      return schema.parse(data);
+    } catch (error) {
+      await handle[INTERNAL5].transitionState({
+        status: "failed",
+        cause: "self",
+        error: createSerializableError(error)
+      });
+      throw new WorkflowRunFailedError2(handle.run.id, handle.run.attempts);
+    }
+  }
   createFailedState(error) {
     if (error instanceof TaskFailedError) {
       return {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@aikirun/workflow",
-	"version": "0.8.0",
+	"version": "0.9.1",
 	"description": "Workflow SDK for Aiki - define durable workflows with tasks, sleeps, waits, and event handling",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -18,7 +18,7 @@
 		"build": "tsup"
 	},
 	"dependencies": {
-		"@aikirun/types": "0.8.0"
+		"@aikirun/types": "0.9.1"
 	},
 	"publishConfig": {
 		"access": "public"