Temporal — CLAUDE.md

# Temporal TypeScript SDK — CLAUDE.md

## Key Concepts

- **Workflow**: Durable, fault-tolerant function. Must be deterministic.
- **Activity**: Non-deterministic I/O (API calls, DB queries). Called from workflows.
- **Worker**: Process that executes workflows and activities.
- **Signal**: Async message sent to a running workflow.
- **Query**: Sync read from a running workflow.

## Determinism Rules (Critical)

Workflow code MUST be deterministic:
- No `Math.random()`, `Date.now()`, or `new Date()`
- No direct network calls
- No file I/O
- Use `workflow.sleep()` instead of `setTimeout`
- Use `workflow.now()` for timestamps
- Use `workflow.uuid4()` for UUIDs

## Project Structure

```
src/
  workflows/    # Deterministic workflow definitions
  activities/   # Non-deterministic activity implementations  
  workers/      # Worker setup and registration
  client.ts     # Temporal client setup
```

## Development

```bash
npm install
# Start Temporal server (requires Docker)
temporal server start-dev

# Run worker
npm run worker

# Run tests
npm test
```

## Testing Workflows

- Use `TestWorkflowEnvironment` for unit tests.
- Mock activities in workflow tests.
- Use `env.sleep()` to advance time deterministically.

## Error Handling

- Activities auto-retry on failure by default.
- Set `maxAttempts` in `ActivityOptions` for bounded retries.
- Use `ApplicationFailure.nonRetryable()` for permanent failures.
- Workflows handle `CancelledFailure` for cancellation.