@aikirun/workflow 0.24.2 → 0.25.0

package/README.md

@@ -1,6 +1,6 @@
 # @aikirun/workflow
 
-Workflow SDK for Aiki durable execution platform.
+Workflow and Task SDK for Aiki durable execution platform.
 
 ## Installation
 
@@ -11,15 +11,29 @@ npm install @aikirun/workflow
 ## Quick Start
 
 ```typescript
-import { workflow } from "@aikirun/workflow";
-import { sendEmail, createProfile } from "./tasks.ts";
+import { task, workflow } from "@aikirun/workflow";
+
+// Define tasks
+const sendEmail = task({
+	name: "send-email",
+	async handler(input: { email: string; message: string }) {
+		return emailService.send(input.email, input.message);
+	},
+});
+
+const createProfile = task({
+	name: "create-profile",
+	async handler(input: { email: string }) {
+		return profileService.create(input.email);
+	},
+});
 
 // Define a workflow
 export const onboardingWorkflow = workflow({ name: "user-onboarding" });
 
 export const onboardingWorkflowV1 = onboardingWorkflow.v("1.0.0", {
 	async handler(run, input: { email: string }) {
-		await sendEmail.start(run, { email: input.email });
+		await sendEmail.start(run, { email: input.email, message: "Welcome!" });
 		await run.sleep("welcome-delay", { days: 1 });
 		await createProfile.start(run, { email: input.email });
 		return { success: true };
@@ -63,6 +77,7 @@ await dailyReport.activate(aikiClient, onboardingWorkflowV1, { email: "daily@exa
 
 - **Durable Execution** - Workflows survive crashes and restarts
 - **Task Orchestration** - Coordinate multiple tasks
+- **Schema Validation** - Validate workflow & task input and output at runtime
 - **Durable Sleep** - Sleep without blocking workers
 - **Event Handling** - Wait for external events with timeouts
 - **Child Workflows** - Compose workflows together
@@ -72,11 +87,10 @@ await dailyReport.activate(aikiClient, onboardingWorkflowV1, { email: "daily@exa
 
 ## Documentation
 
-For comprehensive documentation including retry strategies, schema validation, child workflows, and best practices, see the [Workflows Guide](https://github.com/aikirun/aiki/blob/main/docs/core-concepts/workflows.md).
+For comprehensive documentation including retry strategies, schema validation, child workflows, and best practices, see the [Workflows Guide](https://github.com/aikirun/aiki/blob/main/docs/core-concepts/workflows.md) and [Tasks Guide](https://github.com/aikirun/aiki/blob/main/docs/core-concepts/tasks.md).
 
 ## 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
 

package/dist/index.d.ts

@@ -10,7 +10,7 @@ import { ReplayManifest } from '@aikirun/types/replay-manifest';
 import { SleepResult } from '@aikirun/types/sleep';
 import { EventSendOptions, EventWaitOptions, EventWaitResult } from '@aikirun/types/event';
 import { Serializable } from '@aikirun/types/serializable';
-import { TaskInfo } from '@aikirun/types/task';
+import { TaskInfo, TaskName, TaskStartOptions, TaskDefinitionOptions } from '@aikirun/types/task';
 import { WorkflowRunStateRequest, WorkflowRunTransitionTaskStateRequestV1 } from '@aikirun/types/workflow-run-api';
 import { ScheduleOverlapPolicy, ScheduleActivateOptions, ScheduleId } from '@aikirun/types/schedule';
 
@@ -340,6 +340,70 @@ declare function schedule(params: ScheduleParams): ScheduleDefinition;
 
 declare function getSystemWorkflows(api: ApiClient): AnyWorkflowVersion[];
 
+type UnknownWorkflowRunContext = WorkflowRunContext<unknown, unknown>;
+/**
+ * Defines a durable task with deterministic execution and automatic retries.
+ *
+ * Tasks must be deterministic - the same input should always produce the same output.
+ * Tasks can be retried multiple times, so they should be idempotent when possible.
+ * Tasks execute within a workflow context and can access logging.
+ *
+ * @template Input - Type of task input (must be JSON serializable)
+ * @template Output - Type of task output (must be JSON serializable)
+ * @param params - Task configuration
+ * @param params.name - Unique task name used for execution tracking
+ * @param params.handler - Async function that executes the task logic
+ * @returns Task instance with retry and option configuration methods
+ *
+ * @example
+ * ```typescript
+ * // Simple task without retry
+ * export const sendEmail = task({
+ *   name: "send-email",
+ *   handler(input: { email: string; message: string }) {
+ *     return emailService.send(input.email, input.message);
+ *   },
+ * });
+ *
+ * // Task with retry configuration
+ * export const chargeCard = task({
+ *   name: "charge-card",
+ *   handler(input: { cardId: string; amount: number }) {
+ *     return paymentService.charge(input.cardId, input.amount);
+ *   },
+ *   options: {
+ *     retry: {
+ *       type: "fixed",
+ *       maxAttempts: 3,
+ *       delayMs: 1000,
+ *     },
+ *   },
+ * });
+ *
+ * // Execute task in workflow
+ * const result = await chargeCard.start(run, { cardId: "123", amount: 9999 });
+ * ```
+ */
+declare function task<Input extends Serializable, Output extends Serializable>(params: TaskParams<Input, Output>): Task<Input, Output>;
+interface TaskParams<Input, Output> {
+    name: string;
+    handler: (input: Input) => Promise<Output>;
+    options?: TaskDefinitionOptions;
+    schema?: RequireAtLeastOneProp<{
+        input?: StandardSchemaV1<Input>;
+        output?: StandardSchemaV1<Output>;
+    }>;
+}
+interface Task<Input, Output> {
+    name: TaskName;
+    with(): TaskBuilder<Input, Output>;
+    start: (run: UnknownWorkflowRunContext, ...args: Input extends void ? [] : [Input]) => Promise<Output>;
+}
+interface TaskBuilder<Input, Output> {
+    opt<Path extends PathFromObject<TaskStartOptions>>(path: Path, value: TypeOfValueAtPath<TaskStartOptions, Path>): TaskBuilder<Input, Output>;
+    start: Task<Input, Output>["start"];
+}
+
 /**
  * Defines a durable workflow with versioning and multiple task execution.
  *
@@ -400,4 +464,4 @@ interface Workflow {
     };
 }
 
-export { type AnyWorkflowVersion, type EventDefinition, type EventMulticaster, type EventMulticasters, type EventSender, type EventSenders, type EventWaiter, type EventWaiters, type ExecuteWorkflowParams, type ScheduleDefinition, type ScheduleHandle, type ScheduleParams, type Workflow, type WorkflowExecutionOptions, type WorkflowParams, type WorkflowRegistry, type WorkflowRunContext, type WorkflowRunHandle, type WorkflowRunWaitOptions, type WorkflowVersion, type WorkflowVersionParams, createEventSenders, createEventWaiters, createReplayManifest, createSleeper, event, executeWorkflowRun, getSystemWorkflows, schedule, workflow, workflowRegistry, workflowRunHandle };
+export { type AnyWorkflowVersion, type EventDefinition, type EventMulticaster, type EventMulticasters, type EventSender, type EventSenders, type EventWaiter, type EventWaiters, type ExecuteWorkflowParams, type ScheduleDefinition, type ScheduleHandle, type ScheduleParams, type Task, type TaskParams, type Workflow, type WorkflowExecutionOptions, type WorkflowParams, type WorkflowRegistry, type WorkflowRunContext, type WorkflowRunHandle, type WorkflowRunWaitOptions, type WorkflowVersion, type WorkflowVersionParams, createEventSenders, createEventWaiters, createReplayManifest, createSleeper, event, executeWorkflowRun, getSystemWorkflows, schedule, task, workflow, workflowRegistry, workflowRunHandle };

package/dist/index.js

@@ -965,7 +965,7 @@ function createSerializableError(error) {
   };
 }
 
-// ../task/task.ts
+// task.ts
 import { INTERNAL as INTERNAL5 } from "@aikirun/types/symbols";
 import { TaskFailedError } from "@aikirun/types/task-error";
 import {
@@ -1644,6 +1644,7 @@ export {
   executeWorkflowRun,
   getSystemWorkflows,
   schedule,
+  task,
   workflow,
   workflowRegistry,
   workflowRunHandle

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@aikirun/workflow",
-	"version": "0.24.2",
-	"description": "Workflow SDK for Aiki - define durable workflows with tasks, sleeps, waits, and event handling",
+	"version": "0.25.0",
+	"description": "Workflow and Task SDK for Aiki - define durable workflows and tasks with automatic retries, deterministic execution, and replay",
 	"type": "module",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
@@ -18,7 +18,7 @@
 		"build": "tsup"
 	},
 	"dependencies": {
-		"@aikirun/types": "0.24.2",
+		"@aikirun/types": "0.25.0",
 		"@standard-schema/spec": "^1.1.0"
 	},
 	"publishConfig": {