nestjs-temporal-core 2.0.3 → 2.0.4

package/README.md

@@ -2,22 +2,22 @@
 
 A robust NestJS integration for [Temporal.io](https://temporal.io/) that provides seamless worker and client support for building reliable distributed applications.
 
+## Overview
+
+NestJS Temporal Core simplifies building fault-tolerant, long-running processes in your NestJS applications by integrating with Temporal.io - a durable execution system for reliable microservices and workflow orchestration.
+
 ## Features
 
-- 🚀 Easy integration with NestJS modules
-- 🔄 Automatic worker initialization and shutdown
-- 🎯 Declarative activity and workflow decorators
-- 🔌 Built-in connection management
-- 🛡️ Type-safe workflow execution
-- 📡 Simplified client operations
-- 🔒 TLS support for secure connections
-- 🎛️ Configurable runtime options
-- 🔄 Enhanced worker options customization
-- 📊 Worker status monitoring
-- 📅 Cron workflow scheduling
-- 🔍 Query handling support
-- 📣 Signal handling
-- 🚦 Workflow retry policies
+- 🚀 **Easy NestJS Integration** - Register modules with sync/async configuration
+- 🔄 **Complete Lifecycle Management** - Automatic worker initialization and graceful shutdown
+- 🎯 **Declarative Decorators** - Type-safe `@Activity()`, `@Workflow()`, `@Signal()`, and `@Query()` decorators
+- 🔌 **Connection Management** - Built-in connection handling with TLS support
+- 🔒 **Type Safety** - Strongly typed interfaces for all Temporal concepts
+- 📡 **Client Operation Utilities** - Methods for starting, signaling, querying and managing workflows
+- 📊 **Monitoring Support** - Worker status tracking and metrics
+- 📅 **Scheduling** - Native support for cron and interval-based workflow scheduling
+- 🔍 **Queries and Signals** - First-class support for Temporal's query and signal patterns
+- 🚦 **Advanced Policies** - Built-in retry, timeout, and workflow management policies
 
 ## Installation
 
@@ -33,54 +33,41 @@ First, make sure to enable shutdown hooks in your `main.ts` file:
 
 ```typescript
 async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-  app.enableShutdownHooks();
-  await app.listen(3000);
+    const app = await NestFactory.create(AppModule);
+    app.enableShutdownHooks();
+    await app.listen(3000);
 }
 bootstrap();
 ```
 
-### 2. Register the Module
+### 2. Register the Modules
 
 ```typescript
 import { Module } from '@nestjs/common';
 import { TemporalWorkerModule, TemporalClientModule } from 'nestjs-temporal-core';
 
 @Module({
-  imports: [
-    TemporalWorkerModule.register({
-      connection: {
-        address: 'localhost:7233',
-      },
-      namespace: 'default',
-      taskQueue: 'my-task-queue',
-      workflowsPath: require.resolve('./workflows'),
-      activityClasses: [MyActivity],
-      // Optional runtime configuration
-      runtimeOptions: {
-        // Add your runtime options here
-      },
-      // Optional worker configuration
-      workerOptions: {
-        // Add your worker options here
-      },
-      // Auto-start configuration
-      autoStart: {
-        enabled: true,
-        delayMs: 1000, // Start worker after 1 second
-      },
-      // Optional monitoring configuration
-      monitoring: {
-        statsIntervalMs: 60000, // Log stats every minute
-      },
-    }),
-    TemporalClientModule.register({
-      connection: {
-        address: 'localhost:7233',
-      },
-      namespace: 'default',
-    }),
-  ],
+    imports: [
+        TemporalWorkerModule.register({
+            connection: {
+                address: 'localhost:7233',
+            },
+            namespace: 'default',
+            taskQueue: 'my-task-queue',
+            workflowsPath: require.resolve('./workflows'),
+            activityClasses: [MyActivity],
+            autoStart: {
+                enabled: true,
+                delayMs: 1000, // Start worker after 1 second
+            },
+        }),
+        TemporalClientModule.register({
+            connection: {
+                address: 'localhost:7233',
+            },
+            namespace: 'default',
+        }),
+    ],
 })
 export class AppModule {}
 ```
@@ -91,26 +78,26 @@ export class AppModule {}
 import { Activity, ActivityMethod } from 'nestjs-temporal-core';
 
 @Activity({
-  name: 'PaymentActivities', // Optional custom name
-  description: 'Activities for payment processing',
+    name: 'PaymentActivities', // Optional custom name
+    description: 'Activities for payment processing',
 })
 export class PaymentActivity {
-  @ActivityMethod({
-    name: 'processPayment', // Optional custom name
-    timeout: {
-      startToClose: '30s',
-    },
-  })
-  async processPayment(amount: number): Promise<string> {
-    // Implementation
-    return 'payment-id';
-  }
-
-  @ActivityMethod()
-  async refundPayment(paymentId: string): Promise<boolean> {
-    // Implementation
-    return true;
-  }
+    @ActivityMethod({
+        name: 'processPayment', // Optional custom name
+        timeout: {
+            startToClose: '30s',
+        },
+    })
+    async processPayment(amount: number): Promise<string> {
+        // Implementation
+        return 'payment-id';
+    }
+
+    @ActivityMethod()
+    async refundPayment(paymentId: string): Promise<boolean> {
+        // Implementation
+        return true;
+    }
 }
 ```
 
@@ -120,16 +107,17 @@ export class PaymentActivity {
 import { proxyActivities } from '@temporalio/workflow';
 import type { PaymentActivity } from './payment.activity';
 
+// Reference activities in your workflow
 const { processPayment, refundPayment } = proxyActivities<PaymentActivity>({
-  startToCloseTimeout: '30 seconds',
+    startToCloseTimeout: '30 seconds',
 });
 
 export async function paymentWorkflow(amount: number): Promise<string> {
-  return await processPayment(amount);
+    return await processPayment(amount);
 }
 
 export async function refundWorkflow(paymentId: string): Promise<boolean> {
-  return await refundPayment(paymentId);
+    return await refundPayment(paymentId);
 }
 ```
 
@@ -141,37 +129,137 @@ import { TemporalClientService } from 'nestjs-temporal-core';
 
 @Injectable()
 export class PaymentService {
-  constructor(private readonly temporalClient: TemporalClientService) {}
-
-  async initiatePayment(amount: number) {
-    const { result, workflowId } = await this.temporalClient.startWorkflow<string, [number]>(
-      'paymentWorkflow',
-      [amount],
-      {
-        taskQueue: 'my-task-queue',
-        workflowExecutionTimeout: '1h',
-        workflowTaskTimeout: '10s',
-        retry: {
-          maximumAttempts: 3,
-        },
-      },
-    );
+    constructor(private readonly temporalClient: TemporalClientService) {}
+
+    async initiatePayment(amount: number) {
+        const { result, workflowId } = await this.temporalClient.startWorkflow<string, [number]>(
+            'paymentWorkflow',
+            [amount],
+            {
+                taskQueue: 'my-task-queue',
+                workflowExecutionTimeout: '1h',
+                workflowTaskTimeout: '10s',
+                retry: {
+                    maximumAttempts: 3,
+                },
+            },
+        );
+
+        // Wait for the workflow to complete
+        const paymentId = await result;
+
+        return { paymentId, workflowId };
+    }
+
+    async checkPaymentStatus(workflowId: string) {
+        // Query a running workflow
+        return await this.temporalClient.queryWorkflow<string>(workflowId, 'getPaymentStatus');
+    }
+
+    async cancelPayment(workflowId: string, reason: string) {
+        // Signal a running workflow
+        await this.temporalClient.signalWorkflow(workflowId, 'cancelPayment', [reason]);
+    }
+}
+```
 
-    // Wait for the workflow to complete
-    const paymentId = await result;
+## Advanced Features
 
-    return { paymentId, workflowId };
-  }
+### Class-Based Workflows with Queries and Signals
 
-  async checkPaymentStatus(workflowId: string) {
-    // Query a running workflow
-    return await this.temporalClient.queryWorkflow<string>(workflowId, 'getPaymentStatus');
-  }
+```typescript
+import { Workflow, WorkflowMethod, Query, Signal } from 'nestjs-temporal-core';
 
-  async cancelPayment(workflowId: string, reason: string) {
-    // Signal a running workflow
-    await this.temporalClient.signalWorkflow(workflowId, 'cancelPayment', [reason]);
-  }
+@Workflow({
+    taskQueue: 'order-queue',
+    workflowIdPrefix: 'order-',
+    workflowExecutionTimeout: '24h',
+})
+export class OrderWorkflow {
+    private orderStatus: string = 'PENDING';
+    private cancelReason: string | null = null;
+
+    @WorkflowMethod()
+    async execute(orderId: string): Promise<string> {
+        // Workflow implementation
+        return this.orderStatus;
+    }
+
+    @Query()
+    getStatus(): string {
+        return this.orderStatus;
+    }
+
+    @Signal()
+    cancel(reason: string): void {
+        this.orderStatus = 'CANCELLED';
+        this.cancelReason = reason;
+    }
+}
+```
+
+### Scheduled Workflows
+
+```typescript
+import { ScheduledWorkflow, WorkflowMethod } from 'nestjs-temporal-core';
+
+@ScheduledWorkflow({
+    taskQueue: 'scheduled-tasks',
+    schedule: {
+        cron: '0 0 * * *', // Run daily at midnight
+    },
+    description: 'Daily reporting workflow',
+})
+export class DailyReportWorkflow {
+    @WorkflowMethod()
+    async execute(): Promise<void> {
+        // Generate and send reports
+    }
+}
+```
+
+### Using the Schedule Service
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { TemporalScheduleService } from 'nestjs-temporal-core';
+
+@Injectable()
+export class ReportingService {
+    constructor(private readonly scheduleService: TemporalScheduleService) {}
+
+    async createDailyReportSchedule() {
+        return await this.scheduleService.createCronWorkflow(
+            'daily-sales-report',
+            'generateSalesReport',
+            '0 0 * * *', // Daily at midnight
+            'reports-queue',
+            [], // No arguments
+            'Daily sales report generation',
+        );
+    }
+
+    async createHourlyDataBackup() {
+        return await this.scheduleService.createIntervalWorkflow(
+            'hourly-data-backup',
+            'backupData',
+            { hours: 1 },
+            'backup-queue',
+            [],
+            'Hourly data backup process',
+        );
+    }
+
+    async pauseReports() {
+        await this.scheduleService.pauseSchedule(
+            'daily-sales-report',
+            'Paused for system maintenance',
+        );
+    }
+
+    async listAllSchedules() {
+        return await this.scheduleService.listSchedules();
+    }
 }
 ```
 
@@ -179,178 +267,164 @@ export class PaymentService {
 
 ### Async Configuration
 
+Use factory patterns for dynamic configuration:
+
 ```typescript
 TemporalWorkerModule.registerAsync({
-  imports: [ConfigModule],
-  useFactory: async (configService: ConfigService) => ({
-    connection: {
-      address: configService.get('TEMPORAL_ADDRESS'),
-      connectionTimeout: configService.get('TEMPORAL_CONNECTION_TIMEOUT', 5000),
-    },
-    namespace: configService.get('TEMPORAL_NAMESPACE'),
-    taskQueue: configService.get('TEMPORAL_TASK_QUEUE'),
-    workflowsPath: require.resolve('./workflows'),
-    activityClasses: [MyActivity],
-    autoStart: {
-      enabled: configService.get('TEMPORAL_WORKER_AUTOSTART', true),
-      delayMs: configService.get('TEMPORAL_WORKER_START_DELAY', 0),
-    },
-    allowWorkerFailure: configService.get('TEMPORAL_ALLOW_WORKER_FAILURE', true),
-  }),
-  inject: [ConfigService],
+    imports: [ConfigModule],
+    useFactory: async (configService: ConfigService) => ({
+        connection: {
+            address: configService.get('TEMPORAL_ADDRESS'),
+            connectionTimeout: configService.get('TEMPORAL_CONNECTION_TIMEOUT', 5000),
+        },
+        namespace: configService.get('TEMPORAL_NAMESPACE'),
+        taskQueue: configService.get('TEMPORAL_TASK_QUEUE'),
+        workflowsPath: require.resolve('./workflows'),
+        activityClasses: [MyActivity],
+        autoStart: {
+            enabled: configService.get('TEMPORAL_WORKER_AUTOSTART', true),
+            delayMs: configService.get('TEMPORAL_WORKER_START_DELAY', 0),
+        },
+        allowWorkerFailure: configService.get('TEMPORAL_ALLOW_WORKER_FAILURE', true),
+    }),
+    inject: [ConfigService],
 });
 ```
 
 ### TLS Configuration
 
+Set up secure communications with TLS:
+
 ```typescript
 TemporalClientModule.register({
-  connection: {
-    address: 'temporal.example.com:7233',
-    tls: {
-      clientCertPair: {
-        crt: Buffer.from('...'),
-        key: Buffer.from('...'),
-        ca: Buffer.from('...'), // Optional CA certificate
-      },
-      serverName: 'temporal.example.com', // Optional for SNI
-      verifyServer: true, // Optional, defaults to true
+    connection: {
+        address: 'temporal.example.com:7233',
+        tls: {
+            clientCertPair: {
+                crt: Buffer.from('...'),
+                key: Buffer.from('...'),
+                ca: Buffer.from('...'), // Optional CA certificate
+            },
+            serverName: 'temporal.example.com', // Optional for SNI
+            verifyServer: true, // Optional, defaults to true
+        },
+        connectionTimeout: 10000, // 10 seconds
+    },
+    namespace: 'production',
+    allowConnectionFailure: true, // Allow application to start if Temporal connection fails
+});
+```
+
+### Worker Monitoring
+
+Enable worker monitoring and metrics:
+
+```typescript
+TemporalWorkerModule.register({
+    // ... other options
+    monitoring: {
+        statsIntervalMs: 60000, // Log stats every minute
+        metrics: {
+            enabled: true,
+            prometheus: {
+                enabled: true,
+                port: 9464,
+            },
+        },
     },
-    connectionTimeout: 10000, // 10 seconds
-  },
-  namespace: 'production',
-  allowConnectionFailure: true, // Allow application to start if Temporal connection fails
 });
 ```
 
 ## API Reference
 
+### Core Modules
+
+- `TemporalClientModule` - Client connectivity for workflow operations
+- `TemporalWorkerModule` - Worker process for running activities
+- `TemporalScheduleModule` - Scheduling for recurring workflows
+
 ### Decorators
 
-- `@Activity(options?)`: Marks a class as a Temporal activity with optional configuration
-- `@ActivityMethod(options?)`: Marks a method as a Temporal activity implementation with optional configuration
-- `@Workflow(options)`: Marks a class as a Temporal workflow with configuration
+- `@Activity(options?)` - Marks a class as a Temporal activity
+- `@ActivityMethod(options?)` - Marks a method as an activity implementation
+- `@Workflow(options)` - Marks a class as a Temporal workflow
+- `@WorkflowMethod(options?)` - Marks the primary workflow execution method
+- `@Query(options?)` - Marks a method as a query handler
+- `@Signal(options?)` - Marks a method as a signal handler
+- `@ScheduledWorkflow(options)` - Defines a workflow with schedule configuration
 
 ### Services
 
 #### TemporalClientService
 
-- `startWorkflow<T, A>()`: Start a new workflow execution
-- `signalWorkflow()`: Send a signal to a running workflow
-- `queryWorkflow<T>()`: Query a running workflow
-- `terminateWorkflow()`: Terminate a running workflow
-- `cancelWorkflow()`: Request cancellation of a workflow
-- `getWorkflowHandle()`: Get a handle to manage a workflow
-- `getWorkflowClient()`: Get the underlying workflow client instance
+- `startWorkflow<T, A>()` - Start a new workflow execution
+- `signalWorkflow()` - Send a signal to a running workflow
+- `queryWorkflow<T>()` - Query a running workflow
+- `terminateWorkflow()` - Terminate a running workflow
+- `cancelWorkflow()` - Request cancellation of a workflow
+- `getWorkflowHandle()` - Get a handle to manage a workflow
+- `describeWorkflow()` - Get workflow execution details
+- `getWorkflowClient()` - Get the underlying workflow client
+
+#### TemporalScheduleService
+
+- `createCronWorkflow()` - Create a workflow scheduled by cron expression
+- `createIntervalWorkflow()` - Create a workflow scheduled by time interval
+- `pauseSchedule()` - Pause a schedule
+- `resumeSchedule()` - Resume a paused schedule
+- `deleteSchedule()` - Delete a schedule
+- `triggerNow()` - Trigger an immediate execution
+- `backfill()` - Run schedule actions for a past time range
+- `listSchedules()` - List all schedules
+- `describeSchedule()` - Get detailed schedule information
 
 #### WorkerManager
 
-- `startWorker()`: Manually start the worker if it's not running
-- `shutdown()`: Gracefully shutdown the worker
-- `getWorker()`: Get the underlying worker instance
-
-### Module Options
+- `startWorker()` - Manually start the worker
+- `shutdown()` - Gracefully shutdown the worker
+- `getWorker()` - Get the underlying worker instance
 
-#### TemporalWorkerOptions
+## Error Handling
 
-```typescript
-interface TemporalWorkerOptions {
-  connection: NativeConnectionOptions;
-  namespace: string;
-  taskQueue: string;
-  workflowsPath: string;
-  activityClasses?: Array<new (...args: any[]) => any>;
-  runtimeOptions?: RuntimeOptions;
-  workerOptions?: WorkerOptions;
-  autoStart?: {
-    enabled?: boolean;
-    delayMs?: number;
-  };
-  allowWorkerFailure?: boolean;
-  monitoring?: {
-    statsIntervalMs?: number;
-    metrics?: {
-      enabled?: boolean;
-      prometheus?: {
-        enabled?: boolean;
-        port?: number;
-      };
-    };
-  };
-}
-```
+The module includes comprehensive error handling:
 
-#### TemporalClientOptions
+- Worker initialization errors are logged and handled based on configuration
+- Client operations include detailed error messages and proper error propagation
+- Activities and workflow errors are properly captured and logged
+- Connection errors are handled gracefully with automatic cleanup
+- Configurable failure modes for both client and worker connections
 
-```typescript
-interface TemporalClientOptions {
-  connection: ConnectionOptions;
-  namespace?: string;
-  allowConnectionFailure?: boolean;
-  reconnect?: {
-    enabled?: boolean;
-    maxAttempts?: number;
-    initialDelayMs?: number;
-    maxDelayMs?: number;
-    backoffCoefficient?: number;
-  };
-}
-```
+## Best Practices
 
-### Activity Method Options
+1. **Activity Design**
 
-```typescript
-interface ActivityMethodOptions {
-  name?: string;
-  description?: string;
-  timeout?: {
-    startToClose?: string | number;
-    scheduleToStart?: string | number;
-  };
-}
-```
+    - Define activity interfaces for type safety
+    - Keep activities focused on single responsibilities
+    - Set appropriate timeouts for expected durations
 
-### Workflow Options
+2. **Workflow Design**
 
-```typescript
-interface TemporalWorkflowDecoratorOptions {
-  name?: string;
-  description?: string;
-  taskQueue: string;
-  workflowIdPrefix?: string;
-  executionTimeout?: string;
-  workflowTaskTimeout?: string;
-  retry?: {
-    maximumAttempts?: number;
-    initialInterval?: number;
-    maximumInterval?: number;
-    backoffCoefficient?: number;
-  };
-}
-```
+    - Make workflows deterministic
+    - Use signals for external events
+    - Use queries for retrieving workflow state
+    - Avoid side effects in workflow code
 
-## Error Handling
+3. **Configuration**
 
-The module includes comprehensive error handling:
+    - Use meaningful workflow IDs for tracking
+    - Configure appropriate timeouts for activities and workflows
+    - Use retry policies for transient failures
+    - Set up monitoring for production deployments
 
-- Worker initialization errors are logged and can prevent application startup if critical
-- Client operations include detailed error messages and proper error propagation
-- Activity and workflow errors are properly captured and logged
-- Connection errors are handled gracefully with automatic cleanup
-- Configurable failure modes for both client and worker connections
+4. **Lifecycle Management**
 
-## Best Practices
+    - Enable NestJS shutdown hooks
+    - Configure proper worker shutdown grace periods
+    - Use the WorkerManager service for controlling worker lifecycle
 
-1. Always define activity interfaces for type safety
-2. Use meaningful workflow IDs for tracking
-3. Implement proper error handling in activities
-4. Set appropriate timeouts for activities and workflows
-5. Use signals for long-running workflow coordination
-6. Monitor worker status using the WorkerManager service
-7. Configure appropriate runtime and worker options for production deployments
-8. Implement proper TLS security for production environments
-9. Use workflow queries for reading workflow state without side effects
-10. Configure graceful shutdown for workers to prevent activity interruptions
+5. **Security**
+    - Implement proper TLS security for production environments
+    - Use namespaces to isolate different environments
 
 ## Contributing
 

package/dist/client/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2DAAyC;AACzC,4DAA0C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAGA,2DAAyC;AACzC,4DAA0C"}