@temporal-contract/worker 0.0.1

package/.turbo/turbo-build.log

@@ -0,0 +1,25 @@
+
+> @temporal-contract/worker@0.0.1 build /home/runner/work/temporal-contract/temporal-contract/packages/worker
+> tsdown src/activity.ts src/workflow.ts --format cjs,esm --dts --clean
+
+ℹ tsdown v0.17.2 powered by rolldown v1.0.0-beta.53
+ℹ entry: src/activity.ts, src/workflow.ts
+ℹ tsconfig: tsconfig.json
+ℹ Build start
+ℹ [CJS] dist/workflow.cjs           0.75 kB │ gzip: 0.19 kB
+ℹ [CJS] dist/activity.cjs           0.55 kB │ gzip: 0.19 kB
+ℹ [CJS] dist/handler-B3KY0uDx.cjs  16.12 kB │ gzip: 2.98 kB
+ℹ [CJS] 3 files, total: 17.41 kB
+ℹ [CJS] dist/workflow.d.cts          0.92 kB │ gzip: 0.27 kB
+ℹ [CJS] dist/activity.d.cts          0.67 kB │ gzip: 0.23 kB
+ℹ [CJS] dist/errors-CqX81ysy.d.cts  12.73 kB │ gzip: 2.77 kB
+ℹ [CJS] 3 files, total: 14.32 kB
+✔ Build complete in 3501ms
+ℹ [ESM] dist/workflow.mjs            0.56 kB │ gzip: 0.20 kB
+ℹ [ESM] dist/activity.mjs            0.42 kB │ gzip: 0.18 kB
+ℹ [ESM] dist/handler-aA2RFdV7.mjs   14.29 kB │ gzip: 2.90 kB
+ℹ [ESM] dist/workflow.d.mts          0.92 kB │ gzip: 0.27 kB
+ℹ [ESM] dist/activity.d.mts          0.67 kB │ gzip: 0.23 kB
+ℹ [ESM] dist/errors-oc-Iiwmu.d.mts  12.73 kB │ gzip: 2.77 kB
+ℹ [ESM] 6 files, total: 29.59 kB
+✔ Build complete in 3504ms

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Benoit TRAVERS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# @temporal-contract/worker
+
+> Type-safe worker implementation for Temporal
+
+## Installation
+
+```bash
+pnpm add @temporal-contract/worker @temporal-contract/contract @temporalio/workflow zod
+```
+
+## Important: Separate Entry Points
+
+Use **separate imports** for better tree-shaking:
+
+- **`@temporal-contract/worker/activity`** — For activity files
+- **`@temporal-contract/worker/workflow`** — For workflow files
+
+## Quick Start
+
+### 1. Implement Activities
+
+```typescript
+// activities.ts
+import { declareActivitiesHandler } from '@temporal-contract/worker/activity';
+import { myContract } from './contract';
+
+export const activities = declareActivitiesHandler({
+  contract: myContract,
+  activities: {
+    sendEmail: async ({ to, subject, body }) => {
+      await emailService.send({ to, subject, body });
+      return { sent: true };
+    },
+    processPayment: async ({ customerId, amount }) => {
+      const txId = await paymentGateway.charge(customerId, amount);
+      return { transactionId: txId, success: true };
+    },
+  },
+});
+```
+
+### 2. Implement Workflows
+
+```typescript
+// workflows.ts
+import { declareWorkflow } from '@temporal-contract/worker/workflow';
+import { myContract } from './contract';
+
+export const processOrder = declareWorkflow({
+  workflowName: 'processOrder',
+  contract: myContract,
+  implementation: async (context, { orderId, customerId }) => {
+    const payment = await context.activities.processPayment({ customerId, amount: 100 });
+    await context.activities.sendEmail({ to: customerId, subject: 'Confirmed', body: 'Done!' });
+
+    return {
+      status: payment.success ? 'success' : 'failed',
+      transactionId: payment.transactionId,
+    };
+  },
+});
+```
+
+### 3. Start Worker
+
+```typescript
+// worker.ts
+import { Worker } from '@temporalio/worker';
+import { activities } from './activities';
+
+const worker = await Worker.create({
+  workflowsPath: require.resolve('./workflows'),
+  activities: activities.activities,
+  taskQueue: activities.contract.taskQueue,
+});
+
+await worker.run();
+```
+
+## Features
+
+✅ **Automatic validation** — Input/output validated with Zod at network boundaries  
+✅ **Type inference** — Full TypeScript inference from contract  
+✅ **Typed context** — Activities and workflow info fully typed  
+✅ **Signals, queries, updates** — Type-safe handlers with validation
+
+## Utility Types
+
+For cleaner activity signatures:
+
+```typescript
+import type { ActivityHandler, WorkflowActivityHandler } from '@temporal-contract/contract';
+
+const sendEmail: ActivityHandler<typeof myContract, 'sendEmail'> =
+  async ({ to, subject, body }) => {
+    // Fully typed without explicit annotations
+    return { sent: true };
+  };
+```
+
+See [Activity Handlers documentation](../../docs/ACTIVITY_HANDLERS.md) for details.
+
+## Error Handling
+
+Custom error classes with contextual info:
+
+```typescript
+import { ActivityDefinitionNotFoundError } from '@temporal-contract/worker';
+
+// Errors include helpful context
+if (error instanceof ActivityDefinitionNotFoundError) {
+  console.error('Not found:', error.activityName);
+  console.error('Available:', error.availableActivities);
+}
+```
+
+---
+
+## Learn More
+
+- [Main README](../../README.md) — Quick start guide
+- [Worker Implementation](../../docs/CONTRACT_HANDLER.md) — Complete guide
+- [Entry Points](../../docs/ENTRY_POINTS.md) — Why separate entry points
+- [Activity Handlers](../../docs/ACTIVITY_HANDLERS.md) — Type utilities
+
+## License
+
+MIT

package/dist/activity.cjs

@@ -0,0 +1,8 @@
+const require_handler = require('./handler-B3KY0uDx.cjs');
+
+exports.ActivityDefinitionNotFoundError = require_handler.ActivityDefinitionNotFoundError;
+exports.ActivityImplementationNotFoundError = require_handler.ActivityImplementationNotFoundError;
+exports.ActivityInputValidationError = require_handler.ActivityInputValidationError;
+exports.ActivityOutputValidationError = require_handler.ActivityOutputValidationError;
+exports.WorkerError = require_handler.WorkerError;
+exports.declareActivitiesHandler = require_handler.declareActivitiesHandler;

package/dist/activity.d.cts

@@ -0,0 +1,2 @@
+import { C as declareActivitiesHandler, h as DeclareActivitiesHandlerOptions, i as ActivityOutputValidationError, m as ActivityImplementations, n as ActivityImplementationNotFoundError, p as ActivitiesHandler, r as ActivityInputValidationError, t as ActivityDefinitionNotFoundError, u as WorkerError, v as RawActivityImplementation } from "./errors-CqX81ysy.cjs";
+export { type ActivitiesHandler, ActivityDefinitionNotFoundError, ActivityImplementationNotFoundError, type ActivityImplementations, ActivityInputValidationError, ActivityOutputValidationError, type DeclareActivitiesHandlerOptions, type RawActivityImplementation, WorkerError, declareActivitiesHandler };

package/dist/activity.d.mts

@@ -0,0 +1,2 @@
+import { C as declareActivitiesHandler, h as DeclareActivitiesHandlerOptions, i as ActivityOutputValidationError, m as ActivityImplementations, n as ActivityImplementationNotFoundError, p as ActivitiesHandler, r as ActivityInputValidationError, t as ActivityDefinitionNotFoundError, u as WorkerError, v as RawActivityImplementation } from "./errors-oc-Iiwmu.mjs";
+export { type ActivitiesHandler, ActivityDefinitionNotFoundError, ActivityImplementationNotFoundError, type ActivityImplementations, ActivityInputValidationError, ActivityOutputValidationError, type DeclareActivitiesHandlerOptions, type RawActivityImplementation, WorkerError, declareActivitiesHandler };

package/dist/activity.mjs

@@ -0,0 +1,3 @@
+import { a as ActivityInputValidationError, f as WorkerError, i as ActivityImplementationNotFoundError, o as ActivityOutputValidationError, r as ActivityDefinitionNotFoundError, t as declareActivitiesHandler } from "./handler-aA2RFdV7.mjs";
+
+export { ActivityDefinitionNotFoundError, ActivityImplementationNotFoundError, ActivityInputValidationError, ActivityOutputValidationError, WorkerError, declareActivitiesHandler };

package/dist/errors-CqX81ysy.d.cts

@@ -0,0 +1,302 @@
+import { ActivityOptions, WorkflowInfo } from "@temporalio/workflow";
+import { ActivityDefinition, ContractDefinition, QueryDefinition, SignalDefinition, UpdateDefinition, WorkerInferInput, WorkerInferOutput, WorkerInferWorkflowContextActivities } from "@temporal-contract/contract";
+import { z } from "zod";
+
+//#region src/handler.d.ts
+
+/**
+ * Workflow context with typed activities (workflow + global) and workflow info
+ * Note: activities is typed as 'any' to work around TypeScript generic type inference limitations with Zod tuples
+ */
+interface WorkflowContext<TContract extends ContractDefinition, TWorkflowName extends keyof TContract["workflows"]> {
+  activities: WorkerInferWorkflowContextActivities<TContract, TWorkflowName>;
+  info: WorkflowInfo;
+}
+/**
+ * Workflow implementation function (receives context + typed args as tuple)
+ * Note: We use 'any' for args to work around TypeScript limitations with generic Zod tuple inference
+ * The actual type will be enforced at runtime by Zod validation
+ */
+type WorkflowImplementation<TContract extends ContractDefinition, TWorkflowName extends keyof TContract["workflows"]> = (context: WorkflowContext<TContract, TWorkflowName>, args: WorkerInferInput<TContract["workflows"][TWorkflowName]>) => Promise<WorkerInferOutput<TContract["workflows"][TWorkflowName]>>;
+/**
+ * Raw activity implementation function (receives typed args as tuple)
+ * Note: We use 'any' for args/return to work around TypeScript limitations with generic Zod tuple inference
+ * The actual types will be enforced at runtime by Zod validation
+ */
+type RawActivityImplementation<TActivity extends ActivityDefinition> = (args: WorkerInferInput<TActivity>) => Promise<WorkerInferOutput<TActivity>>;
+/**
+ * Signal handler implementation
+ */
+type SignalHandlerImplementation<TSignal extends SignalDefinition> = (args: WorkerInferInput<TSignal>) => void | Promise<void>;
+/**
+ * Query handler implementation
+ */
+type QueryHandlerImplementation<TQuery extends QueryDefinition> = (args: WorkerInferInput<TQuery>) => WorkerInferOutput<TQuery>;
+/**
+ * Update handler implementation
+ */
+type UpdateHandlerImplementation<TUpdate extends UpdateDefinition> = (args: WorkerInferInput<TUpdate>) => Promise<WorkerInferOutput<TUpdate>>;
+/**
+ * Map of all activity implementations for a contract (global + all workflow-specific)
+ */
+type ActivityImplementations<T extends ContractDefinition> = (T["activities"] extends Record<string, ActivityDefinition> ? { [K in keyof T["activities"]]: RawActivityImplementation<T["activities"][K]> } : {}) & UnionToIntersection<{ [K in keyof T["workflows"]]: T["workflows"][K]["activities"] extends Record<string, ActivityDefinition> ? { [A in keyof T["workflows"][K]["activities"]]: RawActivityImplementation<T["workflows"][K]["activities"][A]> } : {} }[keyof T["workflows"]]>;
+/**
+ * Utility type to convert union to intersection
+ */
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
+/**
+ * Options for creating activities handler
+ */
+interface DeclareActivitiesHandlerOptions<T extends ContractDefinition> {
+  contract: T;
+  activities: ActivityImplementations<T>;
+}
+/**
+ * Activities handler ready for Temporal Worker
+ */
+interface ActivitiesHandler<T extends ContractDefinition> {
+  contract: T;
+  activities: Record<string, (...args: unknown[]) => Promise<unknown>>;
+}
+/**
+ * Options for declaring a workflow implementation
+ */
+interface DeclareWorkflowOptions<TContract extends ContractDefinition, TWorkflowName extends keyof TContract["workflows"]> {
+  workflowName: TWorkflowName;
+  contract: TContract;
+  implementation: WorkflowImplementation<TContract, TWorkflowName>;
+  /**
+   * Default activity options applied to all activities in this workflow.
+   * These will be merged with the default startToCloseTimeout of 60 seconds.
+   * For more control, you can override specific Temporal ActivityOptions like:
+   * - startToCloseTimeout: Maximum time for activity execution
+   * - scheduleToCloseTimeout: End-to-end timeout including queuing
+   * - scheduleToStartTimeout: Maximum time activity can wait in queue
+   * - heartbeatTimeout: Time between heartbeats before considering activity dead
+   * - retry: Retry policy for failed activities
+   *
+   * @example
+   * ```ts
+   * activityOptions: {
+   *   startToCloseTimeout: '5m',
+   *   retry: { maximumAttempts: 3 }
+   * }
+   * ```
+   */
+  activityOptions?: ActivityOptions;
+  /**
+   * Signal handlers (if defined in workflow)
+   */
+  signals?: TContract["workflows"][TWorkflowName]["signals"] extends Record<string, SignalDefinition> ? { [K in keyof TContract["workflows"][TWorkflowName]["signals"]]: SignalHandlerImplementation<TContract["workflows"][TWorkflowName]["signals"][K]> } : never;
+  /**
+   * Query handlers (if defined in workflow)
+   */
+  queries?: TContract["workflows"][TWorkflowName]["queries"] extends Record<string, QueryDefinition> ? { [K in keyof TContract["workflows"][TWorkflowName]["queries"]]: QueryHandlerImplementation<TContract["workflows"][TWorkflowName]["queries"][K]> } : never;
+  /**
+   * Update handlers (if defined in workflow)
+   */
+  updates?: TContract["workflows"][TWorkflowName]["updates"] extends Record<string, UpdateDefinition> ? { [K in keyof TContract["workflows"][TWorkflowName]["updates"]]: UpdateHandlerImplementation<TContract["workflows"][TWorkflowName]["updates"][K]> } : never;
+}
+/**
+ * Create a typed activities handler with automatic validation
+ *
+ * This wraps all activity implementations with Zod validation at network boundaries.
+ * TypeScript ensures ALL activities (global + workflow-specific) are implemented.
+ *
+ * Use this to create the activities object for the Temporal Worker.
+ *
+ * @example
+ * ```ts
+ * import { declareActivitiesHandler } from '@temporal-contract/worker';
+ * import myContract from './contract';
+ *
+ * export const activitiesHandler = declareActivitiesHandler({
+ *   contract: myContract,
+ *   activities: {
+ *     // Global activities
+ *     sendEmail: async (to, subject, body) => {
+ *       await emailService.send({ to, subject, body });
+ *       return { sent: true };
+ *     },
+ *     // Workflow-specific activities
+ *     validateInventory: async (orderId) => {
+ *       const available = await inventory.check(orderId);
+ *       return { available };
+ *     },
+ *   },
+ * });
+ *
+ * // Use with Temporal Worker
+ * import { Worker } from '@temporalio/worker';
+ *
+ * const worker = await Worker.create({
+ *   workflowsPath: require.resolve('./workflows'),
+ *   activities: activitiesHandler.activities,
+ *   taskQueue: activitiesHandler.contract.taskQueue,
+ * });
+ * ```
+ */
+declare function declareActivitiesHandler<T extends ContractDefinition>(options: DeclareActivitiesHandlerOptions<T>): ActivitiesHandler<T>;
+/**
+ * Create a typed workflow implementation with automatic validation
+ *
+ * This wraps a workflow implementation with:
+ * - Input/output validation
+ * - Typed workflow context with activities
+ * - Workflow info access
+ *
+ * Workflows must be defined in separate files and imported by the Temporal Worker
+ * via workflowsPath.
+ *
+ * @example
+ * ```ts
+ * // workflows/processOrder.ts
+ * import { declareWorkflow } from '@temporal-contract/worker';
+ * import myContract from '../contract';
+ *
+ * export const processOrder = declareWorkflow({
+ *   workflowName: 'processOrder',
+ *   contract: myContract,
+ *   implementation: async (context, orderId, customerId) => {
+ *     // context.activities: typed activities (workflow + global)
+ *     // context.info: WorkflowInfo
+ *
+ *     const inventory = await context.activities.validateInventory(orderId);
+ *
+ *     if (!inventory.available) {
+ *       throw new Error('Out of stock');
+ *     }
+ *
+ *     const payment = await context.activities.chargePayment(customerId, 100);
+ *
+ *     // Global activity
+ *     await context.activities.sendEmail(
+ *       customerId,
+ *       'Order processed',
+ *       'Your order has been processed'
+ *     );
+ *
+ *     return {
+ *       orderId,
+ *       status: payment.success ? 'success' : 'failed',
+ *       transactionId: payment.transactionId,
+ *     };
+ *   },
+ *   activityOptions: {
+ *     startToCloseTimeout: '1 minute',
+ *   },
+ * });
+ * ```
+ *
+ * Then in your worker setup:
+ * ```ts
+ * // worker.ts
+ * import { Worker } from '@temporalio/worker';
+ * import { activitiesHandler } from './activities';
+ *
+ * const worker = await Worker.create({
+ *   workflowsPath: require.resolve('./workflows'), // Imports processOrder
+ *   activities: activitiesHandler.activities,
+ *   taskQueue: activitiesHandler.contract.taskQueue,
+ * });
+ * ```
+ */
+declare function declareWorkflow<TContract extends ContractDefinition, TWorkflowName extends keyof TContract["workflows"]>(options: DeclareWorkflowOptions<TContract, TWorkflowName>): (args: WorkerInferInput<TContract["workflows"][TWorkflowName]>) => Promise<WorkerInferOutput<TContract["workflows"][TWorkflowName]>>;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Base error class for worker errors
+ */
+declare class WorkerError extends Error {
+  constructor(message: string);
+}
+/**
+ * Error thrown when an activity implementation is not found
+ */
+declare class ActivityImplementationNotFoundError extends WorkerError {
+  readonly activityName: string;
+  readonly availableActivities: readonly string[];
+  constructor(activityName: string, availableActivities: readonly string[]);
+}
+/**
+ * Error thrown when an activity definition is not found in the contract
+ */
+declare class ActivityDefinitionNotFoundError extends WorkerError {
+  readonly activityName: string;
+  readonly availableDefinitions: readonly string[];
+  constructor(activityName: string, availableDefinitions: readonly string[]);
+}
+/**
+ * Error thrown when activity input validation fails
+ */
+declare class ActivityInputValidationError extends WorkerError {
+  readonly activityName: string;
+  readonly zodError: z.ZodError;
+  constructor(activityName: string, zodError: z.ZodError);
+}
+/**
+ * Error thrown when activity output validation fails
+ */
+declare class ActivityOutputValidationError extends WorkerError {
+  readonly activityName: string;
+  readonly zodError: z.ZodError;
+  constructor(activityName: string, zodError: z.ZodError);
+}
+/**
+ * Error thrown when workflow input validation fails
+ */
+declare class WorkflowInputValidationError extends WorkerError {
+  readonly workflowName: string;
+  readonly zodError: z.ZodError;
+  constructor(workflowName: string, zodError: z.ZodError);
+}
+/**
+ * Error thrown when workflow output validation fails
+ */
+declare class WorkflowOutputValidationError extends WorkerError {
+  readonly workflowName: string;
+  readonly zodError: z.ZodError;
+  constructor(workflowName: string, zodError: z.ZodError);
+}
+/**
+ * Error thrown when signal input validation fails
+ */
+declare class SignalInputValidationError extends WorkerError {
+  readonly signalName: string;
+  readonly zodError: z.ZodError;
+  constructor(signalName: string, zodError: z.ZodError);
+}
+/**
+ * Error thrown when query input validation fails
+ */
+declare class QueryInputValidationError extends WorkerError {
+  readonly queryName: string;
+  readonly zodError: z.ZodError;
+  constructor(queryName: string, zodError: z.ZodError);
+}
+/**
+ * Error thrown when query output validation fails
+ */
+declare class QueryOutputValidationError extends WorkerError {
+  readonly queryName: string;
+  readonly zodError: z.ZodError;
+  constructor(queryName: string, zodError: z.ZodError);
+}
+/**
+ * Error thrown when update input validation fails
+ */
+declare class UpdateInputValidationError extends WorkerError {
+  readonly updateName: string;
+  readonly zodError: z.ZodError;
+  constructor(updateName: string, zodError: z.ZodError);
+}
+/**
+ * Error thrown when update output validation fails
+ */
+declare class UpdateOutputValidationError extends WorkerError {
+  readonly updateName: string;
+  readonly zodError: z.ZodError;
+  constructor(updateName: string, zodError: z.ZodError);
+}
+//#endregion
+export { declareActivitiesHandler as C, WorkflowImplementation as S, QueryHandlerImplementation as _, QueryInputValidationError as a, UpdateHandlerImplementation as b, UpdateInputValidationError as c, WorkflowInputValidationError as d, WorkflowOutputValidationError as f, DeclareWorkflowOptions as g, DeclareActivitiesHandlerOptions as h, ActivityOutputValidationError as i, UpdateOutputValidationError as l, ActivityImplementations as m, ActivityImplementationNotFoundError as n, QueryOutputValidationError as o, ActivitiesHandler as p, ActivityInputValidationError as r, SignalInputValidationError as s, ActivityDefinitionNotFoundError as t, WorkerError as u, RawActivityImplementation as v, declareWorkflow as w, WorkflowContext as x, SignalHandlerImplementation as y };