feat: boxed implementation

Author: btravers

packages/worker-boxed/README.md

@@ -0,0 +1,221 @@
+# @temporal-contract/worker-boxed
+
+Type-safe Temporal worker implementation with **Result/Future pattern** from [@swan-io/boxed](https://github.com/swan-io/boxed) for explicit error handling in activities.
+
+## Why worker-boxed?
+
+This package extends `@temporal-contract/worker` with a functional approach to error handling using the **Result** and **Future** patterns from `@swan-io/boxed`.
+
+### Benefits
+
+- ✅ **Explicit error handling**: Activities return `Result<T, E>` instead of throwing
+- ✅ **Type-safe errors**: Error types are part of the signature
+- ✅ **Composable**: Use Result/Future combinators for elegant error handling
+- ✅ **Railway-oriented programming**: Chain operations safely
+- ✅ **All validation from worker**: Input/output Zod validation still included
+
+## Installation
+
+```bash
+pnpm add @temporal-contract/worker-boxed @swan-io/boxed
+pnpm add @temporalio/worker @temporalio/workflow zod
+```
+
+## Usage
+
+### 1. Implement Activities with Result Pattern
+
+```typescript
+import { createBoxedActivitiesHandler, Result, Future } from '@temporal-contract/worker-boxed';
+import { orderContract } from './contract';
+
+export const activitiesHandler = createBoxedActivitiesHandler({
+  contract: orderContract,
+  activities: {
+    // ✅ Returns Result instead of throwing
+    processPayment: (customerId, amount) => {
+      return Future.make(async resolve => {
+        try {
+          const result = await paymentService.charge(customerId, amount);
+          resolve(Result.Ok({
+            transactionId: result.id,
+            success: true,
+          }));
+        } catch (error) {
+          // Explicit error handling
+          resolve(Result.Error({
+            code: 'PAYMENT_FAILED',
+            message: error.message,
+            details: { customerId, amount },
+          }));
+        }
+      });
+    },
+
+    // ✅ Railway-oriented programming
+    validateInventory: (orderId) => {
+      return Future.make(async resolve => {
+        const stock = await inventory.check(orderId);
+        
+        if (stock > 0) {
+          resolve(Result.Ok({ available: true, quantity: stock }));
+        } else {
+          resolve(Result.Error({
+            code: 'OUT_OF_STOCK',
+            message: `Order ${orderId} is out of stock`,
+          }));
+        }
+      });
+    },
+  },
+});
+```
+
+### 2. Activities are Unwrapped in Workflows
+
+In workflows, activities still throw errors (Result is automatically unwrapped), maintaining Temporal's native error handling:
+
+```typescript
+import { createWorkflow } from '@temporal-contract/worker-boxed';
+
+export const processOrder = createWorkflow({
+  definition: orderContract.workflows.processOrder,
+  contract: orderContract,
+  implementation: async (context, order) => {
+    try {
+      // Activities throw on Error (unwrapped automatically)
+      const payment = await context.activities.processPayment(
+        order.customerId,
+        order.total
+      );
+      
+      const inventory = await context.activities.validateInventory(order.id);
+      
+      return {
+        orderId: order.id,
+        status: 'completed',
+        transactionId: payment.transactionId,
+      };
+    } catch (error) {
+      // Handle activity errors with error.code, error.details
+      return {
+        orderId: order.id,
+        status: 'failed',
+        error: error.code || 'UNKNOWN_ERROR',
+        message: error.message,
+      };
+    }
+  },
+});
+```
+
+### 3. Setup Worker
+
+```typescript
+import { Worker } from '@temporalio/worker';
+import { activitiesHandler } from './activities';
+
+const worker = await Worker.create({
+  workflowsPath: require.resolve('./workflows'),
+  activities: activitiesHandler.activities,
+  taskQueue: activitiesHandler.contract.taskQueue,
+});
+
+await worker.run();
+```
+
+## Error Structure
+
+Activities return errors with a structured format:
+
+```typescript
+interface ActivityError {
+  code: string;           // Error code (e.g., 'PAYMENT_FAILED')
+  message: string;        // Human-readable message
+  details?: unknown;      // Additional context
+}
+```
+
+When an activity returns `Result.Error(...)`, it's automatically converted to a thrown exception in workflows with these properties accessible via `error.code`, `error.message`, and `error.details`.
+
+## Pattern Comparison
+
+### Standard worker (exception-based)
+
+```typescript
+const sendEmail = async (to, subject, body) => {
+  // Throws on error
+  await emailService.send({ to, subject, body });
+  return { sent: true };
+};
+```
+
+### Boxed worker (Result-based)
+
+```typescript
+const sendEmail = (to, subject, body) => {
+  return Future.make(async resolve => {
+    try {
+      await emailService.send({ to, subject, body });
+      resolve(Result.Ok({ sent: true }));
+    } catch (error) {
+      resolve(Result.Error({
+        code: 'EMAIL_SEND_FAILED',
+        message: error.message,
+        details: error,
+      }));
+    }
+  });
+};
+```
+
+## Why Use This Pattern?
+
+1. **Explicit errors**: Errors are part of the return type, not hidden in throws
+2. **Better testability**: Mock `Result.Ok` or `Result.Error` without try/catch
+3. **Functional composition**: Chain operations with `map`, `flatMap`, `getOr`, etc.
+4. **Type safety**: TypeScript knows about both success and error cases
+5. **Railway-oriented programming**: Build robust error handling pipelines
+
+## Boxed Library Features
+
+This package re-exports key utilities from [@swan-io/boxed](https://github.com/swan-io/boxed):
+
+- **Result**: Success/Error sum type
+- **Future**: Promise wrapper with better composition
+- **Option**: Some/None for nullable values
+- **AsyncData**: Loading/Done/Error states
+
+See the [boxed documentation](https://swan-io.github.io/boxed/) for full API.
+
+## API
+
+### `createBoxedActivitiesHandler(options)`
+
+Creates an activities handler where implementations use Result pattern.
+
+```typescript
+type BoxedActivityImplementation<T> = (
+  ...args: InferInput<T>
+) => Future<Result<InferOutput<T>, ActivityError>>;
+```
+
+### `createWorkflow(options)`
+
+Same as standard worker - workflows remain unchanged.
+
+### `ActivityError`
+
+Standard error structure for activity failures:
+
+```typescript
+interface ActivityError {
+  code: string;
+  message: string;
+  details?: unknown;
+}
+```
+
+## License
+
+MIT

packages/worker-boxed/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@temporal-contract/worker-boxed",
+  "version": "0.0.1",
+  "description": "Type-safe Temporal worker with boxed Result/Future pattern for activities",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown src/index.ts --format cjs,esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsdown src/index.ts --format cjs,esm --dts --watch"
+  },
+  "keywords": [
+    "temporal",
+    "workflow",
+    "contract",
+    "type-safe",
+    "boxed",
+    "result",
+    "future"
+  ],
+  "dependencies": {
+    "@swan-io/boxed": "^3.2.1",
+    "@temporal-contract/core": "workspace:*",
+    "@temporalio/workflow": "catalog:",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "tsdown": "catalog:",
+    "typescript": "catalog:"
+  },
+  "peerDependencies": {
+    "@temporalio/worker": ">=1.0.0"
+  }
+}