https://github.com/btravstack/temporal-contract
End-to-end type safety and automatic validation for workflows and activities
https://github.com/btravstack/temporal-contract
nodejs temporalio typescript validation zod
Last synced: 2 days ago
JSON representation
End-to-end type safety and automatic validation for workflows and activities
- Host: GitHub
- URL: https://github.com/btravstack/temporal-contract
- Owner: btravstack
- License: mit
- Created: 2025-12-07T19:51:21.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-06-27T00:04:02.000Z (2 days ago)
- Last Synced: 2026-06-27T00:07:11.451Z (2 days ago)
- Topics: nodejs, temporalio, typescript, validation, zod
- Language: TypeScript
- Homepage: https://btravstack.github.io/temporal-contract/
- Size: 1.96 MB
- Stars: 9
- Watchers: 1
- Forks: 3
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# temporal-contract
**Type-safe contracts for Temporal.io**
End-to-end type safety and automatic validation for workflows and activities
[](https://github.com/btravstack/temporal-contract/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@temporal-contract/contract)
[](https://www.npmjs.com/package/@temporal-contract/contract)
[](https://www.typescriptlang.org/)
[](https://opensource.org/licenses/MIT)
[**Documentation**](https://btravstack.github.io/temporal-contract) · [**Get Started**](https://btravstack.github.io/temporal-contract/guide/getting-started) · [**Examples**](https://btravstack.github.io/temporal-contract/examples/)
## Features
- ✅ **End-to-end type safety** — From contract to client, workflows, and activities
- ✅ **Automatic validation** — Zod schemas validate at all network boundaries
- ✅ **Compile-time checks** — TypeScript catches missing or incorrect implementations
- ✅ **Better DX** — Autocomplete, refactoring support, inline documentation
- ✅ **Child workflows** — Type-safe child workflow execution with unthrown's `AsyncResult`
- ✅ **Result pattern** — Explicit error handling without exceptions, powered by [unthrown](https://github.com/btravstack/unthrown)
- 🚧 **Nexus support** — Cross-namespace operations (planned for v0.5.0)
## Quick Example
```typescript
// Define contract once
const contract = defineContract({
taskQueue: "orders",
workflows: {
processOrder: {
input: z.object({ orderId: z.string() }),
output: z.object({ success: z.boolean() }),
activities: {
processPayment: {
input: z.object({ orderId: z.string() }),
output: z.object({ transactionId: z.string() }),
},
},
},
},
});
// Implement activities with unthrown's AsyncResult
import { declareActivitiesHandler, ApplicationFailure } from "@temporal-contract/worker/activity";
import { fromPromise } from "unthrown";
const activities = declareActivitiesHandler({
contract,
activities: {
processPayment: ({ orderId }) =>
fromPromise(paymentService.process(orderId), (error) =>
ApplicationFailure.create({
type: "PAYMENT_FAILED",
message: error instanceof Error ? error.message : "Payment failed",
...(error instanceof Error ? { cause: error } : {}),
}),
).map((txId) => ({ transactionId: txId })),
},
});
// Call from client - fully typed everywhere
const result = await client.executeWorkflow("processOrder", {
workflowId: "order-123",
args: { orderId: "ORD-123" }, // ✅ TypeScript knows!
});
```
## Installation
```bash
# Core packages
pnpm add @temporal-contract/contract @temporal-contract/worker @temporal-contract/client
# Result/AsyncResult — peer dep used by worker/client APIs
pnpm add unthrown
```
## Documentation
📖 **[Read the full documentation →](https://btravstack.github.io/temporal-contract)**
- [Getting Started](https://btravstack.github.io/temporal-contract/guide/getting-started)
- [Core Concepts](https://btravstack.github.io/temporal-contract/guide/core-concepts)
- [API Reference](https://btravstack.github.io/temporal-contract/api/)
- [Examples](https://btravstack.github.io/temporal-contract/examples/)
## Packages
| Package | Description |
| -------------------------------------------------- | ------------------------------------------ |
| [@temporal-contract/contract](./packages/contract) | Contract builder and type definitions |
| [@temporal-contract/worker](./packages/worker) | Type-safe worker with automatic validation |
| [@temporal-contract/client](./packages/client) | Type-safe client for consuming workflows |
| [@temporal-contract/testing](./packages/testing) | Testing utilities for integration tests |
## Usage Patterns
temporal-contract uses **[unthrown](https://github.com/btravstack/unthrown)** end-to-end (workflows, activities, and the typed client) for explicit error handling via `Result` and `AsyncResult`, with a separate `defect` channel for unanticipated failures. Migrating from a previous release that used `neverthrow`? See [Migrating to unthrown](https://btravstack.github.io/temporal-contract/guide/migrating-to-unthrown).
## Contributing
See [CONTRIBUTING.md](https://github.com/btravstack/temporal-contract/blob/main/CONTRIBUTING.md).
## License
MIT