Add TypeScript (#31)

Adds initial support for TypeScript to the skill

---------

Co-authored-by: James Watkins-Harvey <mjameswh@users.noreply.github.com>
Co-authored-by: Chris Olszewski <chrisdolszewski@gmail.com>

Author: 3 people

SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: temporal-developer
-description: This skill should be used when the user asks to "create a Temporal workflow", "write a Temporal activity", "debug stuck workflow", "fix non-determinism error", "Temporal Python", "workflow replay", "activity timeout", "signal workflow", "query workflow", "worker not starting", "activity keeps retrying", "Temporal heartbeat", "continue-as-new", "child workflow", "saga pattern", "workflow versioning", "durable execution", "reliable distributed systems", or mentions Temporal SDK development.
+description: This skill should be used when the user asks to "create a Temporal workflow", "write a Temporal activity", "debug stuck workflow", "fix non-determinism error", "Temporal Python", "Temporal TypeScript", "workflow replay", "activity timeout", "signal workflow", "query workflow", "worker not starting", "activity keeps retrying", "Temporal heartbeat", "continue-as-new", "child workflow", "saga pattern", "workflow versioning", "durable execution", "reliable distributed systems", or mentions Temporal SDK development.
 version: 1.0.0
 ---
 
 # Skill: temporal-developer
 
 ## Overview
 
-Temporal is a durable execution platform that makes workflows survive failures automatically. This skill provides guidance for building Temporal applications in Python.
+Temporal is a durable execution platform that makes workflows survive failures automatically. This skill provides guidance for building Temporal applications in Python and TypeScript.
 
 ## Core Architecture
 
@@ -91,6 +91,7 @@ Once you've downloaded the file, extract the downloaded archive and add the temp
 
 1. First, read the getting started guide for the language you are working in:
     - Python -> read `references/python/python.md`
+    - TypeScript -> read `references/typescript/typescript.md`
 2. Second, read appropriate `core` and language-specific references for the task at hand.
 
 
@@ -108,7 +109,7 @@ Once you've downloaded the file, extract the downloaded archive and add the temp
 - **`references/core/interactive-workflows.md`** - Testing signals, updates, queries
 - **`references/core/dev-management.md`** - Dev cycle & management of server and workers
 - **`references/core/ai-patterns.md`** - AI/LLM pattern concepts
-    + Langauge-specific info at `references/{your_language}/determinism.md`
+    + Language-specific info at `references/{your_language}/determinism.md`, if available. Currently Python only.
 
 ## Additional Topics
 - **`references/{your_langauge}/observability.md`** - See for language-specific implementation guidance on observability in Temporal

references/core/determinism.md

@@ -79,6 +79,7 @@ For a few simple cases, like timestamps, random values, UUIDs, etc. the Temporal
 Each Temporal SDK language provides a protection mechanism to make it easier to catch non-determinism errors earlier in development:
 
 - Python: The Python SDK runs workflows in a sandbox that intercepts and aborts non-deterministic calls at runtime.
+- TypeScript: The TypeScript SDK runs workflows in an isolated V8 sandbox, intercepting many common sources of non-determinism and replacing them automatically with deterministic variants.
 
 
 ## Detecting Non-Determinism

references/core/gotchas.md

@@ -150,3 +150,47 @@ See language-specific gotchas for details.
 **The Fix**:
 - **Retryable**: Network errors, timeouts, rate limits, temporary unavailability
 - **Non-retryable**: Invalid input, authentication failures, business rule violations, resource not found
+
+## Cancellation Handling
+
+### Not Handling Workflow Cancellation
+
+**The Problem**: When a workflow is cancelled, cleanup code after the cancellation point doesn't run unless explicitly protected.
+
+**Symptoms**:
+- Resources not released after cancellation
+- Incomplete compensation/rollback
+- Leaked state
+
+**The Fix**: Use language-specific cancellation scopes or try/finally blocks to ensure cleanup runs even on cancellation. See language-specific gotchas for implementation details.
+
+### Not Handling Activity Cancellation
+
+**The Problem**: Activities must opt in to receive cancellation. Without proper handling, a cancelled activity continues running to completion, wasting resources.
+
+**Requirements for activity cancellation**:
+1. **Heartbeating** - Cancellation is delivered via heartbeat. Activities that don't heartbeat won't know they've been cancelled.
+2. **Checking for cancellation** - Activity must explicitly check for cancellation or await a cancellation signal.
+
+**Symptoms**:
+- Cancelled activities running to completion
+- Wasted compute on work that will be discarded
+- Delayed workflow cancellation
+
+**The Fix**: Heartbeat regularly and check for cancellation. See language-specific gotchas for implementation patterns.
+
+## Payload Size Limits
+
+**The Problem**: Temporal has built-in limits on payload sizes. Exceeding them causes workflows to fail.
+
+**Limits**:
+- Max 2MB per individual payload
+- Max 4MB per gRPC message
+- Max 50MB for complete workflow history (aim for <10MB in practice)
+
+**Symptoms**:
+- Payload too large errors
+- gRPC message size exceeded errors
+- Workflow history growing unboundedly
+
+**The Fix**: Store large data externally (S3/GCS) and pass references, use compression codecs, or chunk data across multiple activities. See the Large Data Handling pattern in `references/core/patterns.md`.

references/core/patterns.md

@@ -331,6 +331,80 @@ Run:
 
 This ensures that on replay, already-completed steps are skipped.
 
+## Large Data Handling
+
+**Purpose**: Handle data that exceeds Temporal's payload limits without polluting workflow history.
+
+**Limits** (see `references/core/gotchas.md` for details):
+- Max 2MB per individual payload
+- Max 4MB per gRPC message
+- Max 50MB for workflow history (aim for <10MB)
+
+**Key Principle**: Large data should never flow through workflow history. Activities read and write large data directly, passing only small references through the workflow.
+
+**Wrong Approach**:
+```
+Workflow
+    │
+    ├── downloadFromStorage(ref) ──▶ returns large data (enters history)
+    │
+    ├── processData(largeData) ────▶ large data as argument (enters history AGAIN)
+    │
+    └── uploadToStorage(result) ───▶ large data as argument (enters history AGAIN)
+```
+
+This defeats the purpose—large data enters workflow history multiple times.
+
+**Correct Approach**:
+```
+Workflow
+    │
+    └── processLargeData(inputRef) ──▶ returns outputRef (small string)
+                │
+                └── Activity internally:
+                        download(inputRef) → process → upload → return outputRef
+```
+
+The workflow only handles references (small strings). The activity does all large data operations internally.
+
+**Implementation Pattern**:
+1. Accept a reference (URL, S3 key, database ID) as activity input
+2. Download/fetch the large data inside the activity
+3. Process the data inside the activity
+4. Upload/store the result inside the activity
+5. Return only a reference to the result
+
+**Other Strategies**:
+- **Compression**: Use a PayloadCodec to compress data automatically
+- **Chunking**: Split large collections across multiple activities, each handling a subset
+
+## Activity Heartbeating
+
+**Purpose**: Enable cancellation delivery and progress tracking for long-running activities.
+
+**Why Heartbeat**:
+1. **Support activity cancellation** - Cancellations are delivered to activities via heartbeat. Activities that don't heartbeat won't know they've been cancelled.
+2. **Resume progress after failure** - Heartbeat details persist across retries, allowing activities to resume where they left off.
+3. **Detect stuck activities** - If an activity stops heartbeating, Temporal can time it out and retry.
+
+**How Cancellation Works**:
+```
+Workflow requests activity cancellation
+    │
+    ▼
+Temporal Service marks activity for cancellation
+    │
+    ▼
+Activity calls heartbeat()
+    │
+    ├── Not cancelled: heartbeat succeeds, continues
+    │
+    └── Cancelled: heartbeat raises exception
+            Activity can catch this to perform cleanup
+```
+
+**Key Point**: If an activity never heartbeats, it will run to completion even if cancelled—it has no way to learn about the cancellation.
+
 ## Local Activities
 
 **Purpose**: Reduce latency for short, lightweight operations by skipping the task queue. ONLY use these when necessary for performance. Do NOT use these by default, as they are not durable and distributed.

references/core/versioning.md

@@ -53,17 +53,21 @@ else:
 
 ### When to Use
 
-- Adding new activities or steps
-- Changing activity parameters
-- Reordering operations
-- Any change that would cause non-determinism
+- Adding, removing, or reordering activities/child workflows
+- Changing which activity/child workflow is called
+- Any change that alters the Command sequence
 
 ### When NOT to Use
 
-- Changes to activity implementations (activities aren't replayed)
-- Adding new signal/query handlers (additive changes are safe)
+- Changing activity implementations (activities aren't replayed)
+- Changing arguments passed to activities or child workflows
+- Changing retry policies
+- Changing timer durations
+- Adding new signal/query/update handlers (additive changes are safe)
 - Bug fixes that don't change Command sequence
 
+Unnecessary patching adds complexity and can make workflow code unmanageable.
+
 ## Approach 2: Workflow Type Versioning
 
 ### Concept

references/python/data-handling.md

@@ -202,29 +202,6 @@ class OrderWorkflow:
         ...
 ```
 
-## Large Payloads
-
-For large data, consider:
-
-1. **Store externally**: Put large data in S3/GCS, pass references in workflows
-2. **Use Payload Codec**: Compress payloads automatically
-3. **Chunk data**: Split large lists across multiple activities
-
-```python
-# Example: Reference pattern for large data
-@activity.defn
-async def upload_to_storage(data: bytes) -> str:
-    """Upload data and return reference."""
-    key = f"data/{uuid.uuid4()}"
-    await storage_client.upload(key, data)
-    return key
-
-@activity.defn
-async def download_from_storage(key: str) -> bytes:
-    """Download data by reference."""
-    return await storage_client.download(key)
-```
-
 ## Deterministic APIs for Values
 
 Use these APIs within workflows for deterministic random values and UUIDs:
@@ -247,8 +224,7 @@ class MyWorkflow:
 ## Best Practices
 
 1. Use Pydantic for input/output validation
-2. Keep payloads small (< 2MB recommended)
+2. Keep payloads small—see `references/core/gotchas.md` for limits
 3. Encrypt sensitive data with PayloadCodec
-4. Store large data externally with references
-5. Use dataclasses for simple data structures
-6. Use `workflow.uuid4()` and `workflow.random()` for deterministic values
+4. Use dataclasses for simple data structures
+5. Use `workflow.uuid4()` and `workflow.random()` for deterministic values

references/python/gotchas.md

@@ -161,6 +161,83 @@ await workflow.execute_activity(
 )
 ```
 
+Set heartbeat timeout as high as acceptable for your use case — each heartbeat counts as an action.
+
+## Cancellation
+
+### Not Handling Workflow Cancellation
+
+```python
+# BAD - Cleanup doesn't run on cancellation
+@workflow.defn
+class BadWorkflow:
+    @workflow.run
+    async def run(self) -> None:
+        await workflow.execute_activity(
+            acquire_resource,
+            start_to_close_timeout=timedelta(minutes=5),
+        )
+        await workflow.execute_activity(
+            do_work,
+            start_to_close_timeout=timedelta(minutes=5),
+        )
+        await workflow.execute_activity(
+            release_resource,  # Never runs if cancelled!
+            start_to_close_timeout=timedelta(minutes=5),
+        )
+
+# GOOD - Use try/finally for cleanup
+@workflow.defn
+class GoodWorkflow:
+    @workflow.run
+    async def run(self) -> None:
+        await workflow.execute_activity(
+            acquire_resource,
+            start_to_close_timeout=timedelta(minutes=5),
+        )
+        try:
+            await workflow.execute_activity(
+                do_work,
+                start_to_close_timeout=timedelta(minutes=5),
+            )
+        finally:
+            # Runs even on cancellation
+            await workflow.execute_activity(
+                release_resource,
+                start_to_close_timeout=timedelta(minutes=5),
+            )
+```
+
+### Not Handling Activity Cancellation
+
+Activities must **opt in** to receive cancellation. This requires:
+1. **Heartbeating** - Cancellation is delivered via heartbeat
+2. **Catching the cancellation exception** - Exception is raised when heartbeat detects cancellation
+
+**Cancellation exceptions:**
+- Async activities: `asyncio.CancelledError`
+- Sync threaded activities: `temporalio.exceptions.CancelledError`
+
+```python
+# BAD - Activity ignores cancellation
+@activity.defn
+async def long_activity() -> None:
+    await do_expensive_work()  # Runs to completion even if cancelled
+```
+
+```python
+# GOOD - Heartbeat and catch cancellation
+@activity.defn
+async def long_activity() -> None:
+    try:
+        for item in items:
+            activity.heartbeat()
+            await process(item)
+    except asyncio.CancelledError:
+        await cleanup()
+        raise
+```
+
 ## Testing
 
 ### Not Testing Failures