NestJS Temporal Core

---

Table of Contents

- Overview
- Features
- Installation
- Quick Start
- Module Variants
- Configuration
- Basic Configuration
- Multiple Workers
- Async Configuration
- TLS Configuration
- Core Concepts
- Activities
- Workflows
- Signals and Queries
- API Reference
- Examples
- Advanced Usage
- Best Practices
- Health Monitoring
- Troubleshooting
- Migration Guide
- Contributing
- License

Overview

NestJS Temporal Core bridges NestJS's powerful dependency injection system with Temporal.io's robust workflow orchestration engine. It provides a declarative approach to building distributed, fault-tolerant applications with automatic service discovery, enterprise-grade monitoring, and seamless integration.

$3

| Feature | Description |
|---------|-------------|
| Seamless Integration | Native NestJS decorators and dependency injection support |
| Auto-Discovery | Automatic registration of activities and workflows via decorators |
| Type Safety | Full TypeScript support with comprehensive type definitions |
| Enterprise Ready | Built-in health checks, monitoring, and error handling |
| Zero Configuration | Smart defaults with extensive customization options |
| Modular Architecture | Use client-only, worker-only, or full-stack configurations |
| Production Grade | Connection pooling, graceful shutdown, and fault tolerance |

Features

$3

- Declarative Decorators - Use @Activity() and @ActivityMethod() for clean, intuitive activity definitions
- Automatic Discovery - Runtime discovery and registration of activities with zero configuration
- Schedule Management - Programmatic schedule creation, updates, and monitoring
- Health Monitoring - Built-in health checks and comprehensive status reporting

$3

- Connection Management - Automatic connection pooling and lifecycle management
- Error Handling - Structured error handling with detailed logging and retry policies
- Performance Monitoring - Built-in metrics, statistics, and performance tracking
- Graceful Shutdown - Clean resource cleanup and connection termination

$3

- Modular Design - Use only what you need (client-only, worker-only, or combined)
- Multiple Workers - Support for multiple workers with different task queues
- Advanced Configuration - Extensive customization for production environments
- TLS Support - Secure connections for Temporal Cloud deployments

🔝 Back to top

Installation

``bash
npm install nestjs-temporal-core @temporalio/client @temporalio/worker @temporalio/workflow @temporalio/common
`

$3

`bash
npm install @nestjs/common @nestjs/core reflect-metadata rxjs
`

🔝 Back to top

Quick Start

$3

Enable shutdown hooks in your main.ts for proper Temporal resource cleanup:

`typescript
// main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
const app = await NestFactory.create(AppModule);

// Required for graceful Temporal connection cleanup
app.enableShutdownHooks();

await app.listen(3000);
}
bootstrap();
`

$3

Import and configure TemporalModule in your app module:

`typescript
// app.module.ts
import { Module } from '@nestjs/common';
import { TemporalModule } from 'nestjs-temporal-core';
import { PaymentActivity } from './activities/payment.activity';
import { EmailActivity } from './activities/email.activity';

@Module({
imports: [
TemporalModule.register({
connection: {
address: 'localhost:7233',
namespace: 'default',
},
taskQueue: 'my-task-queue',
worker: {
workflowsPath: require.resolve('./workflows'),
activityClasses: [PaymentActivity, EmailActivity],
autoStart: true,
},
}),
],
providers: [PaymentActivity, EmailActivity],
})
export class AppModule {}
`

$3

Create activities using @Activity() and @ActivityMethod() decorators:

`typescript
// payment.activity.ts
import { Injectable } from '@nestjs/common';
import { Activity, ActivityMethod } from 'nestjs-temporal-core';

export interface PaymentData {
amount: number;
currency: string;
customerId: string;
}

@Injectable()
@Activity({ name: 'payment-activities' })
export class PaymentActivity {

@ActivityMethod('processPayment')
async processPayment(data: PaymentData): Promise<{ transactionId: string }> {
// Payment processing logic with full NestJS DI support
console.log(Processing payment: $${data.amount} ${data.currency});

// Simulate payment processing
await new Promise(resolve => setTimeout(resolve, 1000));

return { transactionId: txn_${Date.now()} };
}

@ActivityMethod('refundPayment')
async refundPayment(transactionId: string): Promise<{ refundId: string }> {
// Refund logic
console.log(Refunding transaction: ${transactionId});
return { refundId: ref_${Date.now()} };
}
}
`

$3

Create workflows as pure Temporal functions (NOT NestJS services):

`typescript
// payment.workflow.ts
import { proxyActivities, defineSignal, defineQuery, setHandler } from '@temporalio/workflow';
import type { PaymentActivity } from './payment.activity';

// Create activity proxies
const { processPayment, refundPayment } = proxyActivities({
startToCloseTimeout: '5m',
retry: {
maximumAttempts: 3,
initialInterval: '1s',
},
});

// Define signals and queries
export const cancelPaymentSignal = defineSignal<[string]>('cancelPayment');
export const getPaymentStatusQuery = defineQuery('getPaymentStatus');

export async function processPaymentWorkflow(data: PaymentData): Promise {
let status = 'processing';
let transactionId: string | undefined;

// Set up signal and query handlers
setHandler(cancelPaymentSignal, (reason: string) => {
status = 'cancelled';
});

setHandler(getPaymentStatusQuery, () => status);

try {
// Execute payment activity
const result = await processPayment(data);
transactionId = result.transactionId;
status = 'completed';

return {
success: true,
transactionId,
status,
};
} catch (error) {
status = 'failed';

// Compensate if needed
if (transactionId) {
await refundPayment(transactionId);
}

throw error;
}
}
`

$3

Inject TemporalService to start and manage workflows:

`typescript
// payment.service.ts
import { Injectable } from '@nestjs/common';
import { TemporalService } from 'nestjs-temporal-core';

@Injectable()
export class PaymentService {
constructor(private readonly temporal: TemporalService) {}

async processPayment(paymentData: any) {
// Start workflow
const result = await this.temporal.startWorkflow(
'processPaymentWorkflow',
[paymentData],
{
workflowId: payment-${Date.now()},
taskQueue: 'my-task-queue',
}
);

return {
workflowId: result.result.workflowId,
runId: result.result.runId,
};
}

async checkPaymentStatus(workflowId: string) {
// Query workflow
const statusResult = await this.temporal.queryWorkflow(
workflowId,
'getPaymentStatus'
);

return { status: statusResult.result };
}

async cancelPayment(workflowId: string, reason: string) {
// Send signal
await this.temporal.signalWorkflow(
workflowId,
'cancelPayment',
[reason]
);
}
}
`

🔝 Back to top

Module Variants

The package provides modular architecture with separate modules for different use cases:

$3

Complete integration with both client and worker capabilities:

`typescript
import { TemporalModule } from 'nestjs-temporal-core';

TemporalModule.register({
connection: { address: 'localhost:7233' },
taskQueue: 'my-queue',
worker: {
workflowsPath: require.resolve('./workflows'),
activityClasses: [PaymentActivity, EmailActivity],
},
})
`

$3

For services that only need to start/query workflows:

`typescript
import { TemporalClientModule } from 'nestjs-temporal-core/client';

TemporalClientModule.register({
connection: { address: 'localhost:7233' },
namespace: 'default',
})
`

$3

For dedicated worker processes:

`typescript
import { TemporalWorkerModule } from 'nestjs-temporal-core/worker';

TemporalWorkerModule.register({
connection: { address: 'localhost:7233' },
taskQueue: 'worker-queue',
worker: {
workflowsPath: require.resolve('./workflows'),
activityClasses: [BackgroundActivity],
},
})
`

$3

For standalone activity management:

`typescript
import { TemporalActivityModule } from 'nestjs-temporal-core/activity';

TemporalActivityModule.register({
activityClasses: [DataProcessingActivity],
})
`

$3

For managing Temporal schedules:

`typescript
import { TemporalSchedulesModule } from 'nestjs-temporal-core/schedules';

TemporalSchedulesModule.register({
connection: { address: 'localhost:7233' },
})
`

🔝 Back to top

Configuration

$3

`typescript
TemporalModule.register({
connection: {
address: 'localhost:7233',
namespace: 'default',
},
taskQueue: 'my-task-queue',
worker: {
workflowsPath: require.resolve('./workflows'),
activityClasses: [PaymentActivity, EmailActivity],
autoStart: true,
maxConcurrentActivityExecutions: 100,
},
logLevel: 'info',
enableLogger: true,
})
`

$3

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',
},
autoRestart: true, // Global default for all workers
maxRestarts: 3, // Global default for all workers
workers: [
{
taskQueue: 'payments-queue',
workflowsPath: require.resolve('./workflows/payments'),
activityClasses: [PaymentActivity, RefundActivity],
autoStart: true,
maxRestarts: 5, // Override for this critical worker
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
autoRestart: false, // Disable auto-restart for this worker
},
],
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});
}
}
}
`

$3

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();
}
}
`

$3

For dynamic configuration using environment variables or config services:

`typescript
// config/temporal.config.ts
import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { TemporalOptionsFactory, TemporalOptions } from 'nestjs-temporal-core';

@Injectable()
export class TemporalConfigService implements TemporalOptionsFactory {
constructor(private configService: ConfigService) {}

createTemporalOptions(): TemporalOptions {
return {
connection: {
address: this.configService.get('TEMPORAL_ADDRESS', 'localhost:7233'),
namespace: this.configService.get('TEMPORAL_NAMESPACE', 'default'),
},
taskQueue: this.configService.get('TEMPORAL_TASK_QUEUE', 'default'),
worker: {
workflowsPath: require.resolve('../workflows'),
activityClasses: [], // Populated by module
maxConcurrentActivityExecutions: 100,
},
};
}
}

// app.module.ts
import { ConfigModule } from '@nestjs/config';

@Module({
imports: [
ConfigModule.forRoot({ isGlobal: true }),
TemporalModule.registerAsync({
imports: [ConfigModule],
useClass: TemporalConfigService,
}),
],
})
export class AppModule {}
`

$3

`typescript
TemporalModule.registerAsync({
imports: [ConfigModule],
useFactory: (configService: ConfigService) => ({
connection: {
address: configService.get('TEMPORAL_ADDRESS', 'localhost:7233'),
namespace: configService.get('TEMPORAL_NAMESPACE', 'default'),
},
taskQueue: configService.get('TEMPORAL_TASK_QUEUE', 'default'),
worker: {
workflowsPath: require.resolve('./workflows'),
activityClasses: [PaymentActivity, EmailActivity],
},
}),
inject: [ConfigService],
})
`

$3

For secure connections to Temporal Cloud:

`typescript
import * as fs from 'fs';

TemporalModule.register({
connection: {
address: 'your-namespace.your-account.tmprl.cloud:7233',
namespace: 'your-namespace.your-account',
tls: {
clientCertPair: {
crt: fs.readFileSync('/path/to/client.crt'),
key: fs.readFileSync('/path/to/client.key'),
},
},
},
taskQueue: 'my-task-queue',
worker: {
workflowsPath: require.resolve('./workflows'),
activityClasses: [PaymentActivity],
},
})
`

$3

`typescript
interface TemporalOptions {
// Connection settings
connection: {
address: string; // Temporal server address (default: 'localhost:7233')
namespace?: string; // Temporal namespace (default: 'default')
tls?: TLSConfig; // TLS configuration for secure connections
};

// Task queue name
taskQueue?: string; // Default task queue (default: 'default')

// Worker configuration
worker?: {
workflowsPath?: string; // Path to workflow definitions (use require.resolve)
activityClasses?: any[]; // Array of activity classes to register
autoStart?: boolean; // Auto-start worker on module init (default: true)
autoRestart?: boolean; // Auto-restart on failure (inherits from global)
maxRestarts?: number; // Max restart attempts (inherits from global)
maxConcurrentActivityExecutions?: number; // Max concurrent activities (default: 100)
maxActivitiesPerSecond?: number; // Rate limit for activities
};

// Logging
logLevel?: 'trace' | 'debug' | 'info' | 'warn' | 'error'; // Log level (default: 'info')
enableLogger?: boolean; // Enable logging (default: true)

// Auto-restart configuration
autoRestart?: boolean; // Auto-restart worker on failure (default: true)
maxRestarts?: number; // Max restart attempts before giving up (default: 3)

// Advanced
isGlobal?: boolean; // Make module global (default: false)
}
`

🔝 Back to top

Core Concepts

$3

Activities are NestJS services decorated with @Activity() that perform actual work. They have full access to NestJS dependency injection and can interact with external systems.

Key Points:
- Activities are NestJS services (@Injectable())
- Use @Activity() decorator at class level
- Use @ActivityMethod() decorator for methods to be registered
- Activities should be idempotent and handle retries gracefully
- Full access to NestJS DI (inject services, repositories, etc.)

`typescript
@Injectable()
@Activity({ name: 'order-activities' })
export class OrderActivity {
constructor(
private readonly orderRepository: OrderRepository,
private readonly emailService: EmailService,
) {}

@ActivityMethod('createOrder')
async createOrder(orderData: CreateOrderData): Promise {
// Database operations with full DI support
const order = await this.orderRepository.create(orderData);
await this.emailService.sendConfirmation(order);
return order;
}

@ActivityMethod('validateInventory')
async validateInventory(items: OrderItem[]): Promise {
// Business logic with injected services
return await this.orderRepository.checkInventory(items);
}
}
`

$3

Workflows are pure Temporal functions (NOT NestJS services) that orchestrate activities. They must be deterministic and use Temporal's workflow APIs.

Important: Workflows are NOT decorated with @Injectable() and should NOT use NestJS dependency injection.

`typescript
// order.workflow.ts
import { proxyActivities, defineSignal, defineQuery, setHandler } from '@temporalio/workflow';
import type { OrderActivity } from './order.activity';

// Create activity proxies with proper typing
const { createOrder, validateInventory } = proxyActivities({
startToCloseTimeout: '5m',
retry: {
maximumAttempts: 3,
initialInterval: '1s',
maximumInterval: '30s',
},
});

// Define signals and queries at module level
export const cancelOrderSignal = defineSignal<[string]>('cancelOrder');
export const getOrderStatusQuery = defineQuery('getOrderStatus');

// Workflow function (exported, not a class)
export async function processOrderWorkflow(orderData: CreateOrderData): Promise {
let status = 'pending';

// Set up signal handler
setHandler(cancelOrderSignal, (reason: string) => {
status = 'cancelled';
});

// Set up query handler
setHandler(getOrderStatusQuery, () => status);

try {
// Validate inventory
const isValid = await validateInventory(orderData.items);
if (!isValid) {
throw new Error('Insufficient inventory');
}

// Create order
status = 'processing';
const order = await createOrder(orderData);
status = 'completed';

return {
orderId: order.id,
status,
};
} catch (error) {
status = 'failed';
throw error;
}
}
`

$3

Signals allow external systems to send events to workflows, while queries provide read-only access to workflow state.

`typescript
import { defineSignal, defineQuery, setHandler, condition } from '@temporalio/workflow';

// Define at module level
export const updateStatusSignal = defineSignal<[string]>('updateStatus');
export const addItemSignal = defineSignal<[Item]>('addItem');
export const getItemsQuery = defineQuery('getItems');
export const getStatusQuery = defineQuery('getStatus');

export async function myWorkflow(): Promise {
let status = 'pending';
const items: Item[] = [];

// Set up handlers
setHandler(updateStatusSignal, (newStatus: string) => {
status = newStatus;
});

setHandler(addItemSignal, (item: Item) => {
items.push(item);
});

setHandler(getItemsQuery, () => items);
setHandler(getStatusQuery, () => status);

// Wait for completion signal
await condition(() => status === 'completed');
}
`

$3

Inject TemporalService in your NestJS services to interact with workflows:

`typescript
@Injectable()
export class OrderService {
constructor(private readonly temporal: TemporalService) {}

async createOrder(orderData: CreateOrderData) {
// Start workflow - note the method signature
const result = await this.temporal.startWorkflow(
'processOrderWorkflow', // Workflow function name
[orderData], // Arguments array
{ // Options
workflowId: order-${Date.now()},
taskQueue: 'order-queue',
}
);

return {
workflowId: result.result.workflowId,
runId: result.result.runId,
};
}

async queryOrderStatus(workflowId: string) {
const result = await this.temporal.queryWorkflow(
workflowId,
'getOrderStatus'
);

return result.result;
}

async cancelOrder(workflowId: string, reason: string) {
await this.temporal.signalWorkflow(
workflowId,
'cancelOrder',
[reason]
);
}
}
`

🔝 Back to top

API Reference

For detailed API documentation, visit the Full API Documentation.

$3

The main unified service providing access to all Temporal functionality. See the API Documentation for complete method signatures and examples.

Key methods:
- startWorkflow() - Start a workflow execution
- signalWorkflow() - Send a signal to a running workflow
- queryWorkflow() - Query a running workflow
- getWorkflowHandle() - Get a workflow handle to interact with it
- terminateWorkflow() - Terminate a workflow execution
- cancelWorkflow() - Cancel a workflow execution
- getHealth() - Get service health status
- createSchedule() - Create a schedule
- listSchedules() - List all schedules
- deleteSchedule() - Delete a schedule

🔝 Back to top

Examples

$3

Check out our complete example repository featuring:

- ✅ Real-world implementations - Production-ready examples
- ✅ Multiple use cases - E-commerce, notifications, reports, and more
- ✅ Best practices - Following all recommended patterns
- ✅ Docker setup - Ready-to-run with docker-compose
- ✅ Test coverage - Comprehensive test examples

$3

For more examples, visit our documentation. Key example scenarios include:

1. E-commerce Order Processing - Complete example with compensation logic
2. Scheduled Reports - Creating and managing scheduled workflows
3. Activity Retry Configuration - Custom retry policies
4. Child Workflows - Organizing complex workflows
5. Continue-As-New - For long-running workflows
6. Custom Error Handling - Implementing custom error types

🔝 Back to top

Advanced Usage

$3

`typescript
// workflow.ts
const paymentActivities = proxyActivities({
startToCloseTimeout: '5m',
retry: {
maximumAttempts: 5,
initialInterval: '1s',
maximumInterval: '1m',
backoffCoefficient: 2,
nonRetryableErrorTypes: ['InvalidPaymentMethod', 'InsufficientFunds'],
},
});
`

$3

`typescript
import { TestWorkflowEnvironment } from '@temporalio/testing';
import { Worker } from '@temporalio/worker';
import { processOrderWorkflow } from './order.workflow';

describe('Order Workflow', () => {
let testEnv: TestWorkflowEnvironment;

beforeAll(async () => {
testEnv = await TestWorkflowEnvironment.createTimeSkipping();
});

afterAll(async () => {
await testEnv?.teardown();
});

it('should process order successfully', async () => {
const { client, nativeConnection } = testEnv;

// Mock activities
const mockOrderActivity = {
validatePayment: async () => ({ valid: true }),
reserveInventory: async () => ({ reservationId: 'res-123' }),
chargePayment: async () => ({ transactionId: 'txn-123' }),
sendConfirmationEmail: async () => {},
};

const worker = await Worker.create({
connection: nativeConnection,
taskQueue: 'test',
workflowsPath: require.resolve('./order.workflow'),
activities: mockOrderActivity,
});

await worker.runUntil(async () => {
const result = await client.workflow.execute(processOrderWorkflow, {
workflowId: 'test-order-1',
taskQueue: 'test',
args: [{
orderId: 'order-123',
payment: { amount: 100, currency: 'USD' },
items: [{ id: '1', quantity: 1 }],
}],
});

expect(result.status).toBe('completed');
expect(result.transactionId).toBe('txn-123');
});
});
});
`

🔝 Back to top

Best Practices

$3

✅ DO:
- Keep workflows deterministic (no random numbers, current time, network calls)
- Use activities for any non-deterministic operations
- Keep workflow history size manageable (use continue-as-new for long-running workflows)
- Export workflow functions (not classes)
- Use defineSignal and defineQuery at module level

❌ DON'T:
- Don't use @Injectable() on workflow functions
- Don't inject NestJS services in workflows
- Don't use Math.random() or Date.now() directly in workflows
- Don't make HTTP calls or database queries directly in workflows

$3

✅ DO:
- Make activities idempotent (safe to retry)
- Use @Injectable() and leverage NestJS DI
- Use @Activity() and @ActivityMethod() decorators
- Handle errors appropriately
- Log activity execution for debugging

❌ DON'T:
- Don't make activities too granular (network overhead)
- Don't rely on activity execution order guarantees
- Don't share mutable state between activity invocations

$3

✅ DO:
- Use async configuration for environment-based setup
- Configure appropriate timeouts for your use case
- Set up proper retry policies
- Enable graceful shutdown hooks
- Use task queues to organize work

❌ DON'T:
- Don't hardcode connection strings
- Don't use the same task queue for all workflows
- Don't ignore timeout configurations

$3

✅ DO:
- Implement compensation logic in workflows
- Use appropriate retry policies
- Log errors with context
- Define non-retryable error types
- Handle activity failures gracefully

❌ DON'T:
- Don't swallow errors silently
- Don't retry indefinitely
- Don't ignore business-level failures

$3

✅ DO:
- Write unit tests for activities
- Use TestWorkflowEnvironment for integration tests
- Mock external dependencies
- Test failure scenarios
- Test signal and query handlers

❌ DON'T:
- Don't skip workflow testing
- Don't test against production Temporal server
- Don't assume workflows are correct without testing

🔝 Back to top

Health Monitoring

The package includes comprehensive health monitoring capabilities for production deployments.

$3

`typescript
// app.module.ts
import { Module } from '@nestjs/common';
import { TemporalModule } from 'nestjs-temporal-core';
import { TemporalHealthModule } from 'nestjs-temporal-core/health';

@Module({
imports: [
TemporalModule.register({
connection: { address: 'localhost:7233' },
taskQueue: 'my-queue',
worker: {
workflowsPath: require.resolve('./workflows'),
activityClasses: [MyActivity],
},
}),
TemporalHealthModule, // Adds /health/temporal endpoint
],
})
export class AppModule {}
`

$3

`typescript
@Controller('health')
export class HealthController {
constructor(private readonly temporal: TemporalService) {}

@Get('/status')
async getHealthStatus() {
const health = this.temporal.getHealth();

return {
status: health.overallHealth,
timestamp: new Date(),
services: {
client: {
healthy: health.client.status === 'healthy',
connection: health.client.connectionStatus,
},
worker: {
healthy: health.worker.status === 'healthy',
state: health.worker.state,
activitiesRegistered: health.worker.activitiesCount,
},
discovery: {
healthy: health.discovery.status === 'healthy',
activitiesDiscovered: health.discovery.activitiesDiscovered,
},
},
uptime: health.uptime,
};
}
}
`

🔝 Back to top

Troubleshooting

$3

#### 1. Connection Errors

Problem: Cannot connect to Temporal server

Solutions:
`typescript
// Check connection configuration
const health = temporalService.getHealth();
console.log('Connection status:', health.client.connectionStatus);

// Verify Temporal server is running
// docker ps | grep temporal

// Check connection settings
TemporalModule.register({
connection: {
address: process.env.TEMPORAL_ADDRESS || 'localhost:7233',
namespace: 'default',
},
})
`

#### 2. Activity Not Found

Problem: Workflow cannot find registered activities

Solutions:
`typescript
// 1. Ensure activity is in activityClasses array
TemporalModule.register({
worker: {
activityClasses: [MyActivity], // Must include the activity class
},
})

// 2. Verify activity is registered as provider
@Module({
providers: [MyActivity], // Must be in providers array
})

// 3. Check activity decorator
@Activity({ name: 'my-activities' })
export class MyActivity {
@ActivityMethod('myActivity')
async myActivity() { }
}

// 4. Check discovery status
const health = temporalService.getHealth();
console.log('Activities discovered:', health.discovery.activitiesDiscovered);
`

#### 3. Workflow Registration Issues

Problem: Workflow not found or not executing

Solutions:
`typescript
// 1. Ensure workflowsPath is correct
TemporalModule.register({
worker: {
workflowsPath: require.resolve('./workflows'), // Must resolve to workflows file/directory
},
})

// 2. Export workflow function properly
// workflows/index.ts
export { processOrderWorkflow } from './order.workflow';
export { reportWorkflow } from './report.workflow';

// 3. Use correct workflow name when starting
await temporal.startWorkflow(
'processOrderWorkflow', // Must match exported function name
[args],
options
);
`

#### 4. Timeout Issues

Problem: Activities or workflows timing out

Solutions:
`typescript
// Configure appropriate timeouts
const activities = proxyActivities({
startToCloseTimeout: '10m', // Increase for long-running activities
scheduleToCloseTimeout: '15m', // Total time including queuing
scheduleToStartTimeout: '5m', // Time waiting in queue
});

// For workflows
await temporal.startWorkflow('myWorkflow', [args], {
workflowExecutionTimeout: '24h', // Max total execution time
workflowRunTimeout: '12h', // Max single run time
workflowTaskTimeout: '10s', // Decision task timeout
});
`

$3

Enable comprehensive debugging:

`typescript
TemporalModule.register({
logLevel: 'debug',
enableLogger: true,
connection: {
address: 'localhost:7233',
},
worker: {
debugMode: true, // If available
},
})

// Check detailed health and statistics
const health = temporalService.getHealth();
const stats = temporalService.getStatistics();
console.log('Health:', JSON.stringify(health, null, 2));
console.log('Stats:', JSON.stringify(stats, null, 2));
`

$3

If you're still experiencing issues:

1. Check the logs - Enable debug logging to see detailed information
2. Verify configuration - Double-check all connection and worker settings
3. Test connectivity - Ensure Temporal server is accessible
4. Review health status - Use getHealth() to identify failing components
5. Check GitHub Issues - Search existing issues
6. Create an issue - Provide logs, configuration, and minimal reproduction

🔝 Back to top

Migration Guide

$3

Version 3.0.12 introduces support for multiple workers without breaking existing single-worker configurations.

#### No Changes Required for Single Worker

Your existing configuration continues to work:

`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

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],
},
],
})
`

#### 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);

// 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,
});
`

🔝 Back to top

Requirements

- Node.js: >= 16.0.0
- NestJS: >= 9.0.0
- Temporal Server: >= 1.20.0

Contributing

We welcome contributions! To contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (npm test)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

$3

`bash


Clone the repository

git clone https://github.com/harsh-simform/nestjs-temporal-core.git
cd nestjs-temporal-core

Install dependencies

npm install

Run tests

npm test

Run tests with coverage

npm run test:cov

Build the package

npm run build

Generate documentation

npm run docs:generate
``

🔝 Back to top

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support and Resources

- 📚 Documentation: Full API Documentation
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 📦 NPM: nestjs-temporal-core
- 🔄 Changelog: Releases
- 📖 Example Project: nestjs-temporal-core-example

Related Projects

- Temporal.io - The underlying workflow orchestration platform
- NestJS - Progressive Node.js framework
- @temporalio/sdk - Official Temporal TypeScript SDK

---