@hatchet-dev/typescript-sdk 1.0.7 → 1.1.0

package/README.md

@@ -0,0 +1,109 @@
+# Hatchet TypeScript SDK
+
+<div align="center">
+
+[![npm version](https://badge.fury.io/js/@hatchet-dev%2Ftypescript-sdk.svg)](https://badge.fury.io/js/@hatchet-dev%2Ftypescript-sdk)
+[![Documentation](https://img.shields.io/badge/docs-hatchet.run-blue)](https://docs.hatchet.run)
+[![License: MIT](https://img.shields.io/badge/License-MIT-purple.svg)](https://opensource.org/licenses/MIT)
+
+</div>
+
+This is the official TypeScript SDK for [Hatchet](https://hatchet.run), a distributed, fault-tolerant task queue. The SDK provides a type-safe way to integrate Hatchet's task scheduling and workflow orchestration capabilities into your TypeScript/JavaScript applications.
+
+## Installation
+
+Install the SDK using npm:
+
+```bash
+npm install @hatchet-dev/typescript-sdk
+```
+
+Using yarn:
+
+```bash
+yarn add @hatchet-dev/typescript-sdk
+```
+
+Using pnpm:
+
+```bash
+pnpm add @hatchet-dev/typescript-sdk
+```
+
+## Quick Start
+
+Here's a simple example of how to use the Hatchet TypeScript SDK:
+
+```typescript
+import { HatchetClient } from '@hatchet-dev/typescript-sdk';
+
+export const hatchet = HatchetClient.init();
+
+export type SimpleInput = {
+  Message: string;
+};
+
+export const simple = hatchet.task({
+  name: 'simple',
+  fn: (input: SimpleInput) => {
+    return {
+      TransformedMessage: input.Message.toLowerCase(),
+    };
+  },
+});
+
+async function main() {
+  const worker = await hatchet.worker('simple-worker', {
+    workflows: [simple],
+    slots: 100,
+  });
+
+  await worker.start();
+}
+
+if (require.main === module) {
+  main();
+}
+```
+
+## Features
+
+- 📝 **Type Safety**: Full TypeScript support with type inference for workflow inputs and outputs
+- 🔄 **Workflow Orchestration**: Define complex workflows with dependencies and parallel execution
+- 🔁 **Automatic Retries**: Configure retry policies for handling transient failures
+- 📊 **Observability**: Track workflow progress and monitor execution metrics
+- ⏰ **Scheduling**: Schedule workflows to run at specific times or on a recurring basis
+- 🔄 **Event-Driven**: Trigger workflows based on events in your system
+
+## Documentation
+
+For detailed documentation, examples, and best practices, visit:
+- [Hatchet Documentation](https://docs.hatchet.run)
+- [Examples](https://github.com/hatchet-dev/hatchet/tree/main/sdks/typescript/src/v1/examples)
+
+## Development
+
+We use `pnpm` as our package manager. To get started with development:
+
+1. Install dependencies:
+```bash
+pnpm install
+```
+
+2. Build the SDK:
+```bash
+pnpm build
+```
+
+3. Run tests:
+```bash
+pnpm test
+```
+
+## Contributing
+
+We welcome contributions! Please check out our [contributing guidelines](https://docs.hatchet.run/contributing) and join our [Discord community](https://discord.gg/ZMeUafwH89) for discussions and support.
+
+## License
+
+This SDK is released under the MIT License. See [LICENSE](https://github.com/hatchet-dev/hatchet/blob/main/LICENSE) for details.

package/clients/worker/worker.d.ts

@@ -51,7 +51,7 @@ export declare class V0Worker {
     registerAction<T, K>(actionId: string, action: StepRunFunction<T, K>): void;
     handleStartStepRun(action: Action): Promise<void>;
     handleStartGroupKeyRun(action: Action): Promise<void>;
-    getStepActionEvent(action: Action, eventType: StepActionEventType, payload?: any): StepActionEvent;
+    getStepActionEvent(action: Action, eventType: StepActionEventType, shouldNotRetry: boolean, payload?: any): StepActionEvent;
     getGroupKeyActionEvent(action: Action, eventType: GroupKeyActionEventType, payload?: any): GroupKeyActionEvent;
     handleCancelStepRun(action: Action): Promise<void>;
     stop(): Promise<void>;

package/clients/worker/worker.js

@@ -25,6 +25,7 @@ const dispatcher_1 = require("../../protoc/dispatcher");
 const hatchet_promise_1 = __importDefault(require("../../util/hatchet-promise/hatchet-promise"));
 const workflows_1 = require("../../protoc/workflows");
 const handler_1 = require("./handler");
+const task_1 = require("../../v1/task");
 const transformer_1 = require("../../v1/conditions/transformer");
 const step_1 = require("../../step");
 class V0Worker {
@@ -345,13 +346,13 @@ class V0Worker {
                     this.logger.info(`Step run ${action.stepRunId} succeeded`);
                     try {
                         // Send the action event to the dispatcher
-                        const event = this.getStepActionEvent(action, dispatcher_1.StepActionEventType.STEP_EVENT_TYPE_COMPLETED, result || null);
+                        const event = this.getStepActionEvent(action, dispatcher_1.StepActionEventType.STEP_EVENT_TYPE_COMPLETED, false, result || null);
                         yield this.client.dispatcher.sendStepActionEvent(event);
                     }
                     catch (actionEventError) {
                         this.logger.error(`Could not send completed action event: ${actionEventError.message || actionEventError}`);
                         // send a failure event
-                        const failureEvent = this.getStepActionEvent(action, dispatcher_1.StepActionEventType.STEP_EVENT_TYPE_FAILED, actionEventError.message);
+                        const failureEvent = this.getStepActionEvent(action, dispatcher_1.StepActionEventType.STEP_EVENT_TYPE_FAILED, false, actionEventError.message);
                         try {
                             yield this.client.dispatcher.sendStepActionEvent(failureEvent);
                         }
@@ -371,9 +372,10 @@ class V0Worker {
                     if (error.stack) {
                         this.logger.error(error.stack);
                     }
+                    const shouldNotRetry = error instanceof task_1.NonRetryableError;
                     try {
                         // Send the action event to the dispatcher
-                        const event = this.getStepActionEvent(action, dispatcher_1.StepActionEventType.STEP_EVENT_TYPE_FAILED, {
+                        const event = this.getStepActionEvent(action, dispatcher_1.StepActionEventType.STEP_EVENT_TYPE_FAILED, shouldNotRetry, {
                             message: error === null || error === void 0 ? void 0 : error.message,
                             stack: error === null || error === void 0 ? void 0 : error.stack,
                         });
@@ -401,7 +403,7 @@ class V0Worker {
                 }))());
                 this.futures[action.stepRunId] = future;
                 // Send the action event to the dispatcher
-                const event = this.getStepActionEvent(action, dispatcher_1.StepActionEventType.STEP_EVENT_TYPE_STARTED);
+                const event = this.getStepActionEvent(action, dispatcher_1.StepActionEventType.STEP_EVENT_TYPE_STARTED, false);
                 this.client.dispatcher.sendStepActionEvent(event).catch((e) => {
                     this.logger.error(`Could not send action event: ${e.message}`);
                 });
@@ -487,7 +489,7 @@ class V0Worker {
             }
         });
     }
-    getStepActionEvent(action, eventType, payload = '') {
+    getStepActionEvent(action, eventType, shouldNotRetry, payload = '') {
         return {
             workerId: this.name,
             jobId: action.jobId,
@@ -498,6 +500,7 @@ class V0Worker {
             eventTimestamp: new Date(),
             eventType,
             eventPayload: JSON.stringify(payload),
+            shouldNotRetry,
         };
     }
     getGroupKeyActionEvent(action, eventType, payload = '') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hatchet-dev/typescript-sdk",
-  "version": "1.0.7",
+  "version": "1.1.0",
   "description": "Background task orchestration & visibility for developers",
   "types": "dist/index.d.ts",
   "files": [
@@ -8,7 +8,8 @@
     "!**/*.test.js",
     "!**/*.test.d.ts",
     "!**/*.e2e.js",
-    "!**/*.e2e.d.ts"
+    "!**/*.e2e.d.ts",
+    "README.md"
   ],
   "repository": {
     "type": "git",
@@ -60,8 +61,10 @@
     "worker:multi-workflow": "npm run exec -- ./src/examples/multi-workflow.ts",
     "worker:logger": "npm run exec -- ./src/examples/logger.ts",
     "worker:byo-logger": "npm run exec -- ./src/examples/byo-logger.ts",
+    "worker:no-retry": "npm run exec -- ./src/v1/examples/non_retryable/worker.ts",
+    "worker:no-retry:trigger": "npm run exec -- ./src/v1/examples/non_retryable/run.ts",
     "api": "npm run exec -- ./src/examples/api.ts",
-    "prepublish": "cp package.json dist/package.json;",
+    "prepublish": "cp package.json dist/package.json; cp README.md dist/",
     "publish:ci": "rm -rf ./dist && npm run dump-version && npm run tsc:build && npm run prepublish && cd dist && npm publish --access public --no-git-checks",
     "publish:ci:alpha": "rm -rf ./dist && npm run dump-version && npm run tsc:build && npm run prepublish && cd dist && npm publish --access public --no-git-checks --tag alpha",
     "generate-docs": "typedoc"

package/protoc/dispatcher/dispatcher.d.ts

@@ -207,6 +207,8 @@ export interface StepActionEvent {
     eventPayload: string;
     /** the retry count */
     retryCount?: number | undefined;
+    /** a flag indicating if the task should _not_ be retried */
+    shouldNotRetry?: boolean | undefined;
 }
 export interface ActionEventResponse {
     /** the tenant id */

package/protoc/dispatcher/dispatcher.js

@@ -1737,6 +1737,7 @@ function createBaseStepActionEvent() {
         eventType: 0,
         eventPayload: '',
         retryCount: undefined,
+        shouldNotRetry: undefined,
     };
 }
 exports.StepActionEvent = {
@@ -1771,6 +1772,9 @@ exports.StepActionEvent = {
         if (message.retryCount !== undefined) {
             writer.uint32(80).int32(message.retryCount);
         }
+        if (message.shouldNotRetry !== undefined) {
+            writer.uint32(88).bool(message.shouldNotRetry);
+        }
         return writer;
     },
     decode(input, length) {
@@ -1850,6 +1854,13 @@ exports.StepActionEvent = {
                     message.retryCount = reader.int32();
                     continue;
                 }
+                case 11: {
+                    if (tag !== 88) {
+                        break;
+                    }
+                    message.shouldNotRetry = reader.bool();
+                    continue;
+                }
             }
             if ((tag & 7) === 4 || tag === 0) {
                 break;
@@ -1872,6 +1883,9 @@ exports.StepActionEvent = {
             eventType: isSet(object.eventType) ? stepActionEventTypeFromJSON(object.eventType) : 0,
             eventPayload: isSet(object.eventPayload) ? globalThis.String(object.eventPayload) : '',
             retryCount: isSet(object.retryCount) ? globalThis.Number(object.retryCount) : undefined,
+            shouldNotRetry: isSet(object.shouldNotRetry)
+                ? globalThis.Boolean(object.shouldNotRetry)
+                : undefined,
         };
     },
     toJSON(message) {
@@ -1906,13 +1920,16 @@ exports.StepActionEvent = {
         if (message.retryCount !== undefined) {
             obj.retryCount = Math.round(message.retryCount);
         }
+        if (message.shouldNotRetry !== undefined) {
+            obj.shouldNotRetry = message.shouldNotRetry;
+        }
         return obj;
     },
     create(base) {
         return exports.StepActionEvent.fromPartial(base !== null && base !== void 0 ? base : {});
     },
     fromPartial(object) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
         const message = createBaseStepActionEvent();
         message.workerId = (_a = object.workerId) !== null && _a !== void 0 ? _a : '';
         message.jobId = (_b = object.jobId) !== null && _b !== void 0 ? _b : '';
@@ -1924,6 +1941,7 @@ exports.StepActionEvent = {
         message.eventType = (_h = object.eventType) !== null && _h !== void 0 ? _h : 0;
         message.eventPayload = (_j = object.eventPayload) !== null && _j !== void 0 ? _j : '';
         message.retryCount = (_k = object.retryCount) !== null && _k !== void 0 ? _k : undefined;
+        message.shouldNotRetry = (_l = object.shouldNotRetry) !== null && _l !== void 0 ? _l : undefined;
         return message;
     },
 };

package/v1/examples/non_retryable/run.d.ts

@@ -0,0 +1 @@
+export {};

package/v1/examples/non_retryable/run.js

@@ -0,0 +1,22 @@
+"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 });
+const workflow_1 = require("./workflow");
+function main() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const res = yield workflow_1.nonRetryableWorkflow.runNoWait({});
+        // eslint-disable-next-line no-console
+        console.log(res);
+    });
+}
+if (require.main === module) {
+    main();
+}

package/v1/examples/non_retryable/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/v1/examples/non_retryable/worker.js

@@ -0,0 +1,24 @@
+"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 });
+const hatchet_client_1 = require("../hatchet-client");
+const workflow_1 = require("./workflow");
+function main() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const worker = yield hatchet_client_1.hatchet.worker('no-retry-worker', {
+            workflows: [workflow_1.nonRetryableWorkflow],
+        });
+        yield worker.start();
+    });
+}
+if (require.main === module) {
+    main();
+}

package/v1/examples/non_retryable/workflow.d.ts

@@ -0,0 +1 @@
+export declare const nonRetryableWorkflow: import("../..").WorkflowDeclaration<import("../..").UnknownInputType, {}>;

package/v1/examples/non_retryable/workflow.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nonRetryableWorkflow = void 0;
+const task_1 = require("../../task");
+const hatchet_client_1 = require("../hatchet-client");
+exports.nonRetryableWorkflow = hatchet_client_1.hatchet.workflow({
+    name: 'no-retry-workflow',
+});
+// ❓ Non-retrying task
+const shouldNotRetry = exports.nonRetryableWorkflow.task({
+    name: 'should-not-retry',
+    fn: () => {
+        throw new task_1.NonRetryableError('This task should not retry');
+    },
+    retries: 1,
+});
+// !!
+// Create a task that should retry
+const shouldRetryWrongErrorType = exports.nonRetryableWorkflow.task({
+    name: 'should-retry-wrong-error-type',
+    fn: () => {
+        throw new Error('This task should not retry');
+    },
+    retries: 1,
+});
+const shouldNotRetrySuccessfulTask = exports.nonRetryableWorkflow.task({
+    name: 'should-not-retry-successful-task',
+    fn: () => { },
+});

package/v1/task.d.ts

@@ -29,6 +29,9 @@ export type TaskConcurrency = {
      */
     limitStrategy?: ConcurrencyLimitStrategy;
 };
+export declare class NonRetryableError extends Error {
+    constructor(message?: string);
+}
 export type TaskFn<I extends InputType = UnknownInputType, O extends OutputType = void, C = Context<I>> = (input: I, ctx: C) => O | Promise<O>;
 export type DurableTaskFn<I extends InputType = UnknownInputType, O extends OutputType = void> = TaskFn<I, O, DurableContext<I>>;
 /**

package/v1/task.js

@@ -1,2 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.NonRetryableError = void 0;
+class NonRetryableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NonRetryableError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.NonRetryableError = NonRetryableError;

package/version.d.ts

@@ -1 +1 @@
-export declare const HATCHET_VERSION = "1.0.7";
+export declare const HATCHET_VERSION = "1.1.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.7';
+exports.HATCHET_VERSION = '1.1.0';