@aikirun/task 0.5.3

package/README.md

@@ -0,0 +1,170 @@
+# @aikirun/task
+
+Task SDK for Aiki durable execution platform - define reliable tasks with automatic retries, idempotency, and error
+handling.
+
+## Installation
+
+```bash
+npm install @aikirun/task
+```
+
+## Quick Start
+
+### Define a Simple Task
+
+```typescript
+import { task } from "@aikirun/task";
+
+export const sendVerificationEmail = task({
+	id: "send-verification",
+	async handler(input: { email: string }) {
+		return emailService.sendVerification(input.email);
+	},
+});
+```
+
+### Task with Retry Configuration
+
+```typescript
+export const ringAlarm = task({
+	id: "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
+
+```typescript
+import { workflow } from "@aikirun/workflow";
+
+export const morningWorkflow = workflow({ id: "morning-routine" });
+
+export const morningWorkflowV1 = morningWorkflow.v("1.0", {
+	async handler(input, run) {
+		const result = await ringAlarm.start(run, { song: "alarm.mp3" });
+		console.log("Task completed:", result);
+	},
+});
+```
+
+## Features
+
+- **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
+- **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
+
+```typescript
+interface TaskOptions {
+	retry?: RetryStrategy; // Retry strategy
+	idempotencyKey?: string; // For deduplication
+}
+```
+
+### 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({
+	id: "process-payment",
+	async handler(input: { amount: number }) {
+		return { success: true, transactionId: "tx_123" };
+	},
+});
+
+export const paymentWorkflowV1 = paymentWorkflow.v("1.0", {
+	async handler(input, run) {
+		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 Idempotency Keys** - Use custom keys 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
+
+## 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.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,88 @@
+import { SerializableInput } from '@aikirun/types/error';
+import { RetryStrategy } from '@aikirun/types/retry';
+import { TaskId } from '@aikirun/types/task';
+import { WorkflowRunContext } from '@aikirun/workflow';
+
+type NonEmptyArray<T> = [T, ...T[]];
+
+type NonArrayObject<T> = T extends object ? (T extends ReadonlyArray<unknown> ? never : T) : never;
+type IsSubtype<SubT, SuperT> = SubT extends SuperT ? true : false;
+type And<T extends NonEmptyArray<boolean>> = T extends [infer First, ...infer Rest] ? false extends First ? false : Rest extends NonEmptyArray<boolean> ? And<Rest> : true : never;
+type Or<T extends NonEmptyArray<boolean>> = T extends [infer First, ...infer Rest] ? true extends First ? true : Rest extends NonEmptyArray<boolean> ? Or<Rest> : false : never;
+type PathFromObject<T, IncludeArrayKeys extends boolean = false> = T extends T ? PathFromObjectInternal<T, IncludeArrayKeys> : never;
+type PathFromObjectInternal<T, IncludeArrayKeys extends boolean> = And<[
+    IsSubtype<T, object>,
+    Or<[IncludeArrayKeys, NonArrayObject<T> extends never ? false : true]>
+]> extends true ? {
+    [K in Exclude<keyof T, symbol>]-?: And<[
+        IsSubtype<NonNullable<T[K]>, object>,
+        Or<[IncludeArrayKeys, NonArrayObject<NonNullable<T[K]>> extends never ? false : true]>
+    ]> extends true ? K | `${K}.${PathFromObjectInternal<NonNullable<T[K]>, IncludeArrayKeys>}` : K;
+}[Exclude<keyof T, symbol>] : "";
+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;
+
+/**
+ * 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.id - Unique task id 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({
+ *   id: "send-email",
+ *   handler(input: { email: string; message: string }) {
+ *     return emailService.send(input.email, input.message);
+ *   },
+ * });
+ *
+ * // Task with retry configuration
+ * export const chargeCard = task({
+ *   id: "charge-card",
+ *   handler(input: { cardId: string; amount: number }) {
+ *     return paymentService.charge(input.cardId, input.amount);
+ *   },
+ *   opts: {
+ *     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 SerializableInput = null, Output = void>(params: TaskParams<Input, Output>): Task<Input, Output>;
+interface TaskParams<Input, Output> {
+    id: string;
+    handler: (input: Input) => Promise<Output>;
+    opts?: TaskOptions;
+}
+interface TaskOptions {
+    retry?: RetryStrategy;
+    idempotencyKey?: string;
+}
+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>, ...args: Input extends null ? [] : [Input]) => Promise<Output>;
+}
+
+export { type Task, type TaskParams, task };

package/dist/index.js

@@ -0,0 +1,262 @@
+// ../../lib/array/utils.ts
+function isNonEmptyArray(value) {
+  return value.length > 0;
+}
+
+// ../../lib/async/delay.ts
+function delay(ms, options) {
+  const abortSignal = options?.abortSignal;
+  if (abortSignal?.aborted) {
+    return Promise.reject(abortSignal.reason);
+  }
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      clearTimeout(timeout);
+      reject(abortSignal?.reason);
+    };
+    const timeout = setTimeout(() => {
+      abortSignal?.removeEventListener("abort", abort);
+      resolve();
+    }, ms);
+    abortSignal?.addEventListener("abort", abort, { once: true });
+  });
+}
+
+// ../../lib/crypto/hash.ts
+async function sha256(input) {
+  const data = new TextEncoder().encode(input);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// ../../lib/error/serializable.ts
+function createSerializableError(error) {
+  return error instanceof Error ? {
+    message: error.message,
+    name: error.name,
+    stack: error.stack,
+    cause: error.cause ? createSerializableError(error.cause) : void 0
+  } : {
+    message: String(error),
+    name: "UnknownError"
+  };
+}
+
+// ../../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(".");
+  let currentValue = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i];
+    currentValue = currentValue[key];
+    if (currentValue === void 0 || currentValue === null) {
+      currentValue = {};
+      currentValue[key] = currentValue;
+    }
+  }
+  const lastKey = keys[keys.length - 1];
+  currentValue[lastKey] = value;
+}
+var objectOverrider = (defaultObj) => (obj) => {
+  const createBuilder = (overrides) => ({
+    with: (path, value) => createBuilder([...overrides, { path: `${path}`, value }]),
+    build: () => {
+      const clonedObject = structuredClone(obj ?? defaultObj);
+      for (const { path, value } of overrides) {
+        set(clonedObject, path, value);
+      }
+      return clonedObject;
+    }
+  });
+  return createBuilder([]);
+};
+
+// ../../lib/retry/strategy.ts
+function getRetryParams(attempts, strategy) {
+  const strategyType = strategy.type;
+  switch (strategyType) {
+    case "never":
+      return {
+        retriesLeft: false
+      };
+    case "fixed":
+      if (attempts >= strategy.maxAttempts) {
+        return {
+          retriesLeft: false
+        };
+      }
+      return {
+        retriesLeft: true,
+        delayMs: strategy.delayMs
+      };
+    case "exponential": {
+      if (attempts >= strategy.maxAttempts) {
+        return {
+          retriesLeft: false
+        };
+      }
+      const delayMs = strategy.baseDelayMs * (strategy.factor ?? 2) ** (attempts - 1);
+      return {
+        retriesLeft: true,
+        delayMs: Math.min(delayMs, strategy.maxDelayMs ?? Number.POSITIVE_INFINITY)
+      };
+    }
+    case "jittered": {
+      if (attempts >= strategy.maxAttempts) {
+        return {
+          retriesLeft: false
+        };
+      }
+      const base = strategy.baseDelayMs * (strategy.jitterFactor ?? 2) ** (attempts - 1);
+      const delayMs = Math.random() * base;
+      return {
+        retriesLeft: true,
+        delayMs: Math.min(delayMs, strategy.maxDelayMs ?? Number.POSITIVE_INFINITY)
+      };
+    }
+    default:
+      return strategyType;
+  }
+}
+
+// task.ts
+import { INTERNAL } from "@aikirun/types/symbols";
+import { TaskFailedError } from "@aikirun/types/task";
+function task(params) {
+  return new TaskImpl(params);
+}
+var TaskImpl = class _TaskImpl {
+  constructor(params) {
+    this.params = params;
+    this.id = params.id;
+  }
+  id;
+  with() {
+    const optsOverrider = objectOverrider(this.params.opts ?? {});
+    const createBuilder = (optsBuilder) => ({
+      opt: (path, value) => createBuilder(optsBuilder.with(path, value)),
+      start: (run, ...args) => new _TaskImpl({ ...this.params, opts: optsBuilder.build() }).start(run, ...args)
+    });
+    return createBuilder(optsOverrider());
+  }
+  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 logger = run.logger.child({
+      "aiki.component": "task-execution",
+      "aiki.taskPath": path
+    });
+    let attempts = 0;
+    const retryStrategy = this.params.opts?.retry ?? { type: "never" };
+    if ("attempts" in taskState) {
+      this.assertRetryAllowed(path, taskState.attempts, retryStrategy, logger);
+      logger.warn("Retrying task", {
+        "aiki.attempts": taskState.attempts,
+        "aiki.taskStatus": taskState.status
+      });
+      attempts = taskState.attempts;
+    }
+    if (taskState.status === "failed") {
+      await this.delayIfNecessary(taskState);
+    }
+    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 });
+    logger.info("Task complete", { "aiki.attempts": lastAttempt });
+    return output;
+  }
+  async tryExecuteTask(run, input, path, retryStrategy, currentAttempt, logger) {
+    let attempts = currentAttempt;
+    while (true) {
+      const attemptedAt = Date.now();
+      try {
+        const output = await this.params.handler(input);
+        return { output, lastAttempt: attempts };
+      } catch (error) {
+        const serializableError = createSerializableError(error);
+        const taskFailedState = {
+          status: "failed",
+          reason: serializableError.message,
+          attempts,
+          attemptedAt,
+          error: serializableError
+        };
+        const retryParams = getRetryParams(attempts, retryStrategy);
+        if (!retryParams.retriesLeft) {
+          await run[INTERNAL].handle[INTERNAL].transitionTaskState(path, taskFailedState);
+          logger.error("Task failed", {
+            "aiki.attempts": attempts,
+            "aiki.reason": taskFailedState.reason
+          });
+          throw new TaskFailedError(path, attempts, taskFailedState.reason);
+        }
+        const nextAttemptAt = Date.now() + retryParams.delayMs;
+        await run[INTERNAL].handle[INTERNAL].transitionTaskState(path, { ...taskFailedState, nextAttemptAt });
+        logger.debug("Task failed. Retrying", {
+          "aiki.attempts": attempts,
+          "aiki.nextAttemptAt": nextAttemptAt,
+          "aiki.reason": taskFailedState.reason
+        });
+        await delay(retryParams.delayMs);
+        attempts++;
+      }
+    }
+  }
+  assertRetryAllowed(path, attempts, retryStrategy, logger) {
+    const retryParams = getRetryParams(attempts, retryStrategy);
+    if (!retryParams.retriesLeft) {
+      logger.error("Task retry not allowed", {
+        "aiki.attempts": attempts
+      });
+      throw new TaskFailedError(path, attempts, "Task retry not allowed");
+    }
+  }
+  async delayIfNecessary(taskState) {
+    if (taskState.nextAttemptAt !== void 0) {
+      const now = Date.now();
+      const remainingDelay = Math.max(0, taskState.nextAttemptAt - now);
+      if (remainingDelay > 0) {
+        await delay(remainingDelay);
+      }
+    }
+  }
+  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

@@ -0,0 +1,28 @@
+{
+	"name": "@aikirun/task",
+	"version": "0.5.3",
+	"description": "Task SDK for Aiki - define reliable tasks with automatic retries, idempotency, and error handling",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsup"
+	},
+	"dependencies": {
+		"@aikirun/types": "0.5.3",
+		"@aikirun/workflow": "0.5.3"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"license": "Apache-2.0"
+}