Temporal TypeScript SDK

The Temporal TypeScript SDK is modular. Depending on whether you are running code in a Worker, a Workflow, or interacting with the Temporal Server, you will need to import specific packages:

• @temporalio/worker: Use this to run Workflows and Activities.
• @temporalio/workflow: Use this as the workflow runtime library (code that runs inside a Workflow).
• @temporalio/activity: Use this to access the current Activity's context.
• @temporalio/client: Use this to send commands to the Temporal Server (e.g., starting workflows, querying status).
• @temporalio/nexus: Use this to implement and invoke Nexus Operations.
• @temporalio/common: Provides shared utilities used across Client, Worker, and Workflow code.
• @temporalio/proto: Contains compiled protobuf definitions.
• @temporalio/testing: Provides the framework for testing Temporal code.
• @temporalio/interceptors-opentelemetry: Provides interceptors for adding OpenTelemetry tracing to your Temporal application.

The Temporal SDK generates GCS object names using a consistent format.

Object Name Formats

• Workflow: v0/ns/{namespace}/wt/{workflow-type}/wi/{workflow-id}/ri/{run-id}/d/{hash-algorithm}/{hex-digest}
• Activity: v0/ns/{namespace}/at/{activity-type}/ai/{activity-id}/ri/{run-id}/d/{hash-algorithm}/{hex-digest}
• Fallback: v0/d/{hash-algorithm}/{hex-digest} (used when namespace, workflow, or activity info is unavailable)

Encoding Rules

To ensure compatibility with Google Cloud Storage, the SDK percent-encodes the following:

• Control characters (U+0000–U+001F, U+007F–U+009F)
• The discouraged set: # [ ] * ? : " < > |
• Forward slash (/) to prevent unintended path segments
• Percent (%) to ensure reversible encoding
• Reserved segments . and .. are encoded as %2E and %2E%2E respectively.

Missing values (like a missing run-id) are encoded as null.

The bridge uses BridgeError and the BridgeResult<T> type alias as the standard way to report and propagate errors.

Key Advantages of BridgeError:

• Encapsulation: It can wrap a Throw object, allowing errors to propagate through non-JS-aware functions before being rethrown.
• Thread Safety: Errors can be sent across threads and converted to a Throw object once they reach a JS-aware parent.
• Automatic JS Mapping: The JS Error type is automatically determined based on the BridgeError variant.
• Context Enrichment: You can add context to errors as they propagate.

Best Practices for Error Context:

• Use .field() for object paths: When accessing properties, use .field("propertyName") to prepend the path. This results in clear error messages like fn some_func.args[4].foo.bar: ....
• Use .context() for foreign errors: When wrapping errors from other sources or propagating them up the stack, use .context("description") to provide additional information.

// Adding field context
fn get_user_field(id: u64) -> BridgeResult<User> {
    find_user(id).map_err(|e| e.field("user"))
}

// Adding general context
fn process() -> BridgeResult<()> {
    do_work().context("failed to process task")
}

The bridge layer is organized to facilitate side-by-side comparison between Rust and TypeScript definitions to ensure type safety across the boundary.

Rust Side Organization

• API Functions and Types: Defined in core-bridge/src/ (e.g., client.rs, worker.rs).
• Configuration: Component-specific configuration types are grouped in a nested config submodule within the component's file.
• Helpers: Abstractions are located in the helpers module, with some functionality provided via Derive Macros in the bridge-macros crate.

TypeScript Side Organization

• API Declarations: Functions and types are declared in core-bridge/ts/native.ts.

Naming and Ordering Conventions

To simplify review and maintain consistency:

• Naming: API entrypoint functions use component-specific prefixes (e.g., client_new, worker_poll_activity_task). Function names use snake_case in Rust and camelCase in TypeScript.
• Ordering: Functions, types, and properties should be listed in the same order in both Rust and TypeScript to allow for easy side-by-side comparison.

To ensure type safety and prevent incoherency between JS and Rust, the bridge follows strict rules for optionality:

1. Represent Option<T> with null: In TypeScript, an Option<T> from Rust should be modeled as T | null. Use null to represent an intentionally unspecified value (None).
2. Avoid TypeScript optional properties: Never use the ? operator for properties on objects sent across the bridge (e.g., do not use someProperty?: number).
3. Explicitly set all properties: Every property expected by the Rust side must be present and set to a non-undefined value when sending objects to native code.

This design allows the bridge to distinguish between an intentionally unspecified value (null) and an unintentionally missing property (undefined).

// Correct TypeScript modeling for bridge objects
interface MyBridgeObject {
  someProperty: number | null; // Use | null, NOT someProperty?: number
}