@hatchet-dev/typescript-sdk 0.20.2 → 1.0.0-alpha0

package/step.d.ts

@@ -3,11 +3,13 @@ import { Workflow } from './workflow';
 import { Action } from './clients/dispatcher/action-listener';
 import { LogLevel } from './clients/event/event-client';
 import { Logger } from './util/logger';
-import { HatchetClient } from './clients/hatchet-client';
+import { InternalHatchetClient } from './clients/hatchet-client';
 import WorkflowRunRef from './util/workflow-run-ref';
-import { Worker } from './clients/worker';
+import { V0Worker } from './clients/worker';
 import { WorkerLabels } from './clients/dispatcher/dispatcher-client';
 import { CreateStepRateLimit, RateLimitDuration, WorkerLabelComparator } from './protoc/workflows';
+import { CreateTaskOpts } from './v1/task';
+import { Workflow as WorkflowV1 } from './v1/workflow';
 export declare const CreateRateLimitSchema: z.ZodObject<{
     key: z.ZodOptional<z.ZodString>;
     staticKey: z.ZodOptional<z.ZodString>;
@@ -166,7 +168,7 @@ interface ContextData<T, K> {
 }
 export declare class ContextWorker {
     private worker;
-    constructor(worker: Worker);
+    constructor(worker: V0Worker);
     id(): string | undefined;
     hasWorkflow(workflowName: string): boolean;
     labels(): WorkerLabels;
@@ -177,13 +179,14 @@ export declare class Context<T, K = {}> {
     input: T;
     controller: AbortController;
     action: Action;
-    client: HatchetClient;
+    client: InternalHatchetClient;
     worker: ContextWorker;
     overridesData: Record<string, any>;
     logger: Logger;
     spawnIndex: number;
-    constructor(action: Action, client: HatchetClient, worker: Worker);
-    stepOutput(step: string): NextStep;
+    constructor(action: Action, client: InternalHatchetClient, worker: V0Worker);
+    parentData<L = NextStep>(task: CreateTaskOpts<any, L> | string): Promise<L>;
+    stepOutput<L = NextStep>(step: string): L;
     stepRunErrors(): Record<string, string>;
     triggeredByEvent(): boolean;
     workflowInput(): T;
@@ -203,14 +206,43 @@ export declare class Context<T, K = {}> {
     refreshTimeout(incrementBy: string): Promise<void>;
     releaseSlot(): Promise<void>;
     putStream(data: string | Uint8Array): Promise<void>;
+    /**
+     * Enqueues multiple children workflows in parallel.
+     * @param children an array of objects containing the workflow name, input data, and options for each workflow
+     * @returns a list of workflow run references to the enqueued runs
+     */
+    bulkEnqueueChildren<Q extends Record<string, any> = any, P extends Record<string, any> = any>(children: Array<{
+        workflow: string | Workflow | WorkflowV1<Q, P>;
+        input: Q;
+        options?: {
+            key?: string;
+            sticky?: boolean;
+            additionalMetadata?: Record<string, string>;
+        };
+    }>): Promise<WorkflowRunRef<P>[]>;
+    /**
+     * Runs multiple children workflows in parallel.
+     * @param children an array of objects containing the workflow name, input data, and options for each workflow
+     * @returns a list of results from the children workflows
+     */
+    bulkRunChildren<Q extends Record<string, any> = any, P extends Record<string, any> = any>(children: Array<{
+        workflow: string | Workflow | WorkflowV1<Q, P>;
+        input: Q;
+        options?: {
+            key?: string;
+            sticky?: boolean;
+            additionalMetadata?: Record<string, string>;
+        };
+    }>): Promise<P[]>;
     /**
      * Spawns multiple workflows.
      *
      * @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 bulkEnqueueChildren or bulkRunChildren instead
      */
-    spawnWorkflows<Q = JsonValue, P = JsonValue>(workflows: Array<{
-        workflow: string | Workflow;
+    spawnWorkflows<Q extends Record<string, any> = any, P extends Record<string, any> = any>(workflows: Array<{
+        workflow: string | Workflow | WorkflowV1<Q, P>;
         input: Q;
         options?: {
             key?: string;
@@ -218,6 +250,39 @@ export declare class Context<T, K = {}> {
             additionalMetadata?: Record<string, string>;
         };
     }>): Promise<WorkflowRunRef<P>[]>;
+    /**
+     * Runs a new workflow.
+     *
+     * @param workflow the workflow to run
+     * @param input the input data for the workflow
+     * @param options additional options for spawning the workflow. If a string is provided, it is used as the key.
+     * @param <Q> the type of the input data
+     * @param <P> the type of the output data
+     * @return the result of the workflow
+     */
+    runChild<Q extends Record<string, any>, P extends Record<string, any>>(workflow: string | Workflow | WorkflowV1<Q, P>, input: Q, options?: string | {
+        key?: string;
+        sticky?: boolean;
+        additionalMetadata?: Record<string, string>;
+    }): Promise<P>;
+    /**
+     * Enqueues a new workflow.
+     *
+     * @param workflowName the name of the workflow to spawn
+     * @param input the input data for the workflow
+     * @param options additional options for spawning the workflow. If a string is provided, it is used as the key.
+     *                If an object is provided, it can include:
+     *                - key: a unique identifier for the workflow (deprecated, use options.key instead)
+     *                - sticky: a boolean indicating whether to use sticky execution
+     * @param <Q> the type of the input data
+     * @param <P> the type of the output data
+     * @return a reference to the spawned workflow run
+     */
+    enqueueChild<Q extends Record<string, any>, P extends Record<string, any>>(workflow: string | Workflow | WorkflowV1<Q, P>, input: Q, options?: string | {
+        key?: string;
+        sticky?: boolean;
+        additionalMetadata?: Record<string, string>;
+    }): WorkflowRunRef<P>;
     /**
      * Spawns a new workflow.
      *
@@ -230,8 +295,9 @@ export declare class Context<T, K = {}> {
      * @param <Q> the type of the input data
      * @param <P> the type of the output data
      * @return a reference to the spawned workflow run
+     * @deprecated use runChild or enqueueChild instead
      */
-    spawnWorkflow<Q = JsonValue, P = JsonValue>(workflow: string | Workflow, input: Q, options?: string | {
+    spawnWorkflow<Q extends Record<string, any>, P extends Record<string, any>>(workflow: string | Workflow | WorkflowV1<Q, P>, input: Q, options?: string | {
         key?: string;
         sticky?: boolean;
         additionalMetadata?: Record<string, string>;

package/step.js

@@ -50,7 +50,6 @@ exports.mapRateLimit = mapRateLimit;
 /* eslint-disable max-classes-per-file */
 const hatchet_error_1 = __importDefault(require("./util/errors/hatchet-error"));
 const z = __importStar(require("zod"));
-const workflow_1 = require("./workflow");
 const parse_1 = require("./util/parse");
 const workflows_1 = require("./protoc/workflows");
 exports.CreateRateLimitSchema = z.object({
@@ -79,7 +78,7 @@ exports.DesiredWorkerLabelSchema = z
 exports.CreateStepSchema = z.object({
     name: z.string(),
     parents: z.array(z.string()).optional(),
-    timeout: workflow_1.HatchetTimeoutSchema.optional(),
+    timeout: z.string().optional(),
     retries: z.number().optional(),
     rate_limits: z.array(exports.CreateRateLimitSchema).optional(),
     worker_labels: z.record(z.lazy(() => exports.DesiredWorkerLabelSchema)).optional(),
@@ -133,6 +132,16 @@ class Context {
             throw new hatchet_error_1.default(`Could not parse payload: ${e.message}`);
         }
     }
+    // NOTE: parentData is async since we plan on potentially making this a cacheable server call
+    parentData(task) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (typeof task === 'string') {
+                return this.stepOutput(task);
+            }
+            return this.stepOutput(task.name);
+        });
+    }
+    // TODO deprecated
     stepOutput(step) {
         if (!this.data.parents) {
             throw new hatchet_error_1.default('Step output not found');
@@ -227,11 +236,32 @@ class Context {
             yield this.client.event.putStream(stepRunId, data);
         });
     }
+    /**
+     * Enqueues multiple children workflows in parallel.
+     * @param children an array of objects containing the workflow name, input data, and options for each workflow
+     * @returns a list of workflow run references to the enqueued runs
+     */
+    bulkEnqueueChildren(children) {
+        return this.spawnWorkflows(children);
+    }
+    /**
+     * Runs multiple children workflows in parallel.
+     * @param children an array of objects containing the workflow name, input data, and options for each workflow
+     * @returns a list of results from the children workflows
+     */
+    bulkRunChildren(children) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const runs = yield this.bulkEnqueueChildren(children);
+            const res = runs.map((run) => run.result());
+            return Promise.all(res);
+        });
+    }
     /**
      * Spawns multiple workflows.
      *
      * @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 bulkEnqueueChildren or bulkRunChildren instead
      */
     spawnWorkflows(workflows) {
         const { workflowRunId, stepRunId } = this.action;
@@ -278,6 +308,38 @@ class Context {
             throw new hatchet_error_1.default(e.message);
         }
     }
+    /**
+     * Runs a new workflow.
+     *
+     * @param workflow the workflow to run
+     * @param input the input data for the workflow
+     * @param options additional options for spawning the workflow. If a string is provided, it is used as the key.
+     * @param <Q> the type of the input data
+     * @param <P> the type of the output data
+     * @return the result of the workflow
+     */
+    runChild(workflow, input, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const run = yield this.spawnWorkflow(workflow, input, options);
+            return run.result();
+        });
+    }
+    /**
+     * Enqueues a new workflow.
+     *
+     * @param workflowName the name of the workflow to spawn
+     * @param input the input data for the workflow
+     * @param options additional options for spawning the workflow. If a string is provided, it is used as the key.
+     *                If an object is provided, it can include:
+     *                - key: a unique identifier for the workflow (deprecated, use options.key instead)
+     *                - sticky: a boolean indicating whether to use sticky execution
+     * @param <Q> the type of the input data
+     * @param <P> the type of the output data
+     * @return a reference to the spawned workflow run
+     */
+    enqueueChild(workflow, input, options) {
+        return this.spawnWorkflow(workflow, input, options);
+    }
     /**
      * Spawns a new workflow.
      *
@@ -290,6 +352,7 @@ class Context {
      * @param <Q> the type of the input data
      * @param <P> the type of the output data
      * @return a reference to the spawned workflow run
+     * @deprecated use runChild or enqueueChild instead
      */
     spawnWorkflow(workflow, input, options) {
         const { workflowRunId, stepRunId } = this.action;

package/util/hatchet-promise/hatchet-promise.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 class HatchetPromise {
     constructor(promise) {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
         this.cancel = (reason) => { };
         this.promise = new Promise((resolve, reject) => {
             this.cancel = reject;

package/v1/client/client.d.ts

@@ -0,0 +1,81 @@
+import { ClientConfig, InternalHatchetClient, HatchetClientOptions } from '../../clients/hatchet-client';
+import { AxiosRequestConfig } from 'axios';
+import WorkflowRunRef from '../../util/workflow-run-ref';
+import { Workflow as V0Workflow } from '../../workflow';
+import { CreateWorkflowOpts, RunOpts, Workflow } from '../workflow';
+import { IHatchetClient } from './client.interface';
+import { CreateWorkerOpts, Worker } from './worker';
+/**
+ * HatchetV1 implements the main client interface for interacting with the Hatchet workflow engine.
+ * It provides methods for creating and executing workflows, as well as managing workers.
+ */
+export declare class HatchetClient implements IHatchetClient {
+    /** The underlying v0 client instance */
+    v0: InternalHatchetClient;
+    /** The tenant ID for the Hatchet client */
+    get tenantId(): string;
+    /**
+     * Creates a new Hatchet client instance.
+     * @param config - Optional configuration for the client
+     * @param options - Optional client options
+     * @param axiosConfig - Optional Axios configuration for HTTP requests
+     */
+    constructor(config?: Partial<ClientConfig>, options?: HatchetClientOptions, axiosConfig?: AxiosRequestConfig);
+    /**
+     * Static factory method to create a new Hatchet client instance.
+     * @param config - Optional configuration for the client
+     * @param options - Optional client options
+     * @param axiosConfig - Optional Axios configuration for HTTP requests
+     * @returns A new Hatchet client instance
+     */
+    static init(config?: Partial<ClientConfig>, options?: HatchetClientOptions, axiosConfig?: AxiosRequestConfig): HatchetClient;
+    /**
+     * Creates a new workflow definition.
+     * @template T - The input type for the workflow
+     * @template K - The return type of the workflow
+     * @param options - Configuration options for creating the workflow
+     * @returns A new Workflow instance
+     * @note It is possible to create an orphaned workflow if no client is available using @hatchet/client CreateWorkflow
+     */
+    workflow<T extends Record<string, any> = any, K = any>(options: CreateWorkflowOpts): Workflow<T, K>;
+    /**
+     * Triggers a workflow run without waiting for completion.
+     * @template T - The input type for the workflow
+     * @template K - The return type of the workflow
+     * @param workflow - The workflow to run, either as a Workflow instance or workflow name
+     * @param input - The input data for the workflow
+     * @param options - Configuration options for the workflow run
+     * @returns A WorkflowRunRef containing the run ID and methods to interact with the run
+     */
+    enqueue<T extends Record<string, any> = any, K = any>(workflow: Workflow<T, K> | string | V0Workflow, input: T, options: RunOpts): WorkflowRunRef<K>;
+    /**
+     * Triggers a workflow run and waits for the result.
+     * @template T - The input type for the workflow
+     * @template K - The return type of the workflow
+     * @param workflow - The workflow to run, either as a Workflow instance or workflow name
+     * @param input - The input data for the workflow
+     * @param options - Configuration options for the workflow run
+     * @returns A promise that resolves with the workflow result
+     */
+    run<T extends Record<string, any> = any, K = any>(workflow: Workflow<T, K> | string | V0Workflow, input: T, options?: RunOpts): Promise<K>;
+    get cron(): import("../../clients/hatchet-client/features/cron-client").CronClient;
+    get schedule(): import("../../clients/hatchet-client/features/schedule-client").ScheduleClient;
+    get event(): import("../../clients/event/event-client").EventClient;
+    get api(): import("../..").Api<unknown>;
+    /**
+     * @deprecated use workflow.run or client.run instead
+     */
+    get admin(): import("../..").AdminClient;
+    /**
+     * Creates a new worker instance for processing workflow tasks.
+     * @param options - Configuration options for creating the worker
+     * @returns A promise that resolves with a new HatchetWorker instance
+     */
+    worker(name: string, options?: CreateWorkerOpts | number): Promise<Worker>;
+    /**
+     * Register a webhook with the worker
+     * @param workflows - The workflows to register on the webhooks
+     * @returns A promise that resolves when the webhook is registered
+     */
+    webhooks(workflows: Workflow<any, any>[] | V0Workflow[]): import("../../clients/worker/handler").WebhookHandler;
+}

package/v1/client/client.interface.d.ts

@@ -0,0 +1,4 @@
+import { InternalHatchetClient } from '../../clients/hatchet-client';
+export interface IHatchetClient {
+    v0: InternalHatchetClient;
+}

package/v1/client/client.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/v1/client/client.js

@@ -0,0 +1,134 @@
+"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.HatchetClient = void 0;
+const hatchet_client_1 = require("../../clients/hatchet-client");
+const workflow_1 = require("../workflow");
+const worker_1 = require("./worker");
+/**
+ * HatchetV1 implements the main client interface for interacting with the Hatchet workflow engine.
+ * It provides methods for creating and executing workflows, as well as managing workers.
+ */
+class HatchetClient {
+    /** The tenant ID for the Hatchet client */
+    get tenantId() {
+        return this.v0.tenantId;
+    }
+    /**
+     * Creates a new Hatchet client instance.
+     * @param config - Optional configuration for the client
+     * @param options - Optional client options
+     * @param axiosConfig - Optional Axios configuration for HTTP requests
+     */
+    constructor(config, options, axiosConfig) {
+        this.v0 = new hatchet_client_1.InternalHatchetClient(config, options, axiosConfig);
+    }
+    /**
+     * Static factory method to create a new Hatchet client instance.
+     * @param config - Optional configuration for the client
+     * @param options - Optional client options
+     * @param axiosConfig - Optional Axios configuration for HTTP requests
+     * @returns A new Hatchet client instance
+     */
+    static init(config, options, axiosConfig) {
+        return new HatchetClient(config, options, axiosConfig);
+    }
+    /**
+     * Creates a new workflow definition.
+     * @template T - The input type for the workflow
+     * @template K - The return type of the workflow
+     * @param options - Configuration options for creating the workflow
+     * @returns A new Workflow instance
+     * @note It is possible to create an orphaned workflow if no client is available using @hatchet/client CreateWorkflow
+     */
+    workflow(options) {
+        return (0, workflow_1.CreateWorkflow)(options, this);
+    }
+    /**
+     * Triggers a workflow run without waiting for completion.
+     * @template T - The input type for the workflow
+     * @template K - The return type of the workflow
+     * @param workflow - The workflow to run, either as a Workflow instance or workflow name
+     * @param input - The input data for the workflow
+     * @param options - Configuration options for the workflow run
+     * @returns A WorkflowRunRef containing the run ID and methods to interact with the run
+     */
+    enqueue(workflow, input, options) {
+        let name;
+        if (typeof workflow === 'string') {
+            name = workflow;
+        }
+        else if ('id' in workflow) {
+            name = workflow.id;
+        }
+        else {
+            throw new Error('unable to identify workflow');
+        }
+        return this.v0.admin.runWorkflow(name, input, options);
+    }
+    /**
+     * Triggers a workflow run and waits for the result.
+     * @template T - The input type for the workflow
+     * @template K - The return type of the workflow
+     * @param workflow - The workflow to run, either as a Workflow instance or workflow name
+     * @param input - The input data for the workflow
+     * @param options - Configuration options for the workflow run
+     * @returns A promise that resolves with the workflow result
+     */
+    run(workflow_2, input_1) {
+        return __awaiter(this, arguments, void 0, function* (workflow, input, options = {}) {
+            const run = this.enqueue(workflow, input, options);
+            return run.result();
+        });
+    }
+    get cron() {
+        return this.v0.cron;
+    }
+    get schedule() {
+        return this.v0.schedule;
+    }
+    get event() {
+        return this.v0.event;
+    }
+    get api() {
+        return this.v0.api;
+    }
+    /**
+     * @deprecated use workflow.run or client.run instead
+     */
+    get admin() {
+        return this.v0.admin;
+    }
+    /**
+     * Creates a new worker instance for processing workflow tasks.
+     * @param options - Configuration options for creating the worker
+     * @returns A promise that resolves with a new HatchetWorker instance
+     */
+    worker(name, options) {
+        let opts = {};
+        if (typeof options === 'number') {
+            opts = { slots: options };
+        }
+        else {
+            opts = options || {};
+        }
+        return worker_1.Worker.create(this.v0, name, opts);
+    }
+    /**
+     * Register a webhook with the worker
+     * @param workflows - The workflows to register on the webhooks
+     * @returns A promise that resolves when the webhook is registered
+     */
+    webhooks(workflows) {
+        return this.v0.webhooks(workflows);
+    }
+}
+exports.HatchetClient = HatchetClient;

package/v1/client/worker.d.ts

@@ -0,0 +1,82 @@
+import { WorkerLabels } from '../../clients/dispatcher/dispatcher-client';
+import { InternalHatchetClient } from '../../clients/hatchet-client';
+import { V0Worker } from '../../clients/worker';
+import { Workflow as V0Workflow } from '../../workflow';
+import { WebhookWorkerCreateRequest } from '../../clients/rest/generated/data-contracts';
+import { Workflow } from '../workflow';
+/**
+ * Options for creating a new hatchet worker
+ * @interface CreateWorkerOpts
+ */
+export interface CreateWorkerOpts {
+    /** Maximum number of concurrent runs on this worker */
+    slots?: number;
+    /** Array of workflows to register */
+    workflows?: Workflow<any, any>[] | V0Workflow[];
+    /** Worker labels for affinity-based assignment */
+    labels?: WorkerLabels;
+    /** Whether to handle kill signals */
+    handleKill?: boolean;
+    /** @deprecated Use slots instead */
+    maxRuns?: number;
+}
+/**
+ * HatchetWorker class for workflow execution runtime
+ */
+export declare class Worker {
+    /** Internal reference to the underlying V0 worker implementation */
+    v0: V0Worker;
+    /**
+     * Creates a new HatchetWorker instance
+     * @param v0 - The V0 worker implementation
+     */
+    constructor(v0: V0Worker);
+    /**
+     * Creates and initializes a new HatchetWorker
+     * @param v0 - The HatchetClient instance
+     * @param options - Worker creation options
+     * @returns A new HatchetWorker instance
+     */
+    static create(v0: InternalHatchetClient, name: string, options: CreateWorkerOpts): Promise<Worker>;
+    /**
+     * Registers workflows with the worker
+     * @param workflows - Array of workflows to register
+     * @returns Array of registered workflow promises
+     */
+    registerWorkflows(workflows?: Array<Workflow<any, any> | V0Workflow>): Promise<void>[] | undefined;
+    /**
+     * Registers a single workflow with the worker
+     * @param workflow - The workflow to register
+     * @returns A promise that resolves when the workflow is registered
+     * @deprecated use registerWorkflows instead
+     */
+    registerWorkflow(workflow: Workflow<any, any> | V0Workflow): Promise<void>[] | undefined;
+    /**
+     * Starts the worker
+     * @returns Promise that resolves when the worker is stopped or killed
+     */
+    start(): Promise<void>;
+    /**
+     * Stops the worker
+     * @returns Promise that resolves when the worker stops
+     */
+    stop(): Promise<void>;
+    /**
+     * Updates or inserts worker labels
+     * @param labels - Worker labels to update
+     * @returns Promise that resolves when labels are updated
+     */
+    upsertLabels(labels: WorkerLabels): Promise<WorkerLabels>;
+    /**
+     * Get the labels for the 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>>;
+}
+export declare function toV0Workflow(wf: Workflow<any, any> | V0Workflow): V0Workflow;