@abinnovision/nestjs-hatchet 0.8.0-beta.2 → 0.8.0-beta.3

package/README.md

@@ -1,5 +1,7 @@
 # @abinnovision/nestjs-hatchet
 
+[![npm](https://img.shields.io/npm/v/@abinnovision/nestjs-hatchet?style=flat-square)](https://www.npmjs.com/package/@abinnovision/nestjs-hatchet)
+
 NestJS integration for [Hatchet](https://hatchet.run) - a distributed workflow
 orchestration engine. Provides type-safe decorators, services, and event
 handling for building robust workflows.
@@ -231,3 +233,7 @@ export class MyTask extends taskHost(schema) {
   }
 }
 ```
+
+## License
+
+Apache-2.0

package/dist/events/event-definition.cjs

@@ -1,3 +1,4 @@
+const require_event_payload_malformed_exception = require("../exceptions/event-payload-malformed.exception.cjs");
 //#region src/events/event-definition.ts
 /**
 * Marker embedded in event payload to identify an event type.
@@ -33,12 +34,12 @@
 	*
 	* @param ctx The context to check (TaskCtx, WorkflowCtx, HelperCtx, or SDK Context).
 	* @returns True if the context input is a non-null object that passes schema validation.
-	* @throws Error if the payload fails schema validation.
+	* @throws {EventPayloadMalformedException} If the payload fails schema validation.
 	*/ cast(ctx) {
 		if (typeof ctx.input !== "object" || ctx.input === null) return false;
 		const result = this.schema["~standard"].validate(ctx.input);
 		if (result instanceof Promise) throw new Error(`Event '${this.name}' schema validation must be synchronous. Use a sync schema.`);
-		if ("issues" in result && result.issues) throw new Error(`Event '${this.name}' payload is malformed: ${JSON.stringify(result.issues)}`);
+		if ("issues" in result && result.issues) throw new require_event_payload_malformed_exception.EventPayloadMalformedException(this.name, result.issues);
 		return true;
 	}
 	/**
@@ -47,7 +48,7 @@
 	*
 	* @param ctx The context to check (TaskCtx, WorkflowCtx, HelperCtx, or SDK Context).
 	* @returns True if the context input contains the event marker matching this event.
-	* @throws Error if the event marker matches but the payload fails schema validation.
+	* @throws {EventPayloadMalformedException} If the event marker matches but the payload fails schema validation.
 	*/ isCtx(ctx) {
 		if (typeof ctx.input !== "object" || ctx.input === null || !("__event_name" in ctx.input) || ctx.input["__event_name"] !== this.name) return false;
 		return this.cast(ctx);

package/dist/events/event-definition.d.ts

@@ -33,7 +33,7 @@ export declare class EventDefinition<TName extends string, TSchema extends Stand
      *
      * @param ctx The context to check (TaskCtx, WorkflowCtx, HelperCtx, or SDK Context).
      * @returns True if the context input is a non-null object that passes schema validation.
-     * @throws Error if the payload fails schema validation.
+     * @throws {EventPayloadMalformedException} If the payload fails schema validation.
      */
     cast<C extends {
         input: unknown;
@@ -46,7 +46,7 @@ export declare class EventDefinition<TName extends string, TSchema extends Stand
      *
      * @param ctx The context to check (TaskCtx, WorkflowCtx, HelperCtx, or SDK Context).
      * @returns True if the context input contains the event marker matching this event.
-     * @throws Error if the event marker matches but the payload fails schema validation.
+     * @throws {EventPayloadMalformedException} If the event marker matches but the payload fails schema validation.
      */
     isCtx<C extends {
         input: unknown;

package/dist/events/event-definition.mjs

@@ -1,3 +1,4 @@
+import { EventPayloadMalformedException } from "../exceptions/event-payload-malformed.exception.mjs";
 //#region src/events/event-definition.ts
 /**
 * Marker embedded in event payload to identify an event type.
@@ -33,12 +34,12 @@
 	*
 	* @param ctx The context to check (TaskCtx, WorkflowCtx, HelperCtx, or SDK Context).
 	* @returns True if the context input is a non-null object that passes schema validation.
-	* @throws Error if the payload fails schema validation.
+	* @throws {EventPayloadMalformedException} If the payload fails schema validation.
 	*/ cast(ctx) {
 		if (typeof ctx.input !== "object" || ctx.input === null) return false;
 		const result = this.schema["~standard"].validate(ctx.input);
 		if (result instanceof Promise) throw new Error(`Event '${this.name}' schema validation must be synchronous. Use a sync schema.`);
-		if ("issues" in result && result.issues) throw new Error(`Event '${this.name}' payload is malformed: ${JSON.stringify(result.issues)}`);
+		if ("issues" in result && result.issues) throw new EventPayloadMalformedException(this.name, result.issues);
 		return true;
 	}
 	/**
@@ -47,7 +48,7 @@
 	*
 	* @param ctx The context to check (TaskCtx, WorkflowCtx, HelperCtx, or SDK Context).
 	* @returns True if the context input contains the event marker matching this event.
-	* @throws Error if the event marker matches but the payload fails schema validation.
+	* @throws {EventPayloadMalformedException} If the event marker matches but the payload fails schema validation.
 	*/ isCtx(ctx) {
 		if (typeof ctx.input !== "object" || ctx.input === null || !("__event_name" in ctx.input) || ctx.input["__event_name"] !== this.name) return false;
 		return this.cast(ctx);

package/dist/exceptions/event-payload-malformed.exception.cjs

@@ -0,0 +1,19 @@
+const require_hatchet_exception = require("./hatchet.exception.cjs");
+const require_validation_issue = require("./validation-issue.cjs");
+//#region src/exceptions/event-payload-malformed.exception.ts
+/**
+* Thrown when an event payload received by
+* {@link EventDefinition.cast} or {@link EventDefinition.isCtx} does not
+* match the event's declared schema.
+*/ var EventPayloadMalformedException = class extends require_hatchet_exception.HatchetException {
+	eventName;
+	issues;
+	constructor(eventName, rawIssues) {
+		const issues = require_validation_issue.normalizeIssues(rawIssues);
+		super(require_validation_issue.formatIssueSummary(`Event '${eventName}' payload is malformed`, issues));
+		this.eventName = eventName;
+		this.issues = issues;
+	}
+};
+//#endregion
+exports.EventPayloadMalformedException = EventPayloadMalformedException;

package/dist/exceptions/event-payload-malformed.exception.d.ts

@@ -0,0 +1,13 @@
+import { HatchetException } from "./hatchet.exception.js";
+import type { ValidationIssue } from "./validation-issue.js";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+/**
+ * Thrown when an event payload received by
+ * {@link EventDefinition.cast} or {@link EventDefinition.isCtx} does not
+ * match the event's declared schema.
+ */
+export declare class EventPayloadMalformedException extends HatchetException {
+    readonly eventName: string;
+    readonly issues: ValidationIssue[];
+    constructor(eventName: string, rawIssues: ReadonlyArray<StandardSchemaV1.Issue>);
+}

package/dist/exceptions/event-payload-malformed.exception.mjs

@@ -0,0 +1,19 @@
+import { HatchetException } from "./hatchet.exception.mjs";
+import { formatIssueSummary, normalizeIssues } from "./validation-issue.mjs";
+//#region src/exceptions/event-payload-malformed.exception.ts
+/**
+* Thrown when an event payload received by
+* {@link EventDefinition.cast} or {@link EventDefinition.isCtx} does not
+* match the event's declared schema.
+*/ var EventPayloadMalformedException = class extends HatchetException {
+	eventName;
+	issues;
+	constructor(eventName, rawIssues) {
+		const issues = normalizeIssues(rawIssues);
+		super(formatIssueSummary(`Event '${eventName}' payload is malformed`, issues));
+		this.eventName = eventName;
+		this.issues = issues;
+	}
+};
+//#endregion
+export { EventPayloadMalformedException };

package/dist/exceptions/hatchet.exception.cjs

@@ -0,0 +1,14 @@
+//#region src/exceptions/hatchet.exception.ts
+/**
+* Base class for all exceptions thrown by the hatchet integration.
+*
+* Subclasses set `name` to their own class name for clean stack traces
+* and may expose typed metadata via additional readonly properties.
+*/ var HatchetException = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = new.target.name;
+	}
+};
+//#endregion
+exports.HatchetException = HatchetException;

package/dist/exceptions/hatchet.exception.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Base class for all exceptions thrown by the hatchet integration.
+ *
+ * Subclasses set `name` to their own class name for clean stack traces
+ * and may expose typed metadata via additional readonly properties.
+ */
+export declare abstract class HatchetException extends Error {
+    protected constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}

package/dist/exceptions/hatchet.exception.mjs

@@ -0,0 +1,14 @@
+//#region src/exceptions/hatchet.exception.ts
+/**
+* Base class for all exceptions thrown by the hatchet integration.
+*
+* Subclasses set `name` to their own class name for clean stack traces
+* and may expose typed metadata via additional readonly properties.
+*/ var HatchetException = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = new.target.name;
+	}
+};
+//#endregion
+export { HatchetException };

package/dist/exceptions/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./event-payload-malformed.exception.js";
+export * from "./hatchet.exception.js";
+export * from "./input-validation-failed.exception.js";
+export * from "./validation-issue.js";

package/dist/exceptions/input-validation-failed.exception.cjs

@@ -0,0 +1,21 @@
+const require_hatchet_exception = require("./hatchet.exception.cjs");
+const require_validation_issue = require("./validation-issue.cjs");
+//#region src/exceptions/input-validation-failed.exception.ts
+/**
+* Thrown when a hatchet task or workflow is invoked via the `run`
+* trigger with an input that does not match the host's declared input
+* schema.
+*
+* The {@link InputValidationFailedException.issues} property exposes the
+* structured, per-field validation failures so callers can react
+* programmatically instead of parsing the message string.
+*/ var InputValidationFailedException = class extends require_hatchet_exception.HatchetException {
+	issues;
+	constructor(rawIssues) {
+		const issues = require_validation_issue.normalizeIssues(rawIssues);
+		super(require_validation_issue.formatIssueSummary("Input validation failed", issues));
+		this.issues = issues;
+	}
+};
+//#endregion
+exports.InputValidationFailedException = InputValidationFailedException;

package/dist/exceptions/input-validation-failed.exception.d.ts

@@ -0,0 +1,16 @@
+import { HatchetException } from "./hatchet.exception.js";
+import type { ValidationIssue } from "./validation-issue.js";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+/**
+ * Thrown when a hatchet task or workflow is invoked via the `run`
+ * trigger with an input that does not match the host's declared input
+ * schema.
+ *
+ * The {@link InputValidationFailedException.issues} property exposes the
+ * structured, per-field validation failures so callers can react
+ * programmatically instead of parsing the message string.
+ */
+export declare class InputValidationFailedException extends HatchetException {
+    readonly issues: ValidationIssue[];
+    constructor(rawIssues: ReadonlyArray<StandardSchemaV1.Issue>);
+}

package/dist/exceptions/input-validation-failed.exception.mjs

@@ -0,0 +1,21 @@
+import { HatchetException } from "./hatchet.exception.mjs";
+import { formatIssueSummary, normalizeIssues } from "./validation-issue.mjs";
+//#region src/exceptions/input-validation-failed.exception.ts
+/**
+* Thrown when a hatchet task or workflow is invoked via the `run`
+* trigger with an input that does not match the host's declared input
+* schema.
+*
+* The {@link InputValidationFailedException.issues} property exposes the
+* structured, per-field validation failures so callers can react
+* programmatically instead of parsing the message string.
+*/ var InputValidationFailedException = class extends HatchetException {
+	issues;
+	constructor(rawIssues) {
+		const issues = normalizeIssues(rawIssues);
+		super(formatIssueSummary("Input validation failed", issues));
+		this.issues = issues;
+	}
+};
+//#endregion
+export { InputValidationFailedException };

package/dist/exceptions/validation-issue.cjs

@@ -0,0 +1,52 @@
+//#region src/exceptions/validation-issue.ts
+/**
+* Extracts the raw key from a StandardSchema path entry, which can be
+* either a {@link PropertyKey} or a {@link StandardSchemaV1.PathSegment}.
+*/ function toSegmentKey(entry) {
+	if (typeof entry === "object") return entry.key;
+	return entry;
+}
+/**
+* Formats a sequence of path keys into dot/bracket notation.
+* Numeric keys become `[n]` segments; string keys become dot-joined
+* segments. Symbol keys fall back to their `.toString()` form.
+*/ function formatPath(segments) {
+	let result = "";
+	for (const segment of segments) {
+		if (typeof segment === "number") {
+			result += `[${String(segment)}]`;
+			continue;
+		}
+		const asString = typeof segment === "symbol" ? segment.toString() : segment;
+		if (result.length === 0) result = asString;
+		else result += `.${asString}`;
+	}
+	return result;
+}
+/**
+* Converts the raw issues produced by a StandardSchema-compatible schema
+* into the structured {@link ValidationIssue} shape exposed on hatchet
+* exceptions.
+*/ function normalizeIssues(raw) {
+	return raw.map((issue) => {
+		const segments = (issue.path ?? []).map(toSegmentKey);
+		if (segments.length === 0) return { message: issue.message };
+		return {
+			message: issue.message,
+			path: formatPath(segments)
+		};
+	});
+}
+/**
+* Builds a human-readable summary by joining each issue as
+* `<path>: <message>` (or just `<message>` when no path is present),
+* prefixed with the given prefix.
+*
+* Falls back to just the prefix when no issues are provided.
+*/ function formatIssueSummary(prefix, issues) {
+	if (issues.length === 0) return prefix;
+	return `${prefix}: ${issues.map((issue) => issue.path !== void 0 ? `${issue.path}: ${issue.message}` : issue.message).join("; ")}`;
+}
+//#endregion
+exports.formatIssueSummary = formatIssueSummary;
+exports.normalizeIssues = normalizeIssues;

package/dist/exceptions/validation-issue.d.ts

@@ -0,0 +1,30 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+/**
+ * Structured representation of a single schema validation issue.
+ */
+export interface ValidationIssue {
+    /**
+     * Human-readable description of why this field failed validation.
+     */
+    message: string;
+    /**
+     * Dot/bracket notation path to the offending field
+     * (e.g. `user.email`, `items[0].id`).
+     * Omitted when the failure is at the root.
+     */
+    path?: string;
+}
+/**
+ * Converts the raw issues produced by a StandardSchema-compatible schema
+ * into the structured {@link ValidationIssue} shape exposed on hatchet
+ * exceptions.
+ */
+export declare function normalizeIssues(raw: ReadonlyArray<StandardSchemaV1.Issue>): ValidationIssue[];
+/**
+ * Builds a human-readable summary by joining each issue as
+ * `<path>: <message>` (or just `<message>` when no path is present),
+ * prefixed with the given prefix.
+ *
+ * Falls back to just the prefix when no issues are provided.
+ */
+export declare function formatIssueSummary(prefix: string, issues: ValidationIssue[]): string;

package/dist/exceptions/validation-issue.mjs

@@ -0,0 +1,51 @@
+//#region src/exceptions/validation-issue.ts
+/**
+* Extracts the raw key from a StandardSchema path entry, which can be
+* either a {@link PropertyKey} or a {@link StandardSchemaV1.PathSegment}.
+*/ function toSegmentKey(entry) {
+	if (typeof entry === "object") return entry.key;
+	return entry;
+}
+/**
+* Formats a sequence of path keys into dot/bracket notation.
+* Numeric keys become `[n]` segments; string keys become dot-joined
+* segments. Symbol keys fall back to their `.toString()` form.
+*/ function formatPath(segments) {
+	let result = "";
+	for (const segment of segments) {
+		if (typeof segment === "number") {
+			result += `[${String(segment)}]`;
+			continue;
+		}
+		const asString = typeof segment === "symbol" ? segment.toString() : segment;
+		if (result.length === 0) result = asString;
+		else result += `.${asString}`;
+	}
+	return result;
+}
+/**
+* Converts the raw issues produced by a StandardSchema-compatible schema
+* into the structured {@link ValidationIssue} shape exposed on hatchet
+* exceptions.
+*/ function normalizeIssues(raw) {
+	return raw.map((issue) => {
+		const segments = (issue.path ?? []).map(toSegmentKey);
+		if (segments.length === 0) return { message: issue.message };
+		return {
+			message: issue.message,
+			path: formatPath(segments)
+		};
+	});
+}
+/**
+* Builds a human-readable summary by joining each issue as
+* `<path>: <message>` (or just `<message>` when no path is present),
+* prefixed with the given prefix.
+*
+* Falls back to just the prefix when no issues are provided.
+*/ function formatIssueSummary(prefix, issues) {
+	if (issues.length === 0) return prefix;
+	return `${prefix}: ${issues.map((issue) => issue.path !== void 0 ? `${issue.path}: ${issue.message}` : issue.message).join("; ")}`;
+}
+//#endregion
+export { formatIssueSummary, normalizeIssues };

package/dist/explorer/declaration-builder.service.cjs

@@ -1,3 +1,4 @@
+const require_input_validation_failed_exception = require("../exceptions/input-validation-failed.exception.cjs");
 const require_hosts = require("../abstracts/hosts.cjs");
 const require_accessor = require("../metadata/accessor.cjs");
 const require_factory = require("../execution/context/factory.cjs");
@@ -165,7 +166,7 @@ var DeclarationBuilderService = class {
 				triggerSource,
 				hostConfig
 			};
-			throw new Error(`Input validation failed: ${JSON.stringify(result.issues)}`);
+			throw new require_input_validation_failed_exception.InputValidationFailedException(result.issues);
 		} else return {
 			input,
 			triggerSource,

package/dist/explorer/declaration-builder.service.mjs

@@ -1,3 +1,4 @@
+import { InputValidationFailedException } from "../exceptions/input-validation-failed.exception.mjs";
 import { WorkflowHost } from "../abstracts/hosts.mjs";
 import { fromInstance } from "../metadata/accessor.mjs";
 import { createTaskCtx, createWorkflowCtx } from "../execution/context/factory.mjs";
@@ -165,7 +166,7 @@ var DeclarationBuilderService = class {
 				triggerSource,
 				hostConfig
 			};
-			throw new Error(`Input validation failed: ${JSON.stringify(result.issues)}`);
+			throw new InputValidationFailedException(result.issues);
 		} else return {
 			input,
 			triggerSource,

package/dist/index.cjs

@@ -1,15 +1,19 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_hatchet_exception = require("./exceptions/hatchet.exception.cjs");
+const require_validation_issue = require("./exceptions/validation-issue.cjs");
+const require_event_payload_malformed_exception = require("./exceptions/event-payload-malformed.exception.cjs");
+const require_input_validation_failed_exception = require("./exceptions/input-validation-failed.exception.cjs");
 const require_event_definition = require("./events/event-definition.cjs");
 const require_hosts = require("./abstracts/hosts.cjs");
 const require_helpers = require("./references/helpers.cjs");
 const require_client = require("./client/client.cjs");
 require("./client/index.cjs");
 const require_hatchet_module = require("./hatchet.module.cjs");
+const require_interceptor = require("./interceptor/interceptor.cjs");
 const require_host_decorator = require("./metadata/decorators/host.decorator.cjs");
 const require_task_decorator = require("./metadata/decorators/task.decorator.cjs");
 const require_workflow_task_decorator = require("./metadata/decorators/workflow-task.decorator.cjs");
 require("./metadata/index.cjs");
-const require_interceptor = require("./interceptor/interceptor.cjs");
 Object.defineProperty(exports, "Client", {
 	enumerable: true,
 	get: function() {
@@ -17,6 +21,8 @@ Object.defineProperty(exports, "Client", {
 	}
 });
 exports.EventDefinition = require_event_definition.EventDefinition;
+exports.EventPayloadMalformedException = require_event_payload_malformed_exception.EventPayloadMalformedException;
+exports.HatchetException = require_hatchet_exception.HatchetException;
 Object.defineProperty(exports, "HatchetModule", {
 	enumerable: true,
 	get: function() {
@@ -24,12 +30,15 @@ Object.defineProperty(exports, "HatchetModule", {
 	}
 });
 exports.Host = require_host_decorator.Host;
+exports.InputValidationFailedException = require_input_validation_failed_exception.InputValidationFailedException;
 exports.Interceptor = require_interceptor.Interceptor;
 exports.Task = require_task_decorator.Task;
 exports.TaskHost = require_hosts.TaskHost;
 exports.WorkflowHost = require_hosts.WorkflowHost;
 exports.WorkflowTask = require_workflow_task_decorator.WorkflowTask;
 exports.defineEvent = require_event_definition.defineEvent;
+exports.formatIssueSummary = require_validation_issue.formatIssueSummary;
+exports.normalizeIssues = require_validation_issue.normalizeIssues;
 exports.taskHost = require_hosts.taskHost;
 exports.taskRef = require_helpers.taskRef;
 exports.workflowHost = require_hosts.workflowHost;

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 export * from "./hatchet.module.js";
 export * from "./abstracts/index.js";
 export * from "./client/index.js";
-export * from "./execution/index.js";
-export * from "./metadata/index.js";
 export * from "./events/index.js";
+export * from "./exceptions/index.js";
+export * from "./execution/index.js";
 export * from "./interceptor/index.js";
+export * from "./metadata/index.js";
 export * from "./references/index.js";
 export type { HatchetModuleConfig } from "./hatchet.module-config.js";

package/dist/index.mjs

@@ -1,12 +1,16 @@
+import { HatchetException } from "./exceptions/hatchet.exception.mjs";
+import { formatIssueSummary, normalizeIssues } from "./exceptions/validation-issue.mjs";
+import { EventPayloadMalformedException } from "./exceptions/event-payload-malformed.exception.mjs";
+import { InputValidationFailedException } from "./exceptions/input-validation-failed.exception.mjs";
 import { EventDefinition, defineEvent } from "./events/event-definition.mjs";
 import { TaskHost, WorkflowHost, taskHost, workflowHost } from "./abstracts/hosts.mjs";
 import { taskRef, workflowRef } from "./references/helpers.mjs";
 import { Client } from "./client/client.mjs";
 import "./client/index.mjs";
 import { HatchetModule } from "./hatchet.module.mjs";
+import { Interceptor } from "./interceptor/interceptor.mjs";
 import { Host } from "./metadata/decorators/host.decorator.mjs";
 import { Task } from "./metadata/decorators/task.decorator.mjs";
 import { WorkflowTask } from "./metadata/decorators/workflow-task.decorator.mjs";
 import "./metadata/index.mjs";
-import { Interceptor } from "./interceptor/interceptor.mjs";
-export { Client, EventDefinition, HatchetModule, Host, Interceptor, Task, TaskHost, WorkflowHost, WorkflowTask, defineEvent, taskHost, taskRef, workflowHost, workflowRef };
+export { Client, EventDefinition, EventPayloadMalformedException, HatchetException, HatchetModule, Host, InputValidationFailedException, Interceptor, Task, TaskHost, WorkflowHost, WorkflowTask, defineEvent, formatIssueSummary, normalizeIssues, taskHost, taskRef, workflowHost, workflowRef };

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@abinnovision/nestjs-hatchet",
-  "version": "0.8.0-beta.2",
+  "version": "0.8.0-beta.3",
   "description": "NestJS integration for Hatchet workflow orchestration with declarative task and workflow decorators for building distributed job systems.",
   "keywords": [
     "nestjs",
@@ -82,8 +82,9 @@
     "@abinnovision/eslint-config-base": "^3.4.1",
     "@abinnovision/prettier-config": "^2.2.0",
     "@swc/core": "^1.15.18",
-    "@types/node": "^25.8.0",
-    "eslint": "^10.3.0",
+    "@types/node": "^25.9.1",
+    "arktype": "^2.2.0",
+    "eslint": "^10.4.0",
     "prettier": "^3.8.3",
     "publint": "^0.3.21",
     "reflect-metadata": "^0.2.2",