@io-orkes/conductor-javascript 3.0.1 → 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

@@ -6322,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.
@@ -6722,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
@@ -6742,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

@@ -6322,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.
@@ -6722,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
@@ -6742,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

@@ -41515,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) {
@@ -41589,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}`
@@ -41605,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,
@@ -41635,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