@abinnovision/nestjs-hatchet 0.2.2 → 0.3.0

package/dist/decorators/host-opts.d.ts

@@ -0,0 +1,19 @@
+import type { CreateBaseWorkflowOpts } from "@hatchet-dev/typescript-sdk";
+import type { AnyEventDefinition } from "../events";
+/**
+ * Input type for onEvents - accepts strings or EventDefinitions.
+ */
+export type OnEventsInput = ReadonlyArray<string | AnyEventDefinition>;
+/**
+ * Properties we enhance beyond SDK types.
+ */
+interface EnhancedProperties {
+    name: string;
+    onEvents?: OnEventsInput;
+}
+type PassthroughProperties = Omit<CreateBaseWorkflowOpts, "on" | keyof EnhancedProperties>;
+/**
+ * Enhanced HostOpts for @Host() decorator.
+ */
+export type HostOpts = EnhancedProperties & PassthroughProperties;
+export {};

package/dist/decorators/host-opts.js

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

package/dist/decorators/host.decorator.d.ts

@@ -1,6 +1,19 @@
+import type { AnyEventDefinition } from "../events";
 import type { CreateBaseWorkflowOpts } from "@hatchet-dev/typescript-sdk";
-export type HostOpts = Omit<CreateBaseWorkflowOpts, "on">;
+/**
+ * Properties we enhance beyond SDK types.
+ */
+interface EnhancedProperties {
+    name: string;
+    onEvents?: ReadonlyArray<string | AnyEventDefinition>;
+}
+type PassthroughProperties = Omit<CreateBaseWorkflowOpts, "on" | keyof EnhancedProperties>;
+/**
+ * Enhanced HostOpts for @Host() decorator.
+ */
+export type HostOpts = EnhancedProperties & PassthroughProperties;
 /**
  * Decorator to mark a class as a host (for either a workflow or a task).
  */
-export declare const Host: (_opts: HostOpts) => ClassDecorator;
+export declare const Host: (opts: HostOpts) => ClassDecorator;
+export {};

package/dist/decorators/host.decorator.js

@@ -6,12 +6,12 @@ const internal_1 = require("../internal");
 /**
  * Decorator to mark a class as a host (for either a workflow or a task).
  */
-const Host = (_opts) => {
+const Host = (opts) => {
     return (target) => {
         // Make the workflow injectable.
         (0, common_1.Injectable)()(target);
         // Add the workflow options.
-        Reflect.defineMetadata(internal_1.METADATA_KEY_HOST_OPTS, _opts, target);
+        Reflect.defineMetadata(internal_1.METADATA_KEY_HOST_OPTS, opts, target);
         return target;
     };
 };

package/dist/decorators/workflow-task.decorators.d.ts

@@ -1,5 +1,5 @@
 import type { WorkflowCtx } from "../context";
-import type { ContextMethodKeys, WorkflowHostCtor } from "../ref";
+import type { ContextMethodKeys, WorkflowHostCtor } from "../ref/shared";
 import type { CreateWorkflowTaskOpts } from "@hatchet-dev/typescript-sdk/v1/task";
 export type WorkflowTaskOpts<C extends WorkflowHostCtor<any>> = Omit<CreateWorkflowTaskOpts, "fn" | "parents" | "name"> & {
     parents?: ContextMethodKeys<InstanceType<C>, WorkflowCtx<any>>[];

package/dist/events/index.d.ts

@@ -1 +1,2 @@
-export * from "./event-definition";
+export { EventDefinition, defineEvent } from "./event-definition";
+export type { AnyEventDefinition, EventInput, EventOutput, } from "./event-definition";

package/dist/events/index.js

@@ -1,17 +1,6 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./event-definition"), exports);
+exports.defineEvent = exports.EventDefinition = void 0;
+var event_definition_1 = require("./event-definition");
+Object.defineProperty(exports, "EventDefinition", { enumerable: true, get: function () { return event_definition_1.EventDefinition; } });
+Object.defineProperty(exports, "defineEvent", { enumerable: true, get: function () { return event_definition_1.defineEvent; } });

package/dist/execution/context/factory.d.ts

@@ -0,0 +1,22 @@
+import { type BaseCtx, type HostTriggerConfig, type TaskCtx, type WorkflowCtx } from "./types";
+/**
+ * Arguments for context factory functions.
+ * Derived from BaseCtx using Pick to ensure type alignment.
+ */
+type CreateCtxArgs<I> = Pick<BaseCtx<I>, "fromSDK" | "triggerSource"> & {
+    input: I;
+    hostConfig: HostTriggerConfig;
+};
+/**
+ * Creates a TaskCtx from SDK Context for standalone task execution.
+ *
+ * @param args The arguments for creating the task context.
+ */
+export declare const createTaskCtx: <I>(args: CreateCtxArgs<I>) => TaskCtx<any>;
+/**
+ * Creates a WorkflowCtx from SDK Context for workflow task execution.
+ *
+ * @param args The arguments for creating the workflow context.
+ */
+export declare const createWorkflowCtx: <I>(args: CreateCtxArgs<I>) => WorkflowCtx<any>;
+export {};

package/dist/execution/context/factory.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWorkflowCtx = exports.createTaskCtx = void 0;
+const types_1 = require("./types");
+const adapter_factory_1 = require("../host-run/adapter-factory");
+/**
+ * Creates the helper methods derived from the SDK context.
+ * These are methods that wrap SDK functionality.
+ */
+const createContextHelpers = (fromSDK) => ({
+    run: (0, adapter_factory_1.createHostRunForContext)(fromSDK),
+});
+/**
+ * Creates the trigger guard methods bound to the context's trigger source.
+ */
+const createTriggerGuards = (triggerSource, input) => ({
+    isRun: () => triggerSource === "run",
+    isCron: () => triggerSource === "cron",
+    isEvent: (eventDef) => {
+        if (triggerSource !== "event") {
+            return false;
+        }
+        // If no event definition is provided, then we validate against any event.
+        if (!eventDef) {
+            return true;
+        }
+        return eventDef.isCtx({ input });
+    },
+});
+/**
+ * Maps the args to the 1:1 context properties.
+ */
+const mapContextProperties = (args) => ({
+    fromSDK: args.fromSDK,
+    input: args.input,
+    triggerSource: args.triggerSource,
+    hostConfig: args.hostConfig,
+});
+/**
+ * Creates a TaskCtx from SDK Context for standalone task execution.
+ *
+ * @param args The arguments for creating the task context.
+ */
+const createTaskCtx = (args) => ({
+    [types_1.TASK_MARKER]: true,
+    ...mapContextProperties(args),
+    ...createContextHelpers(args.fromSDK),
+    ...createTriggerGuards(args.triggerSource, args.input),
+});
+exports.createTaskCtx = createTaskCtx;
+/**
+ * Creates a WorkflowCtx from SDK Context for workflow task execution.
+ *
+ * @param args The arguments for creating the workflow context.
+ */
+const createWorkflowCtx = (args) => {
+    const parent = async (method) => {
+        const methodName = method.name;
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return await args.fromSDK.parentOutput(methodName);
+    };
+    return {
+        [types_1.TASK_MARKER]: true,
+        ...mapContextProperties(args),
+        ...createContextHelpers(args.fromSDK),
+        ...createTriggerGuards(args.triggerSource, args.input),
+        parent,
+    };
+};
+exports.createWorkflowCtx = createWorkflowCtx;

package/dist/execution/context/index.d.ts

@@ -0,0 +1,4 @@
+export type { BaseCtx, TaskCtx, WorkflowCtx, HelperCtx, TriggerSource, HostTriggerConfig, } from "./types";
+export { TASK_MARKER } from "./types";
+export type { TaskMarker } from "./types";
+export { createTaskCtx, createWorkflowCtx } from "./factory";

package/dist/execution/context/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWorkflowCtx = exports.createTaskCtx = exports.TASK_MARKER = void 0;
+var types_1 = require("./types");
+Object.defineProperty(exports, "TASK_MARKER", { enumerable: true, get: function () { return types_1.TASK_MARKER; } });
+var factory_1 = require("./factory");
+Object.defineProperty(exports, "createTaskCtx", { enumerable: true, get: function () { return factory_1.createTaskCtx; } });
+Object.defineProperty(exports, "createWorkflowCtx", { enumerable: true, get: function () { return factory_1.createWorkflowCtx; } });

package/dist/execution/context/types.d.ts

@@ -0,0 +1,108 @@
+import type { TaskHost, WorkflowHost } from "../../abstracts";
+import type { AnyEventDefinition, EventOutput } from "../../events";
+import type { AnyTaskFn, OutputOfTaskFn } from "../../references/shared";
+import type { HostRunFn } from "../host-run";
+import type { Context } from "@hatchet-dev/typescript-sdk";
+export declare const TASK_MARKER: unique symbol;
+export type TaskMarker = typeof TASK_MARKER;
+/**
+ * Type representing the source that triggered the task execution.
+ *
+ * - "run": Triggered with default payload via direct run.
+ * - "event": Triggered by an event.
+ * - "cron": Triggered by a cron schedule.
+ *
+ * Note that the detection of trigger source is best-effort and may not be accurate in all cases.
+ * Hatchet does not currently provide first-class support for distinguishing all trigger sources.
+ */
+export type TriggerSource = "run" | "event" | "cron";
+/**
+ * Configuration extracted from host decorator for trigger introspection.
+ */
+export interface HostTriggerConfig {
+    /**
+     * Event names this host listens to
+     */
+    onEvents: string[];
+    /**
+     * Cron schedules this host responds to
+     */
+    onCrons: string[];
+}
+/**
+ * Type for the context when a task is running. This is universal for standalone and workflow tasks.
+ * This partially implements the `Context` type from the SDK.
+ *
+ * @template I The input type of the task.
+ */
+export interface BaseCtx<I> {
+    /**
+     * Host metadata accessor for introspection.
+     */
+    readonly hostConfig: HostTriggerConfig;
+    /**
+     * The source that triggered the task execution.
+     */
+    triggerSource: TriggerSource;
+    /**
+     * Provides access to the underlying SDK context.
+     */
+    fromSDK: Context<I, any>;
+    /**
+     * The input to the task.
+     */
+    input: I;
+    /**
+     * Function to run other tasks within the context of this task.
+     */
+    run: HostRunFn;
+    /**
+     * Returns true if triggered via direct run.
+     * When true, ctx.input is the validated host schema type.
+     */
+    isRun: () => this is BaseCtx<I> & {
+        triggerSource: "run";
+    };
+    /**
+     * Returns true if triggered via event.
+     * Optionally accepts an EventDefinition to check for a specific event type.
+     *
+     * @param eventDef Optional event definition to check for specific event
+     */
+    isEvent: <E extends AnyEventDefinition>(eventDef?: E) => this is BaseCtx<I> & {
+        triggerSource: "event";
+        input: E extends AnyEventDefinition ? EventOutput<E> : unknown;
+    };
+    /**
+     * Returns true if triggered via cron schedule.
+     * When true, ctx.input is void/empty.
+     */
+    isCron: () => this is BaseCtx<I> & {
+        triggerSource: "cron";
+        input: never;
+    };
+}
+/**
+ * Context type of the run of a standalone task.
+ * Branded with TASK_MARKER for compile-time task method detection.
+ */
+export type TaskCtx<T extends TaskHost<any>> = BaseCtx<T extends TaskHost<infer I> ? I : never> & {
+    [TASK_MARKER]: true;
+};
+/**
+ * Context type of the run of a workflow task.
+ * Branded with TASK_MARKER for compile-time task method detection.
+ */
+export type WorkflowCtx<T extends WorkflowHost<any>> = BaseCtx<T extends WorkflowHost<infer I> ? I : never> & {
+    [TASK_MARKER]: true;
+    /**
+     * Provides the output of a parent task.
+     */
+    parent: <F extends AnyTaskFn<any, any>>(method: F) => Promise<OutputOfTaskFn<F>>;
+};
+/**
+ * Context type for helper methods that need access to the task context
+ * but should not be counted as task methods.
+ * This is essentially BaseCtx with the input type extracted from the host.
+ */
+export type HelperCtx<T extends TaskHost<any> | WorkflowHost<any>> = BaseCtx<T extends TaskHost<infer I> ? I : T extends WorkflowHost<infer I> ? I : never>;

package/dist/execution/context/types.js

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

package/dist/execution/host-run/adapter-factory.d.ts

@@ -0,0 +1,12 @@
+import type { HostRunFn } from "./function-type";
+import type { Context, HatchetClient } from "@hatchet-dev/typescript-sdk";
+/**
+ * Creates a HostRunFn that uses SDK Context for spawning child workflows.
+ * Used within task execution contexts.
+ */
+export declare function createHostRunForContext(ctx: Context<any, any>): HostRunFn;
+/**
+ * Creates a HostRunFn that uses HatchetClient for external workflow triggering.
+ * Used by HClient for triggering workflows from outside task contexts.
+ */
+export declare function createHostRunForAdmin(client: HatchetClient): HostRunFn;

package/dist/execution/host-run/adapter-factory.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHostRunForContext = createHostRunForContext;
+exports.createHostRunForAdmin = createHostRunForAdmin;
+const helpers_1 = require("../../references/helpers");
+/**
+ * Creates a HostRunFn using the provided runner strategy.
+ * This is the shared implementation for both context and admin runners.
+ */
+function createHostRunFn(runner) {
+    return async (ref, input, options) => {
+        const workflowName = (0, helpers_1.getRefAccessor)(ref).name;
+        const wait = options?.wait ?? true;
+        if (Array.isArray(input)) {
+            const results = await Promise.all(input.map((i) => runner(workflowName, i, options)));
+            if (wait) {
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+                return (await Promise.all(results.map((r) => r.output)));
+            }
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+            return results;
+        }
+        const runRef = await runner(workflowName, input, options);
+        if (wait) {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+            return runRef.output;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return runRef;
+    };
+}
+/**
+ * Creates a HostRunFn that uses SDK Context for spawning child workflows.
+ * Used within task execution contexts.
+ */
+function createHostRunForContext(ctx) {
+    return createHostRunFn((workflowName, input, options) => ctx.runNoWaitChild(workflowName, input, options));
+}
+/**
+ * Creates a HostRunFn that uses HatchetClient for external workflow triggering.
+ * Used by HClient for triggering workflows from outside task contexts.
+ */
+function createHostRunForAdmin(client) {
+    return createHostRunFn((workflowName, input, options) => client.runNoWait(workflowName, input, options ?? {}));
+}

package/dist/execution/host-run/function-type.d.ts

@@ -0,0 +1,24 @@
+import type { AnyCallableRef, InputOfRef, OutputOfRef } from "../../references";
+import type { RunOpts } from "@hatchet-dev/typescript-sdk";
+import type WorkflowRunRef from "@hatchet-dev/typescript-sdk/util/workflow-run-ref";
+/**
+ * Describes the return type of the {@link HostRunFn} function.
+ *
+ * @param I The input type of the callable reference.
+ * @param R The callable reference.
+ * @param W Whether to wait for the task to complete before returning.
+ */
+export type HostRunReturn<I extends InputOfRef<R> | InputOfRef<R>[], R extends AnyCallableRef, W extends boolean> = I extends InputOfRef<R>[] ? W extends true ? OutputOfRef<R>[] : WorkflowRunRef<OutputOfRef<R>>[] : W extends true ? OutputOfRef<R> : WorkflowRunRef<OutputOfRef<R>>;
+export interface HostRunOpts<W extends boolean> extends RunOpts {
+    /**
+     * Whether to wait for the task to complete before returning.
+     *
+     * @default true
+     */
+    wait?: W;
+}
+/**
+ * Runs a child task or workflow. This can be used to run multiple tasks in parallel.
+ * If `wait` is set to `false`, a `WorkflowRunRef` is returned.
+ */
+export type HostRunFn = <R extends AnyCallableRef, I extends InputOfRef<R> | InputOfRef<R>[], W extends boolean = true>(ref: R, input: I, options?: HostRunOpts<W>) => Promise<HostRunReturn<I, R, W>>;

package/dist/execution/host-run/function-type.js

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

package/dist/execution/host-run/index.d.ts

@@ -0,0 +1,2 @@
+export type { HostRunFn, HostRunOpts, HostRunReturn } from "./function-type";
+export { createHostRunForContext, createHostRunForAdmin, } from "./adapter-factory";

package/dist/execution/host-run/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHostRunForAdmin = exports.createHostRunForContext = void 0;
+var adapter_factory_1 = require("./adapter-factory");
+Object.defineProperty(exports, "createHostRunForContext", { enumerable: true, get: function () { return adapter_factory_1.createHostRunForContext; } });
+Object.defineProperty(exports, "createHostRunForAdmin", { enumerable: true, get: function () { return adapter_factory_1.createHostRunForAdmin; } });

package/dist/execution/index.d.ts

@@ -0,0 +1,2 @@
+export type { BaseCtx, TaskCtx, WorkflowCtx, HelperCtx, TriggerSource, HostTriggerConfig, } from "./context";
+export type { HostRunFn, HostRunOpts, HostRunReturn } from "./host-run";

package/dist/execution/index.js

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

package/dist/explorer/declaration-builder.service.d.ts

@@ -1,7 +1,7 @@
 import { TaskWorkflowDeclaration, WorkflowDeclaration } from "@hatchet-dev/typescript-sdk";
 import { ModuleRef } from "@nestjs/core";
-import { InterceptorRegistration } from "../internal";
-import { AnyHost } from "../ref";
+import { InterceptorRegistration } from "../internal/registrations";
+import { AnyHost } from "../references/shared";
 export declare class DeclarationBuilderService {
     private readonly moduleRef;
     private readonly interceptorRegistration?;
@@ -44,13 +44,12 @@ export declare class DeclarationBuilderService {
      */
     private buildWorkflowHostGraph;
     /**
-     * Validates and transforms input using the host's schema.
-     * Skips validation if input is from an event trigger (contains EVENT_MARKER).
-     * Event validation is handled by the event's isCtx() method instead.
+     * Pre-processes the context by inferring the trigger source and
+     * validating the input (if applicable).
      *
-     * @returns The transformed input if schema exists, otherwise returns original input.
+     * @returns The pre-processed context properties including hostConfig.
      */
-    private validateAndTransformInput;
+    private preProcessContext;
     /**
      * Executes a function, optionally intercepted by the interceptors.
      * Interceptors are chained in array order (first = outermost).
@@ -60,4 +59,12 @@ export declare class DeclarationBuilderService {
      * @returns The result of the function.
      */
     private executeWithInterceptors;
+    /**
+     * Infers the trigger source from the given context.
+     *
+     * @param ctx The context.
+     * @returns The inferred trigger source.
+     * @private
+     */
+    private inferTriggerSource;
 }