@fragno-dev/db 0.3.0 → 0.4.1

package/dist/browser/query/unit-of-work/unit-of-work.d.ts

@@ -0,0 +1,703 @@
+import { DbInterval, DbIntervalInput, DbNow } from "../db-now.js";
+import { Prettify } from "../../util/types.js";
+import { AnySchema, AnyTable, FragnoId, IdColumn, Index, Relation } from "../../schema/create.js";
+import { Condition, ConditionBuilder } from "../condition-builder.js";
+import { Cursor, CursorResult } from "../cursor.js";
+import { HookPayload, HooksMap, TriggerHookOptions, TriggeredHook } from "../../hooks/hooks.js";
+import { CompiledJoin } from "../orm/orm.js";
+import { ExtractJoinOut, ExtractSelect, SelectClause, SelectResult, TableToInsertValues, TableToUpdateValues } from "../simple-query-interface.js";
+
+//#region src/query/unit-of-work/unit-of-work.d.ts
+
+/**
+ * Builder for updateMany operations that supports both whereIndex and set chaining
+ */
+interface UpdateManyBuilder<TTable extends AnyTable> {
+  whereIndex<TIndexName extends ValidIndexName<TTable>>(indexName: TIndexName, condition?: (eb: IndexSpecificConditionBuilder<TTable, TIndexName>) => Condition | boolean): this;
+  set(values: TableToUpdateValues<TTable>): this;
+  now(): DbNow;
+  interval(input: DbIntervalInput): DbInterval;
+}
+/**
+ * Extract column names from a single index
+ */
+type IndexColumns<TIndex extends Index> = TIndex["columnNames"][number];
+type RemoveEmptyObject<T> = T extends object ? (keyof T extends never ? never : T) : never;
+type ExtractJoinBuilderSelect<T> = T extends JoinFindBuilder<infer _Table, infer TSelect, infer _JoinOut> ? TSelect : true;
+type ExtractJoinBuilderOut<T> = T extends JoinFindBuilder<infer _Table, infer _Select, infer TJoinOut> ? TJoinOut : {};
+/**
+ * Extract all indexed column names from a table's indexes
+ */
+type IndexedColumns<TIndexes extends Record<string, Index>> = TIndexes[keyof TIndexes] extends Index ? IndexColumns<TIndexes[keyof TIndexes]> : never;
+type OmitNever<T> = { [K in keyof T as T[K] extends never ? never : K]: T[K] };
+/**
+ * Extract the name of the ID column from a table
+ * Checks if column has 'id' property set to true (which IdColumn class has)
+ */
+type InferIdColumnName<TTable extends AnyTable> = keyof OmitNever<{ [K in keyof TTable["columns"]]: TTable["columns"][K] extends IdColumn<infer _, infer __, infer ___> ? K : never }>;
+/**
+ * Get the columns for a specific index name.
+ * For "primary", returns only the ID column.
+ * For named indexes, returns the columns defined in that index.
+ */
+type ColumnsForIndex<TTable extends AnyTable, TIndexName extends ValidIndexName<TTable>> = TIndexName extends "primary" ? Pick<TTable["columns"], InferIdColumnName<TTable>> : TIndexName extends keyof TTable["indexes"] ? Pick<TTable["columns"], IndexColumns<TTable["indexes"][TIndexName]>> : never;
+/**
+ * ConditionBuilder restricted to indexed columns only.
+ * Used throughout Unit of Work to ensure all queries can leverage indexes for optimal performance.
+ */
+type IndexedConditionBuilder<TTable extends AnyTable> = ConditionBuilder<Pick<TTable["columns"], IndexedColumns<TTable["indexes"]>>>;
+/**
+ * ConditionBuilder restricted to columns in a specific index.
+ */
+type IndexSpecificConditionBuilder<TTable extends AnyTable, TIndexName extends ValidIndexName<TTable>> = ConditionBuilder<ColumnsForIndex<TTable, TIndexName>>;
+/**
+ * Valid index names for a table, including the static "primary" index
+ */
+type ValidIndexName<TTable extends AnyTable> = "primary" | (string & keyof TTable["indexes"]);
+/**
+ * Find options for Unit of Work (internal, used after builder finalization)
+ */
+type FindOptions<TTable extends AnyTable = AnyTable, TSelect$1 extends SelectClause<TTable> = SelectClause<TTable>> = {
+  /**
+   * Which index to use for this query (required)
+   */
+  useIndex: string;
+  /**
+   * Select clause - which columns to return
+   */
+  select?: TSelect$1;
+  /**
+   * Where clause - filtering restricted to indexed columns only
+   */
+  where?: (eb: IndexedConditionBuilder<TTable>) => Condition | boolean;
+  /**
+   * Order by index - specify which index to order by and direction
+   */
+  orderByIndex?: {
+    indexName: string;
+    direction: "asc" | "desc";
+  };
+  /**
+   * Cursor for pagination - continue after this cursor
+   */
+  after?: Cursor | string;
+  /**
+   * Cursor for pagination - continue before this cursor
+   */
+  before?: Cursor | string;
+  /**
+   * Number of results per page
+   */
+  pageSize?: number;
+  /**
+   * Join operations to include related data
+   */
+  joins?: CompiledJoin[];
+};
+/**
+ * Unit of Work state machine
+ */
+type UOWState = "building-retrieval" | "building-mutation" | "executed";
+/**
+ * Retrieval operation - read operations in the first phase
+ */
+type RetrievalOperation<TSchema extends AnySchema, TTable extends AnyTable = TSchema["tables"][keyof TSchema["tables"]]> = {
+  type: "find";
+  schema: TSchema;
+  namespace?: string | null;
+  table: TTable;
+  indexName: string;
+  options: FindOptions<TTable, SelectClause<TTable>>;
+  withCursor?: boolean;
+  withSingleResult?: boolean;
+  readTracking?: boolean;
+} | {
+  type: "count";
+  schema: TSchema;
+  namespace?: string | null;
+  table: TTable;
+  indexName: string;
+  options: Pick<FindOptions<TTable>, "where" | "useIndex">;
+};
+/**
+ * Mutation operations - write operations in the second phase
+ */
+type MutationOperation<TSchema extends AnySchema, TTable extends AnyTable = TSchema["tables"][keyof TSchema["tables"]]> = {
+  type: "update";
+  schema: TSchema;
+  namespace?: string | null;
+  table: TTable["name"];
+  id: FragnoId | string;
+  checkVersion: boolean;
+  set: TableToUpdateValues<TTable>;
+} | {
+  type: "create";
+  schema: TSchema;
+  namespace?: string | null;
+  table: TTable["name"];
+  values: TableToInsertValues<TTable>;
+  generatedExternalId: string;
+} | {
+  type: "delete";
+  schema: TSchema;
+  namespace?: string | null;
+  table: TTable["name"];
+  id: FragnoId | string;
+  checkVersion: boolean;
+} | {
+  type: "check";
+  schema: TSchema;
+  namespace?: string | null;
+  table: TTable["name"];
+  id: FragnoId;
+};
+/**
+ * Compiled mutation with metadata for execution
+ */
+interface CompiledMutation<TOutput> {
+  query: TOutput;
+  /**
+   * Original mutation operation for execution metadata (e.g., outbox payloads).
+   */
+  operation?: MutationOperation<AnySchema>;
+  /**
+   * Idempotency key for the Unit of Work that produced this mutation.
+   */
+  uowId?: string;
+  /**
+   * The type of mutation operation (create, update, delete, or check).
+   */
+  op: "create" | "update" | "delete" | "check";
+  /**
+   * Number of rows this operation must affect for the transaction to succeed.
+   * If actual affected rows doesn't match, it indicates a version conflict.
+   * null means don't check affected rows (e.g., for create operations).
+   */
+  expectedAffectedRows: bigint | null;
+  /**
+   * Number of rows this SELECT query must return for the transaction to succeed.
+   * Used for check operations to verify version without modifying data.
+   * null means this is not a SELECT query that needs row count validation.
+   */
+  expectedReturnedRows: number | null;
+}
+/**
+ * Compiler interface for Unit of Work operations
+ */
+interface UOWCompiler<TOutput> {
+  /**
+   * Compile a retrieval operation to the adapter's query format
+   */
+  compileRetrievalOperation(op: RetrievalOperation<AnySchema>): TOutput | null;
+  /**
+   * Compile a mutation operation to the adapter's query format
+   */
+  compileMutationOperation(op: MutationOperation<AnySchema>): CompiledMutation<TOutput> | null;
+}
+type MutationResult = {
+  success: true;
+  createdInternalIds: (bigint | null)[];
+} | {
+  success: false;
+};
+/**
+ * Executor interface for Unit of Work operations
+ */
+interface UOWExecutor<TOutput, TRawResult = unknown> {
+  executeRetrievalPhase(retrievalBatch: TOutput[]): Promise<TRawResult[]>;
+  /**
+   * Returns success status indicating if mutations completed without conflicts,
+   * and internal IDs for create operations (null if database doesn't support RETURNING)
+   */
+  executeMutationPhase(mutationBatch: CompiledMutation<TOutput>[]): Promise<MutationResult>;
+}
+/**
+ * Decoder interface for Unit of Work retrieval results
+ *
+ * Transforms raw database results into application format (e.g., converting raw columns
+ * into FragnoId objects with external ID, internal ID, and version).
+ */
+interface UOWDecoder<TRawInput = unknown> {
+  /**
+   * Decode raw database results from the retrieval phase
+   *
+   * @param rawResults - Array of raw result sets from database queries
+   * @param operations - Array of retrieval operations that produced these results
+   * @returns Decoded results in application format
+   */
+  decode(rawResults: TRawInput[], operations: RetrievalOperation<AnySchema>[]): unknown[];
+}
+/**
+ * Builder for find operations in Unit of Work
+ */
+declare class FindBuilder<TTable extends AnyTable, TSelect$1 extends SelectClause<TTable> = true, TJoinOut$1 = {}> {
+  #private;
+  constructor(tableName: string, table: TTable);
+  /**
+   * Specify which index to use and optionally filter the results
+   */
+  whereIndex<TIndexName extends ValidIndexName<TTable>>(indexName: TIndexName, condition?: (eb: IndexSpecificConditionBuilder<TTable, TIndexName>) => Condition | boolean): this;
+  /**
+   * Specify columns to select
+   * @throws Error if selectCount() has already been called
+   */
+  select<const TNewSelect extends SelectClause<TTable>>(columns: TNewSelect): FindBuilder<TTable, TNewSelect, TJoinOut$1>;
+  /**
+   * Select count instead of records
+   * @throws Error if select() has already been called
+   */
+  selectCount(): this;
+  /**
+   * Order results by index in ascending or descending order
+   */
+  orderByIndex<TIndexName extends ValidIndexName<TTable>>(indexName: TIndexName, direction: "asc" | "desc"): 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: Cursor | string): 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: Cursor | string): this;
+  /**
+   * Set the number of results per page
+   * @throws {RangeError} If size is not a positive integer
+   */
+  pageSize(size: number): this;
+  /**
+   * Add joins to include related data
+   * Join where clauses are restricted to indexed columns only
+   */
+  join<TNewJoinOut>(joinFn: (jb: IndexedJoinBuilder<TTable, {}>) => IndexedJoinBuilder<TTable, TNewJoinOut>): FindBuilder<TTable, TSelect$1, TNewJoinOut>;
+  /**
+   * @internal
+   */
+  build(): {
+    type: "find";
+    indexName: string;
+    options: FindOptions<TTable, TSelect$1>;
+  } | {
+    type: "count";
+    indexName: string;
+    options: Pick<FindOptions<TTable>, "where" | "useIndex">;
+  };
+}
+/**
+ * Builder for update operations in Unit of Work
+ */
+declare class UpdateBuilder<TTable extends AnyTable> {
+  #private;
+  constructor(tableName: string, id: FragnoId | string);
+  /**
+   * Specify values to update
+   */
+  set(values: TableToUpdateValues<TTable>): this;
+  /**
+   * Database timestamp helper for mutation values.
+   */
+  now(): DbNow;
+  interval(input: DbIntervalInput): DbInterval;
+  /**
+   * Enable version checking for optimistic concurrency control
+   * @throws Error if the ID is just a string (no version available)
+   */
+  check(): this;
+  /**
+   * @internal
+   */
+  build(): {
+    id: FragnoId | string;
+    checkVersion: boolean;
+    set: TableToUpdateValues<TTable>;
+  };
+}
+/**
+ * Builder for delete operations in Unit of Work
+ */
+declare class DeleteBuilder {
+  #private;
+  constructor(tableName: string, id: FragnoId | string);
+  /**
+   * Enable version checking for optimistic concurrency control
+   * @throws Error if the ID is just a string (no version available)
+   */
+  check(): this;
+  /**
+   * @internal
+   */
+  build(): {
+    id: FragnoId | string;
+    checkVersion: boolean;
+  };
+}
+/**
+ * Builder for join operations in Unit of Work
+ * Similar to FindBuilder but tailored for joins (no cursor pagination, no count mode)
+ */
+declare class JoinFindBuilder<TTable extends AnyTable, TSelect$1 extends SelectClause<TTable> = true, TJoinOut$1 = {}> {
+  #private;
+  constructor(tableName: string, table: TTable);
+  /**
+   * Specify which index to use and optionally filter the results
+   */
+  whereIndex<TIndexName extends ValidIndexName<TTable>>(indexName: TIndexName, condition?: (eb: IndexSpecificConditionBuilder<TTable, TIndexName>) => Condition | boolean): this;
+  /**
+   * Specify columns to select
+   */
+  select<const TNewSelect extends SelectClause<TTable>>(columns: TNewSelect): JoinFindBuilder<TTable, TNewSelect, TJoinOut$1>;
+  /**
+   * Order results by index in ascending or descending order
+   */
+  orderByIndex<TIndexName extends ValidIndexName<TTable>>(indexName: TIndexName, direction: "asc" | "desc"): this;
+  /**
+   * Set the number of results to return
+   * @throws {RangeError} If size is not a positive integer
+   */
+  pageSize(size: number): this;
+  /**
+   * Add joins to include related data
+   * Join where clauses are restricted to indexed columns only
+   */
+  join<TNewJoinOut>(joinFn: (jb: IndexedJoinBuilder<TTable, {}>) => IndexedJoinBuilder<TTable, TNewJoinOut>): JoinFindBuilder<TTable, TSelect$1, TJoinOut$1 & TNewJoinOut>;
+  /**
+   * @internal
+   */
+  build(): {
+    indexName: string | undefined;
+    select: TSelect$1 | undefined;
+    where: ((eb: IndexedConditionBuilder<TTable>) => Condition | boolean) | undefined;
+    orderByIndex: {
+      indexName: string;
+      direction: "asc" | "desc";
+    } | undefined;
+    pageSize: number | undefined;
+    joins: CompiledJoin[] | undefined;
+  };
+}
+interface MapRelationType<T> {
+  one: RemoveEmptyObject<T> | null;
+  many: RemoveEmptyObject<T>[];
+}
+/**
+ * Join builder with indexed-only where clauses for Unit of Work
+ * TJoinOut accumulates the types of all joined relations
+ */
+type IndexedJoinBuilder<TTable extends AnyTable, TJoinOut$1> = { [K in keyof TTable["relations"]]: TTable["relations"][K] extends Relation<infer TRelationType, infer TTargetTable> ? <TBuilderFn extends (builder: JoinFindBuilder<TTable["relations"][K]["table"]>) => unknown = (builder: JoinFindBuilder<TTable["relations"][K]["table"]>) => JoinFindBuilder<TTable["relations"][K]["table"]>>(builderFn?: TBuilderFn) => IndexedJoinBuilder<TTable, TJoinOut$1 & { [P in K]: MapRelationType<SelectResult<TTargetTable, ExtractJoinBuilderOut<ReturnType<TBuilderFn>>, ExtractJoinBuilderSelect<ReturnType<TBuilderFn>>>>[TRelationType] }> : never };
+/**
+ * Full Unit of Work interface with all operations including execution.
+ * This allows UOW instances to be passed between different contexts that use different schemas.
+ */
+interface IUnitOfWork {
+  readonly state: UOWState;
+  readonly name: string | undefined;
+  readonly idempotencyKey: string;
+  readonly retrievalPhase: Promise<unknown[]>;
+  readonly mutationPhase: Promise<void>;
+  executeRetrieve(): Promise<unknown[]>;
+  executeMutations(): Promise<{
+    success: boolean;
+  }>;
+  getRetrievalOperations(): ReadonlyArray<RetrievalOperation<AnySchema>>;
+  getMutationOperations(): ReadonlyArray<MutationOperation<AnySchema>>;
+  getCreatedIds(): FragnoId[];
+  restrict(options?: {
+    readyFor?: "mutation" | "retrieval" | "none";
+  }): IUnitOfWork;
+  signalReadyForRetrieval(): void;
+  signalReadyForMutation(): void;
+  reset(): void;
+  forSchema<TOtherSchema extends AnySchema, TOtherHooks extends HooksMap = {}>(schema: TOtherSchema, hooks?: TOtherHooks): TypedUnitOfWork<TOtherSchema, [], any, TOtherHooks>;
+  registerSchema(schema: AnySchema, namespace: string | null): void;
+  triggerHook(namespace: string, hookName: string, payload: unknown, options?: TriggerHookOptions): void;
+  getTriggeredHooks(): readonly TriggeredHook[];
+}
+/**
+ * Restricted UOW interface without execute methods.
+ * Useful when you want to allow building operations but not executing them,
+ * to prevent deadlocks or enforce execution control at a higher level.
+ *
+ * Note: This is just a marker interface. Restriction is enforced by the UnitOfWork class itself.
+ */
+interface IUnitOfWorkRestricted extends Omit<IUnitOfWork, "executeRetrieve" | "executeMutations"> {}
+type UOWInstrumentationPhase = "beforeRetrieve" | "afterRetrieve" | "beforeMutate" | "afterMutate";
+type UOWInstrumentationInjection = {
+  type: "conflict";
+  reason?: string;
+} | {
+  type: "error";
+  error: Error;
+};
+type UOWInstrumentationContext = {
+  phase: UOWInstrumentationPhase;
+  uowName?: string;
+  idempotencyKey: string;
+  retrievalOpsCount: number;
+  mutationOpsCount: number;
+  uow: IUnitOfWork;
+};
+type UOWInstrumentation = {
+  beforeRetrieve?: (ctx: UOWInstrumentationContext) => void | Promise<void> | UOWInstrumentationInjection;
+  afterRetrieve?: (ctx: UOWInstrumentationContext) => void | Promise<void> | UOWInstrumentationInjection;
+  beforeMutate?: (ctx: UOWInstrumentationContext) => void | Promise<void> | UOWInstrumentationInjection;
+  afterMutate?: (ctx: UOWInstrumentationContext) => void | Promise<void> | UOWInstrumentationInjection;
+};
+type UOWInstrumentationFinalizer = {
+  afterRetrieve?: (ctx: UOWInstrumentationContext) => void | Promise<void>;
+  afterMutate?: (ctx: UOWInstrumentationContext) => void | Promise<void>;
+};
+declare function createUnitOfWork(compiler: UOWCompiler<unknown>, executor: UOWExecutor<unknown, unknown>, decoder: UOWDecoder<unknown>, schemaNamespaceMap?: WeakMap<AnySchema, string | null>, name?: string): UnitOfWork;
+interface UnitOfWorkConfig {
+  dryRun?: boolean;
+  onQuery?: (query: unknown) => void;
+  idempotencyKey?: string;
+  instrumentation?: UOWInstrumentation;
+  instrumentationFinalizer?: UOWInstrumentationFinalizer;
+}
+/**
+ * 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
+ * }
+ * ```
+ */
+declare class UnitOfWork<const TRawInput = unknown> implements IUnitOfWork {
+  #private;
+  constructor(compiler: UOWCompiler<unknown>, executor: UOWExecutor<unknown, TRawInput>, decoder: UOWDecoder<TRawInput>, name?: string, config?: UnitOfWorkConfig, schemaNamespaceMap?: WeakMap<AnySchema, string | null>);
+  /**
+   * 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: AnySchema, namespace: string | null): void;
+  /**
+   * 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<TOtherSchema extends AnySchema, TOtherHooks extends HooksMap = {}>(schema: TOtherSchema, _hooks?: TOtherHooks): TypedUnitOfWork<TOtherSchema, [], TRawInput, TOtherHooks>;
+  /**
+   * 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?: {
+    readyFor?: "mutation" | "retrieval" | "none";
+  }): UnitOfWork<TRawInput>;
+  /**
+   * Signal that this child is ready for retrieval phase execution.
+   * Only valid for restricted (child) UOWs.
+   */
+  signalReadyForRetrieval(): void;
+  /**
+   * Signal that this child is ready for mutation phase execution.
+   * Only valid for restricted (child) UOWs.
+   */
+  signalReadyForMutation(): void;
+  /**
+   * Reset the UOW to initial state for retry support.
+   * Clears operations, resets state, and resets phase promises.
+   */
+  reset(): void;
+  /**
+   * Trigger a hook to be executed after the transaction commits.
+   */
+  triggerHook(namespace: string, hookName: string, payload: unknown, options?: TriggerHookOptions): void;
+  /**
+   * Get all triggered hooks for this UOW.
+   */
+  getTriggeredHooks(): ReadonlyArray<TriggeredHook>;
+  get state(): UOWState;
+  enableReadTracking(): void;
+  get readTrackingEnabled(): boolean;
+  get name(): string | undefined;
+  get idempotencyKey(): string;
+  /**
+   * Promise that resolves when the retrieval phase is executed
+   * Service methods can await this to coordinate multi-phase logic
+   */
+  get retrievalPhase(): Promise<unknown[]>;
+  /**
+   * Promise that resolves when the mutation phase is executed
+   * Service methods can await this to coordinate multi-phase logic
+   */
+  get mutationPhase(): Promise<void>;
+  /**
+   * Execute the retrieval phase and transition to mutation phase
+   * Returns all results from find operations
+   */
+  executeRetrieve(): Promise<unknown[]>;
+  /**
+   * Execute the mutation phase
+   * Returns success flag indicating if mutations completed without conflicts
+   */
+  executeMutations(): Promise<{
+    success: boolean;
+  }>;
+  /**
+   * Get the retrieval operations (for inspection/debugging)
+   */
+  getRetrievalOperations(): ReadonlyArray<RetrievalOperation<AnySchema>>;
+  /**
+   * Get the mutation operations (for inspection/debugging)
+   */
+  getMutationOperations(): ReadonlyArray<MutationOperation<AnySchema>>;
+  /**
+   * @internal
+   * Add a retrieval operation (used by TypedUnitOfWork)
+   */
+  addRetrievalOperation(op: RetrievalOperation<AnySchema>): number;
+  /**
+   * @internal
+   * Add a mutation operation (used by TypedUnitOfWork)
+   */
+  addMutationOperation(op: MutationOperation<AnySchema>): void;
+  /**
+   * 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(): FragnoId[];
+  /**
+   * @internal
+   * Compile the unit of work to executable queries for testing
+   */
+  compile<TOutput>(compiler: UOWCompiler<TOutput>): {
+    name?: string;
+    retrievalBatch: TOutput[];
+    mutationBatch: CompiledMutation<TOutput>[];
+  };
+}
+/**
+ * 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.
+ */
+declare class TypedUnitOfWork<const TSchema extends AnySchema, const TRetrievalResults extends unknown[] = [], const TRawInput = unknown, const THooks extends HooksMap = {}> {
+  #private;
+  constructor(schema: TSchema, namespace: string | null | undefined, uow: UnitOfWork<TRawInput>);
+  /**
+   * Type-only access to retrieval results for this typed UOW.
+   */
+  get $results(): Prettify<TRetrievalResults>;
+  get schema(): TSchema;
+  get name(): string | undefined;
+  get idempotencyKey(): string;
+  get state(): UOWState;
+  get retrievalPhase(): Promise<TRetrievalResults>;
+  get mutationPhase(): Promise<void>;
+  getRetrievalOperations(): readonly RetrievalOperation<AnySchema, AnyTable>[];
+  getMutationOperations(): readonly MutationOperation<AnySchema, AnyTable>[];
+  getCreatedIds(): FragnoId[];
+  executeRetrieve(): Promise<TRetrievalResults>;
+  executeMutations(): Promise<{
+    success: boolean;
+  }>;
+  restrict(options?: {
+    readyFor?: "mutation" | "retrieval" | "none";
+  }): IUnitOfWork;
+  signalReadyForRetrieval(): void;
+  signalReadyForMutation(): void;
+  reset(): void;
+  forSchema<TOtherSchema extends AnySchema, TOtherHooks extends HooksMap = {}>(schema: TOtherSchema, hooks?: TOtherHooks): TypedUnitOfWork<TOtherSchema, [], TRawInput, TOtherHooks>;
+  /**
+   * Database timestamp helper for inserts.
+   */
+  now(): DbNow;
+  /**
+   * Build a database interval for use with now().plus(...).
+   */
+  interval(input: DbIntervalInput): DbInterval;
+  registerSchema(schema: AnySchema, namespace: string | null): void;
+  compile<TOutput>(compiler: UOWCompiler<TOutput>): {
+    name?: string;
+    retrievalBatch: TOutput[];
+    mutationBatch: CompiledMutation<TOutput>[];
+  };
+  find<TTableName extends keyof TSchema["tables"] & string, const TBuilderResult>(tableName: TTableName, builderFn: (builder: Omit<FindBuilder<TSchema["tables"][TTableName]>, "build">) => TBuilderResult): TypedUnitOfWork<TSchema, [...TRetrievalResults, SelectResult<TSchema["tables"][TTableName], ExtractJoinOut<TBuilderResult>, Extract<ExtractSelect<TBuilderResult>, SelectClause<TSchema["tables"][TTableName]>>>[]], TRawInput, THooks>;
+  find<TTableName extends keyof TSchema["tables"] & string>(tableName: TTableName): TypedUnitOfWork<TSchema, [...TRetrievalResults, SelectResult<TSchema["tables"][TTableName], {}, true>[]], TRawInput, THooks>;
+  findFirst<TTableName extends keyof TSchema["tables"] & string, const TBuilderResult>(tableName: TTableName, builderFn: (builder: Omit<FindBuilder<TSchema["tables"][TTableName]>, "build">) => TBuilderResult): TypedUnitOfWork<TSchema, [...TRetrievalResults, SelectResult<TSchema["tables"][TTableName], ExtractJoinOut<TBuilderResult>, Extract<ExtractSelect<TBuilderResult>, SelectClause<TSchema["tables"][TTableName]>>> | null], TRawInput, THooks>;
+  findFirst<TTableName extends keyof TSchema["tables"] & string>(tableName: TTableName): TypedUnitOfWork<TSchema, [...TRetrievalResults, SelectResult<TSchema["tables"][TTableName], {}, true> | null], TRawInput, THooks>;
+  findWithCursor<TTableName extends keyof TSchema["tables"] & string, const TBuilderResult>(tableName: TTableName, builderFn: (builder: Omit<FindBuilder<TSchema["tables"][TTableName]>, "build">) => TBuilderResult): TypedUnitOfWork<TSchema, [...TRetrievalResults, CursorResult<SelectResult<TSchema["tables"][TTableName], ExtractJoinOut<TBuilderResult>, Extract<ExtractSelect<TBuilderResult>, SelectClause<TSchema["tables"][TTableName]>>>>], TRawInput, THooks>;
+  /**
+   * 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 extends keyof TSchema["tables"] & string>(tableName: TableName): FragnoId;
+  create<TableName extends keyof TSchema["tables"] & string>(tableName: TableName, values: TableToInsertValues<TSchema["tables"][TableName]>): FragnoId;
+  update<TableName extends keyof TSchema["tables"] & string>(tableName: TableName, id: FragnoId | string, builderFn: (builder: Omit<UpdateBuilder<TSchema["tables"][TableName]>, "build">) => Omit<UpdateBuilder<TSchema["tables"][TableName]>, "build"> | void): void;
+  delete<TableName extends keyof TSchema["tables"] & string>(tableName: TableName, id: FragnoId | string, builderFn?: (builder: Omit<DeleteBuilder, "build">) => Omit<DeleteBuilder, "build"> | void): void;
+  /**
+   * 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 extends keyof TSchema["tables"] & string>(tableName: TableName, id: FragnoId): void;
+  get $hooks(): THooks;
+  get namespace(): string | null | undefined;
+  /**
+   * Trigger a hook to be executed after the transaction commits.
+   * The namespace is automatically injected from this typed view's schema registration.
+   */
+  triggerHook<K$1 extends keyof THooks & string>(hookName: K$1, payload: HookPayload<THooks[K$1]>, options?: TriggerHookOptions): void;
+  getTriggeredHooks(): ReadonlyArray<TriggeredHook>;
+}
+//#endregion
+export { DeleteBuilder, FindBuilder, IUnitOfWork, IUnitOfWorkRestricted, TypedUnitOfWork, UOWCompiler, UOWDecoder, UOWExecutor, UnitOfWork, UpdateBuilder, UpdateManyBuilder, createUnitOfWork };
+//# sourceMappingURL=unit-of-work.d.ts.map