@fragno-dev/db 0.2.1 → 0.3.0

package/dist/query/unit-of-work/execute-unit-of-work.js

@@ -2,188 +2,249 @@ import { ExponentialBackoffRetryPolicy, NoRetryPolicy } from "./retry-policy.js"
 
 //#region src/query/unit-of-work/execute-unit-of-work.ts
 /**
-* Error thrown when a Unit of Work execution fails due to optimistic concurrency conflict.
-* This error triggers automatic retry behavior in executeRestrictedUnitOfWork.
+* Symbol to identify TxResult objects
 */
-var ConcurrencyConflictError = class extends Error {
-	constructor(message = "Optimistic concurrency conflict detected") {
-		super(message);
-		this.name = "ConcurrencyConflictError";
+const TX_RESULT_BRAND = Symbol("TxResult");
+/**
+* Create a TxResult for service context.
+* Schedules retrieve operations on the baseUow and returns a TxResult with callbacks stored.
+* @internal Used by ServiceTxBuilder.build()
+*/
+function createServiceTx(schema, callbacks, baseUow) {
+	const { promise: retrievePhase, resolve: resolveRetrievePhase, reject: rejectRetrievePhase } = Promise.withResolvers();
+	const restrictedUow = baseUow.restrict({ readyFor: "none" });
+	let serviceCalls;
+	try {
+		if (callbacks.serviceCalls) serviceCalls = callbacks.serviceCalls();
+	} catch (error) {
+		restrictedUow.signalReadyForRetrieval();
+		restrictedUow.signalReadyForMutation();
+		retrievePhase.catch(() => {});
+		rejectRetrievePhase(error);
+		throw error;
 	}
-};
+	let typedUow;
+	try {
+		if (schema && callbacks.retrieve) {
+			const emptyUow = restrictedUow.forSchema(schema);
+			typedUow = callbacks.retrieve(emptyUow);
+		}
+	} catch (error) {
+		restrictedUow.signalReadyForRetrieval();
+		restrictedUow.signalReadyForMutation();
+		retrievePhase.catch(() => {});
+		rejectRetrievePhase(error);
+		throw error;
+	}
+	restrictedUow.signalReadyForRetrieval();
+	if (typedUow) typedUow.retrievalPhase.then((results) => resolveRetrievePhase(results), (error) => rejectRetrievePhase(error));
+	else if (!callbacks.retrieve) resolveRetrievePhase([]);
+	const internal = {
+		schema,
+		callbacks,
+		typedUow,
+		restrictedUow,
+		retrievePhase,
+		resolveRetrievePhase,
+		rejectRetrievePhase,
+		retrieveSuccessResult: void 0,
+		mutateResult: void 0,
+		finalResult: void 0,
+		serviceCalls
+	};
+	return {
+		[TX_RESULT_BRAND]: true,
+		_internal: internal
+	};
+}
 /**
-* Await promises in an object 1 level deep
+* Recursively collect all TxResults from a service call tree.
+* Returns them in a flat array in dependency order (serviceCalls before their dependents).
+* Skips undefined values (which can occur with optional service patterns like
+* optionalService?.method()).
 */
-async function awaitPromisesInObject(obj) {
-	if (obj === null || obj === void 0) return obj;
-	if (typeof obj !== "object") return obj;
-	if (obj instanceof Promise) return await obj;
-	if (Array.isArray(obj)) return await Promise.all(obj.map((item) => item instanceof Promise ? item : Promise.resolve(item)));
-	const result = {};
-	const entries = Object.entries(obj);
-	const awaitedEntries = await Promise.all(entries.map(async ([key, value]) => {
-		return [key, value instanceof Promise ? await value : value];
-	}));
-	for (const [key, value] of awaitedEntries) result[key] = value;
-	return result;
+function collectAllTxResults(txResults) {
+	const collected = [];
+	const seen = /* @__PURE__ */ new Set();
+	function collect(txResult) {
+		if (txResult === void 0) return;
+		if (seen.has(txResult)) return;
+		seen.add(txResult);
+		const serviceCalls = txResult._internal.serviceCalls;
+		if (serviceCalls) for (const serviceCall of serviceCalls) collect(serviceCall);
+		collected.push(txResult);
+	}
+	for (const txResult of txResults) collect(txResult);
+	return collected;
 }
 /**
-* Execute a Unit of Work with automatic retry support for optimistic concurrency conflicts.
-*
-* This function orchestrates the two-phase execution (retrieval + mutation) with retry logic.
-* It creates fresh UOW instances for each attempt.
-*
-* @param callbacks - Object containing retrieve, mutate, and onSuccess callbacks
-* @param options - Configuration including UOW factory, retry policy, and abort signal
-* @returns Promise resolving to the execution result
-*
-* @example
-* ```ts
-* const result = await executeUnitOfWork(
-*   {
-*     retrieve: (uow) => uow.find("users", (b) => b.whereIndex("primary")),
-*     mutate: (uow, [users]) => {
-*       const user = users[0];
-*       uow.update("users", user.id, (b) => b.set({ balance: newBalance }));
-*     },
-*     onSuccess: async ({ results, mutationResult }) => {
-*       console.log("Update successful!");
-*     }
-*   },
-*   {
-*     createUnitOfWork: () => queryEngine.createUnitOfWork(),
-*     retryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 3 })
-*   }
-* );
-* ```
+* Execute a single TxResult's callbacks after retrieve phase completes.
+* This processes retrieveSuccess, mutate, and success callbacks in order.
 */
-async function executeUnitOfWork(callbacks, options) {
-	if (!callbacks.retrieve && !callbacks.mutate) throw new Error("At least one of 'retrieve' or 'mutate' callbacks must be provided");
-	const retryPolicy = options.retryPolicy ?? new NoRetryPolicy();
-	const signal = options.signal;
-	let attempt = 0;
-	while (true) {
-		if (signal?.aborted) return {
-			success: false,
-			reason: "aborted"
+async function processTxResultAfterRetrieve(txResult, baseUow) {
+	const internal = txResult._internal;
+	const callbacks = internal.callbacks;
+	const retrieveResults = await internal.retrievePhase;
+	const serviceResults = [];
+	if (internal.serviceCalls) for (const serviceCall of internal.serviceCalls) {
+		if (serviceCall === void 0) {
+			serviceResults.push(void 0);
+			continue;
+		}
+		const serviceCallInternal = serviceCall._internal;
+		if (serviceCallInternal.retrieveSuccessResult !== void 0 && !(Array.isArray(serviceCallInternal.retrieveSuccessResult) && serviceCallInternal.retrieveSuccessResult.length === 0 && serviceCallInternal.callbacks.mutate)) serviceResults.push(serviceCallInternal.retrieveSuccessResult);
+		else if (serviceCallInternal.mutateResult !== void 0) serviceResults.push(serviceCallInternal.mutateResult);
+		else serviceResults.push(serviceCallInternal.retrieveSuccessResult);
+	}
+	if (callbacks.retrieveSuccess) internal.retrieveSuccessResult = callbacks.retrieveSuccess(retrieveResults, serviceResults);
+	else internal.retrieveSuccessResult = retrieveResults;
+	if (callbacks.mutate) {
+		const mutateCtx = {
+			uow: internal.schema ? baseUow.forSchema(internal.schema) : void 0,
+			retrieveResult: internal.retrieveSuccessResult,
+			serviceIntermediateResult: serviceResults
 		};
-		try {
-			const uow = options.createUnitOfWork();
-			let retrievalUow;
-			if (callbacks.retrieve) retrievalUow = callbacks.retrieve(uow);
-			else retrievalUow = uow;
-			const results = await retrievalUow.executeRetrieve();
-			let mutationResult;
-			if (callbacks.mutate) mutationResult = await callbacks.mutate(retrievalUow, results);
-			else mutationResult = void 0;
-			const { success } = await retrievalUow.executeMutations();
-			if (success) {
-				const createdIds = retrievalUow.getCreatedIds();
-				const nonce = retrievalUow.nonce;
-				const awaitedMutationResult = await awaitPromisesInObject(mutationResult);
-				if (callbacks.onSuccess) await callbacks.onSuccess({
-					results,
-					mutationResult: awaitedMutationResult,
-					createdIds,
-					nonce
-				});
-				return {
-					success: true,
-					results,
-					mutationResult: awaitedMutationResult,
-					createdIds,
-					nonce
-				};
-			}
-			if (!retryPolicy.shouldRetry(attempt, void 0, signal)) return {
-				success: false,
-				reason: "conflict"
-			};
-			const delayMs = retryPolicy.getDelayMs(attempt);
-			if (delayMs > 0) await new Promise((resolve) => setTimeout(resolve, delayMs));
-			attempt++;
-		} catch (error) {
-			return {
-				success: false,
-				reason: "error",
-				error
-			};
+		internal.mutateResult = callbacks.mutate(mutateCtx);
+	}
+	if (internal.typedUow) internal.typedUow.signalReadyForMutation();
+	else internal.restrictedUow.signalReadyForMutation();
+}
+/**
+* Execute a single TxResult's success callback after mutations complete.
+*/
+async function processTxResultAfterMutate(txResult) {
+	const internal = txResult._internal;
+	const callbacks = internal.callbacks;
+	const serviceIntermediateResults = [];
+	const serviceFinalResults = [];
+	if (internal.serviceCalls) for (const serviceCall of internal.serviceCalls) {
+		if (serviceCall === void 0) {
+			serviceIntermediateResults.push(void 0);
+			serviceFinalResults.push(void 0);
+			continue;
 		}
+		const serviceCallInternal = serviceCall._internal;
+		if (serviceCallInternal.retrieveSuccessResult !== void 0 && !(Array.isArray(serviceCallInternal.retrieveSuccessResult) && serviceCallInternal.retrieveSuccessResult.length === 0 && serviceCallInternal.callbacks.mutate)) serviceIntermediateResults.push(serviceCallInternal.retrieveSuccessResult);
+		else if (serviceCallInternal.mutateResult !== void 0) serviceIntermediateResults.push(serviceCallInternal.mutateResult);
+		else serviceIntermediateResults.push(serviceCallInternal.retrieveSuccessResult);
+		serviceFinalResults.push(serviceCallInternal.finalResult);
 	}
+	if (callbacks.success) {
+		const successCtx = {
+			retrieveResult: internal.retrieveSuccessResult,
+			mutateResult: internal.mutateResult,
+			serviceResult: serviceFinalResults,
+			serviceIntermediateResult: serviceIntermediateResults
+		};
+		internal.finalResult = callbacks.success(successCtx);
+	} else if (callbacks.mutate) internal.finalResult = await awaitPromisesInObject(internal.mutateResult);
+	else if (callbacks.retrieveSuccess || callbacks.retrieve) internal.finalResult = internal.retrieveSuccessResult;
+	else internal.finalResult = serviceFinalResults;
+	return internal.finalResult;
 }
 /**
-* Execute a Unit of Work with explicit phase control and automatic retry support.
+* Execute a transaction with the unified TxResult pattern.
 *
-* This function provides an alternative API where users write a single callback that receives
-* a context object with forSchema, executeRetrieve, and executeMutate methods. The user can
-* create schema-specific UOWs via forSchema, then call executeRetrieve() and executeMutate()
-* to execute the retrieval and mutation phases. The entire callback is re-executed on optimistic
-* concurrency conflicts, ensuring retries work properly.
+* This is the handler-level function that actually executes TxResults with retry support.
 *
-* @param callback - Async function that receives a context with forSchema, executeRetrieve, executeMutate, nonce, and currentAttempt
+* @param callbacks - Transaction callbacks (serviceCalls, retrieve, retrieveSuccess, mutate, success)
 * @param options - Configuration including UOW factory, retry policy, and abort signal
-* @returns Promise resolving to the callback's return value
-* @throws Error if retries are exhausted or callback throws an error
+* @returns Promise resolving to the result determined by return type priority
 *
 * @example
 * ```ts
-* const { userId, profileId } = await executeRestrictedUnitOfWork(
-*   async ({ forSchema, executeRetrieve, executeMutate, nonce, currentAttempt }) => {
-*     const uow = forSchema(schema);
-*     const userId = uow.create("users", { name: "John" });
-*
-*     // Execute retrieval phase
-*     await executeRetrieve();
-*
-*     const profileId = uow.create("profiles", { userId });
-*
-*     // Execute mutation phase
-*     await executeMutate();
-*
-*     return { userId, profileId };
-*   },
-*   {
-*     createUnitOfWork: () => db.createUnitOfWork(),
-*     retryPolicy: new ExponentialBackoffRetryPolicy({ maxRetries: 5 })
-*   }
-* );
-* ```
+* // Simple retrieve + transform
+* const user = await executeTx({
+*   retrieve: (ctx) => ctx.forSchema(usersSchema).find("users", ...),
+*   retrieveSuccess: ([users]) => users[0] ?? null,
+* }, { createUnitOfWork });
+* @internal Used by HandlerTxBuilder.execute()
 */
-async function executeRestrictedUnitOfWork(callback, options) {
-	const retryPolicy = options.retryPolicy ?? new ExponentialBackoffRetryPolicy({
-		maxRetries: 5,
-		initialDelayMs: 10,
-		maxDelayMs: 100
-	});
+async function executeTx(callbacks, options) {
 	const signal = options.signal;
 	let attempt = 0;
 	while (true) {
-		if (signal?.aborted) throw new Error("Unit of Work execution aborted");
+		if (signal?.aborted) throw new Error("Transaction execution aborted");
+		let retryPolicy;
 		try {
 			const baseUow = options.createUnitOfWork();
-			return await awaitPromisesInObject(await callback({
+			const context = {
 				forSchema: (schema, hooks) => {
 					return baseUow.forSchema(schema, hooks);
 				},
-				executeRetrieve: async () => {
-					await baseUow.executeRetrieve();
-				},
-				executeMutate: async () => {
-					if (baseUow.state === "executed") return;
-					if (baseUow.state === "building-retrieval") await baseUow.executeRetrieve();
-					if (options.onBeforeMutate) options.onBeforeMutate(baseUow);
-					if (!(await baseUow.executeMutations()).success) throw new ConcurrencyConflictError();
-					if (options.onSuccess) await options.onSuccess(baseUow);
-				},
-				nonce: baseUow.nonce,
+				idempotencyKey: baseUow.idempotencyKey,
 				currentAttempt: attempt
-			}));
+			};
+			let serviceCalls;
+			if (callbacks.serviceCalls) serviceCalls = callbacks.serviceCalls();
+			const typedUowFromRetrieve = callbacks.retrieve?.(context);
+			const allServiceCallTxResults = serviceCalls ? collectAllTxResults([...serviceCalls]) : [];
+			if (!(baseUow.getRetrievalOperations().length > 0)) {
+				if (options.retryPolicy) throw new Error("Retry policy is only supported when the transaction includes retrieve operations.");
+				retryPolicy = new NoRetryPolicy();
+			} else retryPolicy = options.retryPolicy ?? new ExponentialBackoffRetryPolicy({
+				maxRetries: 5,
+				initialDelayMs: 10,
+				maxDelayMs: 100
+			});
+			await baseUow.executeRetrieve();
+			const retrieveResult = typedUowFromRetrieve ? await typedUowFromRetrieve.retrievalPhase : [];
+			for (const txResult of allServiceCallTxResults) await processTxResultAfterRetrieve(txResult, baseUow);
+			const serviceResults = [];
+			if (serviceCalls) for (const serviceCall of serviceCalls) {
+				if (serviceCall === void 0) {
+					serviceResults.push(void 0);
+					continue;
+				}
+				const serviceCallInternal = serviceCall._internal;
+				if (serviceCallInternal.retrieveSuccessResult !== void 0 && !(Array.isArray(serviceCallInternal.retrieveSuccessResult) && serviceCallInternal.retrieveSuccessResult.length === 0 && serviceCallInternal.callbacks.mutate)) serviceResults.push(serviceCallInternal.retrieveSuccessResult);
+				else if (serviceCallInternal.mutateResult !== void 0) serviceResults.push(serviceCallInternal.mutateResult);
+				else serviceResults.push(serviceCallInternal.retrieveSuccessResult);
+			}
+			let retrieveSuccessResult;
+			if (callbacks.retrieveSuccess) retrieveSuccessResult = callbacks.retrieveSuccess(retrieveResult, serviceResults);
+			else retrieveSuccessResult = retrieveResult;
+			let mutateResult;
+			if (callbacks.mutate) {
+				const mutateCtx = {
+					...context,
+					retrieveResult: retrieveSuccessResult,
+					serviceIntermediateResult: serviceResults
+				};
+				mutateResult = callbacks.mutate(mutateCtx);
+			}
+			if (options.onBeforeMutate) options.onBeforeMutate(baseUow);
+			if (!(await baseUow.executeMutations()).success) throw new ConcurrencyConflictError();
+			for (const txResult of allServiceCallTxResults) await processTxResultAfterMutate(txResult);
+			const serviceFinalResults = [];
+			if (serviceCalls) for (const serviceCall of serviceCalls) {
+				if (serviceCall === void 0) {
+					serviceFinalResults.push(void 0);
+					continue;
+				}
+				serviceFinalResults.push(serviceCall._internal.finalResult);
+			}
+			let finalResult;
+			if (callbacks.success) {
+				const successCtx = {
+					retrieveResult: retrieveSuccessResult,
+					mutateResult,
+					serviceResult: serviceFinalResults,
+					serviceIntermediateResult: serviceResults
+				};
+				finalResult = callbacks.success(successCtx);
+			} else if (callbacks.mutate) finalResult = await awaitPromisesInObject(mutateResult);
+			else if (callbacks.retrieveSuccess || callbacks.retrieve) finalResult = retrieveSuccessResult;
+			else finalResult = serviceFinalResults;
+			if (options.onAfterMutate) await options.onAfterMutate(baseUow);
+			return await awaitPromisesInObject(finalResult);
 		} catch (error) {
-			if (signal?.aborted) throw new Error("Unit of Work execution aborted");
+			if (signal?.aborted) throw new Error("Transaction execution aborted");
 			if (!(error instanceof ConcurrencyConflictError)) throw error;
+			if (!retryPolicy) throw error;
 			if (!retryPolicy.shouldRetry(attempt, error, signal)) {
-				if (signal?.aborted) throw new Error("Unit of Work execution aborted");
-				throw new Error("Unit of Work execution failed: optimistic concurrency conflict", { cause: error });
+				if (signal?.aborted) throw new Error("Transaction execution aborted");
+				throw new ConcurrencyConflictError();
 			}
 			const delayMs = retryPolicy.getDelayMs(attempt);
 			if (delayMs > 0) await new Promise((resolve) => setTimeout(resolve, delayMs));
@@ -192,138 +253,250 @@ async function executeRestrictedUnitOfWork(callback, options) {
 	}
 }
 /**
-* Execute a transaction with array syntax (handler context).
-* Takes a factory function that creates an array of service promises, enabling proper retry support.
-*
-* @param servicesFactory - Function that creates an array of service promises
-* @param options - Configuration including UOW factory, retry policy, and abort signal
-* @returns Promise resolving to array of awaited service results
+* Error thrown when a Unit of Work execution fails due to optimistic concurrency conflict.
+* This error triggers automatic retry behavior in executeTx.
+*/
+var ConcurrencyConflictError = class extends Error {
+	constructor(message = "Optimistic concurrency conflict detected") {
+		super(message);
+		this.name = "ConcurrencyConflictError";
+	}
+};
+/**
+* Await promises in an object 1 level deep
+*/
+async function awaitPromisesInObject(obj) {
+	if (obj === null || obj === void 0) return obj;
+	if (typeof obj !== "object") return obj;
+	if (obj instanceof Promise) return await obj;
+	if (Array.isArray(obj)) return await Promise.all(obj.map((item) => item instanceof Promise ? item : Promise.resolve(item)));
+	if (obj.constructor !== Object) return obj;
+	const result = {};
+	const entries = Object.entries(obj);
+	const awaitedEntries = await Promise.all(entries.map(async ([key, value]) => {
+		return [key, value instanceof Promise ? await value : value];
+	}));
+	for (const [key, value] of awaitedEntries) result[key] = value;
+	return result;
+}
+/**
+* Builder for service-level transactions.
+* Uses a fluent API to build up transaction callbacks with proper type inference.
 *
 * @example
 * ```ts
-* const [result1, result2] = await executeTxArray(
-*   () => [
-*     executeServiceTx(schema, callbacks1, uow),
-*     executeServiceTx(schema, callbacks2, uow)
-*   ],
-*   { createUnitOfWork }
-* );
+* return serviceTx(schema)
+*   .withServiceCalls(() => [otherService.getData()])
+*   .retrieve((uow) => uow.find("users", ...))
+*   .transformRetrieve(([users], serviceResult) => users[0])
+*   .mutate(({ uow, retrieveResult, serviceIntermediateResult }) =>
+*     uow.create("records", { ... })
+*   )
+*   .transform(({ mutateResult, serviceResult, serviceIntermediateResult }) => ({ id: mutateResult }))
+*   .build();
 * ```
 */
-async function executeTxArray(servicesFactory, options) {
-	const retryPolicy = options.retryPolicy ?? new ExponentialBackoffRetryPolicy({
-		maxRetries: 5,
-		initialDelayMs: 10,
-		maxDelayMs: 100
-	});
-	const signal = options.signal;
-	let attempt = 0;
-	while (true) {
-		if (signal?.aborted) throw new Error("Unit of Work execution aborted");
-		try {
-			const baseUow = options.createUnitOfWork();
-			const services = servicesFactory();
-			await baseUow.executeRetrieve();
-			if (options.onBeforeMutate) options.onBeforeMutate(baseUow);
-			if (!(await baseUow.executeMutations()).success) throw new ConcurrencyConflictError();
-			if (options.onSuccess) await options.onSuccess(baseUow);
-			return await Promise.all(services);
-		} catch (error) {
-			if (signal?.aborted) throw new Error("Unit of Work execution aborted");
-			if (!(error instanceof ConcurrencyConflictError)) throw error;
-			if (!retryPolicy.shouldRetry(attempt, error, signal)) {
-				if (signal?.aborted) throw new Error("Unit of Work execution aborted");
-				throw new Error("Unit of Work execution failed: optimistic concurrency conflict", { cause: error });
-			}
-			const delayMs = retryPolicy.getDelayMs(attempt);
-			if (delayMs > 0) await new Promise((resolve) => setTimeout(resolve, delayMs));
-			attempt++;
-		}
+var ServiceTxBuilder = class ServiceTxBuilder {
+	#state;
+	constructor(state) {
+		this.#state = state;
 	}
-}
+	/**
+	* Add dependencies to execute before this transaction.
+	*/
+	withServiceCalls(fn) {
+		return new ServiceTxBuilder({
+			...this.#state,
+			withServiceCallsFn: fn
+		});
+	}
+	/**
+	* Add retrieval operations to the transaction.
+	*/
+	retrieve(fn) {
+		return new ServiceTxBuilder({
+			...this.#state,
+			retrieveFn: fn,
+			transformRetrieveFn: void 0
+		});
+	}
+	/**
+	* Transform retrieve results before passing to mutate.
+	*/
+	transformRetrieve(fn) {
+		return new ServiceTxBuilder({
+			...this.#state,
+			transformRetrieveFn: fn
+		});
+	}
+	/**
+	* Add mutation operations based on retrieve results.
+	*/
+	mutate(fn) {
+		return new ServiceTxBuilder({
+			...this.#state,
+			mutateFn: fn
+		});
+	}
+	/**
+	* Add final transformation after mutations complete.
+	*/
+	transform(fn) {
+		return new ServiceTxBuilder({
+			...this.#state,
+			transformFn: fn
+		});
+	}
+	/**
+	* Build and return the TxResult.
+	*/
+	build() {
+		const state = this.#state;
+		const callbacks = {
+			serviceCalls: state.withServiceCallsFn,
+			retrieve: state.retrieveFn,
+			retrieveSuccess: state.transformRetrieveFn,
+			mutate: state.mutateFn ? (ctx) => {
+				return state.mutateFn({
+					uow: ctx.uow,
+					retrieveResult: ctx.retrieveResult,
+					serviceIntermediateResult: ctx.serviceIntermediateResult
+				});
+			} : void 0,
+			success: state.transformFn ? (ctx) => {
+				return state.transformFn({
+					retrieveResult: ctx.retrieveResult,
+					mutateResult: ctx.mutateResult,
+					serviceResult: ctx.serviceResult,
+					serviceIntermediateResult: ctx.serviceIntermediateResult
+				});
+			} : void 0
+		};
+		return createServiceTx(state.schema, callbacks, state.baseUow);
+	}
+};
 /**
-* Execute a transaction with callback syntax (handler context).
-* Callbacks are synchronous only to prevent accidentally awaiting services in wrong place.
-*
-* @param callbacks - Object containing retrieve and mutate callbacks
-* @param options - Configuration including UOW factory, retry policy, and abort signal
-* @returns Promise resolving to the mutation result with promises awaited 1 level deep
+* Create a new ServiceTxBuilder for the given schema.
 */
-async function executeTxCallbacks(callbacks, options) {
-	const retryPolicy = options.retryPolicy ?? new ExponentialBackoffRetryPolicy({
-		maxRetries: 5,
-		initialDelayMs: 10,
-		maxDelayMs: 100
+function createServiceTxBuilder(schema, baseUow, hooks) {
+	return new ServiceTxBuilder({
+		schema,
+		baseUow,
+		hooks
 	});
-	const signal = options.signal;
-	let attempt = 0;
-	while (true) {
-		if (signal?.aborted) throw new Error("Unit of Work execution aborted");
-		try {
-			const baseUow = options.createUnitOfWork();
-			const context = { forSchema: (schema, hooks) => {
-				return baseUow.forSchema(schema, hooks);
-			} };
-			let retrieveResult;
-			if (callbacks.retrieve) retrieveResult = callbacks.retrieve(context);
-			else retrieveResult = void 0;
-			await baseUow.executeRetrieve();
-			let mutationResult;
-			if (callbacks.mutate) mutationResult = callbacks.mutate(context, retrieveResult);
-			else mutationResult = retrieveResult;
-			const awaitedMutationResult = await awaitPromisesInObject(mutationResult);
-			if (options.onBeforeMutate) options.onBeforeMutate(baseUow);
-			if (!(await baseUow.executeMutations()).success) throw new ConcurrencyConflictError();
-			if (options.onSuccess) await options.onSuccess(baseUow);
-			return awaitedMutationResult;
-		} catch (error) {
-			if (signal?.aborted) throw new Error("Unit of Work execution aborted");
-			if (!(error instanceof ConcurrencyConflictError)) throw error;
-			if (!retryPolicy.shouldRetry(attempt, error, signal)) {
-				if (signal?.aborted) throw new Error("Unit of Work execution aborted");
-				throw new Error("Unit of Work execution failed: optimistic concurrency conflict", { cause: error });
-			}
-			const delayMs = retryPolicy.getDelayMs(attempt);
-			if (delayMs > 0) await new Promise((resolve) => setTimeout(resolve, delayMs));
-			attempt++;
-		}
-	}
 }
 /**
-* Execute a transaction for service context.
-* Service callbacks can be async for ergonomic async work.
+* Builder for handler-level transactions.
+* Uses a fluent API to build up transaction callbacks with proper type inference.
 *
-* @param schema - Schema to use for the transaction
-* @param callbacks - Object containing retrieve and mutate callbacks
-* @param baseUow - Base Unit of Work (restricted) to use
-* @returns Promise resolving to the mutation result with promises awaited 1 level deep
+* @example
+* ```ts
+* const result = await handlerTx()
+*   .withServiceCalls(() => [userService.getUser(id)])
+*   .mutate(({ forSchema, idempotencyKey, currentAttempt, serviceIntermediateResult }) => {
+*     return forSchema(ordersSchema).create("orders", { ... });
+*   })
+*   .transform(({ mutateResult, serviceResult }) => ({ ... }))
+*   .execute();
+* ```
 */
-async function executeServiceTx(schema, callbacks, baseUow) {
-	const typedUow = baseUow.restrict({ readyFor: "none" }).forSchema(schema);
-	let retrievalUow;
-	try {
-		if (callbacks.retrieve) retrievalUow = callbacks.retrieve(typedUow);
-		else retrievalUow = typedUow;
-	} catch (error) {
-		typedUow.signalReadyForRetrieval();
-		typedUow.signalReadyForMutation();
-		throw error;
+var HandlerTxBuilder = class HandlerTxBuilder {
+	#state;
+	constructor(state) {
+		this.#state = state;
 	}
-	typedUow.signalReadyForRetrieval();
-	const results = await retrievalUow.retrievalPhase;
-	let mutationResult;
-	try {
-		if (callbacks.mutate) mutationResult = await callbacks.mutate(retrievalUow, results);
-		else mutationResult = void 0;
-	} catch (error) {
-		typedUow.signalReadyForMutation();
-		throw error;
+	/**
+	* Add dependencies to execute before this transaction.
+	*/
+	withServiceCalls(fn) {
+		return new HandlerTxBuilder({
+			...this.#state,
+			withServiceCallsFn: fn
+		});
+	}
+	/**
+	* Add retrieval operations to the transaction.
+	* Return a TypedUnitOfWork from forSchema().find() to get typed results.
+	*/
+	retrieve(fn) {
+		return new HandlerTxBuilder({
+			...this.#state,
+			retrieveFn: fn,
+			transformRetrieveFn: void 0
+		});
+	}
+	/**
+	* Transform retrieve results before passing to mutate.
+	*/
+	transformRetrieve(fn) {
+		return new HandlerTxBuilder({
+			...this.#state,
+			transformRetrieveFn: fn
+		});
 	}
-	typedUow.signalReadyForMutation();
-	await retrievalUow.mutationPhase;
-	return await awaitPromisesInObject(mutationResult);
+	/**
+	* Add mutation operations based on retrieve results.
+	*/
+	mutate(fn) {
+		return new HandlerTxBuilder({
+			...this.#state,
+			mutateFn: fn
+		});
+	}
+	/**
+	* Add final transformation after mutations complete.
+	*/
+	transform(fn) {
+		return new HandlerTxBuilder({
+			...this.#state,
+			transformFn: fn
+		});
+	}
+	/**
+	* Execute the transaction and return the result.
+	*/
+	execute() {
+		const state = this.#state;
+		return executeTx({
+			serviceCalls: state.withServiceCallsFn,
+			retrieve: state.retrieveFn ? (context) => {
+				return state.retrieveFn({
+					forSchema: context.forSchema,
+					idempotencyKey: context.idempotencyKey,
+					currentAttempt: context.currentAttempt
+				});
+			} : void 0,
+			retrieveSuccess: state.transformRetrieveFn,
+			mutate: state.mutateFn ? (ctx) => {
+				return state.mutateFn({
+					forSchema: ctx.forSchema,
+					idempotencyKey: ctx.idempotencyKey,
+					currentAttempt: ctx.currentAttempt,
+					retrieveResult: ctx.retrieveResult,
+					serviceIntermediateResult: ctx.serviceIntermediateResult
+				});
+			} : void 0,
+			success: state.transformFn ? (ctx) => {
+				return state.transformFn({
+					retrieveResult: ctx.retrieveResult,
+					mutateResult: ctx.mutateResult,
+					serviceResult: ctx.serviceResult,
+					serviceIntermediateResult: ctx.serviceIntermediateResult
+				});
+			} : void 0
+		}, state.options);
+	}
+};
+/**
+* Create a new HandlerTxBuilder with the given options.
+*/
+function createHandlerTxBuilder(options, hooks) {
+	return new HandlerTxBuilder({
+		options,
+		hooks
+	});
 }
 
 //#endregion
-export { executeRestrictedUnitOfWork, executeServiceTx, executeTxArray, executeTxCallbacks, executeUnitOfWork };
+export { ConcurrencyConflictError, HandlerTxBuilder, ServiceTxBuilder, createHandlerTxBuilder, createServiceTxBuilder };
 //# sourceMappingURL=execute-unit-of-work.js.map