@fragno-dev/db 0.1.14 → 0.2.0

package/dist/query/{unit-of-work.js → unit-of-work/unit-of-work.js}

@@ -1,8 +1,8 @@
-import { FragnoId } from "../schema/create.js";
-import { Cursor } from "./cursor.js";
-import { buildCondition } from "./condition-builder.js";
+import { FragnoId } from "../../schema/create.js";
+import { buildCondition } from "../condition-builder.js";
+import { Cursor } from "../cursor.js";
 
-//#region src/query/unit-of-work.ts
+//#region src/query/unit-of-work/unit-of-work.ts
 /**
 * Builder for find operations in Unit of Work
 */
@@ -83,8 +83,10 @@ var FindBuilder = class {
 	}
 	/**
 	* Set the number of results per page
+	* @throws {RangeError} If size is not a positive integer
 	*/
 	pageSize(size) {
+		if (!Number.isInteger(size) || size <= 0) throw new RangeError(`pageSize must be a positive integer, received: ${size}`);
 		this.#pageSizeValue = size;
 		return this;
 	}
@@ -260,8 +262,10 @@ var JoinFindBuilder = class {
 	}
 	/**
 	* Set the number of results to return
+	* @throws {RangeError} If size is not a positive integer
 	*/
 	pageSize(size) {
+		if (!Number.isInteger(size) || size <= 0) throw new RangeError(`pageSize must be a positive integer, received: ${size}`);
 		this.#pageSizeValue = size;
 		return this;
 	}
@@ -338,29 +342,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,10 +532,10 @@ function createUnitOfWork(schema, compiler, executor, decoder, name) {
 * }
 * ```
 */
-var UnitOfWork = class {
-	#schema;
+var UnitOfWork = class UnitOfWork {
 	#name;
 	#config;
+	#nonce;
 	#state = "building-retrieval";
 	#retrievalOps = [];
 	#mutationOps = [];
@@ -382,39 +545,112 @@ var UnitOfWork = class {
 	#schemaNamespaceMap;
 	#retrievalResults;
 	#createdInternalIds = [];
-	#retrievalPhaseResolve;
-	#mutationPhaseResolve;
-	#retrievalPhasePromise;
-	#mutationPhasePromise;
-	constructor(schema, compiler, executor, decoder, name, config, schemaNamespaceMap) {
-		this.#schema = schema;
+	#retrievalPhaseDeferred = new DeferredPromise();
+	#mutationPhaseDeferred = new DeferredPromise();
+	#retrievalError = null;
+	#mutationError = null;
+	#coordinator = new UOWChildCoordinator();
+	#triggeredHooks = [];
+	constructor(compiler, executor, decoder, name, config, schemaNamespaceMap) {
 		this.#compiler = compiler;
 		this.#executor = executor;
 		this.#decoder = decoder;
+		this.#schemaNamespaceMap = schemaNamespaceMap ?? /* @__PURE__ */ new WeakMap();
 		this.#name = name;
 		this.#config = config;
-		this.#schemaNamespaceMap = schemaNamespaceMap;
-		this.#retrievalPhasePromise = new Promise((resolve) => {
-			this.#retrievalPhaseResolve = resolve;
-		});
-		this.#mutationPhasePromise = new Promise((resolve) => {
-			this.#mutationPhaseResolve = resolve;
-		});
-	}
-	get schema() {
-		return this.#schema;
+		this.#nonce = config?.nonce ?? crypto.randomUUID();
 	}
-	get $results() {
-		throw new Error("type only");
+	/**
+	* Register a schema with its namespace for cross-fragment operations.
+	* This is used for internal fragments like hooks that need to create
+	* records in a different schema during the same transaction.
+	*/
+	registerSchema(schema, namespace) {
+		this.#schemaNamespaceMap.set(schema, namespace);
 	}
 	/**
-	* Get a schema-specific view of this UOW for type-safe operations
-	* Returns a wrapper that uses a different schema for operations.
+	* 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.
+	* The optional hooks parameter is for type inference only - pass your hooks map
+	* to get proper typing for triggerHook. The value is not used at runtime.
+	*/
+	forSchema(schema, _hooks) {
+		return new TypedUnitOfWork(schema, this.#schemaNamespaceMap.get(schema), 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;
+		child.#triggeredHooks = this.#triggeredHooks;
+		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();
+		this.#triggeredHooks = [];
+	}
+	/**
+	* Trigger a hook to be executed after the transaction commits.
+	*/
+	triggerHook(hookName, payload, options) {
+		this.#triggeredHooks.push({
+			hookName,
+			payload,
+			options
+		});
+	}
+	/**
+	* Get all triggered hooks for this UOW.
 	*/
-	forSchema(schema) {
-		const resolvedNamespace = this.#schemaNamespaceMap?.get(schema);
-		return new UnitOfWorkSchemaView(schema, resolvedNamespace, this);
+	getTriggeredHooks() {
+		return this.#triggeredHooks;
 	}
 	get state() {
 		return this.#state;
@@ -422,175 +658,93 @@ 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.#retrievalPhasePromise;
+		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.#mutationPhasePromise;
+		return this.#mutationPhaseDeferred.promise;
 	}
 	/**
 	* Execute the retrieval phase and transition to mutation phase
 	* Returns all results from find operations
 	*/
 	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.`);
-		if (this.#retrievalOps.length === 0) {
-			this.#state = "building-mutation";
-			const emptyResults = [];
-			this.#retrievalPhaseResolve?.(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);
+		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.decode(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) {
-			this.#state = "executed";
-			return [];
-		}
-		const rawResults = await this.#executor.executeRetrievalPhase(retrievalBatch);
-		this.#retrievalResults = this.#decoder(rawResults, this.#retrievalOps);
-		this.#state = "building-mutation";
-		this.#retrievalPhaseResolve?.(this.#retrievalResults);
-		return this.#retrievalResults;
-	}
-	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({
-			type,
-			schema: this.#schema,
-			table,
-			indexName,
-			options
-		});
-		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({
-			type,
-			schema: this.#schema,
-			table,
-			indexName,
-			options,
-			withCursor: true
-		});
-		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`);
-		const idColumn = tableSchema.getIdColumn();
-		let externalId;
-		let updatedValues = values;
-		const providedIdValue = values[idColumn.ormName];
-		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`);
-			externalId = generated;
-			updatedValues = {
-				...values,
-				[idColumn.ormName]: externalId
-			};
-		}
-		this.#mutationOps.push({
-			type: "create",
-			schema: this.#schema,
-			table,
-			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);
-		builderFn(builder);
-		const { id: opId, checkVersion, set } = builder.build();
-		this.#mutationOps.push({
-			type: "update",
-			schema: this.#schema,
-			table,
-			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);
-		builderFn?.(builder);
-		const { id: opId, checkVersion } = builder.build();
-		this.#mutationOps.push({
-			type: "delete",
-			schema: this.#schema,
-			table,
-			id: opId,
-			checkVersion
-		});
 	}
 	/**
 	* 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}.`);
-		const mutationBatch = [];
-		for (const op of this.#mutationOps) {
-			const compiled = this.#compiler.compileMutationOperation(op);
-			if (compiled !== null) {
-				this.#config?.onQuery?.(compiled);
-				mutationBatch.push(compiled);
+		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) {
+			if (this.#config?.dryRun) {
+				this.#state = "executed";
+				this.#mutationPhaseDeferred.resolve();
+				return { success: true };
+			}
+			const result = await this.#executor.executeMutationPhase(mutationBatch);
 			this.#state = "executed";
-			return { success: true };
+			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;
 		}
-		const result = await this.#executor.executeMutationPhase(mutationBatch);
-		this.#state = "executed";
-		if (result.success) this.#createdInternalIds = result.createdInternalIds;
-		this.#mutationPhaseResolve?.();
-		return { success: result.success };
 	}
 	/**
 	* Get the retrieval operations (for inspection/debugging)
@@ -606,17 +760,19 @@ var UnitOfWork = class {
 	}
 	/**
 	* @internal
-	* Add a retrieval operation (used by SchemaView)
+	* 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 SchemaView)
+	* 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);
 	}
 	/**
@@ -665,18 +821,20 @@ var UnitOfWork = class {
 	}
 };
 /**
-* A lightweight wrapper around a parent UOW that provides type-safe operations for a different schema.
-* All operations are stored in the parent UOW, but this wrapper ensures the correct schema is used.
+* 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 UnitOfWorkSchemaView = class {
+var TypedUnitOfWork = class {
 	#schema;
 	#namespace;
-	#parent;
+	#uow;
 	#operationIndices = [];
-	constructor(schema, namespace, parent) {
+	#cachedRetrievalPhase;
+	constructor(schema, namespace, uow) {
 		this.#schema = schema;
 		this.#namespace = namespace;
-		this.#parent = parent;
+		this.#uow = uow;
 	}
 	get $results() {
 		throw new Error("type only");
@@ -685,33 +843,58 @@ var UnitOfWorkSchemaView = class {
 		return this.#schema;
 	}
 	get name() {
-		return this.#parent.name;
+		return this.#uow.name;
+	}
+	get nonce() {
+		return this.#uow.nonce;
 	}
 	get state() {
-		return this.#parent.state;
+		return this.#uow.state;
 	}
 	get retrievalPhase() {
-		return this.#parent.retrievalPhase.then((allResults) => {
-			return this.#operationIndices.map((index) => allResults[index]);
+		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.#parent.mutationPhase;
+		return this.#uow.mutationPhase;
 	}
 	getRetrievalOperations() {
-		return this.#parent.getRetrievalOperations();
+		return this.#uow.getRetrievalOperations();
 	}
 	getMutationOperations() {
-		return this.#parent.getMutationOperations();
+		return this.#uow.getMutationOperations();
 	}
 	getCreatedIds() {
-		return this.#parent.getCreatedIds();
+		return this.#uow.getCreatedIds();
 	}
 	async executeRetrieve() {
-		return this.#parent.executeRetrieve();
+		return this.#uow.executeRetrieve();
 	}
 	async executeMutations() {
-		return this.#parent.executeMutations();
+		return this.#uow.executeMutations();
+	}
+	restrict() {
+		return this.#uow.restrict();
+	}
+	reset() {
+		return this.#uow.reset();
+	}
+	forSchema(schema, hooks) {
+		return this.#uow.forSchema(schema, hooks);
+	}
+	registerSchema(schema, namespace) {
+		this.#uow.registerSchema(schema, namespace);
+	}
+	compile(compiler) {
+		return this.#uow.compile(compiler);
 	}
 	find(tableName, builderFn) {
 		const table = this.#schema.tables[tableName];
@@ -720,7 +903,7 @@ var UnitOfWorkSchemaView = class {
 		if (builderFn) builderFn(builder);
 		else builder.whereIndex("primary");
 		const { indexName, options, type } = builder.build();
-		const operationIndex = this.#parent.addRetrievalOperation({
+		const operationIndex = this.#uow.addRetrievalOperation({
 			type,
 			schema: this.#schema,
 			namespace: this.#namespace,
@@ -731,13 +914,33 @@ var UnitOfWorkSchemaView = class {
 		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;
+	}
 	findWithCursor(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);
 		builderFn(builder);
 		const { indexName, options, type } = builder.build();
-		const operationIndex = this.#parent.addRetrievalOperation({
+		const operationIndex = this.#uow.addRetrievalOperation({
 			type,
 			schema: this.#schema,
 			namespace: this.#namespace,
@@ -767,7 +970,7 @@ var UnitOfWorkSchemaView = class {
 				[idColumn.ormName]: externalId
 			};
 		}
-		this.#parent.addMutationOperation({
+		this.#uow.addMutationOperation({
 			type: "create",
 			schema: this.#schema,
 			namespace: this.#namespace,
@@ -781,7 +984,7 @@ var UnitOfWorkSchemaView = class {
 		const builder = new UpdateBuilder(tableName, id);
 		builderFn(builder);
 		const { id: opId, checkVersion, set } = builder.build();
-		this.#parent.addMutationOperation({
+		this.#uow.addMutationOperation({
 			type: "update",
 			schema: this.#schema,
 			namespace: this.#namespace,
@@ -795,7 +998,7 @@ var UnitOfWorkSchemaView = class {
 		const builder = new DeleteBuilder(tableName, id);
 		builderFn?.(builder);
 		const { id: opId, checkVersion } = builder.build();
-		this.#parent.addMutationOperation({
+		this.#uow.addMutationOperation({
 			type: "delete",
 			schema: this.#schema,
 			namespace: this.#namespace,
@@ -804,11 +1007,45 @@ var UnitOfWorkSchemaView = class {
 			checkVersion
 		});
 	}
-	forSchema(schema) {
-		return this.#parent.forSchema(schema);
+	/**
+	* Check that a record's version hasn't changed since retrieval.
+	* This is useful for ensuring related records remain unchanged during a transaction.
+	*
+	* @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 });
+	* ```
+	*/
+	check(tableName, id) {
+		this.#uow.addMutationOperation({
+			type: "check",
+			schema: this.#schema,
+			namespace: this.#namespace,
+			table: tableName,
+			id
+		});
+	}
+	get $hooks() {
+		throw new Error("type only");
+	}
+	/**
+	* Trigger a hook to be executed after the transaction commits.
+	*/
+	triggerHook(hookName, payload, options) {
+		this.#uow.triggerHook(hookName, payload, options);
+	}
+	getTriggeredHooks() {
+		return this.#uow.getTriggeredHooks();
 	}
 };
 
 //#endregion
-export { DeleteBuilder, FindBuilder, JoinFindBuilder, UnitOfWork, UnitOfWorkSchemaView, UpdateBuilder, buildJoinIndexed, createUnitOfWork };
+export { DeleteBuilder, FindBuilder, JoinFindBuilder, TypedUnitOfWork, UnitOfWork, UpdateBuilder, buildJoinIndexed, createUnitOfWork };
 //# sourceMappingURL=unit-of-work.js.map