nestjs-temporal

You can register multiple workers by making multiple calls to TemporalModule.registerWorker or TemporalModule.registerWorkerAsync.

Important: When using multiple workers, you must explicitly specify your activity classes using the activityClasses option. If you do not, the workers may attempt to register all activities marked with @Activity() in the application.

To avoid conflicts or unintended registrations, it is recommended to import dynamic worker modules into the specific modules containing their respective workflows and activities, rather than registering everything in the root AppModule.

// Register the client once at the app level
@Module({
  imports: [
    TemporalModule.registerClient(),
  ],
})
export class AppModule {}

// Configure Worker #1
@Module({
  imports: [
    TemporalModule.registerWorker({
      workerOptions: {
        taskQueue: 'worker-1',
        workflowsPath: require.resolve('./temporal/workflow-1'),
      },
      activityClasses: [Greeting1Activity],
    }),
  ],
  providers: [Greeting1Activity],
})
export class Worker1Module {}

// Configure Worker #2
@Module({
  imports: [
    TemporalModule.registerWorker({
      workerOptions: {
        taskQueue: 'worker-2',
        workflowsPath: require.resolve('./temporal/workflow-2'),
      },
      activityClasses: [SomeOtherActivity],
    }),
  ],
  providers: [SomeOtherActivity],
})
export class Worker2Module {}

For dynamic configuration (e.g., using ConfigService), use registerWorkerAsync and registerClientAsync.

When configuring a Worker asynchronously, you can manually establish a NativeConnection, install the Temporal Runtime, and provide a workflowBundle created via bundleWorkflowCode.

When configuring a Client asynchronously, you can provide a custom connection created via @temporalio/client's Connection.connect method.

// Async Worker Configuration
@Module({
  imports: [
    TemporalModule.registerWorkerAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: async (config: ConfigService) => {
        Runtime.install({});
        const temporalHost = config.get('app.temporalHost');
        const connection = await NativeConnection.connect({
          address: temporalHost,
        });
        const workflowBundle = await bundleWorkflowCode({
          workflowsPath: path.join(__dirname, './workflows'),
        });

        return {
          workerOptions: {
            connection,
            taskQueue: 'default',
            workflowBundle,
          }
        };
      },
    }),
    ClientModule,
  ],
})
export class AppModule {}

// Async Client Configuration
@Module({
  imports: [
    TemporalModule.registerClientAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: async (config: ConfigService) => {
        const temporalHost = config.get('app.temporalHost');
        const connection = await Connection.connect({
          address: temporalHost,
        });

        return {
          connection,
        };
      },
    }),
  ],
})
export class ClientModule {}

To get started, register a Worker and a Client in your NestJS application.

1. Register the Worker: Use TemporalModule.registerWorker to define the taskQueue and the path to your workflow code.
2. Register the Client: Use TemporalModule.registerClient() to enable workflow orchestration.
3. Define Activities: Use the @Activities() decorator on a class and the @Activity() decorator on specific methods.
4. Invoke Workflows: Inject the WorkflowClient using @InjectTemporalClient() in your controllers or services to start workflows.

import { Module } from '@nestjs/common';
import { TemporalModule } from 'nestjs-temporal';

@Module({
  imports: [
    TemporalModule.registerWorker({
      workerOptions: {
        taskQueue: 'default',
        workflowsPath: require.resolve('./temporal/workflow'),
      },
    }),
    TemporalModule.registerClient(),
  ],
})
export class AppModule {}

// --- Activity Definition ---

import { Injectable } from '@nestjs/common';
import { Activities, Activity } from 'nestjs-temporal';

@Injectable()
@Activities()
export class GreetingActivity {
  @Activity()
  async greeting(name: string): Promise<string> {
    return 'Hello ' + name;
  }
}

// --- Workflow Usage (Temporal SDK side) ---

import { proxyActivities } from '@temporalio/workflow';
import { IGreetingActivity } from '../activities';

const { greeting } = proxyActivities<IGreetingActivity>({
  startToCloseTimeout: '1 minute',
});

export async function example(name: string): Promise<string> {
  return await greeting(name);
}

// --- Controller Usage ---

import { Controller, Post } from '@nestjs/common';
import { WorkflowClient } from '@temporalio/client';
import { InjectTemporalClient } from 'nestjs-temporal';

@Controller()
export class AppController {
  constructor(
    @InjectTemporalClient() private readonly temporalClient: WorkflowClient,
  ) {}

  @Post()
  async greeting() {
    const handle = await this.temporalClient.start('example', {
      args: ['Temporal'],
      taskQueue: 'default',
      workflowId: 'wf-id-' + Math.floor(Math.random() * 1000),
    });
    console.log(`Started workflow ${handle.workflowId}`);
  }
}

When setting up nestjs-temporal, you can provide connection settings using the SharedConnectionAsyncConfiguration interface. This allows you to define how the Temporal connection (of type NativeConnectionOptions) is instantiated, supporting standard NestJS provider patterns like useClass, useFactory, or useValue.

Common ways to provide the configuration include:

• useValue: Provide a static NativeConnectionOptions object.
• useClass: Provide a class that implements SharedConnectionConfigurationFactory.
• useFactory: Provide a function that returns NativeConnectionOptions or a Promise<NativeConnectionOptions>.
• useExisting: Reuse an existing provider that implements SharedConnectionConfigurationFactory.

// Example using useFactory
{ 
  useFactory: () => ({
    address: 'localhost:7233',
    // other NativeConnectionOptions from @temporalio/worker
  }),
  inject: [SomeOtherService]
}

// Example using useClass
class MyConnectionFactory implements SharedConnectionConfigurationFactory {
  async createSharedConfiguration(): Promise<NativeConnectionOptions> {
    return { address: 'localhost:7233' };
  }
}
// Then use: { useClass: MyConnectionFactory }

When setting up a shared Temporal worker in NestJS, use the SharedWorkerAsyncConfiguration interface to define how the worker's WorkerOptions (from @temporalio/worker) are provided. This follows standard NestJS dynamic module patterns. You can provide configuration via:

• useExisting: Reference an existing provider that implements SharedWorkerConfigurationFactory.
• useClass: Provide a class that implements SharedWorkerConfigurationFactory.
• useFactory: A factory function that returns WorkerOptions or a Promise<WorkerOptions>. You can use the inject array to provide dependencies to this factory.
• useValue: Provide a static WorkerOptions object directly.

Note that if you use useClass or useExisting, the provider must implement the SharedWorkerConfigurationFactory interface.

// Example using useFactory
const workerConfig: SharedWorkerAsyncConfiguration = {
  useFactory: (someService: MyService) => {
    return {
      // ... WorkerOptions from @temporalio/worker
      taskQueue: 'my-queue',
    };
  },
  inject: [MyService],
};

// Example using useValue
const staticConfig: SharedWorkerAsyncConfiguration = {
  useValue: {
    taskQueue: 'my-queue',
  },
};

Use createClientProviders to generate an array of NestJS Provider objects. This is useful when you need to support multiple Temporal connections or different workflow configurations within the same NestJS application.

Each object in the input options array results in a separate provider. The provider is identified by a token generated via getQueueToken(option?.name), allowing you to inject specific clients using their unique name.

import { createClientProviders } from '@nestjs/temporal';
import { TemporalModuleOptions } from './interfaces';

const clientOptions: TemporalModuleOptions[] = [
  {
    name: 'primary',
    connection: { address: 'localhost:7233' },
    workflowOptions: { taskQueue: 'primary-queue' },
  },
  {
    name: 'secondary',
    connection: { address: 'other-host:7233' },
    workflowOptions: { taskQueue: 'secondary-queue' },
  },
];

const providers = createClientProviders(clientOptions);
// These providers can then be used in a NestJS Module's 'providers' array