@aikirun/task 0.6.0 → 0.8.0

package/README.md

@@ -17,7 +17,7 @@ npm install @aikirun/task
 import { task } from "@aikirun/task";
 
 export const sendVerificationEmail = task({
-	id: "send-verification",
+	name: "send-verification",
 	async handler(input: { email: string }) {
 		return emailService.sendVerification(input.email);
 	},
@@ -28,7 +28,7 @@ export const sendVerificationEmail = task({
 
 ```typescript
 export const ringAlarm = task({
-	id: "ring-alarm",
+	name: "ring-alarm",
 	handler(input: { song: string }) {
 		return Promise.resolve(audioService.play(input.song));
 	},
@@ -47,10 +47,10 @@ export const ringAlarm = task({
 ```typescript
 import { workflow } from "@aikirun/workflow";
 
-export const morningWorkflow = workflow({ id: "morning-routine" });
+export const morningWorkflow = workflow({ name: "morning-routine" });
 
-export const morningWorkflowV1 = morningWorkflow.v("1.0", {
-	async handler(input, run) {
+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);
 	},
@@ -61,7 +61,7 @@ export const morningWorkflowV1 = morningWorkflow.v("1.0", {
 
 - **Idempotent Execution** - Tasks can be safely retried without unintended side effects
 - **Automatic Retries** - Multiple retry strategies (fixed, exponential, jittered)
-- **Idempotency Keys** - Deduplicate task executions with custom keys
+- **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
@@ -70,8 +70,8 @@ export const morningWorkflowV1 = morningWorkflow.v("1.0", {
 
 ```typescript
 interface TaskOptions {
-	retry?: RetryStrategy; // Retry strategy
-	idempotencyKey?: string; // For deduplication
+	retry?: RetryStrategy;
+	reference?: { id: string; onConflict?: "error" | "return_existing" };
 }
 ```
 
@@ -131,14 +131,14 @@ Tasks are executed within a workflow's execution context. Logging happens in the
 
 ```typescript
 export const processPayment = task({
-	id: "process-payment",
+	name: "process-payment",
 	async handler(input: { amount: number }) {
 		return { success: true, transactionId: "tx_123" };
 	},
 });
 
-export const paymentWorkflowV1 = paymentWorkflow.v("1.0", {
-	async handler(input, run) {
+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);
@@ -149,7 +149,7 @@ export const paymentWorkflowV1 = paymentWorkflow.v("1.0", {
 ## Best Practices
 
 1. **Make Tasks Idempotent** - Tasks may be retried, so re-running should not cause unintended side effects
-2. **Use Idempotency Keys** - Use custom keys to prevent duplicate processing
+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

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-import { SerializableInput } from '@aikirun/types/error';
-import { RetryStrategy } from '@aikirun/types/retry';
-import { TaskId } from '@aikirun/types/task';
+import { Serializable } from '@aikirun/types/serializable';
+import { TaskName, TaskOptions } from '@aikirun/types/task';
+import { Schema } from '@aikirun/types/validator';
 import { WorkflowRunContext } from '@aikirun/workflow';
+import { RequireAtLeastOneProp } from '@aikirun/types/utils';
 
 type NonEmptyArray<T> = [T, ...T[]];
 
@@ -22,9 +23,6 @@ type PathFromObjectInternal<T, IncludeArrayKeys extends boolean> = And<[
 type ExtractObjectType<T> = T extends object ? T : never;
 type TypeOfValueAtPath<T extends object, Path extends PathFromObject<T>> = Path extends keyof T ? T[Path] : Path extends `${infer First}.${infer Rest}` ? First extends keyof T ? undefined extends T[First] ? Rest extends PathFromObject<ExtractObjectType<T[First]>> ? TypeOfValueAtPath<ExtractObjectType<T[First]>, Rest> | undefined : never : Rest extends PathFromObject<ExtractObjectType<T[First]>> ? TypeOfValueAtPath<ExtractObjectType<T[First]>, Rest> : never : never : never;
 
-interface Schema<Data> {
-    parse: (data: unknown) => Data;
-}
 interface EventDefinition<Data> {
     _type: Data;
     schema?: Schema<Data>;
@@ -41,7 +39,7 @@ type EventsDefinition = Record<string, EventDefinition<unknown>>;
  * @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.id - Unique task id used for execution tracking
+ * @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
  *
@@ -49,7 +47,7 @@ type EventsDefinition = Record<string, EventDefinition<unknown>>;
  * ```typescript
  * // Simple task without retry
  * export const sendEmail = task({
- *   id: "send-email",
+ *   name: "send-email",
  *   handler(input: { email: string; message: string }) {
  *     return emailService.send(input.email, input.message);
  *   },
@@ -57,7 +55,7 @@ type EventsDefinition = Record<string, EventDefinition<unknown>>;
  *
  * // Task with retry configuration
  * export const chargeCard = task({
- *   id: "charge-card",
+ *   name: "charge-card",
  *   handler(input: { cardId: string; amount: number }) {
  *     return paymentService.charge(input.cardId, input.amount);
  *   },
@@ -74,24 +72,24 @@ type EventsDefinition = Record<string, EventDefinition<unknown>>;
  * const result = await chargeCard.start(run, { cardId: "123", amount: 9999 });
  * ```
  */
-declare function task<Input extends SerializableInput = null, Output = void>(params: TaskParams<Input, Output>): Task<Input, Output>;
+declare function task<Input extends Serializable, Output extends Serializable>(params: TaskParams<Input, Output>): Task<Input, Output>;
 interface TaskParams<Input, Output> {
-    id: string;
+    name: string;
     handler: (input: Input) => Promise<Output>;
     opts?: TaskOptions;
+    schema?: RequireAtLeastOneProp<{
+        input?: Schema<Input>;
+        output?: Schema<Output>;
+    }>;
 }
-interface TaskOptions {
-    retry?: RetryStrategy;
-    idempotencyKey?: string;
+interface Task<Input, Output> {
+    name: TaskName;
+    with(): TaskBuilder<Input, Output>;
+    start: (run: WorkflowRunContext<unknown, unknown, EventsDefinition>, ...args: Input extends void ? [] : [Input]) => Promise<Output>;
 }
 interface TaskBuilder<Input, Output> {
     opt<Path extends PathFromObject<TaskOptions>>(path: Path, value: TypeOfValueAtPath<TaskOptions, Path>): TaskBuilder<Input, Output>;
     start: Task<Input, Output>["start"];
 }
-interface Task<Input, Output> {
-    id: TaskId;
-    with(): TaskBuilder<Input, Output>;
-    start: <WorkflowInput, WorkflowOutput>(run: WorkflowRunContext<WorkflowInput, WorkflowOutput, EventsDefinition>, ...args: Input extends null ? [] : [Input]) => Promise<Output>;
-}
 
 export { type Task, type TaskParams, task };

package/dist/index.js

@@ -22,6 +22,31 @@ function delay(ms, options) {
   });
 }
 
+// ../../lib/json/stable-stringify.ts
+function stableStringify(value) {
+  return stringifyValue(value);
+}
+function stringifyValue(value) {
+  if (value === null || value === void 0) {
+    return "null";
+  }
+  if (typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(stringifyValue).join(",")}]`;
+  }
+  const keys = Object.keys(value).sort();
+  const pairs = [];
+  for (const key of keys) {
+    const keyValue = value[key];
+    if (keyValue !== void 0) {
+      pairs.push(`${JSON.stringify(key)}:${stringifyValue(keyValue)}`);
+    }
+  }
+  return `{${pairs.join(",")}}`;
+}
+
 // ../../lib/crypto/hash.ts
 async function sha256(input) {
   const data = new TextEncoder().encode(input);
@@ -29,6 +54,9 @@ async function sha256(input) {
   const hashArray = Array.from(new Uint8Array(hashBuffer));
   return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
 }
+async function hashInput(input) {
+  return sha256(stableStringify({ input }));
+}
 
 // ../../lib/error/serializable.ts
 function createSerializableError(error) {
@@ -43,25 +71,6 @@ function createSerializableError(error) {
   };
 }
 
-// ../../lib/json/stable-stringify.ts
-function stableStringify(value) {
-  if (value === null || value === void 0) {
-    return JSON.stringify(value);
-  }
-  if (typeof value !== "object") {
-    return JSON.stringify(value);
-  }
-  if (Array.isArray(value)) {
-    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
-  }
-  const keys = Object.keys(value).sort();
-  const pairs = keys.map((key) => {
-    const val = value[key];
-    return `${JSON.stringify(key)}:${stableStringify(val)}`;
-  });
-  return `{${pairs.join(",")}}`;
-}
-
 // ../../lib/object/overrider.ts
 function set(obj, path, value) {
   const keys = path.split(".");
@@ -91,6 +100,11 @@ var objectOverrider = (defaultObj) => (obj) => {
   return createBuilder([]);
 };
 
+// ../../lib/path/index.ts
+function getTaskPath(name, referenceId) {
+  return `${name}/${referenceId}`;
+}
+
 // ../../lib/retry/strategy.ts
 function getRetryParams(attempts, strategy) {
   const strategyType = strategy.type;
@@ -142,16 +156,20 @@ function getRetryParams(attempts, strategy) {
 // task.ts
 import { INTERNAL } from "@aikirun/types/symbols";
 import { TaskFailedError } from "@aikirun/types/task";
-import { WorkflowRunSuspendedError } from "@aikirun/types/workflow-run";
+import {
+  WorkflowRunConflictError,
+  WorkflowRunFailedError,
+  WorkflowRunSuspendedError
+} from "@aikirun/types/workflow-run";
 function task(params) {
   return new TaskImpl(params);
 }
 var TaskImpl = class _TaskImpl {
   constructor(params) {
     this.params = params;
-    this.id = params.id;
+    this.name = params.name;
   }
-  id;
+  name;
   with() {
     const optsOverrider = objectOverrider(this.params.opts ?? {});
     const createBuilder = (optsBuilder) => ({
@@ -163,50 +181,101 @@ var TaskImpl = class _TaskImpl {
   async start(run, ...args) {
     const handle = run[INTERNAL].handle;
     handle[INTERNAL].assertExecutionAllowed();
-    const input = isNonEmptyArray(args) ? args[0] : (
-      // this cast is okay cos if args is empty, Input must be type null
-      null
-    );
-    const path = await this.getPath(input);
-    const taskState = handle.run.tasksState[path] ?? { status: "none" };
-    if (taskState.status === "completed") {
-      return taskState.output;
+    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);
+      }
     }
-    if (taskState.status === "failed") {
-      throw new TaskFailedError(path, taskState.attempts, taskState.error.message);
+    const inputHash = await hashInput(input);
+    const reference = this.params.opts?.reference;
+    const path = getTaskPath(this.name, reference?.id ?? inputHash);
+    const existingTaskInfo = handle.run.tasks[path];
+    if (existingTaskInfo) {
+      await this.assertUniqueTaskReferenceId(handle, existingTaskInfo, inputHash, reference, run.logger);
+    }
+    if (existingTaskInfo?.state.status === "completed") {
+      return existingTaskInfo.state.output;
+    }
+    if (existingTaskInfo?.state.status === "failed") {
+      const { state } = existingTaskInfo;
+      throw new TaskFailedError(existingTaskInfo.id, state.attempts, state.error.message);
     }
-    const logger = run.logger.child({
-      "aiki.component": "task-execution",
-      "aiki.taskPath": path
-    });
     let attempts = 0;
     const retryStrategy = this.params.opts?.retry ?? { type: "never" };
-    if (taskState.status !== "none") {
-      this.assertRetryAllowed(path, taskState.attempts, retryStrategy, logger);
-      logger.debug("Retrying task", {
-        "aiki.attempts": taskState.attempts,
-        "aiki.taskStatus": taskState.status
+    if (existingTaskInfo?.state) {
+      const taskId2 = existingTaskInfo.id;
+      const state = existingTaskInfo?.state;
+      this.assertRetryAllowed(taskId2, state, retryStrategy, run.logger);
+      run.logger.debug("Retrying task", {
+        "aiki.taskName": this.name,
+        "aiki.taskId": taskId2,
+        "aiki.attempts": state.attempts,
+        "aiki.taskStatus": state.status
       });
-      attempts = taskState.attempts;
-    }
-    if (taskState.status === "awaiting_retry" && handle.run.state.status === "running") {
-      throw new WorkflowRunSuspendedError(run.id);
+      attempts = state.attempts;
+      if (state.status === "awaiting_retry" && handle.run.state.status === "running") {
+        throw new WorkflowRunSuspendedError(run.id);
+      }
     }
     attempts++;
-    logger.info("Starting task", { "aiki.attempts": attempts });
-    await handle[INTERNAL].transitionTaskState(path, { status: "running", attempts });
-    const { output, lastAttempt } = await this.tryExecuteTask(run, input, path, retryStrategy, attempts, logger);
-    await handle[INTERNAL].transitionTaskState(path, { status: "completed", output });
+    const options = { retry: retryStrategy, reference };
+    const { taskId } = existingTaskInfo ? await handle[INTERNAL].transitionTaskState({
+      type: "retry",
+      taskId: existingTaskInfo.id,
+      options,
+      taskState: { status: "running", attempts, input }
+    }) : await handle[INTERNAL].transitionTaskState({
+      type: "create",
+      taskName: this.name,
+      options,
+      taskState: { status: "running", attempts, input }
+    });
+    const logger = run.logger.child({
+      "aiki.component": "task-execution",
+      "aiki.taskName": this.name,
+      "aiki.taskId": taskId
+    });
+    logger.info("Task started", { "aiki.attempts": attempts });
+    const { output, lastAttempt } = await this.tryExecuteTask(run, input, taskId, retryStrategy, attempts, logger);
+    await handle[INTERNAL].transitionTaskState({
+      taskId,
+      taskState: { status: "completed", attempts: lastAttempt, output }
+    });
     logger.info("Task complete", { "aiki.attempts": lastAttempt });
     return output;
   }
-  async tryExecuteTask(run, input, path, retryStrategy, currentAttempt, logger) {
+  async tryExecuteTask(run, input, taskId, retryStrategy, currentAttempt, logger) {
     let attempts = currentAttempt;
     while (true) {
       try {
-        const output = await this.params.handler(input);
+        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);
+          }
+        }
         return { output, lastAttempt: attempts };
       } catch (error) {
+        if (error instanceof WorkflowRunFailedError || error instanceof WorkflowRunSuspendedError || error instanceof WorkflowRunConflictError) {
+          throw error;
+        }
         const serializableError = createSerializableError(error);
         const retryParams = getRetryParams(attempts, retryStrategy);
         if (!retryParams.retriesLeft) {
@@ -214,12 +283,11 @@ var TaskImpl = class _TaskImpl {
             "aiki.attempts": attempts,
             "aiki.reason": serializableError.message
           });
-          await run[INTERNAL].handle[INTERNAL].transitionTaskState(path, {
-            status: "failed",
-            attempts,
-            error: serializableError
+          await run[INTERNAL].handle[INTERNAL].transitionTaskState({
+            taskId,
+            taskState: { status: "failed", attempts, error: serializableError }
           });
-          throw new TaskFailedError(path, attempts, serializableError.message);
+          throw new TaskFailedError(taskId, attempts, serializableError.message);
         }
         logger.debug("Task failed. It will be retried", {
           "aiki.attempts": attempts,
@@ -231,30 +299,55 @@ var TaskImpl = class _TaskImpl {
           attempts++;
           continue;
         }
-        await run[INTERNAL].handle[INTERNAL].transitionTaskState(path, {
-          status: "awaiting_retry",
-          attempts,
-          error: serializableError,
-          nextAttemptInMs: retryParams.delayMs
+        await run[INTERNAL].handle[INTERNAL].transitionTaskState({
+          taskId,
+          taskState: {
+            status: "awaiting_retry",
+            attempts,
+            error: serializableError,
+            nextAttemptInMs: retryParams.delayMs
+          }
         });
         throw new WorkflowRunSuspendedError(run.id);
       }
     }
   }
-  assertRetryAllowed(path, attempts, retryStrategy, logger) {
+  async assertUniqueTaskReferenceId(handle, existingTaskInfo, inputHash, reference, logger) {
+    if (existingTaskInfo.inputHash !== inputHash && reference) {
+      const onConflict = reference.onConflict ?? "error";
+      if (onConflict !== "error") {
+        return;
+      }
+      logger.error("Reference ID already used by another task", {
+        "aiki.taskName": this.name,
+        "aiki.referenceId": reference.id,
+        "aiki.existingTaskId": existingTaskInfo.id
+      });
+      const error = new WorkflowRunFailedError(
+        handle.run.id,
+        handle.run.attempts,
+        `Reference ID "${reference.id}" already used by another task ${existingTaskInfo.id}`
+      );
+      await handle[INTERNAL].transitionState({
+        status: "failed",
+        cause: "self",
+        error: createSerializableError(error)
+      });
+      throw error;
+    }
+  }
+  assertRetryAllowed(taskId, state, retryStrategy, logger) {
+    const { attempts } = state;
     const retryParams = getRetryParams(attempts, retryStrategy);
     if (!retryParams.retriesLeft) {
       logger.error("Task retry not allowed", {
+        "aiki.taskName": this.name,
+        "aiki.taskId": taskId,
         "aiki.attempts": attempts
       });
-      throw new TaskFailedError(path, attempts, "Task retry not allowed");
+      throw new TaskFailedError(taskId, attempts, "Task retry not allowed");
     }
   }
-  async getPath(input) {
-    const inputHash = await sha256(stableStringify(input));
-    const taskPath = this.params.opts?.idempotencyKey ? `${this.id}/${inputHash}/${this.params.opts.idempotencyKey}` : `${this.id}/${inputHash}`;
-    return taskPath;
-  }
 };
 export {
   task

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@aikirun/task",
-	"version": "0.6.0",
+	"version": "0.8.0",
 	"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.6.0",
-		"@aikirun/workflow": "0.6.0"
+		"@aikirun/types": "0.8.0",
+		"@aikirun/workflow": "0.8.0"
 	},
 	"publishConfig": {
 		"access": "public"