/samples-typescript

Primary LanguageTypeScript

samples-typescript

Samples

Each directory in this repo is a sample Temporal project built with the TypeScript SDK.

  • To try these samples without installing locally, you can try this out on Gitpod: Gitpod ready-to-code (there is a good free tier)
  • To run these samples locally, go through the prerequisites listed in our Getting Started docs.
  • To scaffold a new project from one of these samples, run: 
    npx @temporalio/create@latest my-project-name
# or npx @temporalio/create@latest my-project-name --sample sample-name

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.
  • 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: Dynamically assign task queue names to ensure activities execute sequentially on the same machine (eg for CI/CD, file processing workflows).

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: Set up Search Attributes (an experimental feature for now).

Production APIs

  • Production Build: Build code in advance for faster Worker startup times.
  • 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.

Advanced APIs

  • Interceptors
    • OpenTelemetry: Use the Interceptors feature to add OpenTelemetry metrics reporting to your workflows. ⚠️ This sample is broken for now.
    • Query Subscriptions: Use Redis Streams, Immer, and SDK Interceptors to subscribe to Workflow state.

Full Apps

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 start, run these commands in the root directory:

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

for f in */package.json; do jq '.dependencies.temporalio = "NEW_VERSION_HERE"' $f | sponge $f; done

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.