nestjs-temporal-core 2.0.5 → 2.0.7

package/README.md

@@ -1,25 +1,21 @@
 # NestJS Temporal Core
 
-A robust NestJS integration for [Temporal.io](https://temporal.io/) that provides seamless worker and client support for building reliable distributed applications.
+A simplified 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.
+NestJS Temporal Core makes it easy to integrate Temporal.io with your NestJS applications. Temporal is a durable execution system for reliable microservices and workflow orchestration.
 
 ## Features
 
-- 🚀 **Easy NestJS Integration** - Register modules with sync/async configuration
+- 🚀 **Easy NestJS Integration** - Simple module registration with unified configuration
 - 🔄 **Complete Lifecycle Management** - Automatic worker initialization and graceful shutdown
-- 🎯 **Declarative Decorators** - Type-safe `@Activity()`, `@Workflow()`, `@Signal()`, `@Query()`, and `@Update()` 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, updating 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
-- 🆕 **Updates** - Support for Temporal's workflow update functionality
-- 🔢 **Versioning** - Support for Temporal worker versioning
-- 🚦 **Advanced Policies** - Built-in retry, timeout, and workflow management policies
+- 🎯 **Declarative Decorators** - Type-safe `@Activity()`, `@ActivityMethod()`, `@Workflow()`, and more
+- 🔌 **Connection Management** - Simplified connection handling with TLS support
+- 🔒 **Type Safety** - Clean, strongly typed interfaces for all Temporal concepts
+- 📡 **Client Utilities** - Methods for starting, signaling, and querying workflows
+- 📊 **Worker Management** - Simple worker lifecycle control and monitoring
+- 📅 **Scheduling** - Support for cron and interval-based workflow scheduling
 
 ## Installation
 
@@ -42,32 +38,27 @@ async function bootstrap() {
 bootstrap();
 ```
 
-### 2. Register the Modules
+### 2. Register the Module
 
 ```typescript
 import { Module } from '@nestjs/common';
-import { TemporalWorkerModule, TemporalClientModule } from 'nestjs-temporal-core';
+import { TemporalModule } from 'nestjs-temporal-core';
+import { EmailActivities } from './activities/email.activities';
 
 @Module({
     imports: [
-        TemporalWorkerModule.register({
+        TemporalModule.register({
             connection: {
                 address: 'localhost:7233',
+                namespace: 'default',
             },
-            namespace: 'default',
             taskQueue: 'my-task-queue',
-            workflowsPath: require.resolve('./workflows'),
-            activityClasses: [MyActivity],
-            autoStart: {
-                enabled: true,
-                delayMs: 1000, // Start worker after 1 second
+            worker: {
+                workflowsPath: './dist/workflows',
+                activityClasses: [EmailActivities],
+                autoStart: true,
             },
-        }),
-        TemporalClientModule.register({
-            connection: {
-                address: 'localhost:7233',
-            },
-            namespace: 'default',
+            isGlobal: true,
         }),
     ],
 })
@@ -79,25 +70,19 @@ export class AppModule {}
 ```typescript
 import { Activity, ActivityMethod } from 'nestjs-temporal-core';
 
-@Activity({
-    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> {
+@Activity()
+export class EmailActivities {
+    @ActivityMethod()
+    async sendWelcomeEmail(to: string): Promise<boolean> {
         // Implementation
-        return 'payment-id';
+        console.log(`Sending welcome email to ${to}`);
+        return true;
     }
 
-    @ActivityMethod()
-    async refundPayment(paymentId: string): Promise<boolean> {
+    @ActivityMethod('sendPromoEmail')
+    async sendPromotion(to: string, promoCode: string): Promise<boolean> {
         // Implementation
+        console.log(`Sending promo ${promoCode} to ${to}`);
         return true;
     }
 }
@@ -105,329 +90,201 @@ export class PaymentActivity {
 
 ### 4. Define Workflows
 
+Create a workflow file in your workflows directory:
+
 ```typescript
+// workflows/email-workflow.ts
 import { proxyActivities } from '@temporalio/workflow';
-import type { PaymentActivity } from './payment.activity';
 
-// Reference activities in your workflow
-const { processPayment, refundPayment } = proxyActivities<PaymentActivity>({
-    startToCloseTimeout: '30 seconds',
+// Activities interface
+interface EmailActivities {
+    sendWelcomeEmail(to: string): Promise<boolean>;
+    sendPromoEmail(to: string, promoCode: string): Promise<boolean>;
+}
+
+const activities = proxyActivities<EmailActivities>({
+    startToCloseTimeout: '30s',
 });
 
-export async function paymentWorkflow(amount: number): Promise<string> {
-    return await processPayment(amount);
+export async function sendWelcomeWorkflow(email: string): Promise<boolean> {
+    return await activities.sendWelcomeEmail(email);
 }
 
-export async function refundWorkflow(paymentId: string): Promise<boolean> {
-    return await refundPayment(paymentId);
+export async function sendPromoWorkflow(email: string, promoCode: string): Promise<boolean> {
+    return await activities.sendPromoEmail(email, promoCode);
 }
 ```
 
-### 5. Use the Client Service
+### 5. Use the Temporal Service
 
 ```typescript
 import { Injectable } from '@nestjs/common';
-import { TemporalClientService } from 'nestjs-temporal-core';
+import { TemporalService } 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],
+export class EmailService {
+    constructor(private readonly temporalService: TemporalService) {}
+
+    async sendWelcomeEmail(email: string): Promise<string> {
+        // Use the simplified API to start a workflow
+        const { workflowId } = await this.temporalService.startWorkflow(
+            'sendWelcomeWorkflow',
+            [email],
+            'my-task-queue',
             {
-                taskQueue: 'my-task-queue',
-                workflowExecutionTimeout: '1h',
-                workflowTaskTimeout: '10s',
-                retry: {
-                    maximumAttempts: 3,
-                },
+                workflowId: `welcome-${email}-${Date.now()}`,
             },
         );
 
-        // Wait for the workflow to complete
-        const paymentId = await result;
-
-        return { paymentId, workflowId };
+        return workflowId;
     }
 
-    async checkPaymentStatus(workflowId: string) {
-        // Query a running workflow
-        return await this.temporalClient.queryWorkflow<string>(workflowId, 'getPaymentStatus');
-    }
+    async sendPromoEmail(email: string, promoCode: string): Promise<string> {
+        // Use the client service directly for more options
+        const { workflowId } = await this.temporalService
+            .getClient()
+            .startWorkflow('sendPromoWorkflow', [email, promoCode], {
+                taskQueue: 'my-task-queue',
+                workflowId: `promo-${email}-${Date.now()}`,
+                retry: {
+                    maximumAttempts: 3,
+                },
+            });
 
-    async cancelPayment(workflowId: string, reason: string) {
-        // Signal a running workflow
-        await this.temporalClient.signalWorkflow(workflowId, 'cancelPayment', [reason]);
+        return workflowId;
     }
 }
 ```
 
 ## Advanced Features
 
-### Class-Based Workflows with Queries, Signals, and Updates
+### Using Signals and Queries
 
 ```typescript
-import { Workflow, WorkflowMethod, Query, Signal, Update } from 'nestjs-temporal-core';
-
-@Workflow({
-    taskQueue: 'order-queue',
-    workflowExecutionTimeout: '24h',
-})
-export class OrderWorkflow {
-    private orderStatus: string = 'PENDING';
-    private orderItems: string[] = [];
-    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;
-    }
-
-    @Update({
-        validator: (items: string[]) => {
-            if (items.length === 0) {
-                throw new Error('Order must contain at least one item');
-            }
-        },
-    })
-    updateItems(items: string[]): string[] {
-        this.orderItems = items;
-        return this.orderItems;
-    }
-}
-```
-
-### Scheduled Workflows
+import { Injectable } from '@nestjs/common';
+import { TemporalService } from 'nestjs-temporal-core';
 
-```typescript
-import { ScheduledWorkflow, WorkflowMethod } from 'nestjs-temporal-core';
+@Injectable()
+export class OrderService {
+    constructor(private readonly temporalService: TemporalService) {}
 
-@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
+    async addItemToOrder(orderId: string, item: string): Promise<void> {
+        // Signal a running workflow
+        await this.temporalService.getClient().signalWorkflow(orderId, 'addItem', [item]);
     }
-}
 
-@ScheduledWorkflow({
-    taskQueue: 'scheduled-tasks',
-    schedule: {
-        interval: {
-            hours: 1, // Run every hour
-        },
-    },
-    description: 'Hourly data processing',
-})
-export class HourlyProcessingWorkflow {
-    @WorkflowMethod()
-    async execute(): Promise<void> {
-        // Process data hourly
+    async getOrderStatus(orderId: string): Promise<string> {
+        // Query a running workflow
+        return await this.temporalService.getClient().queryWorkflow(orderId, 'getStatus');
     }
 }
 ```
 
-### Using the Schedule Service
+### Schedule Management
 
 ```typescript
 import { Injectable } from '@nestjs/common';
-import { TemporalScheduleService } from 'nestjs-temporal-core';
+import { TemporalService } from 'nestjs-temporal-core';
 
 @Injectable()
 export class ReportingService {
-    constructor(private readonly scheduleService: TemporalScheduleService) {}
+    constructor(private readonly temporalService: TemporalService) {}
 
-    async createDailyReportSchedule() {
-        return await this.scheduleService.createCronWorkflow(
-            'daily-sales-report',
-            'generateSalesReport',
+    async scheduleDailyReport(): Promise<string> {
+        const handle = await this.temporalService.getScheduleService().createCronWorkflow(
+            'daily-report',
+            'generateReportWorkflow',
             '0 0 * * *', // Daily at midnight
             'reports-queue',
-            [], // No arguments
-            'Daily sales report generation',
+            ['daily-summary'],
         );
-    }
 
-    async createHourlyDataBackup() {
-        return await this.scheduleService.createIntervalWorkflow(
-            'hourly-data-backup',
-            'backupData',
-            { hours: 1 },
-            'backup-queue',
-            [],
-            'Hourly data backup process',
-        );
+        return handle.scheduleId;
     }
 
-    async pauseReports() {
-        await this.scheduleService.pauseSchedule(
-            'daily-sales-report',
-            'Paused for system maintenance',
-        );
+    async pauseReporting(): Promise<void> {
+        await this.temporalService
+            .getScheduleService()
+            .pauseSchedule('daily-report', 'Paused for maintenance');
     }
 
-    async listAllSchedules() {
-        return await this.scheduleService.listSchedules();
+    async resumeReporting(): Promise<void> {
+        await this.temporalService.getScheduleService().resumeSchedule('daily-report');
     }
 }
 ```
 
-### Using Workflow Updates
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { TemporalClientService } from 'nestjs-temporal-core';
-
-@Injectable()
-export class OrderService {
-    constructor(private readonly temporalClient: TemporalClientService) {}
-
-    async updateOrderItems(orderId: string, items: string[]) {
-        try {
-            // Use the updateWorkflow method to modify a running workflow
-            const updatedItems = await this.temporalClient.updateWorkflow<string[]>(
-                `order-${orderId}`,
-                'updateItems',
-                [items],
-            );
-
-            return { success: true, items: updatedItems };
-        } catch (error) {
-            return { success: false, error: error.message };
-        }
-    }
-}
-```
-
-## Advanced Configuration
+## Configuration Options
 
 ### 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],
-});
-```
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { TemporalModule } from 'nestjs-temporal-core';
+import { EmailActivities } from './activities/email.activities';
 
-### TLS Configuration
+@Module({
+    imports: [
+        ConfigModule.forRoot(),
+        TemporalModule.registerAsync({
+            imports: [ConfigModule],
+            inject: [ConfigService],
+            useFactory: (configService: ConfigService) => ({
+                connection: {
+                    address: configService.get('TEMPORAL_ADDRESS'),
+                    namespace: configService.get('TEMPORAL_NAMESPACE'),
+                    apiKey: configService.get('TEMPORAL_API_KEY'),
+                },
+                taskQueue: configService.get('TEMPORAL_TASK_QUEUE'),
+                worker: {
+                    workflowsPath: './dist/workflows',
+                    activityClasses: [EmailActivities],
+                },
+
+                isGlobal: true,
+            }),
+        }),
+    ],
+})
+export class AppModule {}
+```
 
-Set up secure communications with TLS:
+### Secure Connection with TLS
 
 ```typescript
-TemporalClientModule.register({
+TemporalModule.register({
     connection: {
         address: 'temporal.example.com:7233',
+        namespace: 'production',
         tls: {
+            // Simple boolean for default TLS
+            // tls: true,
+
+            // Or detailed configuration
+            serverName: 'temporal.example.com',
             clientCertPair: {
-                crt: Buffer.from('...'),
-                key: Buffer.from('...'),
-                ca: Buffer.from('...'), // Optional CA certificate
+                crt: fs.readFileSync('./certs/client.crt'),
+                key: fs.readFileSync('./certs/client.key'),
+                ca: fs.readFileSync('./certs/ca.crt'),
             },
-            serverName: 'temporal.example.com', // Optional for SNI
-            verifyServer: true, // Optional, defaults to true
         },
-        connectionTimeout: 10000, // 10 seconds
+        // For Temporal Cloud
+        apiKey: process.env.TEMPORAL_API_KEY,
     },
-    namespace: 'production',
-    allowConnectionFailure: true, // Allow application to start if Temporal connection fails
-});
-```
-
-### Worker Versioning
-
-Enable worker versioning for compatibility management:
-
-```typescript
-TemporalWorkerModule.register({
-    // ... other options
-    useVersioning: true,
-    buildId: 'v1.2.3-20230615', // Unique identifier for this worker's code version
-});
-```
-
-### Worker Performance Tuning
-
-Optimize worker performance with advanced options:
-
-```typescript
-TemporalWorkerModule.register({
-    // ... other options
-    reuseV8Context: true, // Significantly improves performance and reduces memory usage
-    maxConcurrentWorkflowTaskExecutions: 40,
-    maxConcurrentActivityTaskExecutions: 100,
-    maxConcurrentLocalActivityExecutions: 100,
-    workflowThreadPoolSize: 4,
-    maxActivitiesPerSecond: 50,
-    maxCachedWorkflows: 200,
+    // ...other options
 });
 ```
 
-### 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,
-            },
-        },
-    },
-});
 ```
 
 ## API Reference
 
 ### Core Modules
 
-- `TemporalClientModule` - Client connectivity for workflow operations
-- `TemporalWorkerModule` - Worker process for running activities and workflows
-- `TemporalScheduleModule` - Scheduling for recurring workflows
+- `TemporalModule` - Unified module for both client and worker functionality
+- `TemporalClientModule` - Client-only module for workflow operations
+- `TemporalWorkerModule` - Worker-only module for running activities
 
 ### Decorators
 
@@ -435,33 +292,35 @@ TemporalWorkerModule.register({
 - `@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
-- `@Update(options?)` - Marks a method as an update handler
-- `@ScheduledWorkflow(options)` - Defines a workflow with schedule configuration
+- `@SignalMethod(name?)` - Marks a method as a signal handler
+- `@QueryMethod(name?)` - Marks a method as a query handler
 
 ### Services
 
+#### TemporalService
+
+- `getClient()` - Get the client service
+- `getScheduleService()` - Get the schedule service
+- `getWorkerManager()` - Get the worker manager (if available)
+- `startWorkflow()` - Simplified method to start a workflow
+- `hasWorker()` - Check if worker functionality is available
+
+
 #### TemporalClientService
 
-- `startWorkflow<T, A>()` - Start a new workflow execution
+- `startWorkflow()` - Start a new workflow execution
 - `signalWorkflow()` - Send a signal to a running workflow
-- `queryWorkflow<T>()` - Query a running workflow
-- `updateWorkflow<T>()` - Update a running workflow
+- `queryWorkflow()` - 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
 - `listWorkflows()` - List workflows matching a query
-- `countWorkflows()` - Count workflows matching a query
-- `getWorkflowClient()` - Get the underlying workflow client
-- `getRawClient()` - Get the raw Temporal client
 
 #### TemporalScheduleService
 
 - `createCronWorkflow()` - Create a workflow scheduled by cron expression
 - `createIntervalWorkflow()` - Create a workflow scheduled by time interval
-- `getSchedule()` - Get a handle to an existing schedule
 - `pauseSchedule()` - Pause a schedule
 - `resumeSchedule()` - Resume a paused schedule
 - `deleteSchedule()` - Delete a schedule
@@ -474,64 +333,314 @@ TemporalWorkerModule.register({
 - `shutdown()` - Gracefully shutdown the worker
 - `getWorker()` - Get the underlying worker instance
 
-## Error Handling
+## Project Structure
+
+When integrating Temporal with your NestJS application, organizing your code properly helps maintain separation of concerns and follows NestJS conventions. Here's a recommended project structure:
+
+```
+
+src/
+├── temporal/
+│ ├── activities/
+│ │ ├── email.activities.ts
+│ │ ├── payment.activities.ts
+│ │ └── index.ts
+│ ├── workflows/
+│ │ ├── email-workflows.ts
+│ │ ├── payment-workflows.ts
+│ │ └── index.ts
+│ ├── interfaces/
+│ │ ├── email.interfaces.ts
+│ │ └── payment.interfaces.ts
+│ └── temporal.module.ts
+├── modules/
+│ ├── email/
+│ │ ├── email.service.ts
+│ │ ├── email.controller.ts
+│ │ └── email.module.ts
+│ └── payment/
+│ ├── payment.service.ts
+│ ├── payment.controller.ts
+│ └── payment.module.ts
+└── app.module.ts
+
+````
+
+### Key Files and Their Purpose
+
+1. **Activities (src/temporal/activities/)**:
+   - Contains activity classes decorated with `@Activity()`
+   - Each activity class should group related functionality
+
+2. **Workflows (src/temporal/workflows/)**:
+   - Contains workflow definitions that orchestrate activities
+   - Workflows should be in separate files based on domain
+
+3. **Interfaces (src/temporal/interfaces/)**:
+   - TypeScript interfaces that define activity and workflow parameters/returns
+   - Helps maintain type safety between activities and workflows
+
+4. **Temporal Module (src/temporal/temporal.module.ts)**:
+   - Centralizes Temporal configuration
+   - Imports and registers all activities
+
+5. **Business Services (src/modules/*/)**:
+   - Inject the TemporalService
+   - Use it to start workflows and interact with Temporal
+
+## Integration Examples
+
+### Activity Definition
+
+```typescript
+// src/temporal/activities/email.activities.ts
+import { Activity, ActivityMethod } from 'nestjs-temporal-core';
+import { Injectable } from '@nestjs/common';
+import { EmailService } from '../../modules/email/email.service';
+
+@Injectable()
+@Activity()
+export class EmailActivities {
+  constructor(private readonly emailService: EmailService) {}
+
+  @ActivityMethod()
+  async sendWelcomeEmail(to: string, name: string): Promise<boolean> {
+    await this.emailService.sendEmail({
+      to,
+      subject: 'Welcome!',
+      body: `Hello ${name}, welcome to our platform!`,
+    });
+    return true;
+  }
+
+  @ActivityMethod()
+  async sendPasswordReset(to: string, resetToken: string): Promise<boolean> {
+    await this.emailService.sendEmail({
+      to,
+      subject: 'Password Reset',
+      body: `Please use this token to reset your password: ${resetToken}`,
+    });
+    return true;
+  }
+}
+````
+
+```typescript
+// src/temporal/activities/index.ts
+export * from './email.activities';
+export * from './payment.activities';
+// Export all other activity classes
+```
+
+### Workflow Definition
+
+```typescript
+// src/temporal/workflows/email-workflows.ts
+import { proxyActivities } from '@temporalio/workflow';
+
+// Define the interface of activities this workflow will use
+export interface EmailActivities {
+    sendWelcomeEmail(to: string, name: string): Promise<boolean>;
+    sendPasswordReset(to: string, resetToken: string): Promise<boolean>;
+}
+
+// Create a proxy to the activities
+const activities = proxyActivities<EmailActivities>({
+    startToCloseTimeout: '30 seconds',
+});
 
-The module includes comprehensive error handling:
+// Welcome workflow with retry logic
+export async function welcomeUserWorkflow(email: string, name: string): Promise<boolean> {
+    let attempts = 0;
+    const maxAttempts = 3;
+
+    while (attempts < maxAttempts) {
+        try {
+            return await activities.sendWelcomeEmail(email, name);
+        } catch (error) {
+            attempts++;
+            if (attempts >= maxAttempts) {
+                throw error;
+            }
+            // Wait before retrying
+            await new Promise((resolve) => setTimeout(resolve, 5000));
+        }
+    }
 
-- 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
-- SDK version compatibility checks for feature availability
+    return false;
+}
+
+// Password reset workflow
+export async function passwordResetWorkflow(email: string, resetToken: string): Promise<boolean> {
+    return await activities.sendPasswordReset(email, resetToken);
+}
+```
+
+### Scheduled Workflow Example
+
+```typescript
+// src/temporal/workflows/scheduled-workflows.ts
+import { proxyActivities } from '@temporalio/workflow';
+
+interface ReportActivities {
+    generateDailyReport(): Promise<string>;
+    emailReportToAdmins(reportUrl: string): Promise<boolean>;
+}
+
+const activities = proxyActivities<ReportActivities>({
+    startToCloseTimeout: '10 minutes',
+});
+
+// This workflow will be scheduled to run daily
+export async function dailyReportWorkflow(): Promise<void> {
+    const reportUrl = await activities.generateDailyReport();
+    await activities.emailReportToAdmins(reportUrl);
+}
+```
+
+### Setting Up the Temporal Module
+
+```typescript
+// src/temporal/temporal.module.ts
+import { Module } from '@nestjs/common';
+import { TemporalModule } from 'nestjs-temporal-core';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import * as path from 'path';
+import { EmailActivities, PaymentActivities } from './activities';
+import { EmailModule } from '../modules/email/email.module';
+import { PaymentModule } from '../modules/payment/payment.module';
+
+@Module({
+    imports: [
+        EmailModule,
+        PaymentModule,
+        TemporalModule.registerAsync({
+            imports: [ConfigModule],
+            inject: [ConfigService],
+            useFactory: (configService: ConfigService) => ({
+                connection: {
+                    address: configService.get('TEMPORAL_ADDRESS', 'localhost:7233'),
+                    namespace: configService.get('TEMPORAL_NAMESPACE', 'default'),
+                },
+                taskQueue: configService.get('TEMPORAL_TASK_QUEUE', 'my-app-queue'),
+                worker: {
+                    workflowsPath: path.resolve(__dirname, 'workflows'),
+                    activityClasses: [EmailActivities, PaymentActivities],
+                    autoStart: true,
+                },
+                isGlobal: true,
+            }),
+        }),
+    ],
+    providers: [EmailActivities, PaymentActivities],
+    exports: [TemporalModule],
+})
+export class TemporalAppModule {}
+```
+
+### Using Temporal in Business Services
+
+```typescript
+// src/modules/email/email.service.ts
+import { Injectable } from '@nestjs/common';
+import { TemporalService } from 'nestjs-temporal-core';
+
+@Injectable()
+export class EmailService {
+    constructor(private readonly temporalService: TemporalService) {}
+
+    // Your actual email sending functionality
+    async sendEmail(options: { to: string; subject: string; body: string }): Promise<void> {
+        // Implementation...
+    }
+
+    // Triggering a Temporal workflow
+    async sendWelcomeEmail(email: string, name: string): Promise<string> {
+        const { workflowId } = await this.temporalService.startWorkflow(
+            'welcomeUserWorkflow',
+            [email, name],
+            'my-app-queue',
+            { workflowId: `welcome-${email}-${Date.now()}` },
+        );
+
+        return workflowId;
+    }
+}
+```
+
+### Setting Up Scheduled Workflows
+
+```typescript
+// src/modules/reports/report.service.ts
+import { Injectable, OnModuleInit } from '@nestjs/common';
+import { TemporalService } from 'nestjs-temporal-core';
+
+@Injectable()
+export class ReportService implements OnModuleInit {
+    constructor(private readonly temporalService: TemporalService) {}
+
+    async onModuleInit() {
+        // Set up scheduled workflows when the module initializes
+        await this.setupDailyReport();
+    }
+
+    private async setupDailyReport() {
+        try {
+            // Check if the schedule already exists
+            const schedules = await this.temporalService.getScheduleService().listSchedules();
+
+            if (!schedules.some((s) => s.scheduleId === 'daily-report')) {
+                // Create a new schedule
+                await this.temporalService.getScheduleService().createCronWorkflow(
+                    'daily-report',
+                    'dailyReportWorkflow',
+                    '0 8 * * *', // Run every day at 8 AM
+                    'my-app-queue',
+                    [], // No arguments needed for this workflow
+                    'Daily business report generation',
+                );
+
+                console.log('Daily report schedule created');
+            }
+        } catch (error) {
+            console.error('Failed to set up daily report schedule:', error);
+        }
+    }
+}
+```
 
 ## Best Practices
 
 1. **Activity Design**
 
-    - Define activity interfaces for type safety
     - Keep activities focused on single responsibilities
     - Set appropriate timeouts for expected durations
-    - Use heartbeats for long-running activities
+    - Use dependency injection within activity classes
 
 2. **Workflow Design**
 
     - Make workflows deterministic
     - Use signals for external events
     - Use queries for retrieving workflow state
-    - Use updates for synchronous modifications
-    - Avoid side effects in workflow code
+    - Separate workflows by domain/function
 
 3. **Configuration**
 
     - 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
-    - Enable worker versioning in production
-
-4. **Performance Optimization**
+    - Implement proper error handling
 
-    - Enable V8 context reuse for better performance
-    - Configure appropriate concurrency settings
-    - Use caching for frequently accessed workflows
-    - Balance worker thread pool size
-
-5. **Lifecycle Management**
+4. **Lifecycle Management**
 
     - Enable NestJS shutdown hooks
     - Configure proper worker shutdown grace periods
-    - Use the WorkerManager service for controlling worker lifecycle
+    - Consider using OnModuleInit to set up schedules
 
-6. **Security**
+5. **Security**
     - Implement proper TLS security for production environments
     - Use namespaces to isolate different environments
     - Use API keys for Temporal Cloud authentication
 
-## Contributing
-
-Contributions are welcome! Please see our [contributing guidelines](CONTRIBUTING.md) for details.
-
 ## License
 
 MIT