https://github.com/btravers/temporal-contract
End-to-end type safety and automatic validation for workflows and activities
https://github.com/btravers/temporal-contract
nodejs temporalio typescript validation zod
Last synced: 9 days ago
JSON representation
End-to-end type safety and automatic validation for workflows and activities
- Host: GitHub
- URL: https://github.com/btravers/temporal-contract
- Owner: btravers
- License: mit
- Created: 2025-12-07T19:51:21.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-07T19:32:01.000Z (4 months ago)
- Last Synced: 2026-01-13T13:55:14.254Z (4 months ago)
- Topics: nodejs, temporalio, typescript, validation, zod
- Language: TypeScript
- Homepage: https://btravers.github.io/temporal-contract/
- Size: 688 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
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/btravers/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://btravers.github.io/temporal-contract) · [**Get Started**](https://btravers.github.io/temporal-contract/guide/getting-started) · [**Examples**](https://btravers.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 Result/Future pattern
- ✅ **Result/Future pattern** — Explicit error handling without exceptions
- 🚧 **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 Future/Result pattern
import { declareActivitiesHandler, ApplicationFailure } from "@temporal-contract/worker/activity";
import { Future } from "@swan-io/boxed";
const activities = declareActivitiesHandler({
contract,
activities: {
processPayment: ({ orderId }) => {
return Future.fromPromise(paymentService.process(orderId))
.mapError((error) =>
ApplicationFailure.create({
type: "PAYMENT_FAILED",
message: error instanceof Error ? error.message : "Payment failed",
...(error instanceof Error ? { cause: error } : {}),
}),
)
.mapOk((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/Future pattern (already included in worker/client via @swan-io/boxed)
pnpm add @swan-io/boxed
```
## Documentation
📖 **[Read the full documentation →](https://btravers.github.io/temporal-contract)**
- [Getting Started](https://btravers.github.io/temporal-contract/guide/getting-started)
- [Core Concepts](https://btravers.github.io/temporal-contract/guide/core-concepts)
- [API Reference](https://btravers.github.io/temporal-contract/api/)
- [Examples](https://btravers.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 (uses @swan-io/boxed for activities) |
| [@temporal-contract/client](./packages/client) | Type-safe client for consuming workflows (uses @swan-io/boxed) |
| [@temporal-contract/boxed](./packages/boxed) | Temporal-compatible Result/Future types for workflows (alternative to @swan-io) |
| [@temporal-contract/testing](./packages/testing) | Testing utilities for integration tests |
## Usage Patterns
temporal-contract uses **[@swan-io/boxed](https://github.com/swan-io/boxed)** for activities and clients, providing excellent error handling with Result/Future patterns. For workflows that require Temporal's deterministic execution, use **@temporal-contract/boxed** which provides a compatible API.
## Contributing
See [CONTRIBUTING.md](https://github.com/btravers/temporal-contract/blob/main/CONTRIBUTING.md).
## License
MIT