samples-typescript

Running
Samples
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

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

shopt -s extglob
for f in !(monorepo-folders)/package.json; do jq '.dependencies."@temporalio/client" = "NEW_VERSION_HERE"' $f | sponge $f; done
for f in !(monorepo-folders)/package.json; do jq '.dependencies."@temporalio/worker" = "NEW_VERSION_HERE"' $f | sponge $f; done
for f in !(monorepo-folders)/package.json; do jq '.dependencies."@temporalio/workflow" = "NEW_VERSION_HERE"' $f | sponge $f; done
for f in !(monorepo-folders)/package.json; do jq '.dependencies."@temporalio/activity" = "NEW_VERSION_HERE"' $f | sponge $f; done
jq '.dependencies."@temporalio/common" = "NEW_VERSION_HERE"' ejson/package.json | sponge ejson/package.json;
jq '.dependencies."@temporalio/common" = "NEW_VERSION_HERE"' encryption/package.json | sponge encryption/package.json;
jq '.dependencies."@temporalio/common" = "NEW_VERSION_HERE"' grpc-calls/package.json | sponge grpc-calls/package.json;
jq '.devDependencies."@temporalio/client" = "NEW_VERSION_HERE"' package.json | sponge package.json;
jq '.devDependencies."@temporalio/testing" = "NEW_VERSION_HERE"' activities-examples/package.json | sponge activities-examples/package.json;
jq '.devDependencies."@temporalio/testing" = "NEW_VERSION_HERE"' timer-examples/package.json | sponge timer-examples/package.json;
jq '.dependencies."@temporalio/interceptors-opentelemetry" = "NEW_VERSION_HERE"' interceptors-opentelemetry/package.json | sponge interceptors-opentelemetry/package.json;
jq '.dependencies."@temporalio/client" = "NEW_VERSION_HERE"' monorepo-folders/packages/backend-apis/package.json | sponge monorepo-folders/packages/backend-apis/package.json;
jq '.dependencies."@temporalio/worker" = "NEW_VERSION_HERE"' monorepo-folders/packages/temporal-worker/package.json | sponge monorepo-folders/packages/temporal-worker/package.json;
jq '.dependencies."@temporalio/activity" = "NEW_VERSION_HERE"' monorepo-folders/packages/temporal-workflows/package.json | sponge monorepo-folders/packages/temporal-workflows/package.json;
jq '.dependencies."@temporalio/workflow" = "NEW_VERSION_HERE"' monorepo-folders/packages/temporal-workflows/package.json | sponge monorepo-folders/packages/temporal-workflows/package.json;

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.

jhecking / samples-typescript Goto Github PK