[Feature Request] Sticky Sessions Support in TypeScript SDK

[jinvillaz]

Proposal: Sticky Sessions Support in TypeScript SDK

Hi Temporal team,

First, thank you for all your work maintaining the Temporal SDKs — they’ve been incredibly helpful.

Context

In the Go SDK, Temporal supports sticky sessions (sticky execution), which ensures that all tasks of a workflow are executed on the same worker. This is especially important for workflows that maintain local state or process resources incrementally, such as downloading and processing a large file piece by piece.

Currently, the TypeScript SDK does not have this feature. If multiple workers are running, Temporal may distribute tasks of the same workflow across different workers, breaking workflows that depend on local state.
Even in the official documentation, it is mentioned that sticky sessions are the recommended way to handle this type of workflow, but the feature is only implemented in Go.

Proposed Solution

I have implemented a manual sticky execution mechanism in a NestJS project using the nestjs-temporal-core library and the TypeScript SDK.

The key components are:

1. WorkerRegistrationService – Registers workers, tracks workflow IDs, and manages worker availability.
2. HeartbeatService – Sends periodic heartbeats, detects dead workers, and cleans up workflows that are no longer running.
3. WorkflowBalancerService – Assigns workflows to available workers to ensure a workflow runs entirely on a single worker.

This approach currently runs in my own projects using a manual implementation in TypeScript, and it effectively ensures sticky execution for workflows that require it.

This implementation introduces the concept of worker capacity (maxCapacity) to limit the number of workflows a worker can handle simultaneously. In production environments, each worker runs on a host with finite CPU and memory. By tracking capacity manually, we ensure that workflows are only assigned
to workers with available resources, preventing overloading and maintaining predictable performance.
This complements sticky execution: even if all tasks of a workflow remain on a single worker, we still need to respect its capacity limits. My implementation checks if a workflow with the same workflowId is already running,
whether triggered manually or via a schedule, to prevent duplicate executions and ensure workflow consistency.

I propose to implement native sticky sessions in the TypeScript SDK, using this approach as a reference, so that it becomes an official feature that other developers can use easily without needing to implement it themselves.

Benefits

• Provides workflow consistency for workflows that rely on local state and makes sticky execution available as a native feature.
• Eliminates the need for users to manually track workers and workflow assignments.
• Brings the TypeScript SDK closer to feature parity with the Go SDK.
• Ensures predictable performance by respecting worker capacity limits.

I would love for this feature to be implemented, ideally based on the approach I have already implemented in my own project. If possible, I would be happy to create a PR to contribute this solution to the SDK.

Thank you for considering this proposal! Looking forward to your thoughts.

Regards
Jhonatan
jinvillaz@gmail.com