NestJS Worker Usage

Learn how to integrate temporal-contract workers with NestJS for full dependency injection support.

Overview

The @temporal-contract/worker-nestjs package provides seamless integration between temporal-contract and NestJS, enabling you to use NestJS's powerful dependency injection system in your Temporal activities.

Installation

pnpm add @temporal-contract/worker-nestjs @swan-io/boxed

Quick Start

1. Create the Activities Provider

Create a provider that uses NestJS services to implement activities:

// activities.provider.ts
import { Injectable } from "@nestjs/common";
import { declareActivitiesHandler, ActivityError } from "@temporal-contract/worker/activity";
import { Future, Result } from "@swan-io/boxed";
import { myContract } from "./contract";
import { PaymentService } from "./services/payment.service";
import { NotificationService } from "./services/notification.service";

@Injectable()
export class ActivitiesProvider {
  constructor(
    private readonly paymentService: PaymentService,
    private readonly notificationService: NotificationService,
  ) {}

  createActivities() {
    return declareActivitiesHandler({
      contract: myContract,
      activities: {
        // Global activities
        log: ({ level, message }) => {
          console.log(`[${level}] ${message}`);
          return Future.value(Result.Ok(undefined));
        },

        // Workflow-specific activities with DI
        processOrder: {
          processPayment: ({ customerId, amount }) => {
            return Future.fromPromise(this.paymentService.charge(customerId, amount))
              .mapError(
                (error) =>
                  new ActivityError(
                    "PAYMENT_FAILED",
                    error instanceof Error ? error.message : "Payment failed",
                    error,
                  ),
              )
              .mapOk((transaction) => ({ transactionId: transaction.id }));
          },

          sendNotification: ({ customerId, message }) => {
            return Future.fromPromise(this.notificationService.send(customerId, message))
              .mapError(
                (error) =>
                  new ActivityError(
                    "NOTIFICATION_FAILED",
                    error instanceof Error ? error.message : "Notification failed",
                    error,
                  ),
              )
              .mapOk(() => undefined);
          },
        },
      },
    });
  }
}

2. Configure the Temporal Module

Use TemporalModule.forRootAsync to configure the worker with your activities:

// app.module.ts
import { Module } from "@nestjs/common";
import { TemporalModule } from "@temporal-contract/worker-nestjs";
import { NativeConnection } from "@temporalio/worker";
import { myContract } from "./contract";
import { ActivitiesProvider } from "./activities.provider";
import { PaymentService } from "./services/payment.service";
import { NotificationService } from "./services/notification.service";

@Module({
  imports: [
    TemporalModule.forRootAsync({
      imports: [], // Import other modules if needed
      inject: [ActivitiesProvider],
      useFactory: async (activitiesProvider: ActivitiesProvider) => ({
        contract: myContract,
        connection: await NativeConnection.connect({
          address: "localhost:7233",
        }),
        workflowsPath: require.resolve("./workflows"),
        activities: activitiesProvider.createActivities(),
      }),
    }),
  ],
  providers: [ActivitiesProvider, PaymentService, NotificationService],
})
export class AppModule {}

3. Start the Application

The worker starts automatically when the NestJS application initializes:

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

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

  // Worker starts automatically during module initialization

  // Graceful shutdown
  const shutdown = async () => {
    console.log("Shutting down...");
    await app.close(); // Worker shuts down automatically
    process.exit(0);
  };

  process.on("SIGTERM", shutdown);
  process.on("SIGINT", shutdown);

  console.log("Worker started successfully");
}

bootstrap();

Dependency Injection

Using Services in Activities

Access any NestJS service in your activities:

@Injectable()
export class ActivitiesProvider {
  constructor(
    private readonly paymentService: PaymentService,
    private readonly inventoryService: InventoryService,
    private readonly emailService: EmailService,
    private readonly logger: Logger,
  ) {}

  createActivities() {
    return declareActivitiesHandler({
      contract: myContract,
      activities: {
        processOrder: {
          checkInventory: ({ productId, quantity }) => {
            this.logger.log(`Checking inventory for ${productId}`);
            return Future.fromPromise(this.inventoryService.reserve(productId, quantity))
              .mapError((error) => new ActivityError("INVENTORY_UNAVAILABLE", error.message, error))
              .mapOk((reservation) => ({ reservationId: reservation.id }));
          },
        },
      },
    });
  }
}

Using Configuration

Access configuration values:

import { ConfigService } from "@nestjs/config";

@Injectable()
export class ActivitiesProvider {
  constructor(
    private readonly configService: ConfigService,
    private readonly paymentService: PaymentService,
  ) {}

  createActivities() {
    const paymentGatewayUrl = this.configService.get("PAYMENT_GATEWAY_URL");

    return declareActivitiesHandler({
      contract: myContract,
      activities: {
        processOrder: {
          processPayment: ({ amount }) => {
            return Future.fromPromise(this.paymentService.charge(amount, paymentGatewayUrl))
              .mapError((err) => new ActivityError("PAYMENT_FAILED", err.message, err))
              .mapOk((tx) => ({ transactionId: tx.id }));
          },
        },
      },
    });
  }
}

Module Configuration Options

Synchronous Configuration

Use forRoot for simple, synchronous configuration:

TemporalModule.forRoot({
  contract: myContract,
  connection: await NativeConnection.connect({ address: "localhost:7233" }),
  workflowsPath: require.resolve("./workflows"),
  activities: activitiesProvider.createActivities(),
});

Asynchronous Configuration

Use forRootAsync for configuration that requires async setup or DI:

TemporalModule.forRootAsync({
  imports: [ConfigModule],
  inject: [ConfigService, ActivitiesProvider],
  useFactory: async (config: ConfigService, activitiesProvider: ActivitiesProvider) => ({
    contract: myContract,
    connection: await NativeConnection.connect({
      address: config.get("TEMPORAL_ADDRESS"),
    }),
    namespace: config.get("TEMPORAL_NAMESPACE"),
    workflowsPath: require.resolve("./workflows"),
    activities: activitiesProvider.createActivities(),
  }),
});

Worker Lifecycle

The TemporalService manages the worker lifecycle automatically:

• onModuleInit: Worker is created and started
• onModuleDestroy: Worker is gracefully shut down

You can access the worker instance if needed:

import { Injectable } from "@nestjs/common";
import { TemporalService } from "@temporal-contract/worker-nestjs";

@Injectable()
export class MyService {
  constructor(private readonly temporalService: TemporalService) {}

  async getWorkerStatus() {
    const worker = this.temporalService.getWorker();
    // Access worker if needed
  }
}

Multiple Workers

Run multiple workers in the same NestJS application:

@Module({
  imports: [
    // Order processing worker
    TemporalModule.forRootAsync({
      name: "orders",
      inject: [OrderActivitiesProvider],
      useFactory: async (provider: OrderActivitiesProvider) => ({
        contract: orderContract,
        connection: await NativeConnection.connect({ address: "localhost:7233" }),
        workflowsPath: require.resolve("./order-workflows"),
        activities: provider.createActivities(),
      }),
    }),

    // Payment processing worker
    TemporalModule.forRootAsync({
      name: "payments",
      inject: [PaymentActivitiesProvider],
      useFactory: async (provider: PaymentActivitiesProvider) => ({
        contract: paymentContract,
        connection: await NativeConnection.connect({ address: "localhost:7233" }),
        workflowsPath: require.resolve("./payment-workflows"),
        activities: provider.createActivities(),
      }),
    }),
  ],
  providers: [OrderActivitiesProvider, PaymentActivitiesProvider],
})
export class AppModule {}

Testing

Test your activities with NestJS testing utilities:

import { Test } from "@nestjs/testing";
import { ActivitiesProvider } from "./activities.provider";
import { PaymentService } from "./services/payment.service";

describe("ActivitiesProvider", () => {
  let provider: ActivitiesProvider;
  let paymentService: PaymentService;

  beforeEach(async () => {
    const module = await Test.createTestingModule({
      providers: [
        ActivitiesProvider,
        {
          provide: PaymentService,
          useValue: {
            charge: jest.fn(),
          },
        },
      ],
    }).compile();

    provider = module.get<ActivitiesProvider>(ActivitiesProvider);
    paymentService = module.get<PaymentService>(PaymentService);
  });

  it("should process payment", async () => {
    jest.spyOn(paymentService, "charge").mockResolvedValue({
      id: "tx-123",
    });

    const activities = provider.createActivities();
    const result = await activities.activities.processOrder.processPayment({
      customerId: "CUST-123",
      amount: 100,
    });

    const value = await result;
    expect(value.isOk()).toBe(true);
    expect(value.get()).toEqual({ transactionId: "tx-123" });
  });
});

Best Practices

1. Organize by Domain

// ✅ Good - organized by domain
src/
├── orders/
│   ├── orders.activities.provider.ts
│   ├── orders.contract.ts
│   ├── orders.workflows.ts
│   └── orders.module.ts
├── payments/
│   ├── payments.activities.provider.ts
│   ├── payments.contract.ts
│   ├── payments.workflows.ts
│   └── payments.module.ts

2. Use Global Modules for Shared Services

@Global()
@Module({
  providers: [Logger, ConfigService],
  exports: [Logger, ConfigService],
})
export class CoreModule {}

3. Separate Business Logic from Activities

// ✅ Good - business logic in services
@Injectable()
export class PaymentService {
  async processPayment(customerId: string, amount: number) {
    // Business logic here
  }
}

@Injectable()
export class ActivitiesProvider {
  constructor(private readonly paymentService: PaymentService) {}

  createActivities() {
    return declareActivitiesHandler({
      contract: myContract,
      activities: {
        processOrder: {
          processPayment: ({ customerId, amount }) => {
            return Future.fromPromise(this.paymentService.processPayment(customerId, amount))
              .mapError((err) => new ActivityError("PAYMENT_FAILED", err.message, err))
              .mapOk((tx) => ({ transactionId: tx.id }));
          },
        },
      },
    });
  }
}

Common Issues

Worker Not Starting

Ensure the connection is properly awaited:

// ✅ Correct
useFactory: async () => ({
  connection: await NativeConnection.connect({ address: "localhost:7233" }),
  // ...
});

// ❌ Wrong
useFactory: () => ({
  connection: NativeConnection.connect({ address: "localhost:7233" }),
  // ...
});

Activities Not Found

Verify the workflowsPath is correct:

workflowsPath: require.resolve("./workflows"); // Relative to this file

See Also

• Worker Usage - Standard worker implementation
• Defining Contracts - Creating contracts
• Result Pattern - Error handling with Result/Future
• API Reference - Complete NestJS worker API