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

package/v1/workflow.d.ts

@@ -0,0 +1,152 @@
+import WorkflowRunRef from '../util/workflow-run-ref';
+import { Context } 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'];
+};
+/**
+ * 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 Workflow<T extends Record<string, any>, K> {
+    /**
+     * 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 Record<string, any> = any, K = any>(options: CreateWorkflowOpts, client?: IHatchetClient): Workflow<T, K>;
+export {};

package/v1/workflow.js

@@ -0,0 +1,145 @@
+"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.Workflow = 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 Workflow {
+    /**
+     * 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.Workflow = Workflow;
+/**
+ * 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 Workflow(options, client);
+}

package/version.d.ts

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

package/version.js

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

package/workflow.d.ts

@@ -478,6 +478,9 @@ export declare const CreateWorkflowSchema: z.ZodObject<{
         } | undefined;
     } | undefined;
 }>;
+/**
+ * @deprecated Use client.workflow instead (TODO link to migration doc)
+ */
 export interface Workflow extends z.infer<typeof CreateWorkflowSchema> {
     concurrency?: z.infer<typeof WorkflowConcurrency> & {
         key?: (ctx: any) => string;