@fragno-dev/db 0.2.1 → 0.3.0

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

@@ -1,6 +1,7 @@
+import { generateId } from "../../schema/generate-id.js";
 import { FragnoId } from "../../schema/create.js";
-import { buildCondition } from "../condition-builder.js";
 import { Cursor } from "../cursor.js";
+import { buildCondition } from "../condition-builder.js";
 
 //#region src/query/unit-of-work/unit-of-work.ts
 /**
@@ -303,7 +304,7 @@ function buildJoinIndexed(table, fn) {
 	for (const name in table.relations) {
 		const relation = table.relations[name];
 		builder[name] = (builderFn) => {
-			const joinBuilder = new JoinFindBuilder(relation.table.ormName, relation.table);
+			const joinBuilder = new JoinFindBuilder(relation.table.name, relation.table);
 			if (builderFn) builderFn(joinBuilder);
 			const config = joinBuilder.build();
 			let conditions;
@@ -345,6 +346,11 @@ function buildJoinIndexed(table, fn) {
 function createUnitOfWork(compiler, executor, decoder, schemaNamespaceMap, name) {
 	return new UnitOfWork(compiler, executor, decoder, name, void 0, schemaNamespaceMap);
 }
+function isUowInstrumentationInjection(value) {
+	if (!value || typeof value !== "object") return false;
+	const injection = value;
+	return injection.type === "conflict" || injection.type === "error";
+}
 /**
 * Encapsulates a promise with its resolver/rejecter functions.
 * Simplifies management of deferred promises with built-in error handling.
@@ -535,7 +541,7 @@ var UOWChildCoordinator = class {
 var UnitOfWork = class UnitOfWork {
 	#name;
 	#config;
-	#nonce;
+	#idempotencyKey;
 	#state = "building-retrieval";
 	#retrievalOps = [];
 	#mutationOps = [];
@@ -558,7 +564,40 @@ var UnitOfWork = class UnitOfWork {
 		this.#schemaNamespaceMap = schemaNamespaceMap ?? /* @__PURE__ */ new WeakMap();
 		this.#name = name;
 		this.#config = config;
-		this.#nonce = config?.nonce ?? crypto.randomUUID();
+		this.#idempotencyKey = config?.idempotencyKey ?? crypto.randomUUID();
+	}
+	#createInstrumentationContext(phase) {
+		return {
+			phase,
+			uowName: this.#name,
+			idempotencyKey: this.#idempotencyKey,
+			retrievalOpsCount: this.#retrievalOps.length,
+			mutationOpsCount: this.#mutationOps.length,
+			uow: this
+		};
+	}
+	async #runInstrumentation(phase) {
+		const hook = this.#config?.instrumentation?.[phase];
+		if (!hook) return null;
+		const result = await hook(this.#createInstrumentationContext(phase));
+		if (isUowInstrumentationInjection(result)) return result;
+		return null;
+	}
+	async #runInstrumentationFinalizer(phase) {
+		const hook = this.#config?.instrumentationFinalizer?.[phase];
+		if (!hook) return;
+		await hook(this.#createInstrumentationContext(phase));
+	}
+	#handleRetrieveInjection(injection) {
+		if (injection.type === "error") throw injection.error;
+		throw new Error(injection.reason ?? "Injected conflict");
+	}
+	#handleMutationInjection(injection) {
+		if (injection.type === "error") throw injection.error;
+		this.#state = "executed";
+		this.#createdInternalIds.length = 0;
+		this.#mutationPhaseDeferred.resolve();
+		return { success: false };
 	}
 	/**
 	* Register a schema with its namespace for cross-fragment operations.
@@ -592,7 +631,7 @@ var UnitOfWork = class UnitOfWork {
 		const readyFor = options?.readyFor ?? "mutation";
 		const child = new UnitOfWork(this.#compiler, this.#executor, this.#decoder, this.#name, {
 			...this.#config,
-			nonce: this.#nonce
+			idempotencyKey: this.#idempotencyKey
 		}, this.#schemaNamespaceMap);
 		child.#coordinator.setAsRestricted(this, this.#coordinator);
 		child.#retrievalOps = this.#retrievalOps;
@@ -663,8 +702,8 @@ var UnitOfWork = class UnitOfWork {
 	get name() {
 		return this.#name;
 	}
-	get nonce() {
-		return this.#nonce;
+	get idempotencyKey() {
+		return this.#idempotencyKey;
 	}
 	/**
 	* Promise that resolves when the retrieval phase is executed
@@ -687,11 +726,18 @@ var UnitOfWork = class UnitOfWork {
 	async executeRetrieve() {
 		if (this.#coordinator.isRestricted) throw new Error("executeRetrieve() cannot be called on restricted child UOWs");
 		if (this.#state !== "building-retrieval") throw new Error(`Cannot execute retrieval from state ${this.#state}. Must be in building-retrieval state.`);
+		let afterRan = false;
+		let failed = false;
 		try {
 			await this.#coordinator.retrievalReadinessPromise;
+			const beforeInjection = await this.#runInstrumentation("beforeRetrieve");
+			if (beforeInjection) return this.#handleRetrieveInjection(beforeInjection);
 			if (this.#retrievalOps.length === 0) {
 				this.#state = "building-mutation";
 				const emptyResults = [];
+				afterRan = true;
+				const afterInjection$1 = await this.#runInstrumentation("afterRetrieve");
+				if (afterInjection$1) return this.#handleRetrieveInjection(afterInjection$1);
 				this.#retrievalPhaseDeferred.resolve(emptyResults);
 				return emptyResults;
 			}
@@ -706,17 +752,31 @@ var UnitOfWork = class UnitOfWork {
 			if (this.#config?.dryRun) {
 				this.#state = "executed";
 				const emptyResults = [];
+				afterRan = true;
+				const afterInjection$1 = await this.#runInstrumentation("afterRetrieve");
+				if (afterInjection$1) return this.#handleRetrieveInjection(afterInjection$1);
 				this.#retrievalPhaseDeferred.resolve(emptyResults);
 				return emptyResults;
 			}
 			const rawResults = await this.#executor.executeRetrievalPhase(retrievalBatch);
 			this.#retrievalResults = this.#decoder.decode(rawResults, this.#retrievalOps);
 			this.#state = "building-mutation";
+			afterRan = true;
+			const afterInjection = await this.#runInstrumentation("afterRetrieve");
+			if (afterInjection) return this.#handleRetrieveInjection(afterInjection);
 			this.#retrievalPhaseDeferred.resolve(this.#retrievalResults);
 			return this.#retrievalResults;
 		} catch (error) {
 			this.#retrievalError = error instanceof Error ? error : new Error(String(error));
+			failed = true;
 			throw error;
+		} finally {
+			try {
+				await this.#runInstrumentationFinalizer("afterRetrieve");
+			} catch {}
+			if (!afterRan && failed) try {
+				await this.#runInstrumentation("afterRetrieve");
+			} catch {}
 		}
 	}
 	/**
@@ -726,18 +786,26 @@ var UnitOfWork = class UnitOfWork {
 	async executeMutations() {
 		if (this.#coordinator.isRestricted) throw new Error("executeMutations() cannot be called on restricted child UOWs");
 		if (this.#state === "executed") throw new Error(`Cannot execute mutations from state ${this.#state}.`);
+		let afterRan = false;
+		let failed = false;
 		try {
 			await this.#coordinator.mutationReadinessPromise;
+			const beforeInjection = await this.#runInstrumentation("beforeMutate");
+			if (beforeInjection) return this.#handleMutationInjection(beforeInjection);
 			const mutationBatch = [];
 			for (const op of this.#mutationOps) {
 				const compiled = this.#compiler.compileMutationOperation(op);
 				if (compiled !== null) {
+					compiled.uowId = this.#idempotencyKey;
 					this.#config?.onQuery?.(compiled);
 					mutationBatch.push(compiled);
 				}
 			}
 			if (this.#config?.dryRun) {
 				this.#state = "executed";
+				afterRan = true;
+				const afterInjection$1 = await this.#runInstrumentation("afterMutate");
+				if (afterInjection$1) return this.#handleMutationInjection(afterInjection$1);
 				this.#mutationPhaseDeferred.resolve();
 				return { success: true };
 			}
@@ -747,11 +815,22 @@ var UnitOfWork = class UnitOfWork {
 				this.#createdInternalIds.length = 0;
 				this.#createdInternalIds.push(...result.createdInternalIds);
 			}
+			afterRan = true;
+			const afterInjection = await this.#runInstrumentation("afterMutate");
+			if (afterInjection) return this.#handleMutationInjection(afterInjection);
 			this.#mutationPhaseDeferred.resolve();
 			return { success: result.success };
 		} catch (error) {
 			this.#mutationError = error instanceof Error ? error : new Error(String(error));
+			failed = true;
 			throw error;
+		} finally {
+			try {
+				await this.#runInstrumentationFinalizer("afterMutate");
+			} catch {}
+			if (!afterRan && failed) try {
+				await this.#runInstrumentation("afterMutate");
+			} catch {}
 		}
 	}
 	/**
@@ -819,7 +898,10 @@ var UnitOfWork = class UnitOfWork {
 		const mutationBatch = [];
 		for (const op of this.#mutationOps) {
 			const compiled = compiler.compileMutationOperation(op);
-			if (compiled !== null) mutationBatch.push(compiled);
+			if (compiled !== null) {
+				compiled.uowId = this.#idempotencyKey;
+				mutationBatch.push(compiled);
+			}
 		}
 		return {
 			name: this.#name,
@@ -853,8 +935,8 @@ var TypedUnitOfWork = class {
 	get name() {
 		return this.#uow.name;
 	}
-	get nonce() {
-		return this.#uow.nonce;
+	get idempotencyKey() {
+		return this.#uow.idempotencyKey;
 	}
 	get state() {
 		return this.#uow.state;
@@ -966,22 +1048,37 @@ var TypedUnitOfWork = class {
 		this.#operationIndices.push(operationIndex);
 		return this;
 	}
+	/**
+	* Generate a new ID for a table without creating a record.
+	* This is useful when you need to reference an ID before actually creating the record,
+	* or when you need to pass the ID to external services.
+	*
+	* @example
+	* ```ts
+	* const userId = uow.generateId("users");
+	* // Use userId in related records or pass to external services
+	* uow.create("users", { id: userId, name: "John" });
+	* ```
+	*/
+	generateId(tableName) {
+		return generateId(this.#schema, tableName);
+	}
 	create(tableName, values) {
 		const tableSchema = this.#schema.tables[tableName];
 		if (!tableSchema) throw new Error(`Table ${tableName} not found in schema`);
 		const idColumn = tableSchema.getIdColumn();
 		let externalId;
 		let updatedValues = values;
-		const providedIdValue = values[idColumn.ormName];
+		const providedIdValue = values[idColumn.name];
 		if (providedIdValue !== void 0) if (typeof providedIdValue === "object" && providedIdValue !== null && "externalId" in providedIdValue) externalId = providedIdValue.externalId;
 		else externalId = providedIdValue;
 		else {
 			const generated = idColumn.generateDefaultValue();
-			if (generated === void 0) throw new Error(`No ID value provided and ID column ${idColumn.ormName} has no default generator`);
+			if (generated === void 0) throw new Error(`No ID value provided and ID column ${idColumn.name} has no default generator`);
 			externalId = generated;
 			updatedValues = {
 				...values,
-				[idColumn.ormName]: externalId
+				[idColumn.name]: externalId
 			};
 		}
 		this.#uow.addMutationOperation({