@fragno-dev/db 0.1.13 → 0.1.15

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

@@ -1,6 +1,6 @@
 import { FragnoId } from "../schema/create.js";
-import { Cursor } from "./cursor.js";
 import { buildCondition } from "./condition-builder.js";
+import { Cursor } from "./cursor.js";
 
 //#region src/query/unit-of-work.ts
 /**
@@ -338,29 +338,188 @@ function buildJoinIndexed(table, fn) {
 	fn(builder);
 	return compiled;
 }
-function createUnitOfWork(schema, compiler, executor, decoder, name) {
-	return new UnitOfWork(schema, compiler, executor, decoder, name);
+function createUnitOfWork(compiler, executor, decoder, schemaNamespaceMap, name) {
+	return new UnitOfWork(compiler, executor, decoder, name, void 0, schemaNamespaceMap);
 }
 /**
+* Encapsulates a promise with its resolver/rejecter functions.
+* Simplifies management of deferred promises with built-in error handling.
+*/
+var DeferredPromise = class {
+	#resolve;
+	#reject;
+	#promise;
+	constructor() {
+		const { promise, resolve, reject } = Promise.withResolvers();
+		this.#promise = promise;
+		this.#resolve = resolve;
+		this.#reject = reject;
+		this.#promise.catch(() => {});
+	}
+	get promise() {
+		return this.#promise;
+	}
+	resolve(value) {
+		this.#resolve?.(value);
+	}
+	reject(error) {
+		this.#reject?.(error);
+	}
+	/**
+	* Reset to a new promise
+	*/
+	reset() {
+		const { promise, resolve, reject } = Promise.withResolvers();
+		this.#promise = promise;
+		this.#resolve = resolve;
+		this.#reject = reject;
+		this.#promise.catch(() => {});
+	}
+};
+/**
+* Tracks readiness signals from a group of children.
+* Maintains a promise that resolves when all registered children have signaled.
+*/
+var ReadinessTracker = class {
+	#expectedCount = 0;
+	#signalCount = 0;
+	#resolve;
+	#promise = Promise.resolve();
+	get promise() {
+		return this.#promise;
+	}
+	/**
+	* Register that we're expecting a signal from a child
+	*/
+	registerChild() {
+		if (this.#expectedCount === 0) {
+			const { promise, resolve } = Promise.withResolvers();
+			this.#promise = promise;
+			this.#resolve = resolve;
+		}
+		this.#expectedCount++;
+	}
+	/**
+	* Signal that one child is ready
+	*/
+	signal() {
+		this.#signalCount++;
+		if (this.#signalCount >= this.#expectedCount && this.#resolve) this.#resolve();
+	}
+	/**
+	* Reset to initial state
+	*/
+	reset() {
+		this.#expectedCount = 0;
+		this.#signalCount = 0;
+		this.#resolve = void 0;
+		this.#promise = Promise.resolve();
+	}
+};
+/**
+* Manages parent-child relationships and readiness coordination for Unit of Work instances.
+* This allows parent UOWs to wait for all child UOWs to signal readiness before executing phases.
+*/
+var UOWChildCoordinator = class {
+	#parent = null;
+	#parentCoordinator = null;
+	#children = /* @__PURE__ */ new Set();
+	#isRestricted = false;
+	#retrievalTracker = new ReadinessTracker();
+	#mutationTracker = new ReadinessTracker();
+	get isRestricted() {
+		return this.#isRestricted;
+	}
+	get parent() {
+		return this.#parent;
+	}
+	get children() {
+		return this.#children;
+	}
+	get retrievalReadinessPromise() {
+		return this.#retrievalTracker.promise;
+	}
+	get mutationReadinessPromise() {
+		return this.#mutationTracker.promise;
+	}
+	/**
+	* Mark this UOW as a restricted child of the given parent
+	*/
+	setAsRestricted(parent, parentCoordinator) {
+		this.#parent = parent;
+		this.#parentCoordinator = parentCoordinator;
+		this.#isRestricted = true;
+	}
+	/**
+	* Register a child UOW
+	*/
+	addChild(child) {
+		this.#children.add(child);
+		this.#retrievalTracker.registerChild();
+		this.#mutationTracker.registerChild();
+	}
+	/**
+	* Signal that this child is ready for retrieval phase execution.
+	* Only valid for restricted (child) UOWs.
+	*/
+	signalReadyForRetrieval() {
+		if (!this.#parentCoordinator) throw new Error("signalReadyForRetrieval() can only be called on restricted child UOWs");
+		this.#parentCoordinator.notifyChildReadyForRetrieval();
+	}
+	/**
+	* Signal that this child is ready for mutation phase execution.
+	* Only valid for restricted (child) UOWs.
+	*/
+	signalReadyForMutation() {
+		if (!this.#parentCoordinator) throw new Error("signalReadyForMutation() can only be called on restricted child UOWs");
+		this.#parentCoordinator.notifyChildReadyForMutation();
+	}
+	/**
+	* Notify this coordinator that a child is ready for retrieval (internal use).
+	* Called by child UOWs when they signal readiness.
+	*/
+	notifyChildReadyForRetrieval() {
+		this.#retrievalTracker.signal();
+	}
+	/**
+	* Notify this coordinator that a child is ready for mutation (internal use).
+	* Called by child UOWs when they signal readiness.
+	*/
+	notifyChildReadyForMutation() {
+		this.#mutationTracker.signal();
+	}
+	/**
+	* Reset coordination state for retry support
+	*/
+	reset() {
+		this.#children.clear();
+		this.#retrievalTracker.reset();
+		this.#mutationTracker.reset();
+	}
+};
+/**
 * Unit of Work implementation with optimistic concurrency control
 *
 * UOW has two phases:
 * 1. Retrieval phase: Read operations to fetch entities with their versions
 * 2. Mutation phase: Write operations that check versions before committing
 *
+* This is the untyped base storage. Use TypedUnitOfWork for type-safe operations.
+*
 * @example
 * ```ts
 * const uow = queryEngine.createUnitOfWork("update-user-balance");
+* const typedUow = uow.forSchema(mySchema);
 *
 * // Retrieval phase
-* uow.find("users", (b) => b.where("primary", (eb) => eb("id", "=", userId)));
+* typedUow.find("users", (b) => b.whereIndex("primary", (eb) => eb("id", "=", userId)));
 *
 * // Execute retrieval and transition to mutation phase
 * const [users] = await uow.executeRetrieve();
 *
 * // Mutation phase with version check
 * const user = users[0];
-* uow.update("users", user.id, (b) => b.set({ balance: newBalance }).check());
+* typedUow.update("users", user.id, (b) => b.set({ balance: newBalance }).check());
 *
 * // Execute mutations
 * const { success } = await uow.executeMutations();
@@ -369,28 +528,97 @@ function createUnitOfWork(schema, compiler, executor, decoder, name) {
 * }
 * ```
 */
-var UnitOfWork = class {
-	#schema;
+var UnitOfWork = class UnitOfWork {
 	#name;
 	#config;
+	#nonce;
 	#state = "building-retrieval";
 	#retrievalOps = [];
 	#mutationOps = [];
 	#compiler;
 	#executor;
 	#decoder;
+	#schemaNamespaceMap;
 	#retrievalResults;
 	#createdInternalIds = [];
-	constructor(schema, compiler, executor, decoder, name, config) {
-		this.#schema = schema;
+	#retrievalPhaseDeferred = new DeferredPromise();
+	#mutationPhaseDeferred = new DeferredPromise();
+	#retrievalError = null;
+	#mutationError = null;
+	#coordinator = new UOWChildCoordinator();
+	constructor(compiler, executor, decoder, name, config, schemaNamespaceMap) {
 		this.#compiler = compiler;
 		this.#executor = executor;
 		this.#decoder = decoder;
+		this.#schemaNamespaceMap = schemaNamespaceMap;
 		this.#name = name;
 		this.#config = config;
+		this.#nonce = config?.nonce ?? crypto.randomUUID();
 	}
-	get schema() {
-		return this.#schema;
+	/**
+	* Get a schema-specific typed view of this UOW for type-safe operations.
+	* Returns a wrapper that provides typed operations for the given schema.
+	* The namespace is automatically resolved from the schema-namespace map.
+	*/
+	forSchema(schema) {
+		const resolvedNamespace = this.#schemaNamespaceMap?.get(schema);
+		return new TypedUnitOfWork(schema, resolvedNamespace, this);
+	}
+	/**
+	* Create a restricted child UOW that cannot execute phases.
+	* The child shares the same operation storage but must signal readiness
+	* before the parent can execute each phase.
+	*/
+	restrict() {
+		const child = new UnitOfWork(this.#compiler, this.#executor, this.#decoder, this.#name, {
+			...this.#config,
+			nonce: this.#nonce
+		}, this.#schemaNamespaceMap);
+		child.#coordinator.setAsRestricted(this, this.#coordinator);
+		child.#state = this.#state;
+		child.#retrievalOps = this.#retrievalOps;
+		child.#mutationOps = this.#mutationOps;
+		child.#retrievalResults = this.#retrievalResults;
+		child.#createdInternalIds = this.#createdInternalIds;
+		child.#retrievalPhaseDeferred = this.#retrievalPhaseDeferred;
+		child.#mutationPhaseDeferred = this.#mutationPhaseDeferred;
+		child.#retrievalError = this.#retrievalError;
+		child.#mutationError = this.#mutationError;
+		this.#coordinator.addChild(child);
+		child.signalReadyForRetrieval();
+		child.signalReadyForMutation();
+		return child;
+	}
+	/**
+	* Signal that this child is ready for retrieval phase execution.
+	* Only valid for restricted (child) UOWs.
+	*/
+	signalReadyForRetrieval() {
+		this.#coordinator.signalReadyForRetrieval();
+	}
+	/**
+	* Signal that this child is ready for mutation phase execution.
+	* Only valid for restricted (child) UOWs.
+	*/
+	signalReadyForMutation() {
+		this.#coordinator.signalReadyForMutation();
+	}
+	/**
+	* Reset the UOW to initial state for retry support.
+	* Clears operations, resets state, and resets phase promises.
+	*/
+	reset() {
+		if (this.#coordinator.isRestricted) throw new Error("reset() cannot be called on restricted child UOWs");
+		this.#retrievalOps = [];
+		this.#mutationOps = [];
+		this.#retrievalResults = void 0;
+		this.#createdInternalIds = [];
+		this.#state = "building-retrieval";
+		this.#retrievalError = null;
+		this.#mutationError = null;
+		this.#retrievalPhaseDeferred.reset();
+		this.#mutationPhaseDeferred.reset();
+		this.#coordinator.reset();
 	}
 	get state() {
 		return this.#state;
@@ -398,75 +626,300 @@ var UnitOfWork = class {
 	get name() {
 		return this.#name;
 	}
+	get nonce() {
+		return this.#nonce;
+	}
+	/**
+	* Promise that resolves when the retrieval phase is executed
+	* Service methods can await this to coordinate multi-phase logic
+	*/
+	get retrievalPhase() {
+		return this.#retrievalPhaseDeferred.promise;
+	}
+	/**
+	* Promise that resolves when the mutation phase is executed
+	* Service methods can await this to coordinate multi-phase logic
+	*/
+	get mutationPhase() {
+		return this.#mutationPhaseDeferred.promise;
+	}
 	/**
 	* Execute the retrieval phase and transition to mutation phase
 	* Returns all results from find operations
 	*/
 	async executeRetrieve() {
-		if (this.#retrievalOps.length === 0) return [];
+		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.`);
-		const retrievalBatch = [];
-		for (const op of this.#retrievalOps) {
-			const compiled = this.#compiler.compileRetrievalOperation(op);
-			if (compiled !== null) {
-				this.#config?.onQuery?.(compiled);
-				retrievalBatch.push(compiled);
+		try {
+			await this.#coordinator.retrievalReadinessPromise;
+			if (this.#retrievalOps.length === 0) {
+				this.#state = "building-mutation";
+				const emptyResults = [];
+				this.#retrievalPhaseDeferred.resolve(emptyResults);
+				return emptyResults;
+			}
+			const retrievalBatch = [];
+			for (const op of this.#retrievalOps) {
+				const compiled = this.#compiler.compileRetrievalOperation(op);
+				if (compiled !== null) {
+					this.#config?.onQuery?.(compiled);
+					retrievalBatch.push(compiled);
+				}
 			}
+			if (this.#config?.dryRun) {
+				this.#state = "executed";
+				const emptyResults = [];
+				this.#retrievalPhaseDeferred.resolve(emptyResults);
+				return emptyResults;
+			}
+			const rawResults = await this.#executor.executeRetrievalPhase(retrievalBatch);
+			this.#retrievalResults = this.#decoder(rawResults, this.#retrievalOps);
+			this.#state = "building-mutation";
+			this.#retrievalPhaseDeferred.resolve(this.#retrievalResults);
+			return this.#retrievalResults;
+		} catch (error) {
+			this.#retrievalError = error instanceof Error ? error : new Error(String(error));
+			throw error;
 		}
-		if (this.#config?.dryRun) {
+	}
+	/**
+	* Execute the mutation phase
+	* Returns success flag indicating if mutations completed without conflicts
+	*/
+	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}.`);
+		try {
+			await this.#coordinator.mutationReadinessPromise;
+			const mutationBatch = [];
+			for (const op of this.#mutationOps) {
+				const compiled = this.#compiler.compileMutationOperation(op);
+				if (compiled !== null) {
+					this.#config?.onQuery?.(compiled);
+					mutationBatch.push(compiled);
+				}
+			}
+			if (this.#config?.dryRun) {
+				this.#state = "executed";
+				this.#mutationPhaseDeferred.resolve();
+				return { success: true };
+			}
+			const result = await this.#executor.executeMutationPhase(mutationBatch);
 			this.#state = "executed";
-			return [];
+			if (result.success) this.#createdInternalIds = result.createdInternalIds;
+			this.#mutationPhaseDeferred.resolve();
+			return { success: result.success };
+		} catch (error) {
+			this.#mutationError = error instanceof Error ? error : new Error(String(error));
+			throw error;
+		}
+	}
+	/**
+	* Get the retrieval operations (for inspection/debugging)
+	*/
+	getRetrievalOperations() {
+		return this.#retrievalOps;
+	}
+	/**
+	* Get the mutation operations (for inspection/debugging)
+	*/
+	getMutationOperations() {
+		return this.#mutationOps;
+	}
+	/**
+	* @internal
+	* Add a retrieval operation (used by TypedUnitOfWork)
+	*/
+	addRetrievalOperation(op) {
+		if (this.#state !== "building-retrieval") throw new Error(`Cannot add retrieval operation in state ${this.#state}. Must be in building-retrieval state.`);
+		this.#retrievalOps.push(op);
+		return this.#retrievalOps.length - 1;
+	}
+	/**
+	* @internal
+	* Add a mutation operation (used by TypedUnitOfWork)
+	*/
+	addMutationOperation(op) {
+		if (this.#state === "executed") throw new Error(`Cannot add mutation operation in executed state.`);
+		this.#mutationOps.push(op);
+	}
+	/**
+	* Get the IDs of created entities after executeMutations() has been called.
+	* Returns FragnoId objects with external IDs (always available) and internal IDs
+	* (available when database supports RETURNING).
+	*
+	* @throws Error if called before executeMutations()
+	* @returns Array of FragnoIds in the same order as create() calls
+	*/
+	getCreatedIds() {
+		if (this.#state !== "executed") throw new Error(`getCreatedIds() can only be called after executeMutations(). Current state: ${this.#state}`);
+		const createdIds = [];
+		let createIndex = 0;
+		for (const op of this.#mutationOps) if (op.type === "create") {
+			const internalId = this.#createdInternalIds[createIndex] ?? void 0;
+			createdIds.push(new FragnoId({
+				externalId: op.generatedExternalId,
+				internalId,
+				version: 0
+			}));
+			createIndex++;
 		}
-		this.#retrievalResults = this.#decoder(await this.#executor.executeRetrievalPhase(retrievalBatch), this.#retrievalOps);
-		this.#state = "building-mutation";
-		return this.#retrievalResults;
+		return createdIds;
 	}
 	/**
-	* Add a find operation using a builder callback (retrieval phase only)
+	* @internal
+	* Compile the unit of work to executable queries for testing
 	*/
+	compile(compiler) {
+		const retrievalBatch = [];
+		for (const op of this.#retrievalOps) {
+			const compiled = compiler.compileRetrievalOperation(op);
+			if (compiled !== null) retrievalBatch.push(compiled);
+		}
+		const mutationBatch = [];
+		for (const op of this.#mutationOps) {
+			const compiled = compiler.compileMutationOperation(op);
+			if (compiled !== null) mutationBatch.push(compiled);
+		}
+		return {
+			name: this.#name,
+			retrievalBatch,
+			mutationBatch
+		};
+	}
+};
+/**
+* A typed facade around a UnitOfWork that provides type-safe operations for a specific schema.
+* All operations are stored in the underlying UOW, but this facade ensures type safety and
+* filters retrieval results to only include operations added through this facade.
+*/
+var TypedUnitOfWork = class {
+	#schema;
+	#namespace;
+	#uow;
+	#operationIndices = [];
+	#cachedRetrievalPhase;
+	constructor(schema, namespace, uow) {
+		this.#schema = schema;
+		this.#namespace = namespace;
+		this.#uow = uow;
+	}
+	get $results() {
+		throw new Error("type only");
+	}
+	get schema() {
+		return this.#schema;
+	}
+	get name() {
+		return this.#uow.name;
+	}
+	get nonce() {
+		return this.#uow.nonce;
+	}
+	get state() {
+		return this.#uow.state;
+	}
+	get retrievalPhase() {
+		if (!this.#cachedRetrievalPhase) this.#cachedRetrievalPhase = this.#uow.retrievalPhase.then((allResults) => {
+			const allOperations = this.#uow.getRetrievalOperations();
+			return this.#operationIndices.map((opIndex) => {
+				const result = allResults[opIndex];
+				const operation = allOperations[opIndex];
+				if (operation?.type === "find" && operation.withSingleResult) return Array.isArray(result) ? result[0] ?? null : result;
+				return result;
+			});
+		});
+		return this.#cachedRetrievalPhase;
+	}
+	get mutationPhase() {
+		return this.#uow.mutationPhase;
+	}
+	getRetrievalOperations() {
+		return this.#uow.getRetrievalOperations();
+	}
+	getMutationOperations() {
+		return this.#uow.getMutationOperations();
+	}
+	getCreatedIds() {
+		return this.#uow.getCreatedIds();
+	}
+	async executeRetrieve() {
+		return this.#uow.executeRetrieve();
+	}
+	async executeMutations() {
+		return this.#uow.executeMutations();
+	}
+	restrict() {
+		return this.#uow.restrict();
+	}
+	reset() {
+		return this.#uow.reset();
+	}
+	forSchema(schema) {
+		return this.#uow.forSchema(schema);
+	}
+	compile(compiler) {
+		return this.#uow.compile(compiler);
+	}
 	find(tableName, builderFn) {
-		if (this.#state !== "building-retrieval") throw new Error(`find() can only be called during retrieval phase. Current state: ${this.#state}`);
 		const table = this.#schema.tables[tableName];
 		if (!table) throw new Error(`Table ${tableName} not found in schema`);
 		const builder = new FindBuilder(tableName, table);
 		if (builderFn) builderFn(builder);
 		else builder.whereIndex("primary");
 		const { indexName, options, type } = builder.build();
-		this.#retrievalOps.push({
+		const operationIndex = this.#uow.addRetrievalOperation({
 			type,
+			schema: this.#schema,
+			namespace: this.#namespace,
 			table,
 			indexName,
 			options
 		});
+		this.#operationIndices.push(operationIndex);
+		return this;
+	}
+	findFirst(tableName, builderFn) {
+		const table = this.#schema.tables[tableName];
+		if (!table) throw new Error(`Table ${tableName} not found in schema`);
+		const builder = new FindBuilder(tableName, table);
+		if (builderFn) builderFn(builder);
+		else builder.whereIndex("primary");
+		builder.pageSize(1);
+		const { indexName, options, type } = builder.build();
+		const operationIndex = this.#uow.addRetrievalOperation({
+			type,
+			schema: this.#schema,
+			namespace: this.#namespace,
+			table,
+			indexName,
+			options,
+			withSingleResult: true
+		});
+		this.#operationIndices.push(operationIndex);
 		return this;
 	}
-	/**
-	* Add a find operation with cursor metadata (retrieval phase only)
-	*/
 	findWithCursor(tableName, builderFn) {
-		if (this.#state !== "building-retrieval") throw new Error(`findWithCursor() can only be called during retrieval phase. Current state: ${this.#state}`);
 		const table = this.#schema.tables[tableName];
 		if (!table) throw new Error(`Table ${tableName} not found in schema`);
 		const builder = new FindBuilder(tableName, table);
 		builderFn(builder);
 		const { indexName, options, type } = builder.build();
-		this.#retrievalOps.push({
+		const operationIndex = this.#uow.addRetrievalOperation({
 			type,
+			schema: this.#schema,
+			namespace: this.#namespace,
 			table,
 			indexName,
 			options,
 			withCursor: true
 		});
+		this.#operationIndices.push(operationIndex);
 		return this;
 	}
-	/**
-	* Add a create operation (mutation phase only)
-	* Returns a FragnoId with the external ID that can be used immediately in subsequent operations
-	*/
-	create(table, values) {
-		if (this.#state === "executed") throw new Error(`create() can only be called during mutation phase.`);
-		const tableSchema = this.#schema.tables[table];
-		if (!tableSchema) throw new Error(`Table ${table} not found in schema`);
+	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;
@@ -482,126 +935,70 @@ var UnitOfWork = class {
 				[idColumn.ormName]: externalId
 			};
 		}
-		this.#mutationOps.push({
+		this.#uow.addMutationOperation({
 			type: "create",
-			table,
+			schema: this.#schema,
+			namespace: this.#namespace,
+			table: tableName,
 			values: updatedValues,
 			generatedExternalId: externalId
 		});
 		return FragnoId.fromExternal(externalId, 0);
 	}
-	/**
-	* Add an update operation using a builder callback (mutation phase only)
-	*/
-	update(table, id, builderFn) {
-		if (this.#state === "executed") throw new Error(`update() can only be called during mutation phase.`);
-		const builder = new UpdateBuilder(table, id);
+	update(tableName, id, builderFn) {
+		const builder = new UpdateBuilder(tableName, id);
 		builderFn(builder);
 		const { id: opId, checkVersion, set } = builder.build();
-		this.#mutationOps.push({
+		this.#uow.addMutationOperation({
 			type: "update",
-			table,
+			schema: this.#schema,
+			namespace: this.#namespace,
+			table: tableName,
 			id: opId,
 			checkVersion,
 			set
 		});
 	}
-	/**
-	* Add a delete operation using a builder callback (mutation phase only)
-	*/
-	delete(table, id, builderFn) {
-		if (this.#state === "executed") throw new Error(`delete() can only be called during mutation phase.`);
-		const builder = new DeleteBuilder(table, id);
+	delete(tableName, id, builderFn) {
+		const builder = new DeleteBuilder(tableName, id);
 		builderFn?.(builder);
 		const { id: opId, checkVersion } = builder.build();
-		this.#mutationOps.push({
+		this.#uow.addMutationOperation({
 			type: "delete",
-			table,
+			schema: this.#schema,
+			namespace: this.#namespace,
+			table: tableName,
 			id: opId,
 			checkVersion
 		});
 	}
 	/**
-	* Execute the mutation phase
-	* Returns success flag indicating if mutations completed without conflicts
-	*/
-	async executeMutations() {
-		if (this.#state === "executed") throw new Error(`Cannot execute mutations from state ${this.#state}.`);
-		const mutationBatch = [];
-		for (const op of this.#mutationOps) {
-			const compiled = this.#compiler.compileMutationOperation(op);
-			if (compiled !== null) {
-				this.#config?.onQuery?.(compiled);
-				mutationBatch.push(compiled);
-			}
-		}
-		if (this.#config?.dryRun) {
-			this.#state = "executed";
-			return { success: true };
-		}
-		const result = await this.#executor.executeMutationPhase(mutationBatch);
-		this.#state = "executed";
-		if (result.success) this.#createdInternalIds = result.createdInternalIds;
-		return { success: result.success };
-	}
-	/**
-	* Get the retrieval operations (for inspection/debugging)
-	*/
-	getRetrievalOperations() {
-		return this.#retrievalOps;
-	}
-	/**
-	* Get the mutation operations (for inspection/debugging)
-	*/
-	getMutationOperations() {
-		return this.#mutationOps;
-	}
-	/**
-	* Get the IDs of created entities after executeMutations() has been called.
-	* Returns FragnoId objects with external IDs (always available) and internal IDs
-	* (available when database supports RETURNING).
+	* Check that a record's version hasn't changed since retrieval.
+	* This is useful for ensuring related records remain unchanged during a transaction.
 	*
-	* @throws Error if called before executeMutations()
-	* @returns Array of FragnoIds in the same order as create() calls
-	*/
-	getCreatedIds() {
-		if (this.#state !== "executed") throw new Error(`getCreatedIds() can only be called after executeMutations(). Current state: ${this.#state}`);
-		const createdIds = [];
-		let createIndex = 0;
-		for (const op of this.#mutationOps) if (op.type === "create") {
-			const internalId = this.#createdInternalIds[createIndex] ?? void 0;
-			createdIds.push(new FragnoId({
-				externalId: op.generatedExternalId,
-				internalId,
-				version: 0
-			}));
-			createIndex++;
-		}
-		return createdIds;
-	}
-	/**
-	* @internal
-	* Compile the unit of work to executable queries for testing
+	* @param tableName - The table name
+	* @param id - The FragnoId with version information (string IDs are not allowed)
+	* @throws Error if the ID is a string without version information
+	*
+	* @example
+	* ```ts
+	* // Ensure both accounts haven't changed before creating a transfer
+	* uow.check("accounts", fromAccount.id);
+	* uow.check("accounts", toAccount.id);
+	* uow.create("transactions", { fromAccountId, toAccountId, amount });
+	* ```
 	*/
-	compile(compiler) {
-		const retrievalBatch = [];
-		for (const op of this.#retrievalOps) {
-			const compiled = compiler.compileRetrievalOperation(op);
-			if (compiled !== null) retrievalBatch.push(compiled);
-		}
-		const mutationBatch = [];
-		for (const op of this.#mutationOps) {
-			const compiled = compiler.compileMutationOperation(op);
-			if (compiled !== null) mutationBatch.push(compiled);
-		}
-		return {
-			name: this.#name,
-			retrievalBatch,
-			mutationBatch
-		};
+	check(tableName, id) {
+		this.#uow.addMutationOperation({
+			type: "check",
+			schema: this.#schema,
+			namespace: this.#namespace,
+			table: tableName,
+			id
+		});
 	}
 };
 
 //#endregion
-export { DeleteBuilder, FindBuilder, JoinFindBuilder, UnitOfWork, UpdateBuilder, buildJoinIndexed, createUnitOfWork };
+export { DeleteBuilder, FindBuilder, JoinFindBuilder, TypedUnitOfWork, UnitOfWork, UpdateBuilder, buildJoinIndexed, createUnitOfWork };
 //# sourceMappingURL=unit-of-work.js.map