@fragno-dev/db 0.2.2 → 0.4.1

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

@@ -0,0 +1,1206 @@
+import { generateId } from "../../schema/generate-id.js";
+import { FragnoId } from "../../schema/create.js";
+import { dbInterval, dbNow } from "../db-now.js";
+import { buildCondition } from "../condition-builder.js";
+import { Cursor } from "../cursor.js";
+
+//#region src/query/unit-of-work/unit-of-work.ts
+/**
+* Builder for find operations in Unit of Work
+*/
+var FindBuilder = class {
+	#table;
+	#tableName;
+	#indexName;
+	#whereClause;
+	#orderByIndexClause;
+	#afterCursor;
+	#beforeCursor;
+	#pageSizeValue;
+	#selectClause;
+	#joinClause;
+	#countMode = false;
+	#cursorMetadata;
+	constructor(tableName, table) {
+		this.#tableName = tableName;
+		this.#table = table;
+	}
+	/**
+	* Specify which index to use and optionally filter the results
+	*/
+	whereIndex(indexName, condition) {
+		if (indexName !== "primary" && !(indexName in this.#table.indexes)) throw new Error(`Index "${String(indexName)}" not found on table "${this.#tableName}". Available indexes: primary, ${Object.keys(this.#table.indexes).join(", ")}`);
+		this.#indexName = indexName === "primary" ? "_primary" : indexName;
+		if (condition) this.#whereClause = condition;
+		return this;
+	}
+	/**
+	* Specify columns to select
+	* @throws Error if selectCount() has already been called
+	*/
+	select(columns) {
+		if (this.#countMode) throw new Error(`Cannot call select() after selectCount() on table "${this.#tableName}". Use either select() or selectCount(), not both.`);
+		this.#selectClause = columns;
+		return this;
+	}
+	/**
+	* Select count instead of records
+	* @throws Error if select() has already been called
+	*/
+	selectCount() {
+		if (this.#selectClause !== void 0) throw new Error(`Cannot call selectCount() after select() on table "${this.#tableName}". Use either select() or selectCount(), not both.`);
+		this.#countMode = true;
+		return this;
+	}
+	/**
+	* Order results by index in ascending or descending order
+	*/
+	orderByIndex(indexName, direction) {
+		if (indexName !== "primary" && !(indexName in this.#table.indexes)) throw new Error(`Index "${String(indexName)}" not found on table "${this.#tableName}". Available indexes: primary, ${Object.keys(this.#table.indexes).join(", ")}`);
+		this.#orderByIndexClause = {
+			indexName: indexName === "primary" ? "_primary" : indexName,
+			direction
+		};
+		return this;
+	}
+	/**
+	* Set cursor to continue pagination after this point (forward pagination)
+	* If a Cursor object is provided, its metadata will be used to set defaults for
+	* index, orderByIndex, and pageSize (if not explicitly set)
+	*/
+	after(cursor) {
+		this.#afterCursor = cursor;
+		if (cursor instanceof Cursor) this.#cursorMetadata = cursor;
+		return this;
+	}
+	/**
+	* Set cursor to continue pagination before this point (backward pagination)
+	* If a Cursor object is provided, its metadata will be used to set defaults for
+	* index, orderByIndex, and pageSize (if not explicitly set)
+	*/
+	before(cursor) {
+		this.#beforeCursor = cursor;
+		if (cursor instanceof Cursor) this.#cursorMetadata = cursor;
+		return this;
+	}
+	/**
+	* 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;
+	}
+	/**
+	* Add joins to include related data
+	* Join where clauses are restricted to indexed columns only
+	*/
+	join(joinFn) {
+		this.#joinClause = joinFn;
+		return this;
+	}
+	/**
+	* @internal
+	*/
+	build() {
+		let indexName = this.#indexName;
+		let orderByIndex = this.#orderByIndexClause;
+		let pageSize = this.#pageSizeValue;
+		if (this.#cursorMetadata) {
+			if (!indexName) indexName = this.#cursorMetadata.indexName;
+			if (!orderByIndex) orderByIndex = {
+				indexName: this.#cursorMetadata.indexName,
+				direction: this.#cursorMetadata.orderDirection
+			};
+			if (pageSize === void 0) pageSize = this.#cursorMetadata.pageSize;
+			if (indexName && indexName !== this.#cursorMetadata.indexName) throw new Error(`Index mismatch: builder specifies "${indexName}" but cursor specifies "${this.#cursorMetadata.indexName}"`);
+			if (orderByIndex && (orderByIndex.indexName !== this.#cursorMetadata.indexName || orderByIndex.direction !== this.#cursorMetadata.orderDirection)) throw new Error(`Order mismatch: builder and cursor specify different ordering`);
+			if (pageSize !== void 0 && pageSize !== this.#cursorMetadata.pageSize) throw new Error(`Page size mismatch: builder specifies ${pageSize} but cursor specifies ${this.#cursorMetadata.pageSize}`);
+		}
+		if (!indexName) throw new Error(`Must specify an index using .whereIndex() before finalizing find operation on table "${this.#tableName}"`);
+		if (this.#countMode) return {
+			type: "count",
+			indexName,
+			options: {
+				useIndex: indexName,
+				where: this.#whereClause
+			}
+		};
+		let compiledJoins;
+		if (this.#joinClause) compiledJoins = buildJoinIndexed(this.#table, this.#joinClause);
+		const afterCursor = this.#afterCursor instanceof Cursor ? this.#afterCursor.encode() : this.#afterCursor;
+		const beforeCursor = this.#beforeCursor instanceof Cursor ? this.#beforeCursor.encode() : this.#beforeCursor;
+		const options = {
+			useIndex: indexName,
+			select: this.#selectClause,
+			where: this.#whereClause,
+			orderByIndex,
+			after: afterCursor,
+			before: beforeCursor,
+			pageSize,
+			joins: compiledJoins
+		};
+		return {
+			type: "find",
+			indexName,
+			options
+		};
+	}
+};
+/**
+* Builder for update operations in Unit of Work
+*/
+var UpdateBuilder = class {
+	#tableName;
+	#id;
+	#checkVersion = false;
+	#setValues;
+	constructor(tableName, id) {
+		this.#tableName = tableName;
+		this.#id = id;
+	}
+	/**
+	* Specify values to update
+	*/
+	set(values) {
+		this.#setValues = values;
+		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)
+	*/
+	check() {
+		if (typeof this.#id === "string") throw new Error(`Cannot use check() with a string ID on table "${this.#tableName}". Version checking requires a FragnoId with version information.`);
+		this.#checkVersion = true;
+		return this;
+	}
+	/**
+	* @internal
+	*/
+	build() {
+		if (!this.#setValues) throw new Error(`Must specify values using .set() before finalizing update operation on table "${this.#tableName}"`);
+		return {
+			id: this.#id,
+			checkVersion: this.#checkVersion,
+			set: this.#setValues
+		};
+	}
+};
+/**
+* Builder for delete operations in Unit of Work
+*/
+var DeleteBuilder = class {
+	#tableName;
+	#id;
+	#checkVersion = false;
+	constructor(tableName, id) {
+		this.#tableName = tableName;
+		this.#id = id;
+	}
+	/**
+	* Enable version checking for optimistic concurrency control
+	* @throws Error if the ID is just a string (no version available)
+	*/
+	check() {
+		if (typeof this.#id === "string") throw new Error(`Cannot use check() with a string ID on table "${this.#tableName}". Version checking requires a FragnoId with version information.`);
+		this.#checkVersion = true;
+		return this;
+	}
+	/**
+	* @internal
+	*/
+	build() {
+		return {
+			id: this.#id,
+			checkVersion: this.#checkVersion
+		};
+	}
+};
+/**
+* Builder for join operations in Unit of Work
+* Similar to FindBuilder but tailored for joins (no cursor pagination, no count mode)
+*/
+var JoinFindBuilder = class {
+	#table;
+	#tableName;
+	#indexName;
+	#whereClause;
+	#orderByIndexClause;
+	#pageSizeValue;
+	#selectClause;
+	#joinClause;
+	constructor(tableName, table) {
+		this.#tableName = tableName;
+		this.#table = table;
+	}
+	/**
+	* Specify which index to use and optionally filter the results
+	*/
+	whereIndex(indexName, condition) {
+		if (indexName !== "primary" && !(indexName in this.#table.indexes)) throw new Error(`Index "${String(indexName)}" not found on table "${this.#tableName}". Available indexes: primary, ${Object.keys(this.#table.indexes).join(", ")}`);
+		this.#indexName = indexName === "primary" ? "_primary" : indexName;
+		if (condition) this.#whereClause = condition;
+		return this;
+	}
+	/**
+	* Specify columns to select
+	*/
+	select(columns) {
+		this.#selectClause = columns;
+		return this;
+	}
+	/**
+	* Order results by index in ascending or descending order
+	*/
+	orderByIndex(indexName, direction) {
+		if (indexName !== "primary" && !(indexName in this.#table.indexes)) throw new Error(`Index "${String(indexName)}" not found on table "${this.#tableName}". Available indexes: primary, ${Object.keys(this.#table.indexes).join(", ")}`);
+		this.#orderByIndexClause = {
+			indexName: indexName === "primary" ? "_primary" : indexName,
+			direction
+		};
+		return this;
+	}
+	/**
+	* 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;
+	}
+	/**
+	* Add joins to include related data
+	* Join where clauses are restricted to indexed columns only
+	*/
+	join(joinFn) {
+		this.#joinClause = joinFn;
+		return this;
+	}
+	/**
+	* @internal
+	*/
+	build() {
+		let compiledJoins;
+		if (this.#joinClause) compiledJoins = buildJoinIndexed(this.#table, this.#joinClause);
+		return {
+			indexName: this.#indexName,
+			select: this.#selectClause,
+			where: this.#whereClause,
+			orderByIndex: this.#orderByIndexClause,
+			pageSize: this.#pageSizeValue,
+			joins: compiledJoins
+		};
+	}
+};
+/**
+* Build join operations with indexed-only where clauses for Unit of Work
+* This ensures all join conditions can leverage indexes for optimal performance
+*/
+function buildJoinIndexed(table, fn) {
+	const compiled = [];
+	const builder = {};
+	for (const name in table.relations) {
+		const relation = table.relations[name];
+		builder[name] = (builderFn) => {
+			const joinBuilder = new JoinFindBuilder(relation.table.name, relation.table);
+			if (builderFn) builderFn(joinBuilder);
+			const config = joinBuilder.build();
+			let conditions;
+			if (config.where) {
+				const cond = buildCondition(relation.table.columns, config.where);
+				if (cond === true) conditions = void 0;
+				else if (cond === false) {
+					compiled.push({
+						relation,
+						options: false
+					});
+					delete builder[name];
+					return builder;
+				} else conditions = cond;
+			}
+			let orderBy;
+			if (config.orderByIndex) {
+				const index = relation.table.indexes[config.orderByIndex.indexName];
+				if (index) orderBy = index.columns.map((col) => [col, config.orderByIndex.direction]);
+				else orderBy = [[relation.table.getIdColumn(), config.orderByIndex.direction]];
+			}
+			compiled.push({
+				relation,
+				options: {
+					select: config.select ?? true,
+					where: conditions,
+					orderBy,
+					join: config.joins,
+					limit: config.pageSize
+				}
+			});
+			delete builder[name];
+			return builder;
+		};
+	}
+	fn(builder);
+	return compiled;
+}
+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.
+*/
+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
+* 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];
+* typedUow.update("users", user.id, (b) => b.set({ balance: newBalance }).check());
+*
+* // Execute mutations
+* const { success } = await uow.executeMutations();
+* if (!success) {
+*   // Handle version conflict
+* }
+* ```
+*/
+var UnitOfWork = class UnitOfWork {
+	#name;
+	#config;
+	#idempotencyKey;
+	#state = "building-retrieval";
+	#retrievalOps = [];
+	#mutationOps = [];
+	#compiler;
+	#executor;
+	#decoder;
+	#schemaNamespaceMap;
+	#retrievalResults;
+	#createdInternalIds = [];
+	#readTrackingEnabled = false;
+	#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.#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
+	* records in a different schema during the same transaction.
+	*/
+	registerSchema(schema, namespace) {
+		this.#schemaNamespaceMap.set(schema, namespace);
+	}
+	/**
+	* 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.
+	*
+	* @param options.readyFor - Controls automatic readiness signaling:
+	*   - "mutation" (default): Signals ready for both retrieval and mutation immediately
+	*   - "retrieval": Signals ready for retrieval only
+	*   - "none": No automatic signaling, caller must signal manually
+	*/
+	restrict(options) {
+		const readyFor = options?.readyFor ?? "mutation";
+		const child = new UnitOfWork(this.#compiler, this.#executor, this.#decoder, this.#name, {
+			...this.#config,
+			idempotencyKey: this.#idempotencyKey
+		}, this.#schemaNamespaceMap);
+		child.#coordinator.setAsRestricted(this, this.#coordinator);
+		child.#retrievalOps = this.#retrievalOps;
+		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;
+		child.#mutationError = this.#mutationError;
+		child.#triggeredHooks = this.#triggeredHooks;
+		this.#coordinator.addChild(child);
+		if (readyFor === "mutation" || readyFor === "retrieval") child.signalReadyForRetrieval();
+		if (readyFor === "mutation") 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.#readTrackingEnabled = false;
+		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(namespace, hookName, payload, options) {
+		this.#triggeredHooks.push({
+			namespace,
+			hookName,
+			payload,
+			options
+		});
+	}
+	/**
+	* Get all triggered hooks for this UOW.
+	*/
+	getTriggeredHooks() {
+		return this.#triggeredHooks;
+	}
+	get state() {
+		return this.#coordinator.parent?.state ?? this.#state;
+	}
+	enableReadTracking() {
+		this.#readTrackingEnabled = true;
+	}
+	get readTrackingEnabled() {
+		return this.#readTrackingEnabled;
+	}
+	get name() {
+		return this.#name;
+	}
+	get idempotencyKey() {
+		return this.#idempotencyKey;
+	}
+	/**
+	* 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.#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;
+			}
+			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 = [];
+				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 {}
+		}
+	}
+	/**
+	* 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}.`);
+		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 };
+			}
+			const result = await this.#executor.executeMutationPhase(mutationBatch);
+			this.#state = "executed";
+			if (result.success) {
+				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 {}
+		}
+	}
+	/**
+	* 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++;
+		}
+		return createdIds;
+	}
+	/**
+	* @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) {
+				compiled.uowId = this.#idempotencyKey;
+				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;
+	}
+	/**
+	* Type-only access to retrieval results for this typed UOW.
+	*/
+	get $results() {
+		throw new Error("type only");
+	}
+	get schema() {
+		return this.#schema;
+	}
+	get name() {
+		return this.#uow.name;
+	}
+	get idempotencyKey() {
+		return this.#uow.idempotencyKey;
+	}
+	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(options) {
+		return this.#uow.restrict(options);
+	}
+	signalReadyForRetrieval() {
+		this.#uow.signalReadyForRetrieval();
+	}
+	signalReadyForMutation() {
+		this.#uow.signalReadyForMutation();
+	}
+	reset() {
+		return this.#uow.reset();
+	}
+	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);
+	}
+	compile(compiler) {
+		return this.#uow.compile(compiler);
+	}
+	find(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");
+		const { indexName, options, type } = builder.build();
+		const operationIndex = this.#uow.addRetrievalOperation({
+			type,
+			schema: this.#schema,
+			namespace: this.#namespace,
+			table,
+			indexName,
+			options,
+			readTracking: this.#uow.readTrackingEnabled
+		});
+		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,
+			readTracking: this.#uow.readTrackingEnabled
+		});
+		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.#uow.addRetrievalOperation({
+			type,
+			schema: this.#schema,
+			namespace: this.#namespace,
+			table,
+			indexName,
+			options,
+			withCursor: true,
+			readTracking: this.#uow.readTrackingEnabled
+		});
+		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.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.name} has no default generator`);
+			externalId = generated;
+			updatedValues = {
+				...values,
+				[idColumn.name]: externalId
+			};
+		}
+		this.#uow.addMutationOperation({
+			type: "create",
+			schema: this.#schema,
+			namespace: this.#namespace,
+			table: tableName,
+			values: updatedValues,
+			generatedExternalId: externalId
+		});
+		return FragnoId.fromExternal(externalId, 0);
+	}
+	update(tableName, id, builderFn) {
+		const builder = new UpdateBuilder(tableName, id);
+		builderFn(builder);
+		const { id: opId, checkVersion, set } = builder.build();
+		this.#uow.addMutationOperation({
+			type: "update",
+			schema: this.#schema,
+			namespace: this.#namespace,
+			table: tableName,
+			id: opId,
+			checkVersion,
+			set
+		});
+	}
+	delete(tableName, id, builderFn) {
+		const builder = new DeleteBuilder(tableName, id);
+		builderFn?.(builder);
+		const { id: opId, checkVersion } = builder.build();
+		this.#uow.addMutationOperation({
+			type: "delete",
+			schema: this.#schema,
+			namespace: this.#namespace,
+			table: tableName,
+			id: opId,
+			checkVersion
+		});
+	}
+	/**
+	* 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");
+	}
+	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) {
+		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();
+	}
+};
+
+//#endregion
+export { TypedUnitOfWork, UnitOfWork, createUnitOfWork };
+//# sourceMappingURL=unit-of-work.js.map