Type-safe contracts for Temporal.io
End-to-end type safety and automatic validation for workflows and activities
- ✅ 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)
// 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, ActivityError } 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) =>
new ActivityError('PAYMENT_FAILED', 'Payment failed', 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!
});# Core packages
pnpm add @temporal-contract/contract @temporal-contract/worker @temporal-contract/client
# For NestJS integration
pnpm add @temporal-contract/worker-nestjs
# Result/Future pattern (already included in worker/client via @swan-io/boxed)
pnpm add @swan-io/boxed📖 Read the full documentation →
| Package | Description |
|---|---|
| @temporal-contract/contract | Contract builder and type definitions |
| @temporal-contract/worker | Type-safe worker with automatic validation (uses @swan-io/boxed for activities) |
| @temporal-contract/worker-nestjs | NestJS integration for type-safe workers with dependency injection |
| @temporal-contract/client | Type-safe client for consuming workflows (uses @swan-io/boxed) |
| @temporal-contract/boxed | Temporal-compatible Result/Future types for workflows (alternative to @swan-io) |
| @temporal-contract/testing | Testing utilities for integration tests |
temporal-contract uses @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.
See CONTRIBUTING.md.
MIT