temporalio

Temporal NodeJS SDK

Typescript + NodeJS SDK for Temporal.

!!! This is a work in progress, not ready for use yet !!!

For more information see the proposal.

• Getting started
  • Install system dependencies
  • Create a new project
  • Build everything
  • Run the Temporal server
  • Test your workflow
• Hello World
  • Activities and workflows
  • Worker and client
  • Logging
• Development
  • Environment set up
  • Building
  • Rebuilding (useful for after deleting Typescript files)
  • Building with watch (Typescript only)
  • Testing

Getting started

Install system dependencies

This project requires nodejs LTS version 12 (or later).

Furthermore, to install this module you will need a c++ compiler. If you run into errors during installation it is likely your environment is not properly set up.

The worker package embeds the Temporal Core SDK which requires the Rust toolchain to compile. We provided prebuilt binaries for the worker for:

• Mac with an Intel chip: x86_64-apple-darwin

• Mac with an M1 chip: aarch64-apple-darwin

• Linux with x86_64 architecture: x86_64-unknown-linux-gnu

• Windows with x86_64 architecture: x86_64-pc-windows-gnu

• If you need to compile the worker yourself, set up the Rust toolchain by following the instructions here.

• To set up a C++ compiler for node-gyp, follow the instuctions here

Create a new project

npm init @temporalio ./example
cd ./example

NOTE: init triggers native module compilation which might take a while, npm 7 hides the compilation output so it may appear that the installation is stuck, to see the compilation progress export NPM_CONFIG_FOREGROUND_SCRIPTS=true.

Build everything

npm run build

Run the Temporal server

Download, install, and run the Temporal server via docker-compose. It is easy to do and you can keep it running in the background while you build applications.

Test your workflow

• Run the worker

  node lib/worker/index.js
  

• Run the workflow

  node lib/worker/test.js
  

Hello World

Not working yet, activities not implemented

Activities and workflows

src/activities/greeter.ts

export async function greet(name: string): Promise<string> {
  return `Hello, ${name}!`;
}

src/interfaces/workflows.ts

import { Workflow } from '@temporalio/workflow';

export interface Example extends Workflow {
  main(name: string): Promise<string>;
}

src/workflows/example.ts

import { Example } from '@interfaces/workflows';
import { greet } from '@activities/greeter';

async function main(name: string): Promise<string> {
  return await greet(name);
}

export const workflow: Example = { main };

Worker and client

src/worker/index.ts

import { Worker } from '@temporalio/worker';

(async () => {
  // Automatically locate and register activities and workflows
  const worker = await Worker.create(__dirname);
  // Bind to the `tutorial` queue and start accepting tasks
  await worker.run('tutorial');
})();

src/worker/test.ts

import { Connection } from '@temporalio/client';
import { Example } from '@interfaces/workflows';

(async () => {
  const connection = new Connection();
  const example = connection.workflow<Example>('example', { taskQueue: 'tutorial' });
  const result = await example('Temporal');
  console.log(result); // Hello, Temporal
})();

Logging

See docs

Development

Environment set up

git submodule init
git submodule update
npm ci

Building

npm run build

Rebuilding (useful for after deleting Typescript files)

npm run rebuild

Building with watch (Typescript only)

npm run build  # Must be run once before build.watch
npm run build.watch

Testing

npm run test

-- OR --

npm run test.watch