@temporal-contract/contract 0.0.6 → 0.1.0

package/README.md

@@ -13,18 +13,20 @@ pnpm add @temporal-contract/contract zod
 ## Quick Example
 
 ```typescript
-import { defineContract } from '@temporal-contract/contract';
-import { z } from 'zod';
+import { defineContract } from "@temporal-contract/contract";
+import { z } from "zod";
 
 export const myContract = defineContract({
-  taskQueue: 'orders',
+  taskQueue: "orders",
   workflows: {
     processOrder: {
       input: z.object({ orderId: z.string() }),
       output: z.object({ success: z.boolean() }),
-      activities: { /* ... */ }
-    }
-  }
+      activities: {
+        /* ... */
+      },
+    },
+  },
 });
 ```
 

package/dist/index.cjs

@@ -1,26 +1,214 @@
 let zod = require("zod");
 
 //#region src/builder.ts
+/**
+* Define a Temporal activity with type-safe input and output schemas.
+*
+* Activities are the building blocks of Temporal workflows that execute business logic
+* and interact with external services. This function preserves TypeScript types while
+* providing a consistent structure for activity definitions.
+*
+* @template TActivity - The activity definition type with input/output schemas
+* @param definition - The activity definition containing input and output schemas
+* @returns The same definition with preserved types for type inference
+*
+* @example
+* ```typescript
+* import { defineActivity } from '@temporal-contract/contract';
+* import { z } from 'zod';
+*
+* export const sendEmail = defineActivity({
+*   input: z.object({
+*     to: z.string().email(),
+*     subject: z.string(),
+*     body: z.string(),
+*   }),
+*   output: z.object({
+*     messageId: z.string(),
+*     sentAt: z.date(),
+*   }),
+* });
+* ```
+*/
 function defineActivity(definition) {
 	return definition;
 }
+/**
+* Define a Temporal signal with type-safe input schema.
+*
+* Signals are asynchronous messages sent to running workflows to update their state
+* or trigger certain behaviors. This function ensures type safety for signal payloads.
+*
+* @template TSignal - The signal definition type with input schema
+* @param definition - The signal definition containing input schema
+* @returns The same definition with preserved types for type inference
+*
+* @example
+* ```typescript
+* import { defineSignal } from '@temporal-contract/contract';
+* import { z } from 'zod';
+*
+* export const approveOrder = defineSignal({
+*   input: z.object({
+*     orderId: z.string(),
+*     approvedBy: z.string(),
+*   }),
+* });
+* ```
+*/
 function defineSignal(definition) {
 	return definition;
 }
+/**
+* Define a Temporal query with type-safe input and output schemas.
+*
+* Queries allow you to read the current state of a running workflow without
+* modifying it. They are synchronous and should not perform any mutations.
+*
+* @template TQuery - The query definition type with input/output schemas
+* @param definition - The query definition containing input and output schemas
+* @returns The same definition with preserved types for type inference
+*
+* @example
+* ```typescript
+* import { defineQuery } from '@temporal-contract/contract';
+* import { z } from 'zod';
+*
+* export const getOrderStatus = defineQuery({
+*   input: z.object({ orderId: z.string() }),
+*   output: z.object({
+*     status: z.enum(['pending', 'processing', 'completed', 'failed']),
+*     updatedAt: z.date(),
+*   }),
+* });
+* ```
+*/
 function defineQuery(definition) {
 	return definition;
 }
+/**
+* Define a Temporal update with type-safe input and output schemas.
+*
+* Updates are similar to signals but return a value and wait for the workflow
+* to process them before completing. They provide a synchronous way to modify
+* workflow state and get immediate feedback.
+*
+* @template TUpdate - The update definition type with input/output schemas
+* @param definition - The update definition containing input and output schemas
+* @returns The same definition with preserved types for type inference
+*
+* @example
+* ```typescript
+* import { defineUpdate } from '@temporal-contract/contract';
+* import { z } from 'zod';
+*
+* export const updateOrderQuantity = defineUpdate({
+*   input: z.object({
+*     orderId: z.string(),
+*     newQuantity: z.number().positive(),
+*   }),
+*   output: z.object({
+*     success: z.boolean(),
+*     totalPrice: z.number(),
+*   }),
+* });
+* ```
+*/
 function defineUpdate(definition) {
 	return definition;
 }
+/**
+* Define a Temporal workflow with type-safe input, output, and associated operations.
+*
+* Workflows are durable functions that orchestrate activities, handle timeouts,
+* and manage long-running processes. This function provides type safety for the
+* entire workflow definition including activities, signals, queries, and updates.
+*
+* @template TWorkflow - The workflow definition type with all associated schemas
+* @param definition - The workflow definition containing input, output, and operations
+* @returns The same definition with preserved types for type inference
+*
+* @example
+* ```typescript
+* import { defineWorkflow, defineActivity, defineSignal } from '@temporal-contract/contract';
+* import { z } from 'zod';
+*
+* export const processOrder = defineWorkflow({
+*   input: z.object({ orderId: z.string() }),
+*   output: z.object({ success: z.boolean() }),
+*   activities: {
+*     validatePayment: defineActivity({
+*       input: z.object({ orderId: z.string() }),
+*       output: z.object({ valid: z.boolean() }),
+*     }),
+*   },
+*   signals: {
+*     cancel: defineSignal({
+*       input: z.object({ reason: z.string() }),
+*     }),
+*   },
+* });
+* ```
+*/
 function defineWorkflow(definition) {
 	return definition;
 }
+/**
+* Define a complete Temporal contract with type-safe workflows and activities.
+*
+* A contract is the central definition that ties together your Temporal application's
+* workflows and activities. It provides:
+* - Type safety across client, worker, and workflow code
+* - Automatic validation at runtime
+* - Compile-time verification of implementations
+* - Clear API boundaries and documentation
+*
+* The contract validates the structure and ensures:
+* - Task queue is specified
+* - At least one workflow is defined
+* - Valid JavaScript identifiers are used
+* - No conflicts between global and workflow-specific activities
+* - All schemas implement the Standard Schema specification
+*
+* @template TContract - The contract definition type
+* @param definition - The complete contract definition
+* @returns The same definition with preserved types for type inference
+* @throws {Error} If the contract structure is invalid
+*
+* @example
+* ```typescript
+* import { defineContract } from '@temporal-contract/contract';
+* import { z } from 'zod';
+*
+* export const myContract = defineContract({
+*   taskQueue: 'orders',
+*   workflows: {
+*     processOrder: {
+*       input: z.object({ orderId: z.string() }),
+*       output: z.object({ success: z.boolean() }),
+*       activities: {
+*         chargePayment: {
+*           input: z.object({ amount: z.number() }),
+*           output: z.object({ transactionId: z.string() }),
+*         },
+*       },
+*     },
+*   },
+*   // Optional global activities shared across workflows
+*   activities: {
+*     logEvent: {
+*       input: z.object({ message: z.string() }),
+*       output: z.void(),
+*     },
+*   },
+* });
+* ```
+*/
 function defineContract(definition) {
 	const validationResult = contractValidationSchema.safeParse(definition);
 	if (!validationResult.success) {
 		const cleanMessage = getCleanErrorMessage(validationResult.error);
-		throw new Error(`Contract error: ${cleanMessage}`);
+		throw new Error(`Contract validation failed: ${cleanMessage}`);
 	}
 	return definition;
 }
@@ -112,125 +300,9 @@ const contractValidationSchema = zod.z.object({
 	}
 });
 
-//#endregion
-//#region src/nexus-types.ts
-/**
-* BUILDER FUNCTIONS (Proposed API)
-* These would be added to builder.ts when Nexus support is implemented
-*/
-/**
-* Builder for creating Nexus operation definitions
-*
-* @template TOperation - A NexusOperationDefinition containing input and output schemas
-* @param definition - The Nexus operation definition with typed input/output schemas
-* @returns The same definition with preserved types
-*
-* @example
-* ```typescript
-* const processPayment = defineNexusOperation({
-*   input: z.object({ amount: z.number(), customerId: z.string() }),
-*   output: z.object({ transactionId: z.string(), status: z.enum(['success', 'failed']) }),
-* });
-* ```
-*/
-function defineNexusOperation(definition) {
-	return definition;
-}
-/**
-* Builder for creating Nexus service definitions
-*
-* @template TService - A NexusServiceDefinition containing a record of operations
-* @param definition - The Nexus service definition with typed operations
-* @returns The same definition with preserved types
-*
-* @example
-* ```typescript
-* const PaymentService = defineNexusService({
-*   operations: {
-*     processPayment: defineNexusOperation({ ... }),
-*     refundPayment: defineNexusOperation({ ... }),
-*   },
-* });
-* ```
-*/
-function defineNexusService(definition) {
-	return definition;
-}
-/**
-* USAGE EXAMPLE
-*
-* This example demonstrates the complete type-safe Nexus workflow:
-*
-* ```typescript
-* import { defineContract, defineNexusService, defineNexusOperation } from '@temporal-contract/contract';
-* import { z } from 'zod';
-*
-* // 1. Define contract with Nexus service
-* const paymentContract = defineContract({
-*   taskQueue: 'payments',
-*   workflows: { ... },
-*   nexusServices: {
-*     PaymentService: defineNexusService({
-*       operations: {
-*         processPayment: defineNexusOperation({
-*           input: z.object({
-*             amount: z.number().positive(),
-*             customerId: z.string().uuid(),
-*           }),
-*           output: z.object({
-*             transactionId: z.string(),
-*             status: z.enum(['success', 'failed']),
-*           }),
-*         }),
-*       },
-*     }),
-*   },
-* });
-*
-* // 2. Worker implementation (type-safe handlers)
-* import { createNexusHandlers } from '@temporal-contract/worker';
-*
-* const nexusHandlers = createNexusHandlers(paymentContract, {
-*   PaymentService: {
-*     processPayment: async ({ amount, customerId }) => {
-*       // ✅ Fully typed parameters
-*       // ✅ Input automatically validated
-*       const payment = await processPaymentInDatabase(customerId, amount);
-*       // ✅ Return value validated against schema
-*       return {
-*         transactionId: payment.id,
-*         status: 'success',
-*       };
-*     },
-*   },
-* });
-*
-* // 3. Client usage (type-safe invocation)
-* import { createNexusClient } from '@temporal-contract/client';
-*
-* const nexusClient = createNexusClient<typeof paymentContract>(connection, {
-*   namespace: 'payments-ns',
-* });
-*
-* // ✅ Fully typed invocation
-* const result = await nexusClient.invoke('PaymentService', 'processPayment', {
-*   amount: 100,
-*   customerId: 'cust-123',
-* });
-*
-* // ❌ TypeScript errors caught at compile time
-* await nexusClient.invoke('PaymentService', 'processPayment', {
-*   amount: -50, // Error: amount must be positive
-*   customerId: 'invalid', // Error: customerId must be UUID
-* });
-* ```
-*/
-
 //#endregion
 exports.defineActivity = defineActivity;
 exports.defineContract = defineContract;
-exports.defineNexusOperation = defineNexusOperation;
-exports.defineNexusService = defineNexusService;
 exports.defineQuery = defineQuery;
 exports.defineSignal = defineSignal;
 exports.defineUpdate = defineUpdate;