@io-orkes/conductor-javascript 3.0.0 → 3.0.2

package/README.md

@@ -77,7 +77,7 @@ await workflow.register();
 
 **Step 2: Write a worker**
 
-Workers are TypeScript functions decorated with `@worker` that poll Conductor for tasks and execute them.
+Workers are TypeScript functions decorated with `@worker` that poll Conductor for tasks and execute them. The example below uses the legacy decorator style (standalone function). See [Workers](#workers) for the new TypeScript 5.0+ decorator style (class methods).
 
 ```typescript
 import { worker } from "@io-orkes/conductor-javascript";
@@ -215,30 +215,77 @@ All of these are type-safe, composable, and registered to the server as JSON —
 
 ## Workers
 
-Workers are TypeScript functions that execute Conductor tasks. Decorate any function with `@worker` to register it as a worker (auto-discovered by `TaskHandler`) and use it as a workflow task.
+Workers are TypeScript functions that execute Conductor tasks. Decorate functions with `@worker` to register them as workers (auto-discovered by `TaskHandler`) and use them as workflow tasks.
+
+The SDK supports **both** decorator styles:
+
+### Option 1: New decorators (TypeScript 5.0+)
+
+Use class methods with the new Stage 3 decorators. No `experimentalDecorators` needed — remove it from your `tsconfig.json`.
+
+```typescript
+import { worker, TaskHandler } from "@io-orkes/conductor-javascript";
+import type { Task } from "@io-orkes/conductor-javascript";
+
+class Workers {
+  @worker({ taskDefName: "greet", concurrency: 5, pollInterval: 100 })
+  async greet(task: Task) {
+    return {
+      status: "COMPLETED" as const,
+      outputData: { result: `Hello ${task.inputData?.name ?? "World"}` },
+    };
+  }
+
+  @worker({ taskDefName: "process_payment", domain: "payments" })
+  async processPayment(task: Task) {
+    const result = await paymentGateway.charge(task.inputData.customerId, task.inputData.amount);
+    return { status: "COMPLETED" as const, outputData: { transactionId: result.id } };
+  }
+}
+
+// Class definition triggers decorators — workers are registered
+void new Workers();
+
+const handler = new TaskHandler({ client, scanForDecorated: true });
+await handler.startWorkers();
+```
+
+### Option 2: Legacy decorators (experimentalDecorators)
+
+Use standalone functions. Add `"experimentalDecorators": true` to your `tsconfig.json`.
 
 ```typescript
 import { worker, TaskHandler } from "@io-orkes/conductor-javascript";
+import type { Task } from "@io-orkes/conductor-javascript";
 
 @worker({ taskDefName: "greet", concurrency: 5, pollInterval: 100 })
 async function greet(task: Task) {
   return {
-    status: "COMPLETED",
-    outputData: { result: `Hello ${task.inputData.name}` },
+    status: "COMPLETED" as const,
+    outputData: { result: `Hello ${task.inputData?.name ?? "World"}` },
   };
 }
 
 @worker({ taskDefName: "process_payment", domain: "payments" })
 async function processPayment(task: Task) {
   const result = await paymentGateway.charge(task.inputData.customerId, task.inputData.amount);
-  return { status: "COMPLETED", outputData: { transactionId: result.id } };
+  return { status: "COMPLETED" as const, outputData: { transactionId: result.id } };
 }
 
-// Auto-discover and start all decorated workers
 const handler = new TaskHandler({ client, scanForDecorated: true });
 await handler.startWorkers();
+```
+
+### tsconfig setup
 
-// Graceful shutdown
+| Decorator style | tsconfig.json |
+|-----------------|---------------|
+| **New** (TypeScript 5.0+) | Omit `experimentalDecorators` — use class methods |
+| **Legacy** | `"experimentalDecorators": true` — use standalone functions |
+
+**Graceful shutdown:**
+
+```typescript
 process.on("SIGTERM", async () => {
   await handler.stopWorkers();
   process.exit(0);

package/dist/index.d.mts

@@ -5289,6 +5289,11 @@ declare class TaskRunner {
     get isPaused(): boolean;
     get getOptions(): TaskRunnerOptions;
     private batchPoll;
+    /**
+     * Probed once per process. null = unknown, true = v2 endpoint available,
+     * false = legacy server (no /api/tasks/update-v2 endpoint).
+     */
+    private static updateV2Available;
     updateTaskWithRetry: (task: Task, taskResult: TaskResult) => Promise<Task | undefined>;
     private isValidTask;
     /**
@@ -6317,7 +6322,16 @@ interface WorkerOptions {
  * }
  * ```
  */
-declare function worker(options: WorkerOptions): (target: unknown, propertyKey?: string, descriptor?: PropertyDescriptor) => PropertyDescriptor | ((this: unknown, ...args: unknown[]) => unknown);
+/** Minimal context shape for Stage 3 method decorators (TypeScript 5.0+). */
+interface MethodDecoratorContext {
+    kind: string;
+    name: string | symbol;
+}
+type WorkerMethod = (task: Task) => Promise<Omit<TaskResult, "workflowInstanceId" | "taskId">>;
+declare function worker(options: WorkerOptions): {
+    <T extends WorkerMethod>(value: T, context: MethodDecoratorContext): T | undefined;
+    (target: object, propertyKey?: string, descriptor?: PropertyDescriptor): PropertyDescriptor | WorkerMethod | undefined;
+};
 
 /**
  * Registered worker metadata stored in the global registry.
@@ -6717,9 +6731,12 @@ interface SchemaFieldOptions {
  * When used with `generateSchemaFromClass()`, produces a JSON Schema draft-07
  * object from the decorated properties.
  *
- * If `emitDecoratorMetadata` is enabled in tsconfig.json, the TypeScript type
- * is automatically inferred for `string`, `number`, `boolean` — no need to
- * specify `type` explicitly for those.
+ * Supports both TypeScript 5.0+ (Stage 3) and legacy (experimentalDecorators)
+ * decorator APIs.
+ *
+ * If `emitDecoratorMetadata` is enabled in tsconfig.json (legacy mode), the
+ * TypeScript type is automatically inferred for `string`, `number`, `boolean` —
+ * no need to specify `type` explicitly for those.
  *
  * @example
  * ```typescript
@@ -6737,7 +6754,10 @@ interface SchemaFieldOptions {
  * const schema = generateSchemaFromClass(OrderInput);
  * ```
  */
-declare function schemaField(options?: SchemaFieldOptions): (target: object, propertyKey: string) => void;
+declare function schemaField(options?: SchemaFieldOptions): (targetOrValue: object | undefined, propertyKeyOrContext?: string | {
+    kind: string;
+    name: string | symbol;
+}) => ((initialValue: unknown) => unknown) | undefined;
 /**
  * Generate a JSON Schema (draft-07) from a class decorated with `@schemaField()`.
  *

package/dist/index.d.ts

@@ -5289,6 +5289,11 @@ declare class TaskRunner {
     get isPaused(): boolean;
     get getOptions(): TaskRunnerOptions;
     private batchPoll;
+    /**
+     * Probed once per process. null = unknown, true = v2 endpoint available,
+     * false = legacy server (no /api/tasks/update-v2 endpoint).
+     */
+    private static updateV2Available;
     updateTaskWithRetry: (task: Task, taskResult: TaskResult) => Promise<Task | undefined>;
     private isValidTask;
     /**
@@ -6317,7 +6322,16 @@ interface WorkerOptions {
  * }
  * ```
  */
-declare function worker(options: WorkerOptions): (target: unknown, propertyKey?: string, descriptor?: PropertyDescriptor) => PropertyDescriptor | ((this: unknown, ...args: unknown[]) => unknown);
+/** Minimal context shape for Stage 3 method decorators (TypeScript 5.0+). */
+interface MethodDecoratorContext {
+    kind: string;
+    name: string | symbol;
+}
+type WorkerMethod = (task: Task) => Promise<Omit<TaskResult, "workflowInstanceId" | "taskId">>;
+declare function worker(options: WorkerOptions): {
+    <T extends WorkerMethod>(value: T, context: MethodDecoratorContext): T | undefined;
+    (target: object, propertyKey?: string, descriptor?: PropertyDescriptor): PropertyDescriptor | WorkerMethod | undefined;
+};
 
 /**
  * Registered worker metadata stored in the global registry.
@@ -6717,9 +6731,12 @@ interface SchemaFieldOptions {
  * When used with `generateSchemaFromClass()`, produces a JSON Schema draft-07
  * object from the decorated properties.
  *
- * If `emitDecoratorMetadata` is enabled in tsconfig.json, the TypeScript type
- * is automatically inferred for `string`, `number`, `boolean` — no need to
- * specify `type` explicitly for those.
+ * Supports both TypeScript 5.0+ (Stage 3) and legacy (experimentalDecorators)
+ * decorator APIs.
+ *
+ * If `emitDecoratorMetadata` is enabled in tsconfig.json (legacy mode), the
+ * TypeScript type is automatically inferred for `string`, `number`, `boolean` —
+ * no need to specify `type` explicitly for those.
  *
  * @example
  * ```typescript
@@ -6737,7 +6754,10 @@ interface SchemaFieldOptions {
  * const schema = generateSchemaFromClass(OrderInput);
  * ```
  */
-declare function schemaField(options?: SchemaFieldOptions): (target: object, propertyKey: string) => void;
+declare function schemaField(options?: SchemaFieldOptions): (targetOrValue: object | undefined, propertyKeyOrContext?: string | {
+    kind: string;
+    name: string | symbol;
+}) => ((initialValue: unknown) => unknown) | undefined;
 /**
  * Generate a JSON Schema (draft-07) from a class decorated with `@schemaField()`.
  *

package/dist/index.js

@@ -39271,7 +39271,7 @@ var defaultRunnerOptions = {
   concurrency: DEFAULT_CONCURRENCY,
   batchPollingTimeout: DEFAULT_BATCH_POLLING_TIMEOUT
 };
-var TaskRunner = class {
+var TaskRunner = class _TaskRunner {
   _client;
   worker;
   logger;
@@ -39396,21 +39396,94 @@ var TaskRunner = class {
       throw error;
     }
   };
+  /**
+   * Probed once per process. null = unknown, true = v2 endpoint available,
+   * false = legacy server (no /api/tasks/update-v2 endpoint).
+   */
+  static updateV2Available = null;
   updateTaskWithRetry = async (task, taskResult) => {
     const { workerID } = this.options;
     let retryCount = 0;
     let lastError = null;
     while (retryCount < this.maxRetries) {
       try {
+        if (process.env.CI) {
+          console.log(
+            `[TaskRunner] Submitting task result taskId=${taskResult.taskId} workflowId=${taskResult.workflowInstanceId} taskType=${this.worker.taskDefName} attempt=${retryCount + 1}/${this.maxRetries}`
+          );
+        }
         const updateStart = Date.now();
-        const { data: nextTask } = await TaskResource.updateTaskV2({
-          client: this._client,
-          body: {
-            ...taskResult,
-            workerId: workerID
+        if (_TaskRunner.updateV2Available === false) {
+          await TaskResource.updateTask({
+            client: this._client,
+            body: { ...taskResult, workerId: workerID },
+            throwOnError: true
+          });
+          const updateDurationMs2 = Date.now() - updateStart;
+          if (process.env.CI) {
+            console.log(
+              `[TaskRunner] Task result accepted (legacy) taskId=${taskResult.taskId} durationMs=${updateDurationMs2}`
+            );
           }
+          await this.eventDispatcher.publishTaskUpdateCompleted({
+            taskType: this.worker.taskDefName,
+            taskId: taskResult.taskId ?? "",
+            workerId: workerID,
+            workflowInstanceId: taskResult.workflowInstanceId,
+            durationMs: updateDurationMs2,
+            timestamp: /* @__PURE__ */ new Date()
+          });
+          return void 0;
+        }
+        const {
+          data: nextTask,
+          error,
+          response
+        } = await TaskResource.updateTaskV2({
+          client: this._client,
+          body: { ...taskResult, workerId: workerID },
+          throwOnError: false
         });
+        if (response.status === 404 || response.status === 405) {
+          if (_TaskRunner.updateV2Available === null) {
+            console.log(
+              `[TaskRunner] /api/tasks/update-v2 not available (HTTP ${response.status}), falling back to legacy /api/tasks endpoint`
+            );
+            _TaskRunner.updateV2Available = false;
+          }
+          await TaskResource.updateTask({
+            client: this._client,
+            body: { ...taskResult, workerId: workerID },
+            throwOnError: true
+          });
+          const updateDurationMs2 = Date.now() - updateStart;
+          if (process.env.CI) {
+            console.log(
+              `[TaskRunner] Task result accepted (legacy) taskId=${taskResult.taskId} durationMs=${updateDurationMs2}`
+            );
+          }
+          await this.eventDispatcher.publishTaskUpdateCompleted({
+            taskType: this.worker.taskDefName,
+            taskId: taskResult.taskId ?? "",
+            workerId: workerID,
+            workflowInstanceId: taskResult.workflowInstanceId,
+            durationMs: updateDurationMs2,
+            timestamp: /* @__PURE__ */ new Date()
+          });
+          return void 0;
+        }
+        if (!response.ok) {
+          throw error ?? new Error(`Task update failed with HTTP ${response.status}`);
+        }
+        if (_TaskRunner.updateV2Available === null) {
+          _TaskRunner.updateV2Available = true;
+        }
         const updateDurationMs = Date.now() - updateStart;
+        if (process.env.CI) {
+          console.log(
+            `[TaskRunner] Task result accepted taskId=${taskResult.taskId} durationMs=${updateDurationMs}`
+          );
+        }
         await this.eventDispatcher.publishTaskUpdateCompleted({
           taskType: this.worker.taskDefName,
           taskId: taskResult.taskId ?? "",
@@ -39427,6 +39500,9 @@ var TaskRunner = class {
           `Error updating task ${taskResult.taskId} on retry ${retryCount + 1}/${this.maxRetries}`,
           error
         );
+        console.log(
+          `[TaskRunner] Task update failed taskId=${taskResult.taskId} attempt=${retryCount + 1}/${this.maxRetries} error=${lastError?.message ?? String(error)}`
+        );
         retryCount++;
         if (retryCount < this.maxRetries) {
           const delayMs = retryCount * 10 * 1e3;
@@ -41439,20 +41515,51 @@ var TaskHandler = class _TaskHandler {
 
 // src/sdk/worker/schema/decorators.ts
 var SCHEMA_METADATA_KEY = Symbol("conductor:schemaField");
+function isNewDecoratorContext(arg) {
+  return typeof arg === "object" && arg !== null && "kind" in arg && typeof arg.kind === "string";
+}
+var schemaFieldProcessed = /* @__PURE__ */ new WeakMap();
+function storeSchemaFieldMetadata(cls, propertyKey, options, designType) {
+  const existing = Reflect.getOwnMetadata(SCHEMA_METADATA_KEY, cls) ?? [];
+  existing.push({
+    ...options,
+    propertyKey,
+    designType
+  });
+  Reflect.defineMetadata(SCHEMA_METADATA_KEY, existing, cls);
+}
 function schemaField(options = {}) {
-  return function(target, propertyKey) {
-    const existing = Reflect.getOwnMetadata(SCHEMA_METADATA_KEY, target.constructor) ?? [];
+  return function(targetOrValue, propertyKeyOrContext) {
+    if (isNewDecoratorContext(propertyKeyOrContext)) {
+      const propertyKey2 = String(propertyKeyOrContext.name);
+      return function(initialValue) {
+        const cls = this.constructor;
+        const processed = schemaFieldProcessed.get(cls) ?? /* @__PURE__ */ new Set();
+        if (!processed.has(propertyKey2)) {
+          processed.add(propertyKey2);
+          schemaFieldProcessed.set(cls, processed);
+          let designType2;
+          try {
+            designType2 = Reflect.getMetadata(
+              "design:type",
+              this,
+              propertyKey2
+            );
+          } catch {
+          }
+          storeSchemaFieldMetadata(cls, propertyKey2, options, designType2);
+        }
+        return initialValue;
+      };
+    }
+    const target = targetOrValue;
+    const propertyKey = propertyKeyOrContext;
     let designType;
     try {
       designType = Reflect.getMetadata("design:type", target, propertyKey);
     } catch {
     }
-    existing.push({
-      ...options,
-      propertyKey,
-      designType
-    });
-    Reflect.defineMetadata(SCHEMA_METADATA_KEY, existing, target.constructor);
+    storeSchemaFieldMetadata(target.constructor, propertyKey, options, designType);
   };
 }
 function inferType(designType) {
@@ -41513,9 +41620,20 @@ function generateSchemaFromClass(cls) {
 }
 
 // src/sdk/worker/decorators/worker.ts
+function isNewDecoratorContext2(arg) {
+  return typeof arg === "object" && arg !== null && "kind" in arg && typeof arg.kind === "string";
+}
 function worker(options) {
-  return function(target, propertyKey, descriptor) {
-    const executeFunction = descriptor?.value || target;
+  function decorator(target, propertyKeyOrContext, descriptor) {
+    let executeFunction;
+    let isNewApi = false;
+    if (isNewDecoratorContext2(propertyKeyOrContext)) {
+      executeFunction = target;
+      isNewApi = true;
+    } else {
+      const fn = descriptor?.value ?? target;
+      executeFunction = fn;
+    }
     if (typeof executeFunction !== "function") {
       throw new Error(
         `@worker decorator can only be applied to functions. Received: ${typeof executeFunction}`
@@ -41529,10 +41647,14 @@ function worker(options) {
     let resolvedInputSchema = options.inputSchema;
     let resolvedOutputSchema = options.outputSchema;
     if (options.inputType) {
-      resolvedInputSchema = generateSchemaFromClass(options.inputType);
+      resolvedInputSchema = generateSchemaFromClass(
+        options.inputType
+      );
     }
     if (options.outputType) {
-      resolvedOutputSchema = generateSchemaFromClass(options.outputType);
+      resolvedOutputSchema = generateSchemaFromClass(
+        options.outputType
+      );
     }
     const registeredWorker = {
       taskDefName: options.taskDefName,
@@ -41559,18 +41681,25 @@ function worker(options) {
           builderArgs.inputParameters ?? {}
         );
       }
-      return executeFunction.apply(this, args);
+      return executeFunction.apply(
+        this,
+        args
+      );
     };
     Object.defineProperty(dualModeFunction, "name", {
       value: executeFunction.name,
       configurable: true
     });
+    if (isNewApi) {
+      return dualModeFunction;
+    }
     if (descriptor) {
       descriptor.value = dualModeFunction;
       return descriptor;
     }
     return dualModeFunction;
-  };
+  }
+  return decorator;
 }
 
 // src/sdk/worker/metrics/MetricsCollector.ts