samples-typescript

• Running
  • In browser
  • Locally
  • Scaffold
• Samples
  • Basic
  • API demos
    • Activity APIs and design patterns
    • Workflow APIs
    • Production APIs
    • Advanced APIs
    • Test APIs
  • Full-stack apps
• External apps & libraries
• Contributing
  • Upgrading the SDK version
  • Config files

Each directory in this repo is a sample Temporal project built with the TypeScript SDK (see docs and API reference).

Running

In browser

The fastest way to try out these samples is running them in the browser:

• Gitpod: One click to try (there is a good free tier)
• GitHub Codespaces (if your org admin has enabled this) - 90 second video demo

Locally

Run Temporal Server:

git clone https://github.com/temporalio/docker-compose.git temporal
cd temporal
docker-compose up -d

Use Node version 14+:

• Install Node 16:
  • Mac: brew install node@16
  • Other: nodejs.org/en/download/
• Or use a Node version manager: fnm

Run the hello-world sample:

git clone https://github.com/temporalio/samples-typescript.git
cd samples-typescript/hello-world
npm i
npm start

and in another terminal:

npm run workflow

Scaffold

To scaffold a new project from one of these samples, run:

npx @temporalio/create@latest my-project --sample sample-name

or:

npx @temporalio/create@latest my-project

and you'll be given the list of sample options.

Samples

Basic

• Basic hello world: Simple example of a Workflow Definition and an Activity Definition.
  • Variant: Basic hello world with mTLS shows how to connect to your Temporal Cloud namespace with mTLS authentication.
• Pure ES Modules: Configure Temporal with TypeScript and Pure ESM.
• JavaScript: The Hello World sample in JavaScript instead of TypeScript.

API demos

Activity APIs and design patterns

• Activities Examples:
  • makeHTTPRequest: Make an external HTTP request in an Activity (using axios)
  • cancellableFetch: Make a cancellable HTTP request with cancellationSignal.
• Activity Cancellation and Heartbeating: Heartbeat progress for long running activities and cancel them.
• Dependency Injection: Share dependencies between activities (for example, when you need to initialize a database connection once and then pass it to multiple activities).
• Sticky Activities: Use a unique task queue per Worker to have certain Activities only run on that specific Worker. For instance for a file processing Workflow, where the first Activity is downloading a file, and subsequent Activities need to operate on that file. (And if multiple Workers are on the same queue, subsequent Activities may be run on a different machine that doesn't have the downloaded file.)

Workflow APIs

• Timers:
  • The progress example demonstrates how to use the sleep function from @temporalio/workflow.
  • Timer Examples:
    • Send a notification to the customer if their order is taking longer than expected (using a Promise.race between the order activity and sleep).
    • Create an UpdatableTimer that can be slept on, and at the same time, have its duration updated via Signals.
• Signals and Triggers:
  • The Signals and Queries example demonstrates the usage of Signals, Queries, and Workflow Cancellation.
  • Async activity completion: Example of an Expense reporting Workflow that communicates with a server API. Shows how to kick off a Workflow and manually complete it at an arbitrarily later date.
• Cron Workflows: Schedule a cron job.
• Child Workflows: Start and control Child Workflows.
• Infinite Workflows: Use the continueAsNew API for indefinitely long running Workflows.
• Search Attributes: Create, set, upsert, and read Search Attributes.
• Subscriptions

Production APIs

• Production Build: Build code in advance for faster Worker startup times.
• Debugging: The replay-history sample shows how to retrieve Workflow Event History and debug it using the runReplayHistory Worker API (video).
• Patching: Patch in new Workflow code when making updates to Workflows that have executions in progress in production.
• Logging: Use Sinks to extract data out of Workflows for logging/metrics/tracing purposes.
• Instrumentation: Use a winston logger to get logs out of all SDK components and get metrics and traces out of Rust Core.
• Protobufs: Use Protobufs.
• Custom Payload Converter: Customize data serialization by creating a PayloadConverter that uses EJSON to convert Dates, binary, and regexes.

Advanced APIs

• Interceptors
  • OpenTelemetry: Use the Interceptors feature to add OpenTelemetry metrics reporting to your workflows.
  • Query Subscriptions: Use Redis Streams, Immer, and SDK Interceptors to subscribe to Workflow state.
• gRPC calls: Make raw gRPC calls for advanced queries not covered by the WorkflowClient API.

Test APIs

• Mocha and Jest
• Time skipping

Full-stack apps

• Next.js:
  • One-click e-commerce: Buy an item with one click, and the Workflow will wait 5 seconds to see if the user cancels before it executes the order.

External apps & libraries

The below projects are maintained outside this repo and may not be up to date.

• Express:
  • vkarpov15/temporal-ecommerce-ts: The cartWorkflow used in this blog series
  • temporal-rest: Express middleware router that automatically exposes endpoints for Workflows, Signals, and Queries.
• Remix:
  • gustavofsantos/temporal-survey
• NestJS:
  • nestjs-temporal
• Chatbots:
  • JoshuaKGoldberg/temporal-adventure-bot: Choose-your-own-adventure Slack/Discord chatbot (see tutorial and video)
• Caching:
  • vkarpov15/temporal-api-caching-example: Cache data from a third-party API (see blog post)
• DSL Control Flows:
  • YAML DSL Interpreter: Make Workflows interpret a custom YAML-based Domain Specific Language of your design.
  • XState Interpreter: Interpret XState state charts in a Workflow. Presented at the November 2021 meetup.
• URL Scraping
  • andreasasprou/temporal-url-batch-scraping
• Polyglot:
  • temporalio/temporal-pendulum: Use TS alongside other languages

Contributing

External contributions are very welcome! 🤗 (Big thank you to those who have already contributed 🙏)

Before submitting a major PR, please find consensus on it in Issues.

To get started developing, run:

git clone https://github.com/temporalio/samples-typescript.git
cd samples-typescript
npm install
npm run prepare
npm run bootstrap

Prettier and ESLint are run on each commit, but you can also run them manually:

npm run format
npm run lint

Upgrading the SDK version

npx zx .scripts/upgrade-versions.mjs 'VERSION_STRING_HERE'

Config files

Also on each commit, config files from .shared/ are copied into each sample directory, overwriting the sample directory's config files (with a few exceptions listed in .scripts/copy-shared-files.mjs). So if you're editing config files, you usually want to be editing the versions in .shared/.

The .post-create file is a chalk template that is displayed in the command line after someone uses npx @temporalio/create. If you're adding a sample that requires different instructions from the default message, then add your sample name to POST_CREATE_EXCLUDE and your message template to your-sample/.post-create.