/temporal-samples-typescript

Primary LanguageTypeScriptOtherNOASSERTION

samples-typescript

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:

Locally

Run Temporal Server:

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

Use Node version 14+:

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

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.
    • doSomethingAsync: Complete an Activity async with AsyncCompletionClient.
  • 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.
    • State: The Workflow maintains state in a Map<string, number>, and the state can be updated and read via a Signal and a Query.
    • 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.
  • Sinks: Use Sinks to extract data out of Workflows for alerting/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

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.

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

Updating to latest SDK version

lerna exec -- npm update

Upgrading the SDK version in package.jsons

npx zx .scripts/upgrade-versions.mjs 'VERSION_STRING_HERE'
npm run format

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.