Result Pattern

Learn how to use explicit error handling with the Result/Future pattern.

Overview

temporal-contract uses the Result/Future pattern for explicit error handling. The implementation differs between activities and workflows:

• Activities and Clients: Use @swan-io/boxed - a battle-tested library with excellent performance
• Workflows: Use @temporal-contract/boxed - a Temporal-compatible implementation required for deterministic execution

Both packages provide the same API, making it easy to work with both.

Installation

# For activities and clients
pnpm add @swan-io/boxed

# For workflows (Temporal-compatible)
pnpm add @temporal-contract/boxed

Basic Usage

Activities (using @swan-io/boxed)

Activities use @swan-io/boxed for excellent performance and ecosystem compatibility:

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: {
    processPayment: ({ amount }) => {
      return Future.fromPromise(paymentGateway.charge(amount))
        .mapError(
          (error) =>
            new ActivityError(
              "PAYMENT_FAILED",
              error instanceof Error ? error.message : "Payment failed",
              error,
            ),
        )
        .mapOk((txId) => ({ transactionId: txId, success: true }));
    },

    sendEmail: ({ to, body }) => {
      return Future.fromPromise(emailService.send({ to, body }))
        .mapError(
          (error) =>
            new ActivityError(
              "EMAIL_FAILED",
              error instanceof Error ? error.message : "Email failed",
              error,
            ),
        )
        .mapOk(() => ({ sent: true }));
    },
  },
});

Workflows (using @temporal-contract/boxed)

Workflows require @temporal-contract/boxed for Temporal's deterministic execution:

import { declareWorkflow } from "@temporal-contract/worker/workflow";
import { Result } from "@temporal-contract/boxed";
import { orderContract } from "./contract";

export const processOrder = declareWorkflow({
  workflowName: "processOrder",
  contract: orderContract,
  implementation: async ({ activities }, { orderId, amount }) => {
    // Process payment - activities return plain values
    const payment = await activities.processPayment({ amount });

    // Send confirmation email
    await activities.sendEmail({
      to: "customer@example.com",
      body: `Order ${orderId} confirmed`,
    });

    return {
      success: true,
      transactionId: payment.transactionId,
    };
  },
});

Clients (using @swan-io/boxed)

Clients use @swan-io/boxed to handle workflow results:

import { TypedClient } from "@temporal-contract/client";
import { Result } from "@swan-io/boxed";
import { Client } from "@temporalio/client";
import { orderContract } from "./contract";

const temporalClient = new Client({ connection });

const client = TypedClient.create(orderContract, temporalClient);
const result = await client.executeWorkflow("processOrder", {
  workflowId: "order-123",
  args: { orderId: "ORD-123", amount: 100 },
});

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

Why Two Packages?

@swan-io/boxed (Activities & Clients)

• ✅ Battle-tested with extensive usage
• ✅ Excellent performance optimizations
• ✅ Large ecosystem support
• ✅ Works perfectly outside of Temporal workflows

@temporal-contract/boxed (Workflows)

• ✅ Temporal deterministic execution compatible
• ✅ Same API as @swan-io/boxed
• ✅ Designed specifically for workflow constraints
• ✅ Seamless interoperability with @swan-io/boxed

Interoperability

Both packages share the same API surface, so code is portable:

// Same API for both packages!
const result = Result.Ok(42);
const future = Future.value(42);

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

For explicit conversion between the two (rarely needed), see the @temporal-contract/boxed interop documentation.

Pattern Matching

Activities return plain values when called from workflows. If an activity fails, it will throw an error:

export const processOrder = declareWorkflow({
  workflowName: "processOrder",
  contract: orderContract,
  implementation: async ({ activities }, input) => {
    try {
      // Activity returns plain value (Result is unwrapped internally)
      const payment = await activities.processPayment({ amount: 100 });
      console.log("Payment succeeded:", payment.transactionId);

      return { success: true, transactionId: payment.transactionId };
    } catch (error) {
      // Activity errors are thrown
      console.error("Payment failed:", error);
      return { success: false, transactionId: "" };
    }
  },
});

NOTE

For child workflows, you do get Result objects. See the Child Workflows section below.

Chaining Activities

When calling multiple activities, use standard async/await with try/catch:

export const processOrder = declareWorkflow({
  workflowName: "processOrder",
  contract: orderContract,
  implementation: async ({ activities }, input) => {
    try {
      // Activities return plain values
      const payment = await activities.processPayment({ amount: 100 });

      // Next activity only runs if payment succeeded
      await activities.sendEmail({
        to: "customer@example.com",
        body: `Payment ${payment.transactionId} processed`,
      });

      // Update database
      await activities.updateDatabase({
        status: "completed",
      });

      return { success: true };
    } catch (error) {
      console.error("Workflow failed:", error);
      return { success: false };
    }
  },
});

Error Types

Define typed errors in your activities:

type PaymentError =
  | { type: "InsufficientFunds" }
  | { type: "CardDeclined" }
  | { type: "NetworkError"; message: string };

type EmailError = { type: "InvalidEmail" } | { type: "ServiceUnavailable" };

// Activities return Future with typed errors
processPayment: ({ amount }) => {
  return Future.fromPromise(paymentGateway.charge(amount))
    .mapError<ActivityError>((error) => {
      // Wrap domain errors in ActivityError for Temporal retry policies
      return new ActivityError(
        "PAYMENT_FAILED",
        error instanceof Error ? error.message : "Payment failed",
        error,
      );
    })
    .mapOk((txId) => ({ transactionId: txId }));
};

Benefits

1. Explicit Error Handling

Activities use the Result pattern internally, while workflows use try/catch:

// Activity implementation (uses Result pattern)
const processPayment = ({ amount }) => {
  return Future.fromPromise(paymentGateway.charge(amount))
    .mapError((error) => new ActivityError("PAYMENT_FAILED", "Payment failed", error))
    .mapOk((txId) => ({ transactionId: txId }));
};

// Workflow (uses standard try/catch for activities)
export const processOrder = declareWorkflow({
  workflowName: "processOrder",
  contract: myContract,
  implementation: async ({ activities }, input) => {
    try {
      // Activity returns plain value
      const payment = await activities.processPayment({ amount: 100 });
      return { success: true, transactionId: payment.transactionId };
    } catch (error) {
      // Handle activity error
      return { success: false };
    }
  },
});

2. No Hidden Exceptions in Activities

Activities explicitly return Results instead of throwing:

// ✅ Clear - activity returns Future<Result>
const processPayment = ({ amount }) => {
  return Future.fromPromise(paymentGateway.charge(amount))
    .mapError((error) => new ActivityError("PAYMENT_FAILED", "Payment failed", error))
    .mapOk((txId) => ({ transactionId: txId }));
};

// ❌ Unclear - might throw anything
async function processPayment({ amount }) {
  const txId = await paymentGateway.charge(amount);
  return { transactionId: txId };
}

3. Railway-Oriented Programming (Activities)

Activity implementations can chain operations that short-circuit on error:

// Activity implementation with chaining
const processOrder = ({ orderId }) => {
  return validateOrderId(orderId)
    .flatMap((validId) => fetchOrder(validId))
    .flatMap((order) => processPayment(order))
    .flatMap((payment) => updateDatabase(payment))
    .mapError((error) => new ActivityError("ORDER_FAILED", "Order processing failed", error));
  // Stops at first error
};

4. Partial Success Handling

Track partial success in complex workflows using try/catch blocks:

export const processOrder = declareWorkflow({
  workflowName: "processOrder",
  contract: orderContract,
  implementation: async ({ activities }, input) => {
    let paymentTransactionId: string | undefined;

    try {
      // Step 1: Process payment
      const payment = await activities.processPayment({ amount: input.amount });
      paymentTransactionId = payment.transactionId;

      // Step 2: Schedule shipment
      await activities.scheduleShipment({ orderId: input.orderId });

      return { success: true, transactionId: paymentTransactionId };
    } catch (error) {
      // Payment succeeded but shipment failed - can handle specially
      if (paymentTransactionId) {
        // Rollback payment
        await activities.refundPayment({ transactionId: paymentTransactionId });

        return {
          success: false,
          message: "Shipment failed, payment refunded",
          completedSteps: { payment: paymentTransactionId },
        };
      }

      return { success: false, message: "Payment failed" };
    }
  },
});

Child Workflows

Child workflows use the same Future/Result pattern for consistent error handling:

Execute and Wait

import { declareWorkflow } from "@temporal-contract/worker/workflow";

export const parentWorkflow = declareWorkflow({
  workflowName: "parentWorkflow",
  contract: myContract,
  implementation: async ({ executeChildWorkflow }, input) => {
    // Execute child workflow and wait for result
    const result = await executeChildWorkflow(myContract, "processPayment", {
      workflowId: `payment-${input.orderId}`,
      args: { amount: input.totalAmount },
    });

    return result.match({
      Ok: (output) =>
        Result.Ok({
          success: true,
          transactionId: output.transactionId,
        }),
      Error: (error) =>
        Result.Error({
          type: "ChildWorkflowFailed",
          error,
        }),
    });
  },
});

Start Without Waiting

export const parentWorkflow = declareWorkflow({
  workflowName: "parentWorkflow",
  contract: myContract,
  implementation: async ({ startChildWorkflow }, input) => {
    // Start child workflow without waiting
    const handleResult = await startChildWorkflow(myContract, "sendNotification", {
      workflowId: `notification-${input.orderId}`,
      args: { message: "Order received" },
    });

    handleResult.match({
      Ok: async (handle) => {
        // Child started successfully
        // Can wait for result later if needed
        const result = await handle.result();
      },
      Error: (error) => {
        console.error("Failed to start child:", error);
      },
    });

    return Result.Ok({ success: true });
  },
});

Cross-Contract Child Workflows

Invoke workflows from different contracts/workers:

import { orderContract, notificationContract } from "./contracts";

export const orderWorkflow = declareWorkflow({
  workflowName: "processOrder",
  contract: orderContract,
  implementation: async ({ executeChildWorkflow }, input) => {
    // Child workflow from another contract
    const notifyResult = await executeChildWorkflow(notificationContract, "sendOrderConfirmation", {
      workflowId: `notify-${input.orderId}`,
      args: { orderId: input.orderId },
    });

    return notifyResult.match({
      Ok: () => Result.Ok({ status: "completed" }),
      Error: (error) =>
        Result.Error({
          type: "NotificationFailed",
          error,
        }),
    });
  },
});

When to Use

Use Result/Future Pattern When:

• In Activity Implementations: Always use Future/Result pattern for explicit error handling
• For Child Workflows: Child workflows return Results for explicit error handling
• For Type-Safe Errors: When you need ActivityError with proper retry policies

Use Standard async/await When:

• In Workflow Logic: Use try/catch when calling activities from workflows
• For Simple Error Handling: When standard exception handling is sufficient
• For Deterministic Code: Workflows must remain deterministic

See Also

• @temporal-contract/boxed API Reference
• Order Processing Example
• Worker Implementation