@hatchet-dev/typescript-sdk 1.14.0 → 1.15.1

package/v1/client/features/workers.js

@@ -11,31 +11,50 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WorkersClient = void 0;
 /**
- * WorkersClient is used to list and manage workers
+ * The workers client is a client for managing workers programmatically within Hatchet.
  */
 class WorkersClient {
     constructor(client) {
         this.api = client.api;
         this.tenantId = client.tenantId;
     }
+    /**
+     * Get a worker by its ID.
+     * @param workerId - The ID of the worker to get.
+     * @returns A promise that resolves to the worker.
+     */
     get(workerId) {
         return __awaiter(this, void 0, void 0, function* () {
             const { data } = yield this.api.workerGet(workerId);
             return data;
         });
     }
+    /**
+     * List all workers in the tenant.
+     * @returns A promise that resolves to the list of workers.
+     */
     list() {
         return __awaiter(this, void 0, void 0, function* () {
             const { data } = yield this.api.workerList(this.tenantId);
             return data;
         });
     }
+    /**
+     * Check if a worker is paused.
+     * @param workerId - The ID of the worker to check.
+     * @returns A promise that resolves to true if the worker is paused, false otherwise.
+     */
     isPaused(workerId) {
         return __awaiter(this, void 0, void 0, function* () {
             const wf = yield this.get(workerId);
             return wf.status === 'PAUSED';
         });
     }
+    /**
+     * Pause a worker.
+     * @param workerId - The ID of the worker to pause.
+     * @returns A promise that resolves to the paused worker.
+     */
     pause(workerId) {
         return __awaiter(this, void 0, void 0, function* () {
             const { data } = yield this.api.workerUpdate(workerId, {
@@ -44,6 +63,11 @@ class WorkersClient {
             return data;
         });
     }
+    /**
+     * Unpause a worker.
+     * @param workerId - The ID of the worker to unpause.
+     * @returns A promise that resolves to the unpaused worker.
+     */
     unpause(workerId) {
         return __awaiter(this, void 0, void 0, function* () {
             const { data } = yield this.api.workerUpdate(workerId, {

package/v1/client/features/workflows.d.ts

@@ -3,7 +3,10 @@ import type { LegacyWorkflow } from '../../../legacy/legacy-transformer';
 import { HatchetClient } from '../client';
 export declare const workflowNameString: (workflow: string | WorkflowDefinition | BaseWorkflowDeclaration<any, any> | LegacyWorkflow) => string;
 /**
- * WorkflowsClient is used to list and manage workflows
+ * The workflows client is a client for managing workflows programmatically within Hatchet.
+ *
+ * NOTE: that workflows are the declaration, not the individual runs. If you're looking for runs, use the RunsClient instead.
+ *
  */
 export declare class WorkflowsClient {
     api: HatchetClient['api'];
@@ -18,7 +21,22 @@ export declare class WorkflowsClient {
      * @returns The workflow ID as a string.
      */
     getWorkflowIdFromName(workflow: string | WorkflowDefinition | BaseWorkflowDeclaration<any, any> | LegacyWorkflow): Promise<string>;
+    /**
+     * Get a workflow by its name, ID, or object.
+     * @param workflow - The workflow name, ID, or object.
+     * @returns A promise that resolves to the workflow.
+     */
     get(workflow: string | BaseWorkflowDeclaration<any, any> | LegacyWorkflow): Promise<import("../../../clients/rest/generated/data-contracts").Workflow>;
+    /**
+     * List all workflows in the tenant.
+     * @param opts - The options for the list operation.
+     * @returns A promise that resolves to the list of workflows.
+     */
     list(opts?: Parameters<typeof this.api.workflowList>[1]): Promise<import("../../../clients/rest/generated/data-contracts").WorkflowList>;
+    /**
+     * Delete a workflow by its name, ID, or object.
+     * @param workflow - The workflow name, ID, or object.
+     * @returns A promise that resolves to the deleted workflow.
+     */
     delete(workflow: string | BaseWorkflowDeclaration<any, any> | LegacyWorkflow): Promise<void>;
 }

package/v1/client/features/workflows.js

@@ -27,7 +27,10 @@ const workflowNameString = (workflow) => {
 };
 exports.workflowNameString = workflowNameString;
 /**
- * WorkflowsClient is used to list and manage workflows
+ * The workflows client is a client for managing workflows programmatically within Hatchet.
+ *
+ * NOTE: that workflows are the declaration, not the individual runs. If you're looking for runs, use the RunsClient instead.
+ *
  */
 class WorkflowsClient {
     constructor(client, cacheTTL) {
@@ -69,6 +72,11 @@ class WorkflowsClient {
             return str;
         });
     }
+    /**
+     * Get a workflow by its name, ID, or object.
+     * @param workflow - The workflow name, ID, or object.
+     * @returns A promise that resolves to the workflow.
+     */
     get(workflow) {
         return __awaiter(this, void 0, void 0, function* () {
             // Get workflow name string
@@ -103,12 +111,22 @@ class WorkflowsClient {
             }
         });
     }
+    /**
+     * List all workflows in the tenant.
+     * @param opts - The options for the list operation.
+     * @returns A promise that resolves to the list of workflows.
+     */
     list(opts) {
         return __awaiter(this, void 0, void 0, function* () {
             const { data } = yield this.api.workflowList(this.tenantId, opts);
             return data;
         });
     }
+    /**
+     * Delete a workflow by its name, ID, or object.
+     * @param workflow - The workflow name, ID, or object.
+     * @returns A promise that resolves to the deleted workflow.
+     */
     delete(workflow) {
         return __awaiter(this, void 0, void 0, function* () {
             const name = (0, exports.workflowNameString)(workflow);

package/v1/client/worker/context.d.ts

@@ -1,3 +1,12 @@
+/**
+ * The Hatchet Context class provides helper methods and useful data to tasks at runtime. It is passed as the second argument to all tasks and durable tasks.
+ *
+ * There are two types of context classes you'll encounter:
+ *
+ * - Context - The standard context for regular tasks with methods for logging, task output retrieval, cancellation, and more.
+ * - DurableContext - An extended context for durable tasks that includes additional methods for durable execution.
+ * @module Context
+ */
 import { Priority, RunOpts, TaskWorkflowDeclaration, BaseWorkflowDeclaration as WorkflowV1 } from '../../declaration';
 import { JsonObject } from '@bufbuild/protobuf';
 import { Action } from '../../../clients/dispatcher/action-listener';
@@ -94,6 +103,7 @@ export declare class Context<T, K = {}> {
      * @returns A record mapping task names to error messages.
      * @throws A warning if no errors are found (this method should be used in on-failure tasks).
      * @deprecated use ctx.errors() instead
+     * @hidden
      */
     stepRunErrors(): Record<string, string>;
     /**
@@ -156,6 +166,7 @@ export declare class Context<T, K = {}> {
      * Gets the ID of the current task run.
      * @returns The task run ID.
      * @deprecated use taskRunExternalId() instead
+     * @hidden
      */
     taskRunId(): string;
     /**
@@ -168,6 +179,7 @@ export declare class Context<T, K = {}> {
      * @param message - The message to log.
      * @param level - The log level (optional).
      * @deprecated use ctx.logger.infoger.info, ctx.logger.infoger.debug, ctx.logger.infoger.warn, ctx.logger.infoger.error, ctx.logger.infoger.trace instead
+     * @hidden
      */
     log(message: string, level?: LogLevel, extra?: LogExtra): Promise<void> | Promise<void[]>;
     get logger(): {
@@ -263,18 +275,21 @@ export declare class Context<T, K = {}> {
      * @returns The output of the task.
      * @throws An error if the task output is not found.
      * @deprecated use ctx.parentOutput instead
+     * @hidden
      */
     stepOutput<L = NextStep>(step: string): L;
     /**
      * Gets the input data for the current workflow.
      * @returns The input data for the workflow.
      * @deprecated use task input parameter instead
+     * @hidden
      */
     workflowInput(): T;
     /**
      * Gets the name of the current task.
      * @returns The name of the task.
      * @deprecated use ctx.taskName instead
+     * @hidden
      */
     stepName(): string;
     /**
@@ -283,6 +298,7 @@ export declare class Context<T, K = {}> {
      * @param workflows - An array of objects containing the workflow name, input data, and options for each workflow.
      * @returns A list of references to the spawned workflow runs.
      * @deprecated Use bulkRunNoWaitChildren or bulkRunChildren instead.
+     * @hidden
      */
     spawnWorkflows<Q extends JsonObject = any, P extends JsonObject = any>(workflows: Array<{
         workflow: string | WorkflowV1<Q, P>;
@@ -297,10 +313,15 @@ export declare class Context<T, K = {}> {
      * @param options - Additional options for spawning the workflow.
      * @returns A reference to the spawned workflow run.
      * @deprecated Use runChild or runNoWaitChild instead.
+     * @hidden
      */
     spawnWorkflow<Q extends JsonObject, P extends JsonObject>(workflow: string | WorkflowV1<Q, P> | TaskWorkflowDeclaration<Q, P>, input: Q, options?: ChildRunOpts): Promise<WorkflowRunRef<P>>;
     _incrementStreamIndex(): number;
 }
+/**
+ * DurableContext provides helper methods and useful data to durable tasks at runtime.
+ * It extends the Context class and includes additional methods for durable execution like sleepFor and waitFor.
+ */
 export declare class DurableContext<T, K = {}> extends Context<T, K> {
     waitKey: number;
     /**

package/v1/client/worker/context.js

@@ -13,6 +13,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DurableContext = exports.Context = exports.ContextWorker = void 0;
+/**
+ * The Hatchet Context class provides helper methods and useful data to tasks at runtime. It is passed as the second argument to all tasks and durable tasks.
+ *
+ * There are two types of context classes you'll encounter:
+ *
+ * - Context - The standard context for regular tasks with methods for logging, task output retrieval, cancellation, and more.
+ * - DurableContext - An extended context for durable tasks that includes additional methods for durable execution.
+ * @module Context
+ */
 /* eslint-disable no-underscore-dangle */
 /* eslint-disable max-classes-per-file */
 const declaration_1 = require("../../declaration");
@@ -146,6 +155,7 @@ class Context {
      * @returns A record mapping task names to error messages.
      * @throws A warning if no errors are found (this method should be used in on-failure tasks).
      * @deprecated use ctx.errors() instead
+     * @hidden
      */
     stepRunErrors() {
         return this.errors();
@@ -239,6 +249,7 @@ class Context {
      * Gets the ID of the current task run.
      * @returns The task run ID.
      * @deprecated use taskRunExternalId() instead
+     * @hidden
      */
     taskRunId() {
         return this.taskRunExternalId();
@@ -255,6 +266,7 @@ class Context {
      * @param message - The message to log.
      * @param level - The log level (optional).
      * @deprecated use ctx.logger.infoger.info, ctx.logger.infoger.debug, ctx.logger.infoger.warn, ctx.logger.infoger.error, ctx.logger.infoger.trace instead
+     * @hidden
      */
     log(message, level, extra) {
         const { taskRunExternalId } = this.action;
@@ -491,6 +503,7 @@ class Context {
      * @returns The output of the task.
      * @throws An error if the task output is not found.
      * @deprecated use ctx.parentOutput instead
+     * @hidden
      */
     stepOutput(step) {
         if (!this.data.parents) {
@@ -505,6 +518,7 @@ class Context {
      * Gets the input data for the current workflow.
      * @returns The input data for the workflow.
      * @deprecated use task input parameter instead
+     * @hidden
      */
     workflowInput() {
         return this.input;
@@ -513,6 +527,7 @@ class Context {
      * Gets the name of the current task.
      * @returns The name of the task.
      * @deprecated use ctx.taskName instead
+     * @hidden
      */
     stepName() {
         return this.taskName();
@@ -523,6 +538,7 @@ class Context {
      * @param workflows - An array of objects containing the workflow name, input data, and options for each workflow.
      * @returns A list of references to the spawned workflow runs.
      * @deprecated Use bulkRunNoWaitChildren or bulkRunChildren instead.
+     * @hidden
      */
     spawnWorkflows(workflows) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -586,6 +602,7 @@ class Context {
      * @param options - Additional options for spawning the workflow.
      * @returns A reference to the spawned workflow run.
      * @deprecated Use runChild or runNoWaitChild instead.
+     * @hidden
      */
     spawnWorkflow(workflow, input, options) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -624,6 +641,10 @@ class Context {
     }
 }
 exports.Context = Context;
+/**
+ * DurableContext provides helper methods and useful data to durable tasks at runtime.
+ * It extends the Context class and includes additional methods for durable execution like sleepFor and waitFor.
+ */
 class DurableContext extends Context {
     constructor() {
         super(...arguments);

package/v1/declaration.d.ts

@@ -1,6 +1,14 @@
+/**
+ * `Runnables` in the Hatchet TypeScript SDK are things that can be run, namely tasks and workflows. The two main types of runnables you'll encounter are:
+ *
+ * - `WorkflowDeclaration`, returned by `hatchet.workflow(...)`, which lets you define tasks and call `run()`, `schedule()`, `cron()`, etc.
+ * - `TaskWorkflowDeclaration`, returned by `hatchet.task(...)`, which is a single standalone task that exposes the same execution helpers as a workflow.
+ * @module Runnables
+ */
 import WorkflowRunRef from '../util/workflow-run-ref';
 import { CronWorkflows, ScheduledWorkflows, V1CreateFilterRequest } from '../clients/rest/generated/data-contracts';
 import { z } from 'zod';
+import { WorkerLabelComparator } from '../protoc/v1/workflows';
 import { IHatchetClient } from './client/client.interface';
 import { CreateWorkflowTaskOpts, CreateOnFailureTaskOpts, TaskFn, CreateWorkflowDurableTaskOpts, CreateBaseTaskOpts, CreateOnSuccessTaskOpts, Concurrency, DurableTaskFn } from './task';
 import { Duration } from './client/duration';
@@ -18,6 +26,7 @@ export declare enum Priority {
 type AdditionalMetadata = Record<string, string>;
 /**
  * Options for running a workflow.
+ * @hidden
  */
 export type RunOpts = {
     /**
@@ -46,13 +55,24 @@ export type RunOpts = {
      * failures are Error instances.
      */
     returnExceptions?: boolean;
+    /**
+     * (optional) desired worker labels for routing the workflow run to specific workers.
+     */
+    desiredWorkerLabels?: Record<string, {
+        value: string | number;
+        required?: boolean;
+        weight?: number;
+        comparator?: WorkerLabelComparator;
+    }>;
 };
 /**
  * Helper type to safely extract output types from task results
+ * @hidden
  */
 export type TaskOutput<O, Key extends string, Fallback> = O extends Record<Key, infer Value> ? (Value extends OutputType ? Value : Fallback) : Fallback;
 /**
  * Extracts a property from an object type based on task name, or falls back to inferred type
+ * @hidden
  */
 export type TaskOutputType<O, TaskName extends string, InferredType extends OutputType> = TaskName extends keyof O ? O[TaskName] extends OutputType ? O[TaskName] : InferredType : InferredType;
 type DefaultFilter = Omit<V1CreateFilterRequest, 'workflowId'>;
@@ -62,6 +82,7 @@ type DefaultFilter = Omit<V1CreateFilterRequest, 'workflowId'>;
  * Prefer using `StickyStrategy.SOFT` / `StickyStrategy.HARD` (v1, non-protobuf).
  * For backwards compatibility, the workflow/task `sticky` field also accepts legacy
  * protobuf enum values (`0`/`1`) and strings (`'SOFT'`/`'HARD'`).
+ * @internal
  */
 export declare const StickyStrategy: {
     readonly SOFT: "soft";
@@ -123,6 +144,7 @@ export type CreateTaskWorkflowOpts<I extends InputType = UnknownInputType, O ext
 export type CreateDurableTaskWorkflowOpts<I extends InputType = UnknownInputType, O extends OutputType = void> = CreateBaseWorkflowOpts & CreateBaseTaskOpts<I, O, DurableTaskFn<I, O>>;
 /**
  * Options for creating a new workflow.
+ * @hidden
  */
 export type CreateWorkflowOpts = CreateBaseWorkflowOpts & {
     /**
@@ -133,6 +155,7 @@ export type CreateWorkflowOpts = CreateBaseWorkflowOpts & {
 /**
  * Default configuration for all tasks in the workflow.
  * Can be overridden by task-specific options.
+ * @hidden
  */
 export type TaskDefaults = {
     /**
@@ -181,6 +204,7 @@ export type TaskDefaults = {
 };
 /**
  * Internal definition of a workflow and its tasks.
+ * @hidden
  */
 export type WorkflowDefinition = CreateWorkflowOpts & {
     /**
@@ -208,24 +232,28 @@ export type WorkflowDefinition = CreateWorkflowOpts & {
  * Represents a workflow that can be executed by Hatchet.
  * @template I The input type for the workflow.
  * @template O The return type of the workflow.
+ * @internal
  */
 export declare class BaseWorkflowDeclaration<I extends InputType = UnknownInputType, O extends OutputType = void> {
     /**
      * The Hatchet client instance used to execute the workflow.
+     * @internal
      */
     client: IHatchetClient | undefined;
     /**
      * The internal workflow definition.
+     * @internal
      */
     definition: WorkflowDefinition;
     /**
      * Creates a new workflow instance.
      * @param options The options for creating the workflow.
      * @param client Optional Hatchet client instance.
+     * @internal
      */
     constructor(options: CreateWorkflowOpts, client?: IHatchetClient);
     /**
-     * Triggers a workflow run without waiting for completion.
+     * Synchronously trigger a workflow run without waiting for it to complete. This method is useful for starting a workflow run and immediately returning a reference to the run without blocking while the workflow runs.
      * @param input The input data for the workflow.
      * @param options Optional configuration for this workflow run.
      * @returns A WorkflowRunRef containing the run ID and methods to get results and interact with the run.
@@ -303,6 +331,7 @@ export declare class BaseWorkflowDeclaration<I extends InputType = UnknownInputT
     get(): Promise<import("../clients/rest/generated/data-contracts").Workflow>;
     /**
      * @deprecated use definition.name instead
+     * @hidden
      */
     get id(): string;
     /**
@@ -311,6 +340,44 @@ export declare class BaseWorkflowDeclaration<I extends InputType = UnknownInputT
      */
     get name(): string;
 }
+/**
+ * A Hatchet workflow, which lets you define tasks and perform actions on the workflow.
+ *
+ * Workflows in Hatchet represent coordinated units of work that can be triggered,
+ * scheduled, or run on a cron schedule. Each workflow can contain multiple tasks
+ * that can be arranged in dependencies (DAGs), with customized retry behavior,
+ * timeouts, concurrency controls, and more.
+ *
+ * Example:
+ * ```typescript
+ * import { hatchet } from './hatchet-client';
+ *
+ * type MyInput = { name: string };
+ *
+ * const workflow = hatchet.workflow<MyInput>({
+ *   name: 'my-workflow',
+ * });
+ *
+ * workflow.task({
+ *   name: 'greet',
+ *   fn: async (input) => {
+ *     return { message: `Hello, ${input.name}!` };
+ *   },
+ * });
+ *
+ * // Run the workflow
+ * await workflow.run({ name: 'World' });
+ * ```
+ *
+ * Workflows support various execution patterns, including:
+ * - One-time execution with `run()` and `runNoWait()`
+ * - Scheduled execution with `schedule()`
+ * - Cron-based recurring execution with `cron()`
+ * - Bulk execution by passing an array input to `run()` and `runNoWait()`
+ *
+ * Tasks within workflows can be defined with `workflow.task()` or
+ * `workflow.durableTask()` and arranged into complex dependency patterns.
+ */
 export declare class WorkflowDeclaration<I extends InputType = UnknownInputType, O extends OutputType = void, MiddlewareBefore extends Record<string, any> = {}> extends BaseWorkflowDeclaration<I, O> {
     /**
      * Adds a task to the workflow.
@@ -362,10 +429,26 @@ export declare class WorkflowDeclaration<I extends InputType = UnknownInputType,
     }): CreateWorkflowDurableTaskOpts<I, TO>;
 }
 /**
- * A standalone task workflow that can be run, scheduled, or triggered via cron.
+ * A standalone task declaration that can be run like a workflow.
+ *
+ * `TaskWorkflowDeclaration` is returned by `hatchet.task(...)` and wraps a single
+ * task definition while exposing the same execution helpers as workflows, such as
+ * `run()`, `runNoWait()`, `schedule()`, and `cron()` (inherited from
+ * `BaseWorkflowDeclaration`).
+ *
+ * Example:
+ * ```typescript
+ * const greet = hatchet.task<{ name: string }, { message: string }>({
+ *   name: 'greet',
+ *   fn: async (input) => ({ message: `Hello, ${input.name}!` }),
+ * });
+ *
+ * await greet.run({ name: 'World' });
+ * const ref = await greet.runNoWait({ name: 'World' });
+ * ```
  *
- * @template I - The task-specific input type.
- * @template O - The task output type.
+ * @template I The input type for the standalone task.
+ * @template O The output type returned by the standalone task.
  * @template GlobalInput - Global input type from the client, merged into all run/schedule/cron input signatures.
  * @template MiddlewareBefore - Extra fields added to the task fn input by pre-middleware hooks.
  * @template MiddlewareAfter - Extra fields merged into the task output by post-middleware hooks.
@@ -380,6 +463,7 @@ export declare class TaskWorkflowDeclaration<I extends InputType = UnknownInputT
      * @returns A promise that resolves with the task output merged with post-middleware fields.
      */
     runAndWait(input: I & GlobalInput, options?: RunOpts): Promise<O & Resolved<GlobalOutput, MiddlewareAfter>>;
+    /** @hidden */
     runAndWait(input: (I & GlobalInput)[], options?: RunOpts): Promise<(O & Resolved<GlobalOutput, MiddlewareAfter>)[]>;
     /**
      * Triggers a task run and waits for the result.
@@ -388,6 +472,7 @@ export declare class TaskWorkflowDeclaration<I extends InputType = UnknownInputT
      * @returns A promise that resolves with the task output merged with post-middleware fields.
      */
     run(input: I & GlobalInput, options?: RunOpts): Promise<O & Resolved<GlobalOutput, MiddlewareAfter>>;
+    /** @hidden */
     run(input: (I & GlobalInput)[], options?: RunOpts): Promise<(O & Resolved<GlobalOutput, MiddlewareAfter>)[]>;
     /**
      * Triggers a task run without waiting for completion.
@@ -422,7 +507,6 @@ export declare class TaskWorkflowDeclaration<I extends InputType = UnknownInputT
      * @returns A promise that resolves with the cron workflow details.
      */
     cron(name: string, expression: string, input: I & GlobalInput, options?: RunOpts): Promise<CronWorkflows>;
-    /** Returns the underlying task definition for this declaration. */
     get taskDef(): CreateWorkflowTaskOpts<any, any>;
 }
 /**

package/v1/declaration.js

@@ -29,6 +29,7 @@ var Priority;
  * Prefer using `StickyStrategy.SOFT` / `StickyStrategy.HARD` (v1, non-protobuf).
  * For backwards compatibility, the workflow/task `sticky` field also accepts legacy
  * protobuf enum values (`0`/`1`) and strings (`'SOFT'`/`'HARD'`).
+ * @internal
  */
 exports.StickyStrategy = {
     SOFT: 'soft',
@@ -38,12 +39,14 @@ exports.StickyStrategy = {
  * Represents a workflow that can be executed by Hatchet.
  * @template I The input type for the workflow.
  * @template O The return type of the workflow.
+ * @internal
  */
 class BaseWorkflowDeclaration {
     /**
      * Creates a new workflow instance.
      * @param options The options for creating the workflow.
      * @param client Optional Hatchet client instance.
+     * @internal
      */
     constructor(options, client) {
         this.definition = Object.assign(Object.assign({}, options), { _tasks: [], _durableTasks: [] });
@@ -281,6 +284,7 @@ class BaseWorkflowDeclaration {
     // }
     /**
      * @deprecated use definition.name instead
+     * @hidden
      */
     get id() {
         return this.definition.name;
@@ -294,6 +298,44 @@ class BaseWorkflowDeclaration {
     }
 }
 exports.BaseWorkflowDeclaration = BaseWorkflowDeclaration;
+/**
+ * A Hatchet workflow, which lets you define tasks and perform actions on the workflow.
+ *
+ * Workflows in Hatchet represent coordinated units of work that can be triggered,
+ * scheduled, or run on a cron schedule. Each workflow can contain multiple tasks
+ * that can be arranged in dependencies (DAGs), with customized retry behavior,
+ * timeouts, concurrency controls, and more.
+ *
+ * Example:
+ * ```typescript
+ * import { hatchet } from './hatchet-client';
+ *
+ * type MyInput = { name: string };
+ *
+ * const workflow = hatchet.workflow<MyInput>({
+ *   name: 'my-workflow',
+ * });
+ *
+ * workflow.task({
+ *   name: 'greet',
+ *   fn: async (input) => {
+ *     return { message: `Hello, ${input.name}!` };
+ *   },
+ * });
+ *
+ * // Run the workflow
+ * await workflow.run({ name: 'World' });
+ * ```
+ *
+ * Workflows support various execution patterns, including:
+ * - One-time execution with `run()` and `runNoWait()`
+ * - Scheduled execution with `schedule()`
+ * - Cron-based recurring execution with `cron()`
+ * - Bulk execution by passing an array input to `run()` and `runNoWait()`
+ *
+ * Tasks within workflows can be defined with `workflow.task()` or
+ * `workflow.durableTask()` and arranged into complex dependency patterns.
+ */
 class WorkflowDeclaration extends BaseWorkflowDeclaration {
     /**
      * Adds a task to the workflow.
@@ -378,10 +420,26 @@ class WorkflowDeclaration extends BaseWorkflowDeclaration {
 }
 exports.WorkflowDeclaration = WorkflowDeclaration;
 /**
- * A standalone task workflow that can be run, scheduled, or triggered via cron.
+ * A standalone task declaration that can be run like a workflow.
+ *
+ * `TaskWorkflowDeclaration` is returned by `hatchet.task(...)` and wraps a single
+ * task definition while exposing the same execution helpers as workflows, such as
+ * `run()`, `runNoWait()`, `schedule()`, and `cron()` (inherited from
+ * `BaseWorkflowDeclaration`).
+ *
+ * Example:
+ * ```typescript
+ * const greet = hatchet.task<{ name: string }, { message: string }>({
+ *   name: 'greet',
+ *   fn: async (input) => ({ message: `Hello, ${input.name}!` }),
+ * });
+ *
+ * await greet.run({ name: 'World' });
+ * const ref = await greet.runNoWait({ name: 'World' });
+ * ```
  *
- * @template I - The task-specific input type.
- * @template O - The task output type.
+ * @template I The input type for the standalone task.
+ * @template O The output type returned by the standalone task.
  * @template GlobalInput - Global input type from the client, merged into all run/schedule/cron input signatures.
  * @template MiddlewareBefore - Extra fields added to the task fn input by pre-middleware hooks.
  * @template MiddlewareAfter - Extra fields merged into the task output by post-middleware hooks.
@@ -468,7 +526,7 @@ class TaskWorkflowDeclaration extends BaseWorkflowDeclaration {
             return _super.cron.call(this, name, expression, input, options);
         });
     }
-    /** Returns the underlying task definition for this declaration. */
+    // Returns the underlying task definition for this declaration.
     get taskDef() {
         return this.definition._tasks[0];
     }

package/v1/examples/runtime_affinity/workflow.d.ts

@@ -0,0 +1,3 @@
+export declare const affinityExampleTask: import("../..").TaskWorkflowDeclaration<import("../..").UnknownInputType, {
+    worker_id: string | undefined;
+}, {}, {}, {}, {}>;

package/v1/examples/runtime_affinity/workflow.js

@@ -0,0 +1,19 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.affinityExampleTask = void 0;
+const hatchet_client_1 = require("../hatchet-client");
+exports.affinityExampleTask = hatchet_client_1.hatchet.task({
+    name: 'affinity-example-task',
+    fn: (input, ctx) => __awaiter(void 0, void 0, void 0, function* () {
+        return { worker_id: ctx.worker.id() };
+    }),
+});

package/version.d.ts

@@ -1 +1 @@
-export declare const HATCHET_VERSION = "1.14.0";
+export declare const HATCHET_VERSION = "1.15.1";

package/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HATCHET_VERSION = void 0;
-exports.HATCHET_VERSION = '1.14.0';
+exports.HATCHET_VERSION = '1.15.1';