@hatchet-dev/typescript-sdk 1.0.0-alpha1 → 1.0.0

package/v1/task.d.ts

@@ -1,10 +1,41 @@
-import { Context, CreateStep } from '../step';
+import { ConcurrencyLimitStrategy } from '../protoc/v1/workflows';
+import { Context, CreateStep, DurableContext } from '../step';
+import { Conditions } from './conditions';
+import { Duration } from './client/duration';
+/**
+ * Options for configuring the concurrency for a task.
+ */
+export type TaskConcurrency = {
+    /**
+     * required the CEL expression to use for concurrency
+     *
+     * @example
+     * ```
+     * "input.key" // use the value of the key in the input
+     * ```
+     */
+    expression: string;
+    /**
+     * (optional) the maximum number of concurrent workflow runs
+     *
+     * default: 1
+     */
+    maxRuns?: number;
+    /**
+     * (optional) the strategy to use when the concurrency limit is reached
+     *
+     * default: CANCEL_IN_PROGRESS
+     */
+    limitStrategy?: ConcurrencyLimitStrategy;
+};
+export type TaskFn<T, K> = (input: T, ctx: Context<T>) => K | Promise<K>;
+export type DurableTaskFn<T, K> = (input: T, ctx: DurableContext<T>) => K | Promise<K>;
 /**
  * Options for creating a hatchet task which is an atomic unit of work in a workflow.
  * @template T The input type for the task function.
  * @template K The return type of the task function (can be inferred from the return value of fn).
  */
-export type CreateTaskOpts<T, K> = {
+export type CreateBaseTaskOpts<T, K, C> = {
     /**
      * The name of the task.
      */
@@ -15,37 +46,136 @@ export type CreateTaskOpts<T, K> = {
      * @param ctx The execution context for the task.
      * @returns The result of the task execution.
      */
-    fn: (input: T, ctx: Context<T>) => K | Promise<K>;
+    fn: C;
     /**
-     * Parent tasks that must complete before this task runs.
-     * Used to define the directed acyclic graph (DAG) of the workflow.
+     * @deprecated use executionTimeout instead
      */
-    parents?: CreateTaskOpts<T, any>[];
+    timeout?: CreateStep<T, K>['timeout'];
     /**
-     * Timeout duration for the task in Go duration format (e.g., "1s", "5m", "1h").
+     * (optional) execution timeout duration for the task after it starts running
+     * go duration format (e.g., "1s", "5m", "1h").
+     *
+     * default: 60s
      */
-    timeout?: CreateStep<T, K>['timeout'];
+    executionTimeout?: Duration;
+    /**
+     * (optional) schedule timeout for the task (max duration to allow the task to wait in the queue)
+     * go duration format (e.g., "1s", "5m", "1h").
+     *
+     * default: 5m
+     */
+    scheduleTimeout?: Duration;
     /**
-     * Optional retry configuration for the task.
+     * (optional) number of retries for the task.
+     *
+     * default: 0
      */
     retries?: CreateStep<T, K>['retries'];
     /**
-     * Backoff strategy configuration for retries.
-     * - factor: Multiplier for exponential backoff
+     * (optional) backoff strategy configuration for retries.
+     * - factor: Base of the exponential backoff (base ^ retry count)
      * - maxSeconds: Maximum backoff duration in seconds
      */
     backoff?: CreateStep<T, K>['backoff'];
     /**
-     * Optional rate limiting configuration for the task.
+     * (optional) rate limits for the task.
      */
     rateLimits?: CreateStep<T, K>['rate_limits'];
     /**
-     * Worker labels for task routing and scheduling.
+     * (optional) worker labels for task routing and scheduling.
      * Each label can be a simple string/number value or an object with additional configuration:
      * - value: The label value (string or number)
      * - required: Whether the label is required for worker matching
      * - weight: Priority weight for worker selection
      * - comparator: Custom comparison logic for label matching
      */
-    workerLabels?: CreateStep<T, K>['worker_labels'];
+    desiredWorkerLabels?: CreateStep<T, K>['worker_labels'];
+    /**
+     * (optional) the concurrency options for the task
+     */
+    concurrency?: TaskConcurrency | TaskConcurrency[];
 };
+export type CreateWorkflowTaskOpts<T, K, C = TaskFn<T, K>> = CreateBaseTaskOpts<T, K, C> & {
+    /**
+     * Parent tasks that must complete before this task runs.
+     * Used to define the directed acyclic graph (DAG) of the workflow.
+     */
+    parents?: CreateWorkflowTaskOpts<T, any, any>[];
+    /**
+     * (optional) the conditions to match before the task is queued
+     * all provided conditions must be met (AND logic)
+     * use Or() to create a condition that waits for any of the provided conditions to be met (OR logic)
+     *
+     * @example
+     * ```
+     * waitFor: [{ sleepFor: 5 }, { eventKey: 'user:update' }] // all conditions must be met
+     * ```
+     * @example
+     * ```
+     * waitFor: Or({ eventKey: 'user:update' }, { parent: firstTask }) // any of the conditions must be met
+     * ```
+     * @example
+     * ```
+     * waitFor: [{ sleepFor: 5 }, Or({ eventKey: 'user:update' }, { eventKey: 'user:delete' })] // sleep or both user:update or user:delete must be met
+     * ```
+     */
+    waitFor?: Conditions | Conditions[];
+    /**
+     * (optional) cancel the task if the conditions are met
+     * all provided conditions must be met (AND logic)
+     * use Or() to create a condition that waits for any of the provided conditions to be met (OR logic)
+     *
+     * @example
+     * ```
+     * cancelIf: { eventKey: 'user:update' } // cancel the task if the user:update event is received
+     * ```
+     * @example
+     * ```
+     * cancelIf: [{ sleepFor: 5 }, Or({ eventKey: 'user:update' }, { eventKey: 'user:delete' })] // cancel the task if the sleep or both user:update or user:delete are met
+     */
+    cancelIf?: Conditions | Conditions[];
+    /**
+     * (optional) skip the task if the conditions are met
+     * all provided conditions must be met (AND logic)
+     * use Or() to create a condition that waits for any of the provided conditions to be met (OR logic)
+     *
+     * @example
+     * ```
+     * skipIf: [{ eventKey: 'user:update' }] // skip the task if the user:update event is received
+     * ```
+     * @example
+     * ```
+     * skipIf: [{ sleepFor: 5 }, Or({ eventKey: 'user:update' }, { eventKey: 'user:delete' })] // skip the task if the sleep or both user:update or user:delete are met
+     * ```
+     * @example
+     * ```
+     * skipIf: [{ parent: firstTask }] // skip the task if the parent task completes
+     * ```
+     */
+    skipIf?: Conditions | Conditions[];
+};
+export type CreateStandaloneTaskOpts<T, K> = CreateBaseTaskOpts<T, K, TaskFn<T, K>>;
+/**
+ * Options for creating a hatchet durable task which is an atomic unit of work in a workflow.
+ * @template T The input type for the task function.
+ * @template K The return type of the task function (can be inferred from the return value of fn).
+ */
+export type CreateWorkflowDurableTaskOpts<T, K> = CreateWorkflowTaskOpts<T, K, DurableTaskFn<T, K>>;
+/**
+ * Options for creating a hatchet task which is an atomic unit of work in a workflow.
+ * @template T The input type for the task function.
+ * @template K The return type of the task function (can be inferred from the return value of fn).
+ */
+export type CreateStandaloneDurableTaskOpts<T, K> = CreateBaseTaskOpts<T, K, DurableTaskFn<T, K>>;
+/**
+ * Options for configuring the onSuccess task that is invoked when a task succeeds.
+ * @template T The input type for the task function.
+ * @template K The return type of the task function (can be inferred from the return value of fn).
+ */
+export type CreateOnSuccessTaskOpts<T, K> = CreateBaseTaskOpts<T, K, TaskFn<T, K>>;
+/**
+ * Options for configuring the onFailure task that is invoked when a task fails.
+ * @template T The input type for the task function.
+ * @template K The return type of the task function (can be inferred from the return value of fn).
+ */
+export type CreateOnFailureTaskOpts<T, K> = CreateBaseTaskOpts<T, K, TaskFn<T, K>>;

package/version.d.ts

@@ -1 +1 @@
-export declare const HATCHET_VERSION = "1.0.0-alpha1";
+export declare const HATCHET_VERSION = "1.0.0";

package/version.js

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

package/v1/workflow.d.ts

@@ -1,158 +0,0 @@
-import WorkflowRunRef from '../util/workflow-run-ref';
-import { Context, JsonObject } from '../step';
-import { CronWorkflows, ScheduledWorkflows } from '../clients/rest/generated/data-contracts';
-import { Workflow as WorkflowV0 } from '../workflow';
-import { IHatchetClient } from './client/client.interface';
-import { CreateTaskOpts } from './task';
-/**
- * Additional metadata that can be attached to a workflow run.
- */
-type AdditionalMetadata = Record<string, string>;
-/**
- * Options for running a workflow.
- */
-export type RunOpts = {
-    /**
-     * Additional metadata to attach to the workflow run.
-     */
-    additionalMetadata?: AdditionalMetadata;
-};
-/**
- * Extracts a property from an object type based on task name, or falls back to inferred type
- */
-type TaskOutputType<K, TaskName extends string, InferredType> = TaskName extends keyof K ? K[TaskName] : InferredType;
-/**
- * Options for creating a new workflow.
- */
-export type CreateWorkflowOpts = {
-    /**
-     * The name of the workflow.
-     */
-    name: WorkflowV0['id'];
-    /**
-     * (optional) description of the workflow.
-     */
-    description?: WorkflowV0['description'];
-    /**
-     * (optional) version of the workflow.
-     */
-    version?: WorkflowV0['version'];
-    /**
-     * (optional) sticky strategy for the workflow.
-     */
-    sticky?: WorkflowV0['sticky'];
-    /**
-     * (optional) schedule timeout for the workflow.
-     */
-    scheduleTimeout?: WorkflowV0['scheduleTimeout'];
-    /**
-     * (optional) on config for the workflow.
-     */
-    on?: WorkflowV0['on'];
-    concurrency?: WorkflowV0['concurrency'];
-    /**
-     * (optional) onFailure handler for the workflow.
-     * Invoked when any task in the workflow fails.
-     * @param ctx The context of the workflow.
-     */
-    onFailure?: (ctx: Context<any>) => void;
-};
-/**
- * Internal definition of a workflow and its tasks.
- */
-type WorkflowDefinition = CreateWorkflowOpts & {
-    /**
-     * The tasks that make up this workflow.
-     */
-    tasks: CreateTaskOpts<any, any>[];
-};
-/**
- * Represents a workflow that can be executed by Hatchet.
- * @template T The input type for the workflow.
- * @template K The return type of the workflow.
- */
-export declare class WorkflowDeclaration<T extends JsonObject, K extends JsonObject> {
-    /**
-     * The Hatchet client instance used to execute the workflow.
-     */
-    client: IHatchetClient | undefined;
-    /**
-     * The internal workflow definition.
-     */
-    definition: WorkflowDefinition;
-    /**
-     * Creates a new workflow instance.
-     * @param options The options for creating the workflow.
-     * @param client Optional Hatchet client instance.
-     */
-    constructor(options: CreateWorkflowOpts, client?: IHatchetClient);
-    /**
-     * Triggers a workflow run without waiting for completion.
-     * @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.
-     * @throws Error if the workflow is not bound to a Hatchet client.
-     */
-    enqueue(input: T, options?: RunOpts): WorkflowRunRef<K>;
-    /**
-     * Executes the workflow with the given input and awaits the results.
-     * @param input The input data for the workflow.
-     * @param options Optional configuration for this workflow run.
-     * @returns A promise that resolves with the workflow result.
-     * @throws Error if the workflow is not bound to a Hatchet client.
-     */
-    run(input: T, options?: RunOpts): Promise<K>;
-    run(input: T[], options?: RunOpts): Promise<K[]>;
-    /**
-     * Schedules a workflow to run at a specific date and time in the future.
-     * @param enqueueAt The date when the workflow should be triggered.
-     * @param input The input data for the workflow.
-     * @param options Optional configuration for this workflow run.
-     * @returns A promise that resolves with the scheduled workflow details.
-     * @throws Error if the workflow is not bound to a Hatchet client.
-     */
-    schedule(enqueueAt: Date, input: T, options?: RunOpts): Promise<ScheduledWorkflows>;
-    /**
-     * Schedules a workflow to run after a specified delay.
-     * @param duration The delay in seconds before the workflow should run.
-     * @param input The input data for the workflow.
-     * @param options Optional configuration for this workflow run.
-     * @returns A promise that resolves with the scheduled workflow details.
-     * @throws Error if the workflow is not bound to a Hatchet client.
-     */
-    delay(duration: number, input: T, options?: RunOpts): Promise<ScheduledWorkflows>;
-    /**
-     * Creates a cron schedule for the workflow.
-     * @param name The name of the cron schedule.
-     * @param expression The cron expression defining the schedule.
-     * @param input The input data for the workflow.
-     * @param options Optional configuration for this workflow run.
-     * @returns A promise that resolves with the cron workflow details.
-     * @throws Error if the workflow is not bound to a Hatchet client.
-     */
-    cron(name: string, expression: string, input: T, options?: RunOpts): Promise<CronWorkflows>;
-    /**
-     * Adds a task to the workflow.
-     * The return type will be either the property on K that corresponds to the task name,
-     * or if there is no matching property, the inferred return type of the function.
-     * @template Name The literal string name of the task.
-     * @template L The inferred return type of the task function.
-     * @param options The task configuration options.
-     * @returns The task options that were added.
-     */
-    task<Name extends string, L>(options: Omit<CreateTaskOpts<T, TaskOutputType<K, Name, L>>, 'fn'> & {
-        name: Name;
-        fn: (input: T, ctx: Context<T>) => TaskOutputType<K, Name, L> | Promise<TaskOutputType<K, Name, L>>;
-    }): CreateTaskOpts<T, TaskOutputType<K, Name, L>>;
-    get id(): string;
-}
-/**
- * Creates a new workflow instance.
- * @template T The input type for the workflow.
- * @template K The return type of the workflow.
- * @param options The options for creating the workflow.
- * @param client Optional Hatchet client instance.
- * @returns A new Workflow instance.
- */
-export declare function CreateWorkflow<T extends JsonObject = any, K extends JsonObject = any>(options: CreateWorkflowOpts, client?: IHatchetClient): WorkflowDeclaration<T, K>;
-export {};

package/v1/workflow.js

@@ -1,145 +0,0 @@
-"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.WorkflowDeclaration = void 0;
-exports.CreateWorkflow = CreateWorkflow;
-const UNBOUND_ERR = new Error('workflow unbound to hatchet client, hint: use client.run instead');
-/**
- * Represents a workflow that can be executed by Hatchet.
- * @template T The input type for the workflow.
- * @template K The return type of the workflow.
- */
-class WorkflowDeclaration {
-    /**
-     * Creates a new workflow instance.
-     * @param options The options for creating the workflow.
-     * @param client Optional Hatchet client instance.
-     */
-    constructor(options, client) {
-        this.definition = Object.assign(Object.assign({}, options), { tasks: [] });
-        this.client = client;
-    }
-    /**
-     * Triggers a workflow run without waiting for completion.
-     * @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.
-     * @throws Error if the workflow is not bound to a Hatchet client.
-     */
-    enqueue(input, options) {
-        if (!this.client) {
-            throw UNBOUND_ERR;
-        }
-        return this.client.v0.admin.runWorkflow(this.definition.name, input, options);
-    }
-    run(input, options) {
-        return __awaiter(this, void 0, void 0, function* () {
-            if (!this.client) {
-                throw UNBOUND_ERR;
-            }
-            if (Array.isArray(input)) {
-                // FIXME use bulk endpoint?
-                return Promise.all(input.map((i) => this.run(i, options)));
-            }
-            const res = this.client.v0.admin.runWorkflow(this.definition.name, input, options);
-            return res.result();
-        });
-    }
-    /**
-     * Schedules a workflow to run at a specific date and time in the future.
-     * @param enqueueAt The date when the workflow should be triggered.
-     * @param input The input data for the workflow.
-     * @param options Optional configuration for this workflow run.
-     * @returns A promise that resolves with the scheduled workflow details.
-     * @throws Error if the workflow is not bound to a Hatchet client.
-     */
-    schedule(enqueueAt, input, options) {
-        return __awaiter(this, void 0, void 0, function* () {
-            if (!this.client) {
-                throw UNBOUND_ERR;
-            }
-            const scheduled = this.client.v0.schedule.create(this.definition.name, {
-                triggerAt: enqueueAt,
-                input,
-                additionalMetadata: options === null || options === void 0 ? void 0 : options.additionalMetadata,
-            });
-            return scheduled;
-        });
-    }
-    /**
-     * Schedules a workflow to run after a specified delay.
-     * @param duration The delay in seconds before the workflow should run.
-     * @param input The input data for the workflow.
-     * @param options Optional configuration for this workflow run.
-     * @returns A promise that resolves with the scheduled workflow details.
-     * @throws Error if the workflow is not bound to a Hatchet client.
-     */
-    delay(duration, input, options) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const now = Date.now();
-            const triggerAt = new Date(now + duration * 1000);
-            return this.schedule(triggerAt, input, options);
-        });
-    }
-    /**
-     * Creates a cron schedule for the workflow.
-     * @param name The name of the cron schedule.
-     * @param expression The cron expression defining the schedule.
-     * @param input The input data for the workflow.
-     * @param options Optional configuration for this workflow run.
-     * @returns A promise that resolves with the cron workflow details.
-     * @throws Error if the workflow is not bound to a Hatchet client.
-     */
-    cron(name, expression, input, options) {
-        return __awaiter(this, void 0, void 0, function* () {
-            if (!this.client) {
-                throw UNBOUND_ERR;
-            }
-            const cronDef = this.client.v0.cron.create(this.definition.name, {
-                expression,
-                input,
-                additionalMetadata: options === null || options === void 0 ? void 0 : options.additionalMetadata,
-                name,
-            });
-            return cronDef;
-        });
-    }
-    /**
-     * Adds a task to the workflow.
-     * The return type will be either the property on K that corresponds to the task name,
-     * or if there is no matching property, the inferred return type of the function.
-     * @template Name The literal string name of the task.
-     * @template L The inferred return type of the task function.
-     * @param options The task configuration options.
-     * @returns The task options that were added.
-     */
-    task(options) {
-        const typedOptions = options;
-        this.definition.tasks.push(typedOptions);
-        return typedOptions;
-    }
-    // @deprecated use definition.name instead
-    get id() {
-        return this.definition.name;
-    }
-}
-exports.WorkflowDeclaration = WorkflowDeclaration;
-/**
- * Creates a new workflow instance.
- * @template T The input type for the workflow.
- * @template K The return type of the workflow.
- * @param options The options for creating the workflow.
- * @param client Optional Hatchet client instance.
- * @returns A new Workflow instance.
- */
-function CreateWorkflow(options, client) {
-    return new WorkflowDeclaration(options, client);
-}