@hatchet-dev/typescript-sdk 1.14.0 → 1.15.0

package/{v1 → src/v1}/client/worker/context.d.ts

@@ -1,14 +1,23 @@
-import { Priority, RunOpts, TaskWorkflowDeclaration, BaseWorkflowDeclaration as WorkflowV1 } from '../../declaration';
+/**
+ * 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 '../../../../v1/declaration';
 import { JsonObject } from '@bufbuild/protobuf';
-import { Action } from '../../../clients/dispatcher/action-listener';
-import { Logger, LogLevel } from '../../../util/logger';
-import WorkflowRunRef from '../../../util/workflow-run-ref';
-import { Conditions } from '../../conditions';
-import { CreateWorkflowDurableTaskOpts, CreateWorkflowTaskOpts } from '../../task';
-import { OutputType } from '../../types';
-import { HatchetClient } from '../..';
-import { WorkerLabels } from '../../../clients/dispatcher/dispatcher-client';
-import { NextStep } from '../../../legacy/step';
+import { Action } from '../../../../clients/dispatcher/action-listener';
+import { Logger, LogLevel } from '../../../../util/logger';
+import WorkflowRunRef from '../../../../util/workflow-run-ref';
+import { Conditions } from '../../../../v1/conditions';
+import { CreateWorkflowDurableTaskOpts, CreateWorkflowTaskOpts } from '../../../../v1/task';
+import { OutputType } from '../../../../v1/types';
+import { HatchetClient } from '../../../../v1';
+import { WorkerLabels } from '../../../../clients/dispatcher/dispatcher-client';
+import { NextStep } from '../../../../legacy/step';
 import { InternalWorker } from './worker-internal';
 import { Duration } from '../duration';
 type TriggerData = Record<string, Record<string, any>>;
@@ -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 → src/v1}/client/worker/context.js

@@ -13,16 +13,25 @@ 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");
-const hatchet_error_1 = __importDefault(require("../../../util/errors/hatchet-error"));
-const parse_1 = require("../../../util/parse");
-const conditions_1 = require("../../conditions");
-const transformer_1 = require("../../conditions/transformer");
-const condition_1 = require("../../../protoc/v1/shared/condition");
-const apply_namespace_1 = require("../../../util/apply-namespace");
-const abort_error_1 = require("../../../util/abort-error");
+const declaration_1 = require("../../../../v1/declaration");
+const hatchet_error_1 = __importDefault(require("../../../../util/errors/hatchet-error"));
+const parse_1 = require("../../../../util/parse");
+const conditions_1 = require("../../../../v1/conditions");
+const transformer_1 = require("../../../../v1/conditions/transformer");
+const condition_1 = require("../../../../protoc/v1/shared/condition");
+const apply_namespace_1 = require("../../../../util/apply-namespace");
+const abort_error_1 = require("../../../../util/abort-error");
 /**
  * ContextWorker is a wrapper around the V1Worker class that provides a more user-friendly interface for the worker from the context of a run.
  */
@@ -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 → src/v1}/client/worker/deprecated/deprecation.d.ts

@@ -8,7 +8,7 @@
  *
  * Defaults: warnDays=90, errorDays=undefined (error phase disabled unless set).
  */
-import { Logger } from '../../../../util/logger';
+import { Logger } from '../../../../../util/logger';
 export declare class DeprecationError extends Error {
     feature: string;
     constructor(feature: string, message: string);

package/{v1 → src/v1}/client/worker/deprecated/legacy-registration.d.ts

@@ -3,8 +3,8 @@
  * instead of `slotConfig`. For backward compatibility with engines
  * that do not support multiple slot types.
  */
-import { DispatcherClient, WorkerLabels } from '../../../../clients/dispatcher/dispatcher-client';
-import { ActionListener } from '../../../../clients/dispatcher/action-listener';
+import { DispatcherClient, WorkerLabels } from '../../../../../clients/dispatcher/dispatcher-client';
+import { ActionListener } from '../../../../../clients/dispatcher/action-listener';
 export interface LegacyRegistrationOptions {
     workerName: string;
     services: string[];

package/{v1 → src/v1}/client/worker/deprecated/legacy-registration.js

@@ -15,8 +15,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.legacyGetActionListener = legacyGetActionListener;
-const dispatcher_client_1 = require("../../../../clients/dispatcher/dispatcher-client");
-const action_listener_1 = require("../../../../clients/dispatcher/action-listener");
+const dispatcher_client_1 = require("../../../../../clients/dispatcher/dispatcher-client");
+const action_listener_1 = require("../../../../../clients/dispatcher/action-listener");
 /**
  * Registers a worker using the legacy `slots` proto field instead of `slotConfig`.
  */

package/{v1 → src/v1}/client/worker/deprecated/legacy-v1-worker.d.ts

@@ -2,8 +2,8 @@
  * Legacy V1Worker subclass that registers with the old `slots` proto field
  * instead of `slotConfig`. Used when connected to pre-slot-config engines.
  */
-import { ActionListener } from '../../../../clients/dispatcher/action-listener';
-import { HatchetClient } from '../../..';
+import { ActionListener } from '../../../../../clients/dispatcher/action-listener';
+import { HatchetClient } from '../../../../../v1';
 import { InternalWorker } from '../worker-internal';
 export declare class LegacyV1Worker extends InternalWorker {
     private _legacySlotCount;

package/{v1 → src/v1}/client/worker/health-server.d.ts

@@ -1,4 +1,4 @@
-import { Logger } from '../../../util/logger';
+import { Logger } from '../../../../util/logger';
 export declare const workerStatus: {
     readonly INITIALIZED: "INITIALIZED";
     readonly STARTING: "STARTING";

package/{v1 → src/v1}/client/worker/worker-internal.d.ts

@@ -1,11 +1,11 @@
-import { Action, ActionListener } from '../../../clients/dispatcher/action-listener';
-import { StepActionEvent, StepActionEventType, GroupKeyActionEvent, GroupKeyActionEventType } from '../../../protoc/dispatcher';
-import HatchetPromise from '../../../util/hatchet-promise/hatchet-promise';
-import { CreateStepRateLimit } from '../../../protoc/workflows';
-import { Logger } from '../../../util/logger';
-import { BaseWorkflowDeclaration, WorkflowDefinition, HatchetClient } from '../..';
-import { CreateWorkflowTaskOpts } from '../../task';
-import { WorkerLabels } from '../../../clients/dispatcher/dispatcher-client';
+import { Action, ActionListener } from '../../../../clients/dispatcher/action-listener';
+import { StepActionEvent, StepActionEventType, GroupKeyActionEvent, GroupKeyActionEventType } from '../../../../protoc/dispatcher';
+import HatchetPromise from '../../../../util/hatchet-promise/hatchet-promise';
+import { CreateStepRateLimit } from '../../../../protoc/workflows';
+import { Logger } from '../../../../util/logger';
+import { BaseWorkflowDeclaration, WorkflowDefinition, HatchetClient } from '../../../../v1';
+import { CreateWorkflowTaskOpts } from '../../../../v1/task';
+import { WorkerLabels } from '../../../../clients/dispatcher/dispatcher-client';
 import { Context } from './context';
 import { SlotConfig } from '../../slot-types';
 export type ActionRegistry = Record<Action['actionId'], Function>;

package/{v1 → src/v1}/client/worker/worker-internal.js

@@ -23,17 +23,17 @@ exports.InternalWorker = void 0;
 exports.mapRateLimitPb = mapRateLimitPb;
 /* eslint-disable no-underscore-dangle */
 /* eslint-disable no-nested-ternary */
-const hatchet_error_1 = __importDefault(require("../../../util/errors/hatchet-error"));
-const dispatcher_1 = require("../../../protoc/dispatcher");
-const hatchet_promise_1 = __importDefault(require("../../../util/hatchet-promise/hatchet-promise"));
-const workflows_1 = require("../../../protoc/workflows");
-const logger_1 = require("../../../util/logger");
-const task_1 = require("../../task");
-const transformer_1 = require("../../conditions/transformer");
+const hatchet_error_1 = __importDefault(require("../../../../util/errors/hatchet-error"));
+const dispatcher_1 = require("../../../../protoc/dispatcher");
+const hatchet_promise_1 = __importDefault(require("../../../../util/hatchet-promise/hatchet-promise"));
+const workflows_1 = require("../../../../protoc/workflows");
+const logger_1 = require("../../../../util/logger");
+const task_1 = require("../../../../v1/task");
+const transformer_1 = require("../../../../v1/conditions/transformer");
 const zod_to_json_schema_1 = require("zod-to-json-schema");
-const apply_namespace_1 = require("../../../util/apply-namespace");
-const sleep_1 = __importDefault(require("../../../util/sleep"));
-const abort_error_1 = require("../../../util/abort-error");
+const apply_namespace_1 = require("../../../../util/apply-namespace");
+const sleep_1 = __importDefault(require("../../../../util/sleep"));
+const abort_error_1 = require("../../../../util/abort-error");
 const context_1 = require("./context");
 const parent_run_context_vars_1 = require("../../parent-run-context-vars");
 const health_server_1 = require("./health-server");

package/{v1 → src/v1}/client/worker/worker.d.ts

@@ -1,4 +1,4 @@
-import { WorkerLabels } from '../../../clients/dispatcher/dispatcher-client';
+import { WorkerLabels } from '../../../../clients/dispatcher/dispatcher-client';
 import { BaseWorkflowDeclaration } from '../../declaration';
 import type { LegacyWorkflow } from '../../../legacy/legacy-transformer';
 import { HatchetClient } from '../..';

package/{v1 → src/v1}/client/worker/worker.js

@@ -13,7 +13,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.__testing = exports.Worker = void 0;
-const sleep_1 = __importDefault(require("../../../util/sleep"));
+const sleep_1 = __importDefault(require("../../../../util/sleep"));
 const legacy_transformer_1 = require("../../../legacy/legacy-transformer");
 const worker_internal_1 = require("./worker-internal");
 const slot_utils_1 = require("./slot-utils");

package/{v1 → src/v1}/conditions/transformer.d.ts

@@ -1,4 +1,4 @@
-import { TaskConditions } from '../../protoc/v1/shared/condition';
+import { TaskConditions } from '../../../protoc/v1/shared/condition';
 import { CreateWorkflowTaskOpts } from '../task';
 import { Condition } from './base';
 export declare function taskConditionsToPb(task: Omit<CreateWorkflowTaskOpts<any, any>, 'fn'>): TaskConditions;

package/{v1 → src/v1}/declaration.d.ts

@@ -1,6 +1,14 @@
-import WorkflowRunRef from '../util/workflow-run-ref';
-import { CronWorkflows, ScheduledWorkflows, V1CreateFilterRequest } from '../clients/rest/generated/data-contracts';
+/**
+ * `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.
@@ -300,9 +328,10 @@ export declare class BaseWorkflowDeclaration<I extends InputType = UnknownInputT
      * @returns A promise that resolves with the workflow state.
      * @throws Error if the workflow is not bound to a Hatchet client.
      */
-    get(): Promise<import("../clients/rest/generated/data-contracts").Workflow>;
+    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>;
 }
 /**