@hatchet-dev/typescript-sdk 1.13.1 → 1.15.0

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

@@ -1,10 +1,8 @@
-import { WorkerLabels } from '../../../clients/dispatcher/dispatcher-client';
-import { LegacyHatchetClient } from '../../../clients/hatchet-client';
-import { Workflow as V0Workflow } from '../../../workflow';
-import { WebhookWorkerCreateRequest } from '../../../clients/rest/generated/data-contracts';
+import { WorkerLabels } from '../../../../clients/dispatcher/dispatcher-client';
 import { BaseWorkflowDeclaration } from '../../declaration';
+import type { LegacyWorkflow } from '../../../legacy/legacy-transformer';
 import { HatchetClient } from '../..';
-import { V1Worker } from './worker-internal';
+import { InternalWorker } from './worker-internal';
 import { type WorkerSlotOptions } from './slot-utils';
 /**
  * Options for creating a new hatchet worker
@@ -23,9 +21,8 @@ export declare class Worker {
     config: CreateWorkerOpts;
     name: string;
     _v1: HatchetClient;
-    _v0: LegacyHatchetClient;
     /** Internal reference to the underlying V0 worker implementation */
-    _internal: V1Worker;
+    _internal: InternalWorker;
     /** Set when connected to a legacy engine that needs dual-worker architecture */
     private _legacyWorker;
     /** Tracks all workflows registered after construction (via registerWorkflow/registerWorkflows) */
@@ -34,27 +31,31 @@ export declare class Worker {
      * Creates a new HatchetWorker instance
      * @param nonDurable - The V0 worker implementation
      */
-    constructor(v1: HatchetClient, v0: LegacyHatchetClient, nonDurable: V1Worker, config: CreateWorkerOpts, name: string);
+    constructor(v1: HatchetClient, nonDurable: InternalWorker, config: CreateWorkerOpts, name: string);
     /**
      * Creates and initializes a new HatchetWorker
      * @param v0 - The HatchetClient instance
      * @param options - Worker creation options
      * @returns A new HatchetWorker instance
      */
-    static create(v1: HatchetClient, v0: LegacyHatchetClient, name: string, options: CreateWorkerOpts): Promise<Worker>;
+    static create(v1: HatchetClient, name: string, options: CreateWorkerOpts): Promise<Worker>;
     /**
-     * Registers workflows with the worker
+     * Registers workflows with the worker.
+     * Accepts both v1 BaseWorkflowDeclaration and legacy Workflow objects.
+     * Legacy workflows are automatically transformed and a deprecation warning is emitted.
      * @param workflows - Array of workflows to register
      * @returns Array of registered workflow promises
      */
-    registerWorkflows(workflows?: Array<BaseWorkflowDeclaration<any, any> | V0Workflow>): Promise<void>;
+    registerWorkflows(workflows?: Array<BaseWorkflowDeclaration<any, any> | LegacyWorkflow>): Promise<void>;
     /**
-     * Registers a single workflow with the worker
+     * Registers a single workflow with the worker.
+     * Accepts both v1 BaseWorkflowDeclaration and legacy Workflow objects.
+     * Legacy workflows are automatically transformed and a deprecation warning is emitted.
      * @param workflow - The workflow to register
      * @returns A promise that resolves when the workflow is registered
      * @deprecated use registerWorkflows instead
      */
-    registerWorkflow(workflow: BaseWorkflowDeclaration<any, any> | V0Workflow): Promise<void>;
+    registerWorkflow(workflow: BaseWorkflowDeclaration<any, any> | LegacyWorkflow): Promise<void>;
     /**
      * Starts the worker
      * @returns Promise that resolves when the worker is stopped or killed
@@ -76,14 +77,13 @@ export declare class Worker {
      * @returns The labels for the worker
      */
     getLabels(): WorkerLabels;
-    /**
-     * Register a webhook with the worker
-     * @param webhook - The webhook to register
-     * @returns A promise that resolves when the webhook is registered
-     */
-    registerWebhook(webhook: WebhookWorkerCreateRequest): Promise<import("axios").AxiosResponse<import("../../../clients/rest/generated/data-contracts").WebhookWorkerCreated, any, {}>>;
     isPaused(): Promise<boolean>;
     pause(): Promise<void> | Promise<import("../../../clients/rest/generated/data-contracts").Worker>;
     unpause(): Promise<void> | Promise<import("../../../clients/rest/generated/data-contracts").Worker>;
+    /**
+     * Waits until the worker has connected and registered with the server.
+     * Polls every 200ms. Use after start() to avoid fixed sleeps before running workflows.
+     */
+    waitUntilReady(timeoutMs?: number): Promise<void>;
 }
 export { testingExports as __testing } from './slot-utils';

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

@@ -8,9 +8,13 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.__testing = exports.Worker = void 0;
-const declaration_1 = require("../../declaration");
+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");
 const deprecated_1 = require("./deprecated");
@@ -22,11 +26,10 @@ class Worker {
      * Creates a new HatchetWorker instance
      * @param nonDurable - The V0 worker implementation
      */
-    constructor(v1, v0, nonDurable, config, name) {
+    constructor(v1, nonDurable, config, name) {
         /** Tracks all workflows registered after construction (via registerWorkflow/registerWorkflows) */
         this._registeredWorkflows = [];
         this._v1 = v1;
-        this._v0 = v0;
         this._internal = nonDurable;
         this.config = config;
         this.name = name;
@@ -37,41 +40,40 @@ class Worker {
      * @param options - Worker creation options
      * @returns A new HatchetWorker instance
      */
-    static create(v1, v0, name, options) {
+    static create(v1, name, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            const resolvedOptions = (0, slot_utils_1.resolveWorkerOptions)(options);
+            // Normalize any legacy workflows before resolving worker options
+            const normalizedOptions = Object.assign(Object.assign({}, options), { workflows: options.workflows ? (0, legacy_transformer_1.normalizeWorkflows)(options.workflows) : undefined });
+            const resolvedOptions = (0, slot_utils_1.resolveWorkerOptions)(normalizedOptions);
             const opts = Object.assign({ name }, resolvedOptions);
-            const internalWorker = new worker_internal_1.V1Worker(v1, opts);
-            const worker = new Worker(v1, v0, internalWorker, options, name);
-            yield worker.registerWorkflows(options.workflows);
+            const internalWorker = new worker_internal_1.InternalWorker(v1, opts);
+            const worker = new Worker(v1, internalWorker, normalizedOptions, name);
+            yield worker.registerWorkflows(normalizedOptions.workflows);
             return worker;
         });
     }
     /**
-     * Registers workflows with the worker
+     * Registers workflows with the worker.
+     * Accepts both v1 BaseWorkflowDeclaration and legacy Workflow objects.
+     * Legacy workflows are automatically transformed and a deprecation warning is emitted.
      * @param workflows - Array of workflows to register
      * @returns Array of registered workflow promises
      */
     registerWorkflows(workflows) {
         return __awaiter(this, void 0, void 0, function* () {
-            for (const wf of workflows || []) {
-                this._registeredWorkflows.push(wf);
-                if (wf instanceof declaration_1.BaseWorkflowDeclaration) {
-                    // TODO check if tenant is V1
-                    yield this._internal.registerWorkflowV1(wf);
-                    if (wf.definition._durableTasks.length > 0) {
-                        this._internal.registerDurableActionsV1(wf.definition);
-                    }
-                }
-                else {
-                    // fallback to v0 client for backwards compatibility
-                    yield this._internal.registerWorkflow(wf);
+            const normalized = workflows ? (0, legacy_transformer_1.normalizeWorkflows)(workflows) : [];
+            for (const wf of normalized) {
+                yield this._internal.registerWorkflow(wf);
+                if (wf.definition._durableTasks.length > 0) {
+                    this._internal.registerDurableActions(wf.definition);
                 }
             }
         });
     }
     /**
-     * Registers a single workflow with the worker
+     * Registers a single workflow with the worker.
+     * Accepts both v1 BaseWorkflowDeclaration and legacy Workflow objects.
+     * Legacy workflows are automatically transformed and a deprecation warning is emitted.
      * @param workflow - The workflow to register
      * @returns A promise that resolves when the workflow is registered
      * @deprecated use registerWorkflows instead
@@ -123,14 +125,6 @@ class Worker {
     getLabels() {
         return this._internal.labels;
     }
-    /**
-     * Register a webhook with the worker
-     * @param webhook - The webhook to register
-     * @returns A promise that resolves when the webhook is registered
-     */
-    registerWebhook(webhook) {
-        return this._internal.registerWebhook(webhook);
-    }
     isPaused() {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
@@ -155,6 +149,27 @@ class Worker {
         }
         return this._v1.workers.unpause(this._internal.workerId);
     }
+    /**
+     * Waits until the worker has connected and registered with the server.
+     * Polls every 200ms. Use after start() to avoid fixed sleeps before running workflows.
+     */
+    waitUntilReady() {
+        return __awaiter(this, arguments, void 0, function* (timeoutMs = 10000) {
+            var _a;
+            if (this._legacyWorker) {
+                yield (0, sleep_1.default)(2000);
+                return;
+            }
+            const pollInterval = 200;
+            const start = Date.now();
+            while (Date.now() - start < timeoutMs) {
+                if ((_a = this._internal) === null || _a === void 0 ? void 0 : _a.workerId)
+                    return;
+                yield (0, sleep_1.default)(pollInterval);
+            }
+            throw new Error(`Worker ${this.name} did not become ready within ${timeoutMs}ms`);
+        });
+    }
 }
 exports.Worker = Worker;
 var slot_utils_2 = 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,7 +1,14 @@
-import WorkflowRunRef from '../util/workflow-run-ref';
-import { CronWorkflows, ScheduledWorkflows, V1CreateFilterRequest } from '../clients/rest/generated/data-contracts';
-import { Workflow as WorkflowV0 } from '../workflow';
+/**
+ * `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';
@@ -19,6 +26,7 @@ export declare enum Priority {
 type AdditionalMetadata = Record<string, string>;
 /**
  * Options for running a workflow.
+ * @hidden
  */
 export type RunOpts = {
     /**
@@ -41,38 +49,72 @@ export type RunOpts = {
      * only used if spawned from within a parent task.
      */
     childKey?: string;
+    /**
+     * (optional) when running multiple workflows (array input), if true, return
+     * exceptions in the result array instead of throwing. Successes are outputs,
+     * 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'>;
+/**
+ * Sticky strategy for workflow scheduling.
+ *
+ * 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";
+    readonly HARD: "hard";
+};
+export type StickyStrategy = (typeof StickyStrategy)[keyof typeof StickyStrategy];
+export type StickyStrategyInput = StickyStrategy | 'SOFT' | 'HARD' | 0 | 1;
 export type CreateBaseWorkflowOpts = {
     /**
      * The name of the workflow.
      */
-    name: WorkflowV0['id'];
+    name: string;
     /**
      * (optional) description of the workflow.
      */
-    description?: WorkflowV0['description'];
+    description?: string;
     /**
      * (optional) version of the workflow.
      */
-    version?: WorkflowV0['version'];
+    version?: string;
     /**
      * (optional) sticky strategy for the workflow.
      */
-    sticky?: WorkflowV0['sticky'];
+    sticky?: StickyStrategyInput;
     /**
      * (optional) on config for the workflow.
-     * @deprecated use onCrons and onEvents instead
+     * @alias for onCrons and onEvents
      */
-    on?: WorkflowV0['on'];
+    on?: {
+        cron?: string | string[];
+        event?: string | string[];
+    };
     /**
      * (optional) cron config for the workflow.
      */
@@ -102,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 & {
     /**
@@ -112,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 = {
     /**
@@ -160,6 +204,7 @@ export type TaskDefaults = {
 };
 /**
  * Internal definition of a workflow and its tasks.
+ * @hidden
  */
 export type WorkflowDefinition = CreateWorkflowOpts & {
     /**
@@ -187,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.
@@ -279,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;
     /**
@@ -290,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.
@@ -341,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.
@@ -359,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.
@@ -367,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.
@@ -401,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>;
 }
 /**