@temporal-contract/worker 0.0.3 → 0.0.5

package/dist/handler-DFFpSaGN.mjs

@@ -0,0 +1,502 @@
+import { Future, Result } from "@temporal-contract/boxed";
+import { defineQuery, defineSignal, defineUpdate, executeChild, proxyActivities, setHandler, startChild, workflowInfo } from "@temporalio/workflow";
+
+//#region src/errors.ts
+/**
+* Base error class for worker errors
+*/
+var WorkerError = class extends Error {
+	constructor(message, cause) {
+		super(message, { cause });
+		this.name = "WorkerError";
+		if (Error.captureStackTrace) Error.captureStackTrace(this, this.constructor);
+	}
+};
+/**
+* Activity error class that should be used to wrap all technical exceptions
+* Forces proper error handling and enables retry policies
+*/
+var ActivityError = class ActivityError extends Error {
+	code;
+	cause;
+	constructor(code, message, cause) {
+		super(message, { cause });
+		this.code = code;
+		this.cause = cause;
+		this.name = "ActivityError";
+		if (Error.captureStackTrace) Error.captureStackTrace(this, ActivityError);
+	}
+};
+/**
+* Error thrown when an activity definition is not found in the contract
+*/
+var ActivityDefinitionNotFoundError = class extends WorkerError {
+	constructor(activityName, availableDefinitions = []) {
+		const available = availableDefinitions.length > 0 ? availableDefinitions.join(", ") : "none";
+		super(`Activity definition not found for: "${activityName}". Available activities: ${available}`);
+		this.activityName = activityName;
+		this.availableDefinitions = availableDefinitions;
+		this.name = "ActivityDefinitionNotFoundError";
+	}
+};
+/**
+* Error thrown when activity input validation fails
+*/
+var ActivityInputValidationError = class extends WorkerError {
+	constructor(activityName, issues) {
+		const message = issues.map((issue) => issue.message).join("; ");
+		super(`Activity "${activityName}" input validation failed: ${message}`);
+		this.activityName = activityName;
+		this.issues = issues;
+		this.name = "ActivityInputValidationError";
+	}
+};
+/**
+* Error thrown when activity output validation fails
+*/
+var ActivityOutputValidationError = class extends WorkerError {
+	constructor(activityName, issues) {
+		const message = issues.map((issue) => issue.message).join("; ");
+		super(`Activity "${activityName}" output validation failed: ${message}`);
+		this.activityName = activityName;
+		this.issues = issues;
+		this.name = "ActivityOutputValidationError";
+	}
+};
+/**
+* Error thrown when workflow input validation fails
+*/
+var WorkflowInputValidationError = class extends WorkerError {
+	constructor(workflowName, issues) {
+		const message = issues.map((issue) => issue.message).join("; ");
+		super(`Workflow "${workflowName}" input validation failed: ${message}`);
+		this.workflowName = workflowName;
+		this.issues = issues;
+		this.name = "WorkflowInputValidationError";
+	}
+};
+/**
+* Error thrown when workflow output validation fails
+*/
+var WorkflowOutputValidationError = class extends WorkerError {
+	constructor(workflowName, issues) {
+		const message = issues.map((issue) => issue.message).join("; ");
+		super(`Workflow "${workflowName}" output validation failed: ${message}`);
+		this.workflowName = workflowName;
+		this.issues = issues;
+		this.name = "WorkflowOutputValidationError";
+	}
+};
+/**
+* Error thrown when signal input validation fails
+*/
+var SignalInputValidationError = class extends WorkerError {
+	constructor(signalName, issues) {
+		const message = issues.map((issue) => issue.message).join("; ");
+		super(`Signal "${signalName}" input validation failed: ${message}`);
+		this.signalName = signalName;
+		this.issues = issues;
+		this.name = "SignalInputValidationError";
+	}
+};
+/**
+* Error thrown when query input validation fails
+*/
+var QueryInputValidationError = class extends WorkerError {
+	constructor(queryName, issues) {
+		const message = issues.map((issue) => issue.message).join("; ");
+		super(`Query "${queryName}" input validation failed: ${message}`);
+		this.queryName = queryName;
+		this.issues = issues;
+		this.name = "QueryInputValidationError";
+	}
+};
+/**
+* Error thrown when query output validation fails
+*/
+var QueryOutputValidationError = class extends WorkerError {
+	constructor(queryName, issues) {
+		const message = issues.map((issue) => issue.message).join("; ");
+		super(`Query "${queryName}" output validation failed: ${message}`);
+		this.queryName = queryName;
+		this.issues = issues;
+		this.name = "QueryOutputValidationError";
+	}
+};
+/**
+* Error thrown when update input validation fails
+*/
+var UpdateInputValidationError = class extends WorkerError {
+	constructor(updateName, issues) {
+		const message = issues.map((issue) => issue.message).join("; ");
+		super(`Update "${updateName}" input validation failed: ${message}`);
+		this.updateName = updateName;
+		this.issues = issues;
+		this.name = "UpdateInputValidationError";
+	}
+};
+/**
+* Error thrown when update output validation fails
+*/
+var UpdateOutputValidationError = class extends WorkerError {
+	constructor(updateName, issues) {
+		const message = issues.map((issue) => issue.message).join("; ");
+		super(`Update "${updateName}" output validation failed: ${message}`);
+		this.updateName = updateName;
+		this.issues = issues;
+		this.name = "UpdateOutputValidationError";
+	}
+};
+/**
+* Error thrown when a child workflow is not found in the contract
+*/
+var ChildWorkflowNotFoundError = class extends WorkerError {
+	constructor(workflowName, availableWorkflows = []) {
+		const available = availableWorkflows.length > 0 ? availableWorkflows.join(", ") : "none";
+		super(`Child workflow not found: "${workflowName}". Available workflows: ${available}`);
+		this.workflowName = workflowName;
+		this.availableWorkflows = availableWorkflows;
+		this.name = "ChildWorkflowNotFoundError";
+	}
+};
+/**
+* Generic error for child workflow operations
+*/
+var ChildWorkflowError = class extends WorkerError {
+	constructor(message, cause) {
+		super(message, cause);
+		this.name = "ChildWorkflowError";
+	}
+};
+
+//#endregion
+//#region src/handler.ts
+/**
+* Create a validated activities proxy that parses inputs and outputs
+*
+* This wrapper ensures data integrity across the network boundary between
+* workflow and activity execution.
+*/
+function createValidatedActivities(rawActivities, workflowActivitiesDefinition, contractActivitiesDefinition) {
+	const validatedActivities = {};
+	const allActivitiesDefinition = {
+		...contractActivitiesDefinition,
+		...workflowActivitiesDefinition
+	};
+	for (const [activityName, activityDef] of Object.entries(allActivitiesDefinition)) {
+		const rawActivity = rawActivities[activityName];
+		if (!rawActivity) throw new Error(`Activity implementation not found for: "${activityName}". Available activities: ${Object.keys(rawActivities).length > 0 ? Object.keys(rawActivities).join(", ") : "none"}`);
+		const wrappedActivity = async (input) => {
+			const inputResult = await activityDef.input["~standard"].validate(input);
+			if (inputResult.issues) throw new ActivityInputValidationError(activityName, inputResult.issues);
+			const result = await rawActivity(inputResult.value);
+			const outputResult = await activityDef.output["~standard"].validate(result);
+			if (outputResult.issues) throw new ActivityOutputValidationError(activityName, outputResult.issues);
+			return outputResult.value;
+		};
+		validatedActivities[activityName] = wrappedActivity;
+	}
+	return validatedActivities;
+}
+/**
+* Create a typed activities handler with automatic validation and Result pattern
+*
+* This wraps all activity implementations with:
+* - Validation at network boundaries
+* - Result<T, ActivityError> pattern for explicit error handling
+* - Automatic conversion from Result to Promise (throwing on Error)
+*
+* TypeScript ensures ALL activities (global + workflow-specific) are implemented.
+*
+* Use this to create the activities object for the Temporal Worker.
+*
+* @example
+* ```ts
+* import { declareActivitiesHandler, ActivityError } from '@temporal-contract/worker/activity';
+* import { Result, Future } from '@temporal-contract/boxed';
+* import myContract from './contract';
+*
+* export const activitiesHandler = declareActivitiesHandler({
+*   contract: myContract,
+*   activities: {
+*     // Activity returns Result instead of throwing
+*     // All technical exceptions must be wrapped in ActivityError for retry policies
+*     sendEmail: (args) => {
+*       return Future.make(async resolve => {
+*         try {
+*           await emailService.send(args);
+*           resolve(Result.Ok({ sent: true }));
+*         } catch (error) {
+*           // Wrap technical errors in ActivityError to enable retries
+*           resolve(Result.Error(
+*             new ActivityError(
+*               'EMAIL_SEND_FAILED',
+*               'Failed to send email',
+*               error // Original error as cause for debugging
+*             )
+*           ));
+*         }
+*       });
+*     },
+*   },
+* });
+*
+* // 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,
+* });
+* ```
+*/
+function declareActivitiesHandler(options) {
+	const { contract, activities } = options;
+	const wrappedActivities = {};
+	const allDefinitions = [];
+	if (contract.activities) allDefinitions.push(...Object.keys(contract.activities));
+	for (const workflow of Object.values(contract.workflows)) if (workflow.activities) allDefinitions.push(...Object.keys(workflow.activities));
+	for (const [activityName, activityImpl] of Object.entries(activities)) {
+		let activityDef;
+		if (contract.activities?.[activityName]) activityDef = contract.activities[activityName];
+		else for (const workflow of Object.values(contract.workflows)) if (workflow.activities?.[activityName]) {
+			activityDef = workflow.activities[activityName];
+			break;
+		}
+		if (!activityDef) throw new ActivityDefinitionNotFoundError(activityName, allDefinitions);
+		wrappedActivities[activityName] = async (...args) => {
+			const input = args.length === 1 ? args[0] : args;
+			const inputResult = await activityDef.input["~standard"].validate(input);
+			if (inputResult.issues) throw new ActivityInputValidationError(activityName, inputResult.issues);
+			const result = await activityImpl(inputResult.value);
+			if (result.isOk()) {
+				const outputResult = await activityDef.output["~standard"].validate(result.value);
+				if (outputResult.issues) throw new ActivityOutputValidationError(activityName, outputResult.issues);
+				return outputResult.value;
+			} else throw result.error;
+		};
+	}
+	return {
+		contract,
+		activities: wrappedActivities
+	};
+}
+/**
+* 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,
+* });
+* ```
+*/
+function declareWorkflow(options) {
+	const { workflowName, contract, implementation, activityOptions } = options;
+	const definition = contract.workflows[workflowName];
+	return async (args) => {
+		const singleArg = Array.isArray(args) ? args[0] : args;
+		const inputResult = await definition.input["~standard"].validate(singleArg);
+		if (inputResult.issues) throw new WorkflowInputValidationError(String(workflowName), inputResult.issues);
+		const validatedInput = inputResult.value;
+		let contextActivities = {};
+		if (definition.activities || contract.activities) contextActivities = createValidatedActivities(proxyActivities({
+			startToCloseTimeout: activityOptions?.startToCloseTimeout ?? 6e4,
+			...activityOptions
+		}), definition.activities, contract.activities);
+		async function validateChildWorkflowOutput(childDefinition, result$1, childWorkflowName) {
+			const outputResult$1 = await childDefinition.output["~standard"].validate(result$1);
+			if (outputResult$1.issues) return Result.Error(new ChildWorkflowError(`Child workflow "${childWorkflowName}" output validation failed: ${outputResult$1.issues.map((i) => i.message).join("; ")}`));
+			return Result.Ok(outputResult$1.value);
+		}
+		async function getAndValidateChildWorkflow(childContract, childWorkflowName, args$1) {
+			const childDefinition = childContract.workflows[childWorkflowName];
+			if (!childDefinition) return Result.Error(new ChildWorkflowNotFoundError(String(childWorkflowName), Object.keys(childContract.workflows)));
+			const inputResult$1 = await childDefinition.input["~standard"].validate(args$1);
+			if (inputResult$1.issues) return Result.Error(new ChildWorkflowError(`Child workflow "${String(childWorkflowName)}" input validation failed: ${inputResult$1.issues.map((i) => i.message).join("; ")}`));
+			const validatedInput$1 = inputResult$1.value;
+			return Result.Ok({
+				definition: childDefinition,
+				validatedInput: validatedInput$1,
+				taskQueue: childContract.taskQueue
+			});
+		}
+		function createTypedChildHandle(handle, childDefinition, childWorkflowName) {
+			return {
+				workflowId: handle.workflowId,
+				result: () => {
+					return Future.make((resolve) => {
+						(async () => {
+							try {
+								resolve(await validateChildWorkflowOutput(childDefinition, await handle.result(), childWorkflowName));
+							} catch (error) {
+								resolve(Result.Error(new ChildWorkflowError(`Child workflow execution failed: ${error instanceof Error ? error.message : String(error)}`, error)));
+							}
+						})();
+					});
+				}
+			};
+		}
+		function createStartChildWorkflow(childContract, childWorkflowName, options$1) {
+			return Future.make((resolve) => {
+				(async () => {
+					const validationResult = await getAndValidateChildWorkflow(childContract, childWorkflowName, options$1.args);
+					if (validationResult.isError()) {
+						resolve(Result.Error(validationResult.error));
+						return;
+					}
+					const { definition: childDefinition, validatedInput: validatedInput$1, taskQueue } = validationResult.value;
+					try {
+						const { args: _args, ...temporalOptions } = options$1;
+						const typedHandle = createTypedChildHandle(await startChild(childWorkflowName, {
+							...temporalOptions,
+							taskQueue,
+							args: [validatedInput$1]
+						}), childDefinition, String(childWorkflowName));
+						resolve(Result.Ok(typedHandle));
+					} catch (error) {
+						resolve(Result.Error(new ChildWorkflowError(`Failed to start child workflow: ${error instanceof Error ? error.message : String(error)}`, error)));
+					}
+				})();
+			});
+		}
+		function createExecuteChildWorkflow(childContract, childWorkflowName, options$1) {
+			return Future.make((resolve) => {
+				(async () => {
+					const validationResult = await getAndValidateChildWorkflow(childContract, childWorkflowName, options$1.args);
+					if (validationResult.isError()) {
+						resolve(Result.Error(validationResult.error));
+						return;
+					}
+					const { definition: childDefinition, validatedInput: validatedInput$1, taskQueue } = validationResult.value;
+					try {
+						const { args: _args, ...temporalOptions } = options$1;
+						const outputValidationResult = await validateChildWorkflowOutput(childDefinition, await executeChild(childWorkflowName, {
+							...temporalOptions,
+							taskQueue,
+							args: [validatedInput$1]
+						}), String(childWorkflowName));
+						if (outputValidationResult.isError()) {
+							resolve(Result.Error(outputValidationResult.error));
+							return;
+						}
+						resolve(Result.Ok(outputValidationResult.value));
+					} catch (error) {
+						resolve(Result.Error(new ChildWorkflowError(`Failed to execute child workflow: ${error instanceof Error ? error.message : String(error)}`, error)));
+					}
+				})();
+			});
+		}
+		function createDefineSignal(signalName, handler) {
+			if (!definition.signals) throw new Error(`Signal "${String(signalName)}" cannot be defined: workflow "${String(workflowName)}" has no signals in its contract`);
+			const signalDef = definition.signals[signalName];
+			if (!signalDef) throw new Error(`Signal "${String(signalName)}" not found in workflow "${String(workflowName)}" contract`);
+			setHandler(defineSignal(signalName), async (...args$1) => {
+				const input = args$1.length === 1 ? args$1[0] : args$1;
+				const inputResult$1 = await signalDef.input["~standard"].validate(input);
+				if (inputResult$1.issues) throw new SignalInputValidationError(signalName, inputResult$1.issues);
+				await handler(inputResult$1.value);
+			});
+		}
+		function createDefineQuery(queryName, handler) {
+			if (!definition.queries) throw new Error(`Query "${String(queryName)}" cannot be defined: workflow "${String(workflowName)}" has no queries in its contract`);
+			const queryDef = definition.queries[queryName];
+			if (!queryDef) throw new Error(`Query "${String(queryName)}" not found in workflow "${String(workflowName)}" contract`);
+			setHandler(defineQuery(queryName), (...args$1) => {
+				const input = args$1.length === 1 ? args$1[0] : args$1;
+				const inputResult$1 = queryDef.input["~standard"].validate(input);
+				if (inputResult$1 instanceof Promise) throw new Error(`Query "${String(queryName)}" validation must be synchronous. Use a schema library that supports synchronous validation for queries.`);
+				if (inputResult$1.issues) throw new QueryInputValidationError(queryName, inputResult$1.issues);
+				const result$1 = handler(inputResult$1.value);
+				const outputResult$1 = queryDef.output["~standard"].validate(result$1);
+				if (outputResult$1 instanceof Promise) throw new Error(`Query "${String(queryName)}" output validation must be synchronous. Use a schema library that supports synchronous validation for queries.`);
+				if (outputResult$1.issues) throw new QueryOutputValidationError(queryName, outputResult$1.issues);
+				return outputResult$1.value;
+			});
+		}
+		function createDefineUpdate(updateName, handler) {
+			if (!definition.updates) throw new Error(`Update "${String(updateName)}" cannot be defined: workflow "${String(workflowName)}" has no updates in its contract`);
+			const updateDef = definition.updates[updateName];
+			if (!updateDef) throw new Error(`Update "${String(updateName)}" not found in workflow "${String(workflowName)}" contract`);
+			setHandler(defineUpdate(updateName), async (...args$1) => {
+				const input = args$1.length === 1 ? args$1[0] : args$1;
+				const inputResult$1 = await updateDef.input["~standard"].validate(input);
+				if (inputResult$1.issues) throw new UpdateInputValidationError(updateName, inputResult$1.issues);
+				const result$1 = await handler(inputResult$1.value);
+				const outputResult$1 = await updateDef.output["~standard"].validate(result$1);
+				if (outputResult$1.issues) throw new UpdateOutputValidationError(updateName, outputResult$1.issues);
+				return outputResult$1.value;
+			});
+		}
+		const result = await implementation({
+			activities: contextActivities,
+			info: workflowInfo(),
+			startChildWorkflow: createStartChildWorkflow,
+			executeChildWorkflow: createExecuteChildWorkflow,
+			defineSignal: createDefineSignal,
+			defineQuery: createDefineQuery,
+			defineUpdate: createDefineUpdate
+		}, validatedInput);
+		const outputResult = await definition.output["~standard"].validate(result);
+		if (outputResult.issues) throw new WorkflowOutputValidationError(String(workflowName), outputResult.issues);
+		return outputResult.value;
+	};
+}
+
+//#endregion
+export { ActivityInputValidationError as a, ChildWorkflowNotFoundError as c, SignalInputValidationError as d, UpdateInputValidationError as f, WorkflowOutputValidationError as g, WorkflowInputValidationError as h, ActivityError as i, QueryInputValidationError as l, WorkerError as m, declareWorkflow as n, ActivityOutputValidationError as o, UpdateOutputValidationError as p, ActivityDefinitionNotFoundError as r, ChildWorkflowError as s, declareActivitiesHandler as t, QueryOutputValidationError as u };