nestjs-temporal-core 3.0.11 → 3.0.12

package/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [3.0.12] - 2025-11-07
+
+### Added
+- **Multiple Workers Support**: Configure and manage multiple workers with different task queues in the same process
+- New `workers` array property in `TemporalOptions` for defining multiple worker configurations
+- `getAllWorkers()`: Get information about all registered workers
+- `getWorker(taskQueue)`: Get a specific worker by task queue name
+- `getWorkerStatusByTaskQueue(taskQueue)`: Get status of a specific worker
+- `startWorkerByTaskQueue(taskQueue)`: Start a specific worker
+- `stopWorkerByTaskQueue(taskQueue)`: Stop a specific worker
+- `registerWorker(workerDef)`: Dynamically register new workers at runtime
+- `getWorkerManager()`: Access worker manager service
+- `getConnection()`: Access native Temporal connection for custom worker creation
+- New interfaces: `WorkerDefinition`, `MultipleWorkersInfo`, `CreateWorkerResult`, `WorkerInstance`
+- Comprehensive migration guide in README for upgrading from single to multiple workers
+- Documentation for manual worker creation using native Temporal SDK
+
+### Changed
+- Refactored `TemporalWorkerManagerService` to support both legacy single worker and new multiple workers
+- Enhanced worker lifecycle management with per-worker state tracking
+- Improved worker initialization with better error handling
+- All interfaces consolidated in `src/interfaces.ts` (moved `WorkerInstance` from service file)
+
+### Fixed
+- No breaking changes - fully backward compatible with v3.0.11
+- Legacy single worker configuration continues to work without modifications
+
+## [3.0.11] - 2025-11-01
+
+### Fixed
+- Improved stability and error handling
+- Enhanced logging for better debugging
+
+## [3.0.10] - 2025-10-15
+
+### Added
+- Enhanced monitoring capabilities
+- Improved health check endpoints
+
+### Changed
+- Updated internal architecture for better performance
+
+## [3.0.0] - 2025-09-01
+
+### Added
+- Complete rewrite with modular architecture
+- Auto-discovery of activities via decorators
+- Enhanced monitoring and health checks
+- Comprehensive TypeScript support
+- Production-ready error handling
+
+### Changed
+- Breaking changes from v2.x - see migration guide
+
+## [2.x] - Historical Versions
+
+See previous releases for v2.x changelog.
+
+---
+
+## Migration Guide
+
+### Upgrading from 3.0.11 to 3.0.12
+
+No breaking changes. All existing code continues to work. See README.md for new multiple workers features.
+
+### Upgrading from 3.0.10 to 3.0.11
+
+No breaking changes. Minor improvements and bug fixes.
+
+### Upgrading from 2.x to 3.x
+
+Major rewrite - see full migration guide in documentation.

package/README.md

@@ -362,6 +362,136 @@ TemporalModule.register({
 })
 ```
 
+### Multiple Workers Configuration
+
+**New in 3.0.12**: Support for multiple workers with different task queues in the same process.
+
+```typescript
+TemporalModule.register({
+  connection: {
+    address: 'localhost:7233',
+    namespace: 'default',
+  },
+  workers: [
+    {
+      taskQueue: 'payments-queue',
+      workflowsPath: require.resolve('./workflows/payments'),
+      activityClasses: [PaymentActivity, RefundActivity],
+      autoStart: true,
+      workerOptions: {
+        maxConcurrentActivityTaskExecutions: 100,
+      },
+    },
+    {
+      taskQueue: 'notifications-queue',
+      workflowsPath: require.resolve('./workflows/notifications'),
+      activityClasses: [EmailActivity, SmsActivity],
+      autoStart: true,
+      workerOptions: {
+        maxConcurrentActivityTaskExecutions: 50,
+      },
+    },
+    {
+      taskQueue: 'background-jobs',
+      workflowsPath: require.resolve('./workflows/jobs'),
+      activityClasses: [DataProcessingActivity],
+      autoStart: false, // Start manually later
+    },
+  ],
+  logLevel: 'info',
+  enableLogger: true,
+})
+```
+
+#### Accessing Multiple Workers
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { TemporalService } from 'nestjs-temporal-core';
+
+@Injectable()
+export class WorkerManagementService {
+  constructor(private readonly temporal: TemporalService) {}
+
+  async checkWorkerStatus() {
+    // Get all workers info
+    const workersInfo = this.temporal.getAllWorkers();
+    console.log(`Total workers: ${workersInfo.totalWorkers}`);
+    console.log(`Running workers: ${workersInfo.runningWorkers}`);
+
+    // Get specific worker status
+    const paymentWorkerStatus = this.temporal.getWorkerStatusByTaskQueue('payments-queue');
+    if (paymentWorkerStatus?.isHealthy) {
+      console.log('Payment worker is healthy');
+    }
+  }
+
+  async controlWorkers() {
+    // Start a specific worker
+    await this.temporal.startWorkerByTaskQueue('background-jobs');
+
+    // Stop a specific worker
+    await this.temporal.stopWorkerByTaskQueue('notifications-queue');
+  }
+
+  async registerNewWorker() {
+    // Dynamically register a new worker at runtime
+    const result = await this.temporal.registerWorker({
+      taskQueue: 'new-queue',
+      workflowsPath: require.resolve('./workflows/new'),
+      activityClasses: [NewActivity],
+      autoStart: true,
+    });
+
+    if (result.success) {
+      console.log(`Worker registered for queue: ${result.taskQueue}`);
+    }
+  }
+}
+```
+
+### Manual Worker Creation (Advanced)
+
+For users who need full control, you can access the native Temporal connection to create custom workers:
+
+```typescript
+import { Injectable, OnModuleInit } from '@nestjs/common';
+import { TemporalService } from 'nestjs-temporal-core';
+import { Worker } from '@temporalio/worker';
+
+@Injectable()
+export class CustomWorkerService implements OnModuleInit {
+  private customWorker: Worker;
+
+  constructor(private readonly temporal: TemporalService) {}
+
+  async onModuleInit() {
+    const workerManager = this.temporal.getWorkerManager();
+    const connection = workerManager.getConnection();
+
+    if (!connection) {
+      throw new Error('No connection available');
+    }
+
+    // Create your custom worker using the native Temporal SDK
+    this.customWorker = await Worker.create({
+      connection,
+      taskQueue: 'custom-task-queue',
+      namespace: 'default',
+      workflowsPath: require.resolve('./workflows/custom'),
+      activities: {
+        myCustomActivity: async (data: string) => {
+          return `Processed: ${data}`;
+        },
+      },
+    });
+
+    // Start the worker
+    await this.customWorker.run();
+  }
+}
+```
+
 ### Async Configuration
 
 For dynamic configuration using environment variables or config services:
@@ -1425,6 +1555,208 @@ interface ServiceHealth {
 ```
 ```
 
+## Migration Guide
+
+### Migrating to v3.0.12+ (Multiple Workers Support)
+
+Version 3.0.12 introduces support for multiple workers without breaking existing single-worker configurations.
+
+#### No Changes Required for Single Worker
+
+If you're using a single worker, your existing configuration continues to work without any changes:
+
+```typescript
+// ✅ This still works exactly as before
+TemporalModule.register({
+  connection: { address: 'localhost:7233' },
+  taskQueue: 'my-queue',
+  worker: {
+    workflowsPath: require.resolve('./workflows'),
+    activityClasses: [MyActivity],
+  },
+})
+```
+
+#### Migrating to Multiple Workers
+
+**Before (v3.0.10):**
+```typescript
+// You had to create custom workers manually
+@Injectable()
+export class ScheduleService implements OnModuleInit {
+  private customWorker: Worker;
+
+  constructor(private temporal: TemporalService) {}
+
+  async onModuleInit() {
+    // This pattern required accessing internal APIs
+    const workerManager = this.temporal.getWorkerManager();
+    const connection = workerManager?.getConnection(); // This wasn't available!
+
+    // Manual worker creation...
+  }
+}
+```
+
+**After (v3.0.12):**
+```typescript
+// Option 1: Configure multiple workers in module
+TemporalModule.register({
+  connection: { address: 'localhost:7233' },
+  workers: [
+    {
+      taskQueue: 'main-queue',
+      workflowsPath: require.resolve('./workflows/main'),
+      activityClasses: [MainActivity],
+    },
+    {
+      taskQueue: 'schedule-queue',
+      workflowsPath: require.resolve('./workflows/schedule'),
+      activityClasses: [ScheduleActivity],
+    },
+  ],
+})
+
+// Option 2: Get native connection for manual worker creation
+@Injectable()
+export class CustomWorkerService implements OnModuleInit {
+  constructor(private temporal: TemporalService) {}
+
+  async onModuleInit() {
+    const workerManager = this.temporal.getWorkerManager();
+    const connection = workerManager.getConnection(); // Now available!
+
+    if (!connection) return;
+
+    const customWorker = await Worker.create({
+      connection, // Native NativeConnection object
+      taskQueue: 'custom-queue',
+      workflowsPath: require.resolve('./workflows/custom'),
+      activities: {
+        myActivity: async (data: string) => data,
+      },
+    });
+
+    await customWorker.run();
+  }
+}
+
+// Option 3: Register workers dynamically at runtime
+@Injectable()
+export class DynamicWorkerService {
+  constructor(private temporal: TemporalService) {}
+
+  async registerNewQueue(taskQueue: string) {
+    const result = await this.temporal.registerWorker({
+      taskQueue,
+      workflowsPath: require.resolve('./workflows/dynamic'),
+      activityClasses: [DynamicActivity],
+      autoStart: true,
+    });
+
+    if (result.success) {
+      console.log(`Worker registered for ${taskQueue}`);
+    }
+  }
+}
+```
+
+#### New APIs in v3.0.12
+
+```typescript
+// Get native connection for custom worker creation
+const workerManager = temporal.getWorkerManager();
+const connection: NativeConnection | null = workerManager.getConnection();
+
+// Get specific worker by task queue
+const worker: Worker | null = temporal.getWorker('payments-queue');
+
+// Get all workers information
+const workersInfo: MultipleWorkersInfo = temporal.getAllWorkers();
+console.log(`${workersInfo.runningWorkers}/${workersInfo.totalWorkers} workers running`);
+
+// Get specific worker status
+const status: WorkerStatus | null = temporal.getWorkerStatusByTaskQueue('payments-queue');
+
+// Control specific workers
+await temporal.startWorkerByTaskQueue('payments-queue');
+await temporal.stopWorkerByTaskQueue('notifications-queue');
+
+// Register new worker dynamically
+const result = await temporal.registerWorker({
+  taskQueue: 'new-queue',
+  workflowsPath: require.resolve('./workflows/new'),
+  activityClasses: [NewActivity],
+  autoStart: true,
+});
+```
+
+#### Breaking Changes from v3.0.10 to v3.0.11
+
+If you're upgrading from v3.0.10, note these changes:
+
+1. **Internal Architecture**: The internal connection management was refactored. If you were accessing private/internal APIs, those may have changed.
+
+2. **getConnection() Now Available**: In v3.0.10, accessing the native connection wasn't possible. This is now officially supported via `getWorkerManager().getConnection()`.
+
+3. **No API Removals**: All public APIs from v3.0.10 remain available in v3.0.11+.
+
+#### Best Practices for Multiple Workers
+
+```typescript
+// 1. Separate workers by domain/responsibility
+TemporalModule.register({
+  connection: { address: 'localhost:7233' },
+  workers: [
+    {
+      taskQueue: 'payments',        // Financial transactions
+      workflowsPath: require.resolve('./workflows/payments'),
+      activityClasses: [PaymentActivity, RefundActivity],
+      workerOptions: {
+        maxConcurrentActivityTaskExecutions: 50,
+      },
+    },
+    {
+      taskQueue: 'notifications',   // User notifications
+      workflowsPath: require.resolve('./workflows/notifications'),
+      activityClasses: [EmailActivity, SmsActivity],
+      workerOptions: {
+        maxConcurrentActivityTaskExecutions: 100,
+      },
+    },
+    {
+      taskQueue: 'background-jobs',  // Async background processing
+      workflowsPath: require.resolve('./workflows/jobs'),
+      activityClasses: [DataProcessingActivity],
+      autoStart: false, // Start only when needed
+    },
+  ],
+})
+
+// 2. Monitor worker health individually
+@Injectable()
+export class WorkerHealthService {
+  constructor(private temporal: TemporalService) {}
+
+  async checkAllWorkers() {
+    const allWorkers = this.temporal.getAllWorkers();
+    
+    for (const [taskQueue, status] of allWorkers.workers.entries()) {
+      if (!status.isHealthy) {
+        // Alert or restart unhealthy worker
+        await this.restartWorker(taskQueue);
+      }
+    }
+  }
+
+  private async restartWorker(taskQueue: string) {
+    await this.temporal.stopWorkerByTaskQueue(taskQueue);
+    await new Promise(resolve => setTimeout(resolve, 1000));
+    await this.temporal.startWorkerByTaskQueue(taskQueue);
+  }
+}
+```
+
 ## Troubleshooting
 
 ### Common Issues and Solutions

package/dist/interfaces.d.ts

@@ -20,6 +20,14 @@ export interface RetryPolicyConfig {
     maximumInterval: string;
     backoffCoefficient: number;
 }
+export interface WorkerDefinition {
+    taskQueue: string;
+    workflowsPath?: string;
+    workflowBundle?: Record<string, unknown>;
+    activityClasses?: Array<Type<object>>;
+    autoStart?: boolean;
+    workerOptions?: WorkerCreateOptions;
+}
 export interface TemporalOptions extends LoggerConfig {
     connection?: {
         address: string;
@@ -36,6 +44,7 @@ export interface TemporalOptions extends LoggerConfig {
         autoStart?: boolean;
         workerOptions?: WorkerCreateOptions;
     };
+    workers?: WorkerDefinition[];
     autoRestart?: boolean;
     isGlobal?: boolean;
     allowConnectionFailure?: boolean;
@@ -178,6 +187,30 @@ export interface WorkerStatus {
     startedAt?: Date;
     uptime?: number;
 }
+export interface MultipleWorkersInfo {
+    workers: Map<string, WorkerStatus>;
+    totalWorkers: number;
+    runningWorkers: number;
+    healthyWorkers: number;
+}
+export interface CreateWorkerResult {
+    success: boolean;
+    taskQueue: string;
+    error?: Error;
+    worker?: Worker;
+}
+export interface WorkerInstance {
+    worker: Worker;
+    taskQueue: string;
+    namespace: string;
+    isRunning: boolean;
+    isInitialized: boolean;
+    lastError: string | null;
+    startedAt: Date | null;
+    restartCount: number;
+    activities: Map<string, Function>;
+    workflowSource: 'bundle' | 'filesystem' | 'registered' | 'none';
+}
 export interface SignalMethodMetadata {
     signalName: string;
     methodName: string;

package/dist/services/temporal-worker.service.d.ts

@@ -1,6 +1,6 @@
 import { OnModuleInit, OnModuleDestroy, OnApplicationBootstrap } from '@nestjs/common';
-import { NativeConnection } from '@temporalio/worker';
-import { TemporalOptions, WorkerStatus, WorkerRestartResult, WorkerHealthStatus, WorkerStats, ActivityRegistrationResult } from '../interfaces';
+import { Worker, NativeConnection } from '@temporalio/worker';
+import { TemporalOptions, WorkerStatus, WorkerRestartResult, WorkerHealthStatus, WorkerStats, ActivityRegistrationResult, WorkerDefinition, MultipleWorkersInfo, CreateWorkerResult } from '../interfaces';
 import { TemporalDiscoveryService } from './temporal-discovery.service';
 export declare class TemporalWorkerManagerService implements OnModuleInit, OnModuleDestroy, OnApplicationBootstrap {
     private readonly discoveryService;
@@ -10,17 +10,30 @@ export declare class TemporalWorkerManagerService implements OnModuleInit, OnMod
     private worker;
     private restartCount;
     private readonly maxRestarts;
-    private connection;
     private isInitialized;
     private isRunning;
     private lastError;
     private startedAt;
     private readonly activities;
+    private readonly workers;
+    private connection;
     private shutdownPromise;
     constructor(discoveryService: TemporalDiscoveryService, options: TemporalOptions, injectedConnection: NativeConnection | null);
     onModuleInit(): Promise<void>;
     onApplicationBootstrap(): Promise<void>;
     onModuleDestroy(): Promise<void>;
+    private initializeMultipleWorkers;
+    private createWorkerFromDefinition;
+    registerWorker(workerDef: WorkerDefinition): Promise<CreateWorkerResult>;
+    getWorker(taskQueue: string): Worker | null;
+    getAllWorkers(): MultipleWorkersInfo;
+    getWorkerStatusByTaskQueue(taskQueue: string): WorkerStatus | null;
+    startWorkerByTaskQueue(taskQueue: string): Promise<void>;
+    stopWorkerByTaskQueue(taskQueue: string): Promise<void>;
+    getConnection(): NativeConnection | null;
+    private getWorkerStatusFromInstance;
+    private loadActivitiesForWorker;
+    private getWorkflowSourceFromDef;
     startWorker(): Promise<void>;
     private runWorkerWithAutoRestart;
     private autoRestartWorker;