@aikirun/task 0.8.0 → 0.9.1

package/README.md

@@ -1,7 +1,6 @@
 # @aikirun/task
 
-Task SDK for Aiki durable execution platform - define reliable tasks with automatic retries, idempotency, and error
-handling.
+Task SDK for Aiki durable execution platform.
 
 ## Installation
 
@@ -11,159 +10,52 @@ npm install @aikirun/task
 
 ## Quick Start
 
-### Define a Simple Task
-
 ```typescript
 import { task } from "@aikirun/task";
 
-export const sendVerificationEmail = task({
-	name: "send-verification",
-	async handler(input: { email: string }) {
-		return emailService.sendVerification(input.email);
+export const sendEmail = task({
+	name: "send-email",
+	async handler(input: { email: string; message: string }) {
+		return emailService.send(input.email, input.message);
 	},
 });
 ```
 
-### Task with Retry Configuration
-
-```typescript
-export const ringAlarm = task({
-	name: "ring-alarm",
-	handler(input: { song: string }) {
-		return Promise.resolve(audioService.play(input.song));
-	},
-	opts: {
-		retry: {
-			type: "fixed",
-			maxAttempts: 3,
-			delayMs: 1000,
-		},
-	},
-});
-```
-
-### Execute Task in a Workflow
+Execute in a workflow:
 
 ```typescript
 import { workflow } from "@aikirun/workflow";
 
-export const morningWorkflow = workflow({ name: "morning-routine" });
+export const notificationWorkflow = workflow({ name: "notifications" });
 
-export const morningWorkflowV1 = morningWorkflow.v("1.0.0", {
-	async handler(run, input) {
-		const result = await ringAlarm.start(run, { song: "alarm.mp3" });
-		console.log("Task completed:", result);
+export const notificationWorkflowV1 = notificationWorkflow.v("1.0.0", {
+	async handler(run, input: { email: string }) {
+		await sendEmail.start(run, {
+			email: input.email,
+			message: "Welcome!",
+		});
+		return { sent: true };
 	},
 });
 ```
 
 ## Features
 
-- **Idempotent Execution** - Tasks can be safely retried without unintended side effects
-- **Automatic Retries** - Multiple retry strategies (fixed, exponential, jittered)
-- **Reference IDs** - Custom identifiers for tracking and deduplication
-- **Error Handling** - Structured error information with recovery strategies
-- **State Tracking** - Task execution state persists across failures
-- **Type Safety** - Full TypeScript support with input/output types
-
-## Task Configuration
+- **Automatic Retries** - Configurable retry strategies (fixed, exponential, jittered)
+- **Idempotent Execution** - Same input returns cached result
+- **Reference IDs** - Custom identifiers for deduplication
+- **Schema Validation** - Validate input and output at runtime
+- **Type Safety** - Full TypeScript support
 
-```typescript
-interface TaskOptions {
-	retry?: RetryStrategy;
-	reference?: { id: string; onConflict?: "error" | "return_existing" };
-}
-```
+## Documentation
 
-### Retry Strategies
-
-#### Never Retry
-
-```typescript
-opts: {
-  retry: { type: "never" },
-}
-```
-
-#### Fixed Delay
-
-```typescript
-opts: {
-  retry: {
-    type: "fixed",
-    maxAttempts: 3,
-    delayMs: 1000,
-  },
-}
-```
-
-#### Exponential Backoff
-
-```typescript
-opts: {
-  retry: {
-    type: "exponential",
-    maxAttempts: 5,
-    baseDelayMs: 1000,
-    factor: 2,
-    maxDelayMs: 30000,
-  },
-}
-```
-
-#### Jittered Exponential
-
-```typescript
-opts: {
-  retry: {
-    type: "jittered",
-    maxAttempts: 5,
-    baseDelayMs: 1000,
-    jitterFactor: 0.1,
-    maxDelayMs: 30000,
-  },
-}
-```
-
-## Execution Context
-
-Tasks are executed within a workflow's execution context. Logging happens in the workflow:
-
-```typescript
-export const processPayment = task({
-	name: "process-payment",
-	async handler(input: { amount: number }) {
-		return { success: true, transactionId: "tx_123" };
-	},
-});
-
-export const paymentWorkflowV1 = paymentWorkflow.v("1.0.0", {
-	async handler(run, input) {
-		run.logger.info("Processing payment", { amount: input.amount });
-		const result = await processPayment.start(run, { amount: input.amount });
-		run.logger.info("Payment complete", result);
-	},
-});
-```
-
-## Best Practices
-
-1. **Make Tasks Idempotent** - Tasks may be retried, so re-running should not cause unintended side effects
-2. **Use Reference IDs** - Use custom reference IDs to prevent duplicate processing
-3. **Use Meaningful Errors** - Help diagnose failures
-4. **Log Information** - Use `run.logger` for debugging
-5. **Keep Tasks Focused** - One responsibility per task
+For comprehensive documentation including retry strategies, schema validation, and best practices, see the [Tasks Guide](https://aiki.run/docs/core-concepts/tasks).
 
 ## Related Packages
 
-- [@aikirun/workflow](https://www.npmjs.com/package/@aikirun/workflow) - Use tasks in workflows
-- [@aikirun/worker](https://www.npmjs.com/package/@aikirun/worker) - Execute tasks in workers
-- [@aikirun/client](https://www.npmjs.com/package/@aikirun/client) - Manage task execution
-- [@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.
+- [@aikirun/workflow](https://www.npmjs.com/package/@aikirun/workflow) - Define workflows
+- [@aikirun/client](https://www.npmjs.com/package/@aikirun/client) - Start workflows
+- [@aikirun/worker](https://www.npmjs.com/package/@aikirun/worker) - Execute workflows
 
 ## License
 

package/dist/index.js

@@ -182,19 +182,7 @@ var TaskImpl = class _TaskImpl {
     const handle = run[INTERNAL].handle;
     handle[INTERNAL].assertExecutionAllowed();
     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 handle[INTERNAL].transitionState({
-          status: "failed",
-          cause: "self",
-          error: createSerializableError(error)
-        });
-        throw new WorkflowRunFailedError(run.id, handle.run.attempts);
-      }
-    }
+    const input = await this.parse(handle, this.params.schema?.input, inputRaw);
     const inputHash = await hashInput(input);
     const reference = this.params.opts?.reference;
     const path = getTaskPath(this.name, reference?.id ?? inputHash);
@@ -203,7 +191,7 @@ var TaskImpl = class _TaskImpl {
       await this.assertUniqueTaskReferenceId(handle, existingTaskInfo, inputHash, reference, run.logger);
     }
     if (existingTaskInfo?.state.status === "completed") {
-      return existingTaskInfo.state.output;
+      return this.parse(handle, this.params.schema?.output, existingTaskInfo.state.output);
     }
     if (existingTaskInfo?.state.status === "failed") {
       const { state } = existingTaskInfo;
@@ -245,7 +233,15 @@ var TaskImpl = class _TaskImpl {
       "aiki.taskId": taskId
     });
     logger.info("Task started", { "aiki.attempts": attempts });
-    const { output, lastAttempt } = await this.tryExecuteTask(run, input, taskId, retryStrategy, attempts, logger);
+    const { output, lastAttempt } = await this.tryExecuteTask(
+      handle,
+      input,
+      taskId,
+      retryStrategy,
+      attempts,
+      run[INTERNAL].options.spinThresholdMs,
+      logger
+    );
     await handle[INTERNAL].transitionTaskState({
       taskId,
       taskState: { status: "completed", attempts: lastAttempt, output }
@@ -253,24 +249,12 @@ var TaskImpl = class _TaskImpl {
     logger.info("Task complete", { "aiki.attempts": lastAttempt });
     return output;
   }
-  async tryExecuteTask(run, input, taskId, retryStrategy, currentAttempt, logger) {
+  async tryExecuteTask(handle, input, taskId, retryStrategy, currentAttempt, spinThresholdMs, logger) {
     let attempts = currentAttempt;
     while (true) {
       try {
         const outputRaw = await this.params.handler(input);
-        let output = outputRaw;
-        if (this.params.schema?.output) {
-          try {
-            output = this.params.schema.output.parse(outputRaw);
-          } catch (error) {
-            await run[INTERNAL].handle[INTERNAL].transitionState({
-              status: "failed",
-              cause: "self",
-              error: createSerializableError(error)
-            });
-            throw new WorkflowRunFailedError(run.id, run[INTERNAL].handle.run.attempts);
-          }
-        }
+        const output = await this.parse(handle, this.params.schema?.output, outputRaw);
         return { output, lastAttempt: attempts };
       } catch (error) {
         if (error instanceof WorkflowRunFailedError || error instanceof WorkflowRunSuspendedError || error instanceof WorkflowRunConflictError) {
@@ -283,7 +267,7 @@ var TaskImpl = class _TaskImpl {
             "aiki.attempts": attempts,
             "aiki.reason": serializableError.message
           });
-          await run[INTERNAL].handle[INTERNAL].transitionTaskState({
+          await handle[INTERNAL].transitionTaskState({
             taskId,
             taskState: { status: "failed", attempts, error: serializableError }
           });
@@ -294,12 +278,12 @@ var TaskImpl = class _TaskImpl {
           "aiki.nextAttemptInMs": retryParams.delayMs,
           "aiki.reason": serializableError.message
         });
-        if (retryParams.delayMs <= run[INTERNAL].options.spinThresholdMs) {
+        if (retryParams.delayMs <= spinThresholdMs) {
           await delay(retryParams.delayMs);
           attempts++;
           continue;
         }
-        await run[INTERNAL].handle[INTERNAL].transitionTaskState({
+        await handle[INTERNAL].transitionTaskState({
           taskId,
           taskState: {
             status: "awaiting_retry",
@@ -308,7 +292,7 @@ var TaskImpl = class _TaskImpl {
             nextAttemptInMs: retryParams.delayMs
           }
         });
-        throw new WorkflowRunSuspendedError(run.id);
+        throw new WorkflowRunSuspendedError(handle.run.id);
       }
     }
   }
@@ -348,6 +332,21 @@ var TaskImpl = class _TaskImpl {
       throw new TaskFailedError(taskId, attempts, "Task retry not allowed");
     }
   }
+  async parse(handle, schema, data) {
+    if (!schema) {
+      return data;
+    }
+    try {
+      return schema.parse(data);
+    } catch (error) {
+      await handle[INTERNAL].transitionState({
+        status: "failed",
+        cause: "self",
+        error: createSerializableError(error)
+      });
+      throw new WorkflowRunFailedError(handle.run.id, handle.run.attempts);
+    }
+  }
 };
 export {
   task

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@aikirun/task",
-	"version": "0.8.0",
+	"version": "0.9.1",
 	"description": "Task SDK for Aiki - define reliable tasks with automatic retries, idempotency, and error handling",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -18,8 +18,8 @@
 		"build": "tsup"
 	},
 	"dependencies": {
-		"@aikirun/types": "0.8.0",
-		"@aikirun/workflow": "0.8.0"
+		"@aikirun/types": "0.9.1",
+		"@aikirun/workflow": "0.9.1"
 	},
 	"publishConfig": {
 		"access": "public"