@temporal-contract/worker 2.0.0 → 2.1.0

package/dist/workflow.cjs

@@ -1,7 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_internal = require("./internal-C8MB-kez.cjs");
+const require_internal = require("./internal-Cwch3OHR.cjs");
 let _temporalio_workflow = require("@temporalio/workflow");
 let neverthrow = require("neverthrow");
+let _temporal_contract_contract_result_async = require("@temporal-contract/contract/result-async");
 //#region src/cancellation.ts
 /**
 * Typed wrappers around Temporal's `CancellationScope` so workflows can
@@ -11,9 +12,11 @@ let neverthrow = require("neverthrow");
 * context — callers branch on `err(WorkflowCancelledError)` instead of
 * catching `CancelledFailure`.
 *
-* Non-cancellation errors thrown inside the scope are *not* swallowed:
-* the ResultAsync rejects with the original error so user-domain failures
-* keep their identity.
+* Non-cancellation errors thrown inside the scope are wrapped in a
+* {@link WorkflowScopeError} (with the original error preserved on
+* `cause`) and surfaced on the same `err(...)` channel. Together with
+* `WorkflowCancelledError` this makes the failure modes exhaustive on
+* `result.match(...)` — nothing escapes as an unhandled rejection.
 */
 /**
 * Run `fn` inside a cancellable Temporal scope. If the workflow (or an
@@ -22,6 +25,11 @@ let neverthrow = require("neverthrow");
 * letting callers handle cancellation explicitly — typically to perform
 * a graceful exit from the current step.
 *
+* Non-cancellation errors thrown by `fn` resolve to
+* `err(WorkflowScopeError)` (with the original error on `cause`) so
+* domain failures surface on the same typed error channel rather than
+* leaking as unhandled rejections.
+*
 * @example
 * ```ts
 * const result = await context.cancellableScope(async () => {
@@ -30,8 +38,12 @@ let neverthrow = require("neverthrow");
 *
 * result.match(
 *   (output) => { ... },
-*   (cancelled) => {
-*     // cancelled instanceof WorkflowCancelledError — graceful exit
+*   (error) => {
+*     if (error instanceof WorkflowCancelledError) {
+*       // graceful exit
+*     } else {
+*       // error instanceof WorkflowScopeError — domain failure on `cause`
+*     }
 *   },
 * );
 * ```
@@ -42,10 +54,10 @@ function cancellableScope(fn) {
 			return (0, neverthrow.ok)(await _temporalio_workflow.CancellationScope.cancellable(async () => fn()));
 		} catch (error) {
 			if ((0, _temporalio_workflow.isCancellation)(error)) return (0, neverthrow.err)(new require_internal.WorkflowCancelledError(error));
-			throw error;
+			return (0, neverthrow.err)(new require_internal.WorkflowScopeError(error));
 		}
 	};
-	return new neverthrow.ResultAsync(work());
+	return (0, _temporal_contract_contract_result_async._internal_makeResultAsync)(work, (e) => new require_internal.WorkflowScopeError(e));
 }
 /**
 * Run `fn` inside a non-cancellable Temporal scope. Cancellation requests
@@ -53,9 +65,10 @@ function cancellableScope(fn) {
 * to perform cleanup that must not be interrupted (e.g. releasing a
 * resource after a graceful shutdown).
 *
-* Mirrors `cancellableScope`'s `ResultAsync<...>` shape for symmetry;
-* the `err(...)` branch only triggers when cancellation is raised from
-* inside the scope (rare).
+* Mirrors `cancellableScope`'s `ResultAsync<...>` shape for symmetry; the
+* `err(WorkflowCancelledError)` branch only triggers when cancellation is
+* raised from inside the scope (rare). Non-cancellation errors surface as
+* `err(WorkflowScopeError)`.
 *
 * @example
 * ```ts
@@ -70,10 +83,10 @@ function nonCancellableScope(fn) {
 			return (0, neverthrow.ok)(await _temporalio_workflow.CancellationScope.nonCancellable(async () => fn()));
 		} catch (error) {
 			if ((0, _temporalio_workflow.isCancellation)(error)) return (0, neverthrow.err)(new require_internal.WorkflowCancelledError(error));
-			throw error;
+			return (0, neverthrow.err)(new require_internal.WorkflowScopeError(error));
 		}
 	};
-	return new neverthrow.ResultAsync(work());
+	return (0, _temporal_contract_contract_result_async._internal_makeResultAsync)(work, (e) => new require_internal.WorkflowScopeError(e));
 }
 //#endregion
 //#region src/handlers.ts
@@ -125,8 +138,30 @@ function bindQueryHandler(workflowDefinition, workflowName, queryName, handler)
 	});
 }
 /**
-* Bind a typed update handler to the running workflow. Validates both
-* input and output (asynchronously, like signals).
+* Bind a typed update handler to the running workflow.
+*
+* Input validation runs in Temporal's `validator` slot — a synchronous
+* pre-admission hook. If it throws, Temporal rejects the update *before*
+* appending a workflow history event: clients see
+* `WorkflowUpdateValidationRejectedError` and the workflow's history is
+* unaffected. This is the documented contract for `setHandler`'s
+* `validator` option, and it is strictly better than running validation
+* inside the handler body — which forces Temporal to admit the update,
+* write a history event, and surface a `WorkflowUpdateFailedError` to
+* the client only after the fact.
+*
+* Because the validator slot is synchronous, the input schema must also
+* validate synchronously. Standard Schema is allowed to be async (Zod's
+* `.refine(async)` is the typical case), but we trip a clear error when
+* that happens rather than silently breaking admission semantics — same
+* approach as `bindQueryHandler`. Users who need async input checks
+* should run them inside the handler body and accept the post-admission
+* failure mode, or restructure their schema.
+*
+* Output validation continues to run inside the handler body. Update
+* outputs are *not* admission-gated — the handler must execute to
+* produce a value to validate against — so the async-allowed shape is
+* preserved.
 */
 function bindUpdateHandler(workflowDefinition, workflowName, updateName, handler) {
 	if (!workflowDefinition.updates) throw new Error(`Update "${updateName}" cannot be defined: workflow "${workflowName}" has no updates in its contract`);
@@ -134,14 +169,120 @@ function bindUpdateHandler(workflowDefinition, workflowName, updateName, handler
 	if (!updateDef) throw new Error(`Update "${updateName}" not found in workflow "${workflowName}" contract`);
 	(0, _temporalio_workflow.setHandler)((0, _temporalio_workflow.defineUpdate)(updateName), async (...args) => {
 		const input = require_internal.extractHandlerInput(args);
-		const inputResult = await updateDef.input["~standard"].validate(input);
+		const inputResult = updateDef.input["~standard"].validate(input);
+		if (inputResult instanceof Promise) throw new Error(`Update "${updateName}" input validation must be synchronous. Use a schema library that supports synchronous validation for update inputs (Temporal's update validator slot is synchronous).`);
 		if (inputResult.issues) throw new require_internal.UpdateInputValidationError(updateName, inputResult.issues);
 		const result = await handler(inputResult.value);
 		const outputResult = await updateDef.output["~standard"].validate(result);
 		if (outputResult.issues) throw new require_internal.UpdateOutputValidationError(updateName, outputResult.issues);
 		return outputResult.value;
+	}, { validator: (...args) => {
+		const input = require_internal.extractHandlerInput(args);
+		const inputResult = updateDef.input["~standard"].validate(input);
+		if (inputResult instanceof Promise) throw new Error(`Update "${updateName}" input validation must be synchronous. Use a schema library that supports synchronous validation for update inputs (Temporal's update validator slot is synchronous).`);
+		if (inputResult.issues) throw new require_internal.UpdateInputValidationError(updateName, inputResult.issues);
+	} });
+}
+//#endregion
+//#region src/child-workflow.ts
+async function validateChildWorkflowOutput(childDefinition, result, childWorkflowName) {
+	const outputResult = await childDefinition.output["~standard"].validate(result);
+	if (outputResult.issues) return (0, neverthrow.err)(new require_internal.ChildWorkflowError(require_internal.formatChildWorkflowValidationMessage(childWorkflowName, "output", outputResult.issues)));
+	return (0, neverthrow.ok)(outputResult.value);
+}
+async function getAndValidateChildWorkflow(childContract, childWorkflowName, args) {
+	const childDefinition = childContract.workflows[childWorkflowName];
+	if (!childDefinition) return (0, neverthrow.err)(new require_internal.ChildWorkflowNotFoundError(childWorkflowName, Object.keys(childContract.workflows)));
+	const inputResult = await childDefinition.input["~standard"].validate(args);
+	if (inputResult.issues) return (0, neverthrow.err)(new require_internal.ChildWorkflowError(require_internal.formatChildWorkflowValidationMessage(childWorkflowName, "input", inputResult.issues)));
+	const validatedInput = inputResult.value;
+	return (0, neverthrow.ok)({
+		definition: childDefinition,
+		validatedInput,
+		taskQueue: childContract.taskQueue
 	});
 }
+function createTypedChildHandle(handle, childDefinition, childWorkflowName) {
+	return {
+		workflowId: handle.workflowId,
+		result: () => {
+			const work = async () => {
+				try {
+					return validateChildWorkflowOutput(childDefinition, await handle.result(), childWorkflowName);
+				} catch (error) {
+					return (0, neverthrow.err)(require_internal.classifyChildWorkflowError("result", error, childWorkflowName));
+				}
+			};
+			return (0, _temporal_contract_contract_result_async._internal_makeResultAsync)(work, (error) => new require_internal.ChildWorkflowError(`Child workflow execution failed: ${error instanceof Error ? error.message : String(error)}`, error));
+		}
+	};
+}
+function createStartChildWorkflow(childContract, childWorkflowName, options) {
+	const work = async () => {
+		const validationResult = await getAndValidateChildWorkflow(childContract, childWorkflowName, options.args);
+		if (validationResult.isErr()) return (0, neverthrow.err)(validationResult.error);
+		const { definition: childDefinition, validatedInput, taskQueue } = validationResult.value;
+		try {
+			const { args: _args, ...temporalOptions } = options;
+			return (0, neverthrow.ok)(createTypedChildHandle(await (0, _temporalio_workflow.startChild)(childWorkflowName, {
+				...temporalOptions,
+				taskQueue,
+				args: [validatedInput]
+			}), childDefinition, childWorkflowName));
+		} catch (error) {
+			return (0, neverthrow.err)(require_internal.classifyChildWorkflowError("startChild", error, String(childWorkflowName)));
+		}
+	};
+	return (0, _temporal_contract_contract_result_async._internal_makeResultAsync)(work, (error) => new require_internal.ChildWorkflowError(`Failed to start child workflow: ${error instanceof Error ? error.message : String(error)}`, error));
+}
+function createExecuteChildWorkflow(childContract, childWorkflowName, options) {
+	const work = async () => {
+		const validationResult = await getAndValidateChildWorkflow(childContract, childWorkflowName, options.args);
+		if (validationResult.isErr()) return (0, neverthrow.err)(validationResult.error);
+		const { definition: childDefinition, validatedInput, taskQueue } = validationResult.value;
+		try {
+			const { args: _args, ...temporalOptions } = options;
+			const outputValidationResult = await validateChildWorkflowOutput(childDefinition, await (0, _temporalio_workflow.executeChild)(childWorkflowName, {
+				...temporalOptions,
+				taskQueue,
+				args: [validatedInput]
+			}), childWorkflowName);
+			if (outputValidationResult.isErr()) return (0, neverthrow.err)(outputValidationResult.error);
+			return (0, neverthrow.ok)(outputValidationResult.value);
+		} catch (error) {
+			return (0, neverthrow.err)(require_internal.classifyChildWorkflowError("executeChild", error, String(childWorkflowName)));
+		}
+	};
+	return (0, _temporal_contract_contract_result_async._internal_makeResultAsync)(work, (error) => new require_internal.ChildWorkflowError(`Failed to execute child workflow: ${error instanceof Error ? error.message : String(error)}`, error));
+}
+//#endregion
+//#region src/activities-proxy.ts
+/**
+* Wrap the raw activities proxy with input/output validation against the
+* Standard Schema definitions on the contract. The wrapper enforces data
+* integrity at the workflow → activity boundary in addition to the
+* activity-side validation that `declareActivitiesHandler` already runs.
+*/
+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"}`);
+		validatedActivities[activityName] = async (input) => {
+			const inputResult = await activityDef.input["~standard"].validate(input);
+			if (inputResult.issues) throw new require_internal.ActivityInputValidationError(activityName, inputResult.issues);
+			const result = await rawActivity(inputResult.value);
+			const outputResult = await activityDef.output["~standard"].validate(result);
+			if (outputResult.issues) throw new require_internal.ActivityOutputValidationError(activityName, outputResult.issues);
+			return outputResult.value;
+		};
+	}
+	return validatedActivities;
+}
 //#endregion
 //#region src/workflow.ts
 /**
@@ -219,13 +360,16 @@ function bindUpdateHandler(workflowDefinition, workflowName, updateName, handler
 */
 function declareWorkflow({ workflowName, contract, implementation, activityOptions, activityOptionsByName }) {
 	const definition = contract.workflows[workflowName];
+	let contextActivities = {};
+	if (definition.activities || contract.activities) {
+		contextActivities = createValidatedActivities(require_internal.buildRawActivitiesProxy(definition.activities, contract.activities, activityOptions, activityOptionsByName), definition.activities, contract.activities);
+		Object.freeze(contextActivities);
+	}
 	return async (...args) => {
 		const input = require_internal.extractHandlerInput(args);
 		const inputResult = await definition.input["~standard"].validate(input);
-		if (inputResult.issues) throw new require_internal.WorkflowInputValidationError(String(workflowName), inputResult.issues);
+		if (inputResult.issues) throw new require_internal.WorkflowInputValidationError(workflowName, inputResult.issues);
 		const validatedInput = inputResult.value;
-		let contextActivities = {};
-		if (definition.activities || contract.activities) contextActivities = createValidatedActivities(require_internal.buildRawActivitiesProxy(definition.activities, contract.activities, activityOptions, activityOptionsByName), definition.activities, contract.activities);
 		const result = await implementation({
 			activities: contextActivities,
 			info: (0, _temporalio_workflow.workflowInfo)(),
@@ -233,115 +377,20 @@ function declareWorkflow({ workflowName, contract, implementation, activityOptio
 			executeChildWorkflow: createExecuteChildWorkflow,
 			cancellableScope,
 			nonCancellableScope,
-			defineSignal: ((signalName, handler) => bindSignalHandler(definition, String(workflowName), signalName, handler)),
-			defineQuery: ((queryName, handler) => bindQueryHandler(definition, String(workflowName), queryName, handler)),
-			defineUpdate: ((updateName, handler) => bindUpdateHandler(definition, String(workflowName), updateName, handler)),
+			defineSignal: ((signalName, handler) => bindSignalHandler(definition, workflowName, signalName, handler)),
+			defineQuery: ((queryName, handler) => bindQueryHandler(definition, workflowName, queryName, handler)),
+			defineUpdate: ((updateName, handler) => bindUpdateHandler(definition, workflowName, updateName, handler)),
 			continueAsNew: require_internal.createContinueAsNew(contract, workflowName)
 		}, validatedInput);
 		const outputResult = await definition.output["~standard"].validate(result);
-		if (outputResult.issues) throw new require_internal.WorkflowOutputValidationError(String(workflowName), outputResult.issues);
+		if (outputResult.issues) throw new require_internal.WorkflowOutputValidationError(workflowName, outputResult.issues);
 		return outputResult.value;
 	};
 }
-/**
-* 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"}`);
-		validatedActivities[activityName] = async (input) => {
-			const inputResult = await activityDef.input["~standard"].validate(input);
-			if (inputResult.issues) throw new require_internal.ActivityInputValidationError(activityName, inputResult.issues);
-			const result = await rawActivity(inputResult.value);
-			const outputResult = await activityDef.output["~standard"].validate(result);
-			if (outputResult.issues) throw new require_internal.ActivityOutputValidationError(activityName, outputResult.issues);
-			return outputResult.value;
-		};
-	}
-	return validatedActivities;
-}
-async function validateChildWorkflowOutput(childDefinition, result, childWorkflowName) {
-	const outputResult = await childDefinition.output["~standard"].validate(result);
-	if (outputResult.issues) return (0, neverthrow.err)(new require_internal.ChildWorkflowError(require_internal.formatChildWorkflowValidationMessage(childWorkflowName, "output", outputResult.issues)));
-	return (0, neverthrow.ok)(outputResult.value);
-}
-async function getAndValidateChildWorkflow(childContract, childWorkflowName, args) {
-	const childDefinition = childContract.workflows[childWorkflowName];
-	if (!childDefinition) return (0, neverthrow.err)(new require_internal.ChildWorkflowNotFoundError(String(childWorkflowName), Object.keys(childContract.workflows)));
-	const inputResult = await childDefinition.input["~standard"].validate(args);
-	if (inputResult.issues) return (0, neverthrow.err)(new require_internal.ChildWorkflowError(require_internal.formatChildWorkflowValidationMessage(String(childWorkflowName), "input", inputResult.issues)));
-	const validatedInput = inputResult.value;
-	return (0, neverthrow.ok)({
-		definition: childDefinition,
-		validatedInput,
-		taskQueue: childContract.taskQueue
-	});
-}
-function createTypedChildHandle(handle, childDefinition, childWorkflowName) {
-	return {
-		workflowId: handle.workflowId,
-		result: () => {
-			const work = async () => {
-				try {
-					return validateChildWorkflowOutput(childDefinition, await handle.result(), childWorkflowName);
-				} catch (error) {
-					return (0, neverthrow.err)(new require_internal.ChildWorkflowError(`Child workflow execution failed: ${error instanceof Error ? error.message : String(error)}`, error));
-				}
-			};
-			return new neverthrow.ResultAsync(work());
-		}
-	};
-}
-function createStartChildWorkflow(childContract, childWorkflowName, options) {
-	const work = async () => {
-		const validationResult = await getAndValidateChildWorkflow(childContract, childWorkflowName, options.args);
-		if (validationResult.isErr()) return (0, neverthrow.err)(validationResult.error);
-		const { definition: childDefinition, validatedInput, taskQueue } = validationResult.value;
-		try {
-			const { args: _args, ...temporalOptions } = options;
-			return (0, neverthrow.ok)(createTypedChildHandle(await (0, _temporalio_workflow.startChild)(childWorkflowName, {
-				...temporalOptions,
-				taskQueue,
-				args: [validatedInput]
-			}), childDefinition, String(childWorkflowName)));
-		} catch (error) {
-			return (0, neverthrow.err)(new require_internal.ChildWorkflowError(`Failed to start child workflow: ${error instanceof Error ? error.message : String(error)}`, error));
-		}
-	};
-	return new neverthrow.ResultAsync(work());
-}
-function createExecuteChildWorkflow(childContract, childWorkflowName, options) {
-	const work = async () => {
-		const validationResult = await getAndValidateChildWorkflow(childContract, childWorkflowName, options.args);
-		if (validationResult.isErr()) return (0, neverthrow.err)(validationResult.error);
-		const { definition: childDefinition, validatedInput, taskQueue } = validationResult.value;
-		try {
-			const { args: _args, ...temporalOptions } = options;
-			const outputValidationResult = await validateChildWorkflowOutput(childDefinition, await (0, _temporalio_workflow.executeChild)(childWorkflowName, {
-				...temporalOptions,
-				taskQueue,
-				args: [validatedInput]
-			}), String(childWorkflowName));
-			if (outputValidationResult.isErr()) return (0, neverthrow.err)(outputValidationResult.error);
-			return (0, neverthrow.ok)(outputValidationResult.value);
-		} catch (error) {
-			return (0, neverthrow.err)(new require_internal.ChildWorkflowError(`Failed to execute child workflow: ${error instanceof Error ? error.message : String(error)}`, error));
-		}
-	};
-	return new neverthrow.ResultAsync(work());
-}
 //#endregion
 exports.ActivityInputValidationError = require_internal.ActivityInputValidationError;
 exports.ActivityOutputValidationError = require_internal.ActivityOutputValidationError;
+exports.ChildWorkflowCancelledError = require_internal.ChildWorkflowCancelledError;
 exports.ChildWorkflowError = require_internal.ChildWorkflowError;
 exports.ChildWorkflowNotFoundError = require_internal.ChildWorkflowNotFoundError;
 exports.QueryInputValidationError = require_internal.QueryInputValidationError;
@@ -352,4 +401,5 @@ exports.UpdateOutputValidationError = require_internal.UpdateOutputValidationErr
 exports.WorkflowCancelledError = require_internal.WorkflowCancelledError;
 exports.WorkflowInputValidationError = require_internal.WorkflowInputValidationError;
 exports.WorkflowOutputValidationError = require_internal.WorkflowOutputValidationError;
+exports.WorkflowScopeError = require_internal.WorkflowScopeError;
 exports.declareWorkflow = declareWorkflow;