@fragno-dev/db 0.3.0 → 0.4.1

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

@@ -0,0 +1,507 @@
+import { ExponentialBackoffRetryPolicy, NoRetryPolicy } from "./retry-policy.js";
+
+//#region src/query/unit-of-work/execute-unit-of-work.ts
+/**
+* Symbol to identify TxResult objects
+*/
+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
+	};
+}
+/**
+* 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()).
+*/
+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 single TxResult's callbacks after retrieve phase completes.
+* This processes retrieveSuccess, mutate, and success callbacks in order.
+*/
+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
+		};
+		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 transaction with the unified TxResult pattern.
+*
+* This is the handler-level function that actually executes TxResults with retry support.
+*
+* @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 result determined by return type priority
+*
+* @example
+* ```ts
+* // 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 executeTx(callbacks, options) {
+	const signal = options.signal;
+	let attempt = 0;
+	while (true) {
+		if (signal?.aborted) throw new Error("Transaction execution aborted");
+		let retryPolicy;
+		try {
+			const baseUow = options.createUnitOfWork();
+			if (options.onAfterRetrieve) baseUow.enableReadTracking?.();
+			const context = {
+				forSchema: (schema, hooks) => {
+					return baseUow.forSchema(schema, hooks);
+				},
+				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
+			});
+			const allRetrieveResults = await baseUow.executeRetrieve();
+			if (options.onAfterRetrieve) await options.onAfterRetrieve(baseUow, allRetrieveResults);
+			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.planMode && 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.planMode && options.onAfterMutate) await options.onAfterMutate(baseUow);
+			return await awaitPromisesInObject(finalResult);
+		} catch (error) {
+			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("Transaction execution aborted");
+				throw new ConcurrencyConflictError();
+			}
+			const delayMs = retryPolicy.getDelayMs(attempt);
+			if (delayMs > 0) await new Promise((resolve) => setTimeout(resolve, delayMs));
+			attempt++;
+		}
+	}
+}
+/**
+* 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
+* 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();
+* ```
+*/
+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);
+	}
+};
+/**
+* Create a new ServiceTxBuilder for the given schema.
+*/
+function createServiceTxBuilder(schema, baseUow, hooks) {
+	return new ServiceTxBuilder({
+		schema,
+		baseUow,
+		hooks
+	});
+}
+/**
+* Builder for handler-level transactions.
+* Uses a fluent API to build up transaction callbacks with proper type inference.
+*
+* @example
+* ```ts
+* const result = await handlerTx()
+*   .withServiceCalls(() => [userService.getUser(id)])
+*   .mutate(({ forSchema, idempotencyKey, currentAttempt, serviceIntermediateResult }) => {
+*     return forSchema(ordersSchema).create("orders", { ... });
+*   })
+*   .transform(({ mutateResult, serviceResult }) => ({ ... }))
+*   .execute();
+* ```
+*/
+var HandlerTxBuilder = class HandlerTxBuilder {
+	#state;
+	constructor(state) {
+		this.#state = state;
+	}
+	/**
+	* 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
+		});
+	}
+	/**
+	* 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;
+		const callbacks = {
+			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
+		};
+		const run = () => executeTx(callbacks, state.options);
+		return state.executeWrapper ? state.executeWrapper(run) : run();
+	}
+};
+/**
+* Create a new HandlerTxBuilder with the given options.
+*/
+function createHandlerTxBuilder(options, hooks, executeWrapper) {
+	return new HandlerTxBuilder({
+		options,
+		hooks,
+		executeWrapper
+	});
+}
+
+//#endregion
+export { HandlerTxBuilder, ServiceTxBuilder, createHandlerTxBuilder, createServiceTxBuilder };
+//# sourceMappingURL=execute-unit-of-work.js.map