Client Usage

Learn how to use the typed client to execute workflows with full type safety.

Overview

The @temporal-contract/client package provides a type-safe wrapper around Temporal's client that enforces your contract definitions at compile time.

Installation

pnpm add @temporal-contract/client @swan-io/boxed

Basic Setup

import { Connection, Client } from "@temporalio/client";
import { TypedClient } from "@temporal-contract/client";
import { myContract } from "./contract";

// Connect to Temporal
const connection = await Connection.connect({
  address: "localhost:7233",
});

// Create Temporal client and typed client
const temporalClient = new Client({ connection });
const client = TypedClient.create(myContract, temporalClient);

Executing Workflows

Basic Execution

Execute a workflow and wait for completion using the Result/Future pattern:

const future = client.executeWorkflow("processOrder", {
  workflowId: "order-123",
  args: {
    orderId: "ORD-123",
    customerId: "CUST-456",
  },
});

// await the Future to get the Result
const result = await future;

// Handle the Result with pattern matching
result.match({
  Ok: (output) => {
    console.log("Order processed:", output.status); // TypeScript knows the shape!
  },
  Error: (error) => {
    console.error("Workflow failed:", error);
  },
});

Start Without Waiting

Start a workflow without waiting for completion:

const handleResult = await client.startWorkflow("processOrder", {
  workflowId: "order-123",
  args: {
    orderId: "ORD-123",
    customerId: "CUST-456",
  },
});

handleResult.match({
  Ok: async (handle) => {
    // Get workflow ID
    console.log("Started workflow:", handle.workflowId);

    // Wait for result later
    const result = await handle.result();
    result.match({
      Ok: (output) => console.log("Completed:", output),
      Error: (error) => console.error("Failed:", error),
    });
  },
  Error: (error) => {
    console.error("Failed to start workflow:", error);
  },
});

Type Safety

The typed client provides compile-time safety:

// ✅ Correct - TypeScript validates args
await client.executeWorkflow("processOrder", {
  workflowId: "order-123",
  args: {
    orderId: "ORD-123",
    customerId: "CUST-456",
  },
});

// ❌ Error - Missing required field
await client.executeWorkflow("processOrder", {
  workflowId: "order-123",
  args: {
    orderId: "ORD-123",
    // customerId is missing - TypeScript error!
  },
});

// ❌ Error - Wrong workflow name
await client.executeWorkflow("invalidWorkflow", {
  workflowId: "order-123",
  args: {
    /* ... */
  },
});

Result/Future Pattern

The client uses @swan-io/boxed for explicit error handling:

import { Result } from "@swan-io/boxed";

const result = await client.executeWorkflow("processOrder", {
  workflowId: "order-123",
  args: { orderId: "ORD-123", customerId: "CUST-456" },
});

// Handle result with pattern matching
result.match({
  Ok: (value) => {
    console.log("Order processed:", value.transactionId);
  },
  Error: (error) => {
    console.error("Order failed:", error);
  },
});

Workflow Options

Pass standard Temporal workflow options:

await client.executeWorkflow("processOrder", {
  workflowId: "order-123",
  args: { orderId: "ORD-123", customerId: "CUST-456" },

  // Standard Temporal options
  taskQueue: "orders", // Override task queue
  workflowExecutionTimeout: "1 hour",
  workflowRunTimeout: "30 minutes",
  retry: {
    maximumAttempts: 3,
  },
  memo: {
    description: "Customer order processing",
  },
  searchAttributes: {
    CustomerId: ["CUST-456"],
  },
});

Getting Workflow Handle

Get a handle to an existing workflow:

const handle = client.getHandle("order-123");

// Query the workflow
const status = await handle.query("getStatus");

// Signal the workflow
await handle.signal("cancelOrder", { reason: "Customer request" });

// Get the result
const result = await handle.result();

Multiple Workflows

The same client can execute any workflow in the contract:

const orderResult = await client.executeWorkflow("processOrder", {
  workflowId: "order-123",
  args: { orderId: "ORD-123", customerId: "CUST-456" },
});

const refundResult = await client.executeWorkflow("processRefund", {
  workflowId: "refund-123",
  args: { orderId: "ORD-123", reason: "Damaged item" },
});

Error Handling

Workflow Execution Errors

const result = await client.executeWorkflow("processOrder", {
  workflowId: "order-123",
  args: { orderId: "ORD-123", customerId: "CUST-456" },
});

result.match({
  Ok: (value) => console.log("Success:", value),
  Error: (error) => console.error("Workflow returned error:", error),
});

Workflow Failures

import { WorkflowFailedError } from "@temporalio/client";

try {
  await client.executeWorkflow("processOrder", {
    workflowId: "order-123",
    args: { orderId: "ORD-123", customerId: "CUST-456" },
  });
} catch (error) {
  if (error instanceof WorkflowFailedError) {
    console.error("Workflow failed:", error.message);
    console.error("Cause:", error.cause);
  }
}

Connection Management

Single Connection

Reuse connections across clients:

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

const temporalClient = new Client({ connection });

const orderClient = TypedClient.create(orderContract, temporalClient);
const inventoryClient = TypedClient.create(inventoryContract, temporalClient);

// Both clients share the same connection and Temporal client instance

Connection Pooling

For high-throughput applications:

const connection = await Connection.connect({
  address: "localhost:7233",
  // Connection pool settings
  maxConcurrentWorkflowTaskPollers: 10,
  maxConcurrentActivityTaskPollers: 20,
});

Closing Connections

// Close connection when done
await connection.close();

Working with Multiple Contracts

Different clients for different contracts:

import { orderContract } from "./contracts/order";
import { paymentContract } from "./contracts/payment";
import { inventoryContract } from "./contracts/inventory";

const temporalClient = new Client({ connection });

const orderClient = TypedClient.create(orderContract, temporalClient);
const paymentClient = TypedClient.create(paymentContract, temporalClient);
const inventoryClient = TypedClient.create(inventoryContract, temporalClient);

// Each client is typed to its contract
await orderClient.executeWorkflow("processOrder", {
  /* ... */
});
await paymentClient.executeWorkflow("processPayment", {
  /* ... */
});
await inventoryClient.executeWorkflow("updateStock", {
  /* ... */
});

Testing

Mock the client for testing:

import { describe, it, expect, vi } from "vitest";
import { Result } from "@swan-io/boxed";

describe("OrderService", () => {
  it("should process order", async () => {
    const mockClient = {
      executeWorkflow: vi
        .fn()
        .mockResolvedValue(Result.Ok({ status: "success", transactionId: "tx-123" })),
    };

    const service = new OrderService(mockClient);
    const result = await service.createOrder({
      orderId: "ORD-123",
      customerId: "CUST-456",
    });

    expect(mockClient.executeWorkflow).toHaveBeenCalledWith(
      "processOrder",
      expect.objectContaining({
        args: { orderId: "ORD-123", customerId: "CUST-456" },
      }),
    );
  });
});

Best Practices

1. Reuse Connections

// ✅ Good - single connection
const connection = await Connection.connect({ address: "localhost:7233" });
const temporalClient = new Client({ connection });
const client = TypedClient.create(contract, temporalClient);

// ❌ Avoid - creating connections repeatedly
for (const order of orders) {
  const connection = await Connection.connect({ address: "localhost:7233" });
  const temporalClient = new Client({ connection });
  const client = TypedClient.create(contract, temporalClient);
  await client.executeWorkflow(/* ... */);
}

2. Use Meaningful Workflow IDs

// ✅ Good - descriptive and unique
workflowId: `order-${orderId}-${Date.now()}`;

// ❌ Avoid - random or non-descriptive
workflowId: Math.random().toString();

3. Handle Both Success and Error Cases

// ✅ Good - handle all cases
const result = await client.executeWorkflow("processOrder", {
  workflowId: "order-123",
  args: { orderId: "ORD-123", customerId: "CUST-456" },
});

result.match({
  Ok: (value) => {
    // Handle success
    updateDatabase(value);
  },
  Error: (error) => {
    // Handle error
    logError(error);
    notifySupport(error);
  },
});

See Also

• Defining Contracts - Creating your contract definitions
• Worker Usage - Implementing workflows and activities
• Result Pattern - Understanding Result/Future error handling
• API Reference - Complete client API documentation