docs: align examples with actual Future/Result implementation patterns (#84)

* Initial plan

* Fix documentation examples for Future/Result pattern usage

- Update Getting Started guide with correct activity implementation patterns
- Fix Activity Handlers guide to show Future/Result pattern
- Update Worker Implementation guide with proper error handling examples
- Correct Result Pattern guide to clarify activities vs workflows
- Fix Client Usage guide to show Future/Result pattern correctly
- Update package READMEs with consistent examples
- Fix main README with proper example

Co-authored-by: btravers <3476441+btravers@users.noreply.github.com>

* Fix worker-usage guide and sample READMEs

- Remove references to non-existent createWorker function
- Update to use standard Worker.create from @temporalio/worker
- Fix child workflow examples to show Result pattern
- Update sample READMEs to reflect actual samples
- Remove references to non-existent worker-boxed sample

Co-authored-by: btravers <3476441+btravers@users.noreply.github.com>

* Fix homepage examples and remove createWorker references

- Update index.md with correct Worker.create usage
- Fix client example to show Future/Result pattern
- Add proper Connection setup in client example
- Ensure all worker examples use standard Temporal Worker API

Co-authored-by: btravers <3476441+btravers@users.noreply.github.com>

* Destructure context parameter in all workflow examples

Changed all workflow implementations from:
  implementation: async (context, input) => {}
to:
  implementation: async ({ activities, executeChildWorkflow, ... }, input) => {}

This follows the codebase convention of destructuring the context parameter directly.

Co-authored-by: btravers <3476441+btravers@users.noreply.github.com>

* Changes before error encountered

Co-authored-by: btravers <3476441+btravers@users.noreply.github.com>

* Fix formatting issues (remove trailing whitespace)

Run oxfmt to fix CI formatting issues.

Co-authored-by: btravers <3476441+btravers@users.noreply.github.com>

* Fix worker README to destructure context parameter

Updated packages/worker/README.md to use destructured context parameter pattern:
- Changed from: implementation: async (context, input) => {}
- Changed to: implementation: async ({ activities }, input) => {}

This ensures consistency across all documentation examples.

Co-authored-by: btravers <3476441+btravers@users.noreply.github.com>

* Update website/docs/guide/result-pattern.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Simplify variable naming: resultFuture -> future

Changed variable name from 'resultFuture' to 'future' across all documentation to avoid redundancy since it's already clear from context that it's a Future.

Updated files:
- website/docs/index.md (2 instances)
- website/docs/guide/getting-started.md
- website/docs/guide/client-usage.md

Co-authored-by: btravers <3476441+btravers@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: btravers <3476441+btravers@users.noreply.github.com>
Co-authored-by: Benoit Travers <benoit.travers.fr@gmail.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

README.md

@@ -36,12 +36,34 @@ const contract = defineContract({
     processOrder: {
       input: z.object({ orderId: z.string() }),
       output: z.object({ success: z.boolean() }),
-      activities: { /* ... */ }
+      activities: {
+        processPayment: {
+          input: z.object({ orderId: z.string() }),
+          output: z.object({ transactionId: z.string() })
+        }
+      }
     }
   }
 });
 
-// Fully typed everywhere
+// 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!

packages/client/README.md

@@ -14,10 +14,11 @@ pnpm add @temporal-contract/client @temporal-contract/contract @temporalio/clien
 
 ```typescript
 import { TypedClient } from '@temporal-contract/client';
-import { Connection } from '@temporalio/client';
+import { Connection, Client } from '@temporalio/client';
 
 const connection = await Connection.connect({ address: 'localhost:7233' });
-const client = TypedClient.create(myContract, { connection });
+const temporalClient = new Client({ connection });
+const client = TypedClient.create(myContract, temporalClient);
 
 // Execute workflow (fully typed!)
 const result = await client.executeWorkflow('processOrder', {

packages/worker/README.md

@@ -14,12 +14,23 @@ pnpm add @temporal-contract/worker @temporal-contract/contract @temporalio/workf
 
 ```typescript
 // activities.ts
-import { declareActivitiesHandler } from '@temporal-contract/worker/activity';
+import { declareActivitiesHandler, ActivityError } from '@temporal-contract/worker/activity';
+import { Future, Result } from '@swan-io/boxed';
 
 export const activities = declareActivitiesHandler({
   contract: myContract,
   activities: {
-    sendEmail: async ({ to, body }) => ({ sent: true })
+    sendEmail: ({ to, body }) => {
+      return Future.fromPromise(emailService.send({ to, body }))
+        .mapError((error) =>
+          new ActivityError(
+            'EMAIL_FAILED',
+            error instanceof Error ? error.message : 'Failed to send email',
+            error
+          )
+        )
+        .mapOk(() => ({ sent: true }));
+    }
   }
 });
 
@@ -29,28 +40,23 @@ import { declareWorkflow } from '@temporal-contract/worker/workflow';
 export const processOrder = declareWorkflow({
   workflowName: 'processOrder',
   contract: myContract,
-  implementation: async (context, input) => {
-    await context.activities.sendEmail({ to: 'user@example.com', body: 'Done!' });
+  implementation: async ({ activities }, input) => {
+    // Activities return plain values (Result is unwrapped internally)
+    await activities.sendEmail({ to: 'user@example.com', body: 'Done!' });
     return { success: true };
   }
 });
 
 // worker.ts
-import { NativeConnection } from '@temporalio/worker';
-import { createWorker } from '@temporal-contract/worker/worker';
+import { Worker } from '@temporalio/worker';
 import { activities } from './activities';
 import myContract from './contract';
 
 async function run() {
-  const connection = await NativeConnection.connect({
-    address: 'localhost:7233',
-  });
-
-  const worker = await createWorker({
-    contract: myContract,
-    connection,
+  const worker = await Worker.create({
     workflowsPath: require.resolve('./workflows'),
     activities,
+    taskQueue: myContract.taskQueue,
   });
 
   await worker.run();
@@ -70,9 +76,9 @@ import { declareWorkflow } from '@temporal-contract/worker/workflow';
 export const parentWorkflow = declareWorkflow({
   workflowName: 'parentWorkflow',
   contract: myContract,
-  implementation: async (context, input) => {
+  implementation: async ({ executeChildWorkflow }, input) => {
     // Execute child workflow from same contract and wait for result
-    const childResult = await context.executeChildWorkflow(myContract, 'processPayment', {
+    const childResult = await executeChildWorkflow(myContract, 'processPayment', {
       workflowId: `payment-${input.orderId}`,
       args: { amount: input.totalAmount }
     });
@@ -83,13 +89,13 @@ export const parentWorkflow = declareWorkflow({
     });
 
     // Execute child workflow from another contract (another worker)
-    const notificationResult = await context.executeChildWorkflow(notificationContract, 'sendNotification', {
+    const notificationResult = await executeChildWorkflow(notificationContract, 'sendNotification', {
       workflowId: `notification-${input.orderId}`,
       args: { message: 'Order received' }
     });
 
     // Or start child workflow without waiting
-    const handleResult = await context.startChildWorkflow(myContract, 'sendEmail', {
+    const handleResult = await startChildWorkflow(myContract, 'sendEmail', {
       workflowId: `email-${input.orderId}`,
       args: { to: 'user@example.com', body: 'Order received' }
     });

samples/order-processing-client/README.md

@@ -8,10 +8,10 @@ This sample demonstrates that a single client can interact with any worker imple
 
 This client package demonstrates that:
 
-- Both `order-processing-worker` and `order-processing-worker-boxed` workers implement the **same unified contract**
+- Both `order-processing-worker` and `order-processing-worker-nestjs` workers implement the **same unified contract**
 - A single client works with any worker implementation
 - From the client's perspective, all workers are identical
-- The only difference is in how workers handle errors internally (Promise-based vs. Result/Future pattern)
+- Workers handle errors internally using the Result/Future pattern with ActivityError
 
 ## Running the Sample
 
@@ -34,17 +34,17 @@ pnpm install && pnpm build
 
 1. Start a worker (choose one):
 
-**Option A: Basic Worker**
+**Option A: Standard Worker**
 
 ```bash
 cd ../order-processing-worker
 pnpm dev
 ```
 
-**Option B: Boxed Worker**
+**Option B: NestJS Worker**
 
 ```bash
-cd ../order-processing-worker-boxed
+cd ../order-processing-worker-nestjs
 pnpm dev
 ```
 
@@ -89,19 +89,19 @@ The unified contract (`orderProcessingContract`) defines:
 
 ### Worker Implementations
 
-Both workers implement the exact same contract but with different patterns:
+Both workers implement the exact same contract but with different frameworks:
 
-1. **Basic Worker** (`samples/order-processing-worker`)
+1. **Standard Worker** (`samples/order-processing-worker`)
    - Uses `@temporal-contract/worker`
-   - Promise-based activities
-   - Traditional error handling with try/catch
-   - Simpler to understand and implement
-
-2. **Boxed Worker** (`samples/order-processing-worker-boxed`)
-   - Uses `@temporal-contract/worker-boxed`
-   - Result/Future pattern with `@temporal-contract/boxed`
-   - Explicit error types in function signatures
-   - Better type safety and functional composition
+   - Activities use Result/Future pattern with ActivityError
+   - Clean Architecture with dependency injection
+   - Standalone TypeScript application
+
+2. **NestJS Worker** (`samples/order-processing-worker-nestjs`)
+   - Uses `@temporal-contract/worker-nestjs`
+   - Activities use Result/Future pattern with ActivityError
+   - NestJS dependency injection and decorators
+   - Better for NestJS-based applications
 
 ### Client Perspective
 

samples/order-processing-worker/README.md

@@ -1,6 +1,6 @@
-# Basic Order Processing
+# Order Processing Worker
 
-> Standard Promise-based workflow with Clean Architecture
+> Type-safe order processing worker with Clean Architecture and Result/Future pattern
 
 ## Running
 
@@ -15,6 +15,7 @@ pnpm dev
 ## What It Demonstrates
 
 - ✅ Type-safe contracts with Zod
+- ✅ Result/Future pattern with ActivityError for explicit error handling
 - ✅ Clean Architecture (Domain → Infrastructure → Application)
 - ✅ Dependency injection for testability
 - ✅ Error handling with compensating actions

website/docs/guide/activity-handlers.md

@@ -12,20 +12,36 @@ Instead of defining activity implementations inline, you can extract types for r
 
 ```typescript
 import type { ActivityHandlers } from '@temporal-contract/worker/activity';
+import { declareActivitiesHandler, ActivityError } from '@temporal-contract/worker/activity';
+import { Future, Result } from '@swan-io/boxed';
 import { orderContract } from './contract';
 
 // Extract all activity handler types from contract
 type OrderActivityHandlers = ActivityHandlers<typeof orderContract>;
 
-// Implement activities with explicit types
-const sendEmail: OrderActivityHandlers['sendEmail'] = async ({ to, body }) => {
-  await emailService.send({ to, body });
-  return { sent: true };
+// Implement activities with explicit types using Future/Result pattern
+const sendEmail: OrderActivityHandlers['sendEmail'] = ({ to, body }) => {
+  return Future.fromPromise(emailService.send({ to, body }))
+    .mapError((error) =>
+      new ActivityError(
+        'EMAIL_FAILED',
+        error instanceof Error ? error.message : 'Failed to send email',
+        error
+      )
+    )
+    .mapOk(() => ({ sent: true }));
 };
 
-const processPayment: OrderActivityHandlers['processPayment'] = async ({ amount }) => {
-  const txId = await paymentGateway.charge(amount);
-  return { transactionId: txId };
+const processPayment: OrderActivityHandlers['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 }));
 };
 
 // Use in handler
@@ -77,26 +93,44 @@ Implement activities in separate files:
 ```typescript
 // activities/email.ts
 import type { ActivityHandlers } from '@temporal-contract/worker/activity';
+import { ActivityError } from '@temporal-contract/worker/activity';
+import { Future, Result } from '@swan-io/boxed';
 import { orderContract } from '../contracts/order.contract';
 
 type Handlers = ActivityHandlers<typeof orderContract>;
 
-export const sendEmail: Handlers['sendEmail'] = async ({ to, body }) => {
-  await emailService.send({ to, body });
-  return { sent: true };
+export const sendEmail: Handlers['sendEmail'] = ({ to, body }) => {
+  return Future.fromPromise(emailService.send({ to, body }))
+    .mapError((error) =>
+      new ActivityError(
+        'EMAIL_FAILED',
+        error instanceof Error ? error.message : 'Failed to send email',
+        error
+      )
+    )
+    .mapOk(() => ({ sent: true }));
 };
 ```
 
 ```typescript
 // activities/payment.ts
 import type { ActivityHandlers } from '@temporal-contract/worker/activity';
+import { ActivityError } from '@temporal-contract/worker/activity';
+import { Future, Result } from '@swan-io/boxed';
 import { orderContract } from '../contracts/order.contract';
 
 type Handlers = ActivityHandlers<typeof orderContract>;
 
-export const processPayment: Handlers['processPayment'] = async ({ amount }) => {
-  const txId = await paymentGateway.charge(amount);
-  return { transactionId: txId };
+export const processPayment: Handlers['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 }));
 };
 ```
 
@@ -165,13 +199,14 @@ Mock activities with correct types:
 
 ```typescript
 import type { ActivityHandlers } from '@temporal-contract/worker/activity';
+import { Future, Result } from '@swan-io/boxed';
 
 type Handlers = ActivityHandlers<typeof orderContract>;
 
 // Create mock activities for testing
 const mockActivities: Handlers = {
-  sendEmail: async ({ to, body }) => ({ sent: true }),
-  processPayment: async ({ amount }) => ({ transactionId: 'TEST-TXN' })
+  sendEmail: ({ to, body }) => Future.value(Result.Ok({ sent: true })),
+  processPayment: ({ amount }) => Future.value(Result.Ok({ transactionId: 'TEST-TXN' }))
 };
 
 // Use in tests