@fragno-dev/db 0.2.2 → 0.4.1

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

@@ -1,7 +1,8 @@
+import { dbInterval, dbNow } from "../db-now.js";
+import { buildCondition } from "../condition-builder.js";
 import { generateId } from "../../schema/generate-id.js";
 import { FragnoId } from "../../schema/create.js";
 import { Cursor } from "../cursor.js";
-import { buildCondition } from "../condition-builder.js";
 
 //#region src/query/unit-of-work/unit-of-work.ts
 /**
@@ -167,6 +168,15 @@ var UpdateBuilder = class {
 		return this;
 	}
 	/**
+	* Database timestamp helper for mutation values.
+	*/
+	now() {
+		return dbNow();
+	}
+	interval(input) {
+		return dbInterval(input);
+	}
+	/**
 	* Enable version checking for optimistic concurrency control
 	* @throws Error if the ID is just a string (no version available)
 	*/
@@ -304,7 +314,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;
@@ -346,6 +356,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.
@@ -546,6 +561,7 @@ var UnitOfWork = class UnitOfWork {
 	#schemaNamespaceMap;
 	#retrievalResults;
 	#createdInternalIds = [];
+	#readTrackingEnabled = false;
 	#retrievalPhaseDeferred = new DeferredPromise();
 	#mutationPhaseDeferred = new DeferredPromise();
 	#retrievalError = null;
@@ -561,6 +577,39 @@ var UnitOfWork = class UnitOfWork {
 		this.#config = config;
 		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.
 	* This is used for internal fragments like hooks that need to create
@@ -600,6 +649,7 @@ var UnitOfWork = class UnitOfWork {
 		child.#mutationOps = this.#mutationOps;
 		child.#retrievalResults = this.#retrievalResults;
 		child.#createdInternalIds = this.#createdInternalIds;
+		child.#readTrackingEnabled = this.#readTrackingEnabled;
 		child.#retrievalPhaseDeferred = this.#retrievalPhaseDeferred;
 		child.#mutationPhaseDeferred = this.#mutationPhaseDeferred;
 		child.#retrievalError = this.#retrievalError;
@@ -634,6 +684,7 @@ var UnitOfWork = class UnitOfWork {
 		this.#mutationOps = [];
 		this.#retrievalResults = void 0;
 		this.#createdInternalIds = [];
+		this.#readTrackingEnabled = false;
 		this.#state = "building-retrieval";
 		this.#retrievalError = null;
 		this.#mutationError = null;
@@ -645,8 +696,9 @@ var UnitOfWork = class UnitOfWork {
 	/**
 	* Trigger a hook to be executed after the transaction commits.
 	*/
-	triggerHook(hookName, payload, options) {
+	triggerHook(namespace, hookName, payload, options) {
 		this.#triggeredHooks.push({
+			namespace,
 			hookName,
 			payload,
 			options
@@ -661,6 +713,12 @@ var UnitOfWork = class UnitOfWork {
 	get state() {
 		return this.#coordinator.parent?.state ?? this.#state;
 	}
+	enableReadTracking() {
+		this.#readTrackingEnabled = true;
+	}
+	get readTrackingEnabled() {
+		return this.#readTrackingEnabled;
+	}
 	get name() {
 		return this.#name;
 	}
@@ -688,11 +746,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;
 			}
@@ -707,17 +772,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 {}
 		}
 	}
 	/**
@@ -727,18 +806,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 };
 			}
@@ -748,11 +835,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 {}
 		}
 	}
 	/**
@@ -820,7 +918,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,
@@ -845,6 +946,9 @@ var TypedUnitOfWork = class {
 		this.#namespace = namespace;
 		this.#uow = uow;
 	}
+	/**
+	* Type-only access to retrieval results for this typed UOW.
+	*/
 	get $results() {
 		throw new Error("type only");
 	}
@@ -905,6 +1009,18 @@ var TypedUnitOfWork = class {
 	forSchema(schema, hooks) {
 		return this.#uow.forSchema(schema, hooks);
 	}
+	/**
+	* Database timestamp helper for inserts.
+	*/
+	now() {
+		return dbNow();
+	}
+	/**
+	* Build a database interval for use with now().plus(...).
+	*/
+	interval(input) {
+		return dbInterval(input);
+	}
 	registerSchema(schema, namespace) {
 		this.#uow.registerSchema(schema, namespace);
 	}
@@ -924,7 +1040,8 @@ var TypedUnitOfWork = class {
 			namespace: this.#namespace,
 			table,
 			indexName,
-			options
+			options,
+			readTracking: this.#uow.readTrackingEnabled
 		});
 		this.#operationIndices.push(operationIndex);
 		return this;
@@ -944,7 +1061,8 @@ var TypedUnitOfWork = class {
 			table,
 			indexName,
 			options,
-			withSingleResult: true
+			withSingleResult: true,
+			readTracking: this.#uow.readTrackingEnabled
 		});
 		this.#operationIndices.push(operationIndex);
 		return this;
@@ -962,7 +1080,8 @@ var TypedUnitOfWork = class {
 			table,
 			indexName,
 			options,
-			withCursor: true
+			withCursor: true,
+			readTracking: this.#uow.readTrackingEnabled
 		});
 		this.#operationIndices.push(operationIndex);
 		return this;
@@ -988,16 +1107,16 @@ var TypedUnitOfWork = class {
 		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({
@@ -1065,11 +1184,17 @@ var TypedUnitOfWork = class {
 	get $hooks() {
 		throw new Error("type only");
 	}
+	get namespace() {
+		return this.#namespace;
+	}
 	/**
 	* Trigger a hook to be executed after the transaction commits.
+	* The namespace is automatically injected from this typed view's schema registration.
 	*/
 	triggerHook(hookName, payload, options) {
-		this.#uow.triggerHook(hookName, payload, options);
+		if (this.#namespace === void 0) throw new Error("Cannot trigger hook: schema has no registered namespace. Ensure the schema is registered with a namespace via registerSchema().");
+		const hookNamespace = this.#namespace ?? this.#schema.name;
+		this.#uow.triggerHook(hookNamespace, hookName, payload, options);
 	}
 	getTriggeredHooks() {
 		return this.#uow.getTriggeredHooks();