Getting Started

Welcome to temporal-contract! This guide will help you get up and running with type-safe Temporal workflows.

What is temporal-contract?

temporal-contract is a TypeScript library that brings end-to-end type safety and automatic validation to Temporal.io workflows and activities. It uses a contract-first approach with Zod schemas to ensure your workflows are type-safe from definition to execution.

Why Use temporal-contract?

The Problem

Working with Temporal.io is powerful, but comes with challenges:

• No type safety — Workflow parameters and return types are loosely typed
• Manual validation — You need to validate inputs and outputs manually
• Runtime errors — Type mismatches are only caught at runtime
• Scattered definitions — Activity types are defined separately from workflows

The Solution

temporal-contract solves these problems by:

• ✅ 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 issues before runtime
• ✅ Better DX — Autocomplete, refactoring support, inline documentation

Installation

Install the required packages:

pnpm

pnpm add @temporal-contract/contract @temporal-contract/worker @temporal-contract/client
pnpm add zod @temporalio/client @temporalio/worker @temporalio/workflow

npm

npm install @temporal-contract/contract @temporal-contract/worker @temporal-contract/client
npm install zod @temporalio/client @temporalio/worker @temporalio/workflow

yarn

yarn add @temporal-contract/contract @temporal-contract/worker @temporal-contract/client
yarn add zod @temporalio/client @temporalio/worker @temporalio/workflow

Quick Start

Let's build a simple order processing workflow in 3 steps.

1. Define Your Contract

Create a contract that defines your workflow's interface:

// contract.ts
import { defineContract } from '@temporal-contract/contract';
import { z } from 'zod';

export const orderContract = defineContract({
  taskQueue: 'orders',

  // Global activities available to all workflows
  activities: {
    sendEmail: {
      input: z.object({
        to: z.string().email(),
        subject: z.string(),
        body: z.string()
      }),
      output: z.object({ sent: z.boolean() }),
    },
  },

  workflows: {
    processOrder: {
      input: z.object({
        orderId: z.string(),
        customerId: z.string()
      }),
      output: z.object({
        status: z.enum(['success', 'failed']),
        transactionId: z.string()
      }),

      // Workflow-specific activities
      activities: {
        processPayment: {
          input: z.object({
            customerId: z.string(),
            amount: z.number().positive()
          }),
          output: z.object({
            transactionId: z.string(),
            success: z.boolean()
          }),
        },
      },
    },
  },
});

2. Implement Activities & Workflows

Implement your activities and workflows with full type safety:

// activities.ts
import { declareActivitiesHandler, ActivityError } from '@temporal-contract/worker/activity';
import { Future, Result } from '@swan-io/boxed';
import { orderContract } from './contract';

export const activities = declareActivitiesHandler({
  contract: orderContract,
  activities: {
    sendEmail: async ({ to, subject, body }) => {
      // Full type safety - parameters are automatically typed!
      return Future.fromPromise(emailService.send({ to, subject, body }))
        .mapError((error) =>
          new ActivityError(
            'EMAIL_FAILED',
            error instanceof Error ? error.message : 'Failed to send email',
            error
          )
        )
        .mapOk(() => ({ sent: true }));
    },
    processPayment: async ({ customerId, amount }) => {
      // TypeScript knows the exact types
      return Future.fromPromise(paymentGateway.charge(customerId, amount))
        .mapError((error) =>
          new ActivityError(
            'PAYMENT_FAILED',
            error instanceof Error ? error.message : 'Payment failed',
            error
          )
        )
        .mapOk((txId) => ({ transactionId: txId, success: true }));
    },
  },
});

// workflows.ts
import { declareWorkflow } from '@temporal-contract/worker/workflow';
import { orderContract } from './contract';

export const processOrder = declareWorkflow({
  workflowName: 'processOrder',
  contract: orderContract,
  implementation: async ({ activities }, { orderId, customerId }) => {
    // Full autocomplete for activities and their parameters
    // Activities return plain values (Result is unwrapped internally)
    const payment = await activities.processPayment({
      customerId,
      amount: 100
    });

    await activities.sendEmail({
      to: customerId,
      subject: 'Order Confirmed',
      body: `Order ${orderId} processed`,
    });

    // Return plain object (not Result - network serialization requirement)
    return {
      status: payment.success ? 'success' : 'failed',
      transactionId: payment.transactionId,
    };
  },
});

3. Start Worker & Call from Client

Set up your worker and client:

// worker.ts
import { Worker } from '@temporalio/worker';
import { activities } from './activities';

const worker = await Worker.create({
  workflowsPath: require.resolve('./workflows'),
  activities,
  taskQueue: 'orders', // or activities.contract.taskQueue
});

await worker.run();

// client.ts
import { TypedClient } from '@temporal-contract/client';
import { Connection, Client } from '@temporalio/client';
import { orderContract } from './contract';

const connection = await Connection.connect({
  address: 'localhost:7233'
});

const temporalClient = new Client({ connection });
const client = TypedClient.create(orderContract, temporalClient);

// Fully typed workflow execution with Result/Future pattern
const future = client.executeWorkflow('processOrder', {
  workflowId: 'order-123',
  args: { orderId: 'ORD-123', customerId: 'CUST-456' },
});

const result = await future;

result.match({
  Ok: (output) => {
    console.log(output.status);  // 'success' | 'failed' — fully typed!
  },
  Error: (error) => {
    console.error('Workflow failed:', error);
  },
});

What's Next?

• 📚 Learn about Core Concepts
• 🔨 Explore Worker Implementation
• 📖 Check out Examples
• 🔍 Browse the API Reference