@holo-js/db 0.2.5 → 0.2.6

package/dist/index.mjs

@@ -122,6 +122,11 @@ function redactSql(sql, policy) {
 // src/cache.ts
 import { createHash } from "crypto";
 import { AsyncLocalStorage } from "async_hooks";
+var DATABASE_DEPENDENCY_PREFIX = "db:";
+var DATABASE_DEPENDENCY_METADATA_KEY = "__holoDatabaseDependencyMetadata__";
+var MUTATION_DEPENDENCY_SUFFIX = "mutation";
+var WHERE_DEPENDENCY_PREFIX = "where:";
+var WHERE_EXACT_DEPENDENCY_PREFIX = "where-exact:";
 var databaseDependencyCollector = new AsyncLocalStorage();
 function getQueryCacheBridgeState() {
   const runtime = globalThis;
@@ -140,20 +145,32 @@ function resetDatabaseQueryCacheBridge() {
 function onDatabaseDependencyInvalidated(listener) {
   const state = getQueryCacheBridgeState();
   state.dependencyInvalidationListeners ??= /* @__PURE__ */ new Set();
-  state.dependencyInvalidationListeners.add(listener);
+  const internalListener = listener;
+  state.dependencyInvalidationListeners.add(internalListener);
   return () => {
-    state.dependencyInvalidationListeners?.delete(listener);
+    state.dependencyInvalidationListeners?.delete(internalListener);
   };
 }
 function resetDatabaseDependencyInvalidationListeners() {
   getQueryCacheBridgeState().dependencyInvalidationListeners = void 0;
 }
 async function collectDatabaseQueryDependencies(callback) {
-  const dependencies = /* @__PURE__ */ new Set();
-  const value = await databaseDependencyCollector.run(dependencies, callback);
+  const result = await collectDatabaseQueryDependenciesInternal(callback);
+  return Object.freeze({
+    value: result.value,
+    dependencies: result.dependencies
+  });
+}
+async function collectDatabaseQueryDependenciesInternal(callback) {
+  const state = {
+    dependencies: /* @__PURE__ */ new Set(),
+    queries: []
+  };
+  const value = await databaseDependencyCollector.run(state, callback);
   return Object.freeze({
     value,
-    dependencies: Object.freeze([...dependencies])
+    dependencies: Object.freeze([...state.dependencies]),
+    queries: Object.freeze([...state.queries])
   });
 }
 function hasActiveDatabaseDependencyCollector() {
@@ -163,12 +180,227 @@ function recordDatabaseQueryDependencies(dependencies) {
   if (!dependencies || dependencies.length === 0) {
     return;
   }
-  const active = databaseDependencyCollector.getStore();
-  if (!active) {
+  const state = databaseDependencyCollector.getStore();
+  if (!state) {
     return;
   }
   for (const dependency of dependencies) {
-    active.add(dependency);
+    state.dependencies.add(dependency);
+  }
+}
+function recordDatabaseQueryObservation(observation) {
+  if (!observation) {
+    return;
+  }
+  const state = databaseDependencyCollector.getStore();
+  if (!state) {
+    return;
+  }
+  state.queries.push(observation);
+}
+function readDatabaseQueryObservationCount() {
+  return databaseDependencyCollector.getStore()?.queries.length ?? 0;
+}
+function truncateDatabaseQueryObservations(count) {
+  const state = databaseDependencyCollector.getStore();
+  if (!state || count >= state.queries.length) {
+    return;
+  }
+  state.queries.length = Math.max(0, count);
+}
+function rebindDatabaseQueryObservationResult(source, result) {
+  rebindDatabaseQueryObservation(source, result);
+}
+function rebindDatabaseQueryObservationHydratedResult(source, result, belongsToHydrations, relatedHydrations) {
+  rebindDatabaseQueryObservation(source, result, void 0, void 0, void 0, void 0, belongsToHydrations, relatedHydrations);
+}
+function rebindDatabaseQueryObservationPagination(source, data, meta, pagination, offset, belongsToHydrations, relatedHydrations) {
+  const state = databaseDependencyCollector.getStore();
+  if (!state) {
+    return;
+  }
+  for (let index = state.queries.length - 1; index >= 0; index -= 1) {
+    const query = state.queries[index];
+    if (!query || query.result !== source) {
+      continue;
+    }
+    state.queries[index] = Object.freeze({
+      aggregate: void 0,
+      belongsToHydrations: belongsToHydrations ?? query.belongsToHydrations,
+      connectionName: query.connectionName,
+      tableName: query.tableName,
+      dependencies: query.dependencies,
+      limit: pagination.perPage,
+      offset,
+      orderBy: query.orderBy,
+      patchable: query.patchable,
+      pagination: void 0,
+      predicates: query.predicates,
+      relation: query.relation,
+      result: data,
+      resultPath: query.resultPath,
+      relatedHydrations: relatedHydrations ?? query.relatedHydrations,
+      scalarColumn: void 0,
+      scalarListColumn: void 0,
+      scalarListRows: void 0,
+      selections: query.selections
+    });
+    state.queries.push(Object.freeze({
+      aggregate: void 0,
+      belongsToHydrations: void 0,
+      connectionName: query.connectionName,
+      tableName: query.tableName,
+      dependencies: query.dependencies,
+      limit: void 0,
+      offset: void 0,
+      orderBy: query.orderBy,
+      patchable: query.patchable,
+      pagination,
+      predicates: query.predicates,
+      relation: query.relation,
+      result: meta,
+      resultPath: void 0,
+      relatedHydrations: void 0,
+      scalarColumn: void 0,
+      scalarListColumn: void 0,
+      scalarListRows: void 0,
+      selections: query.selections
+    }));
+    return;
+  }
+}
+function rebindDatabaseQueryObservationCursorPagination(source, data, meta, pagination, belongsToHydrations, relatedHydrations) {
+  const state = databaseDependencyCollector.getStore();
+  if (!state) {
+    return;
+  }
+  for (let index = state.queries.length - 1; index >= 0; index -= 1) {
+    const query = state.queries[index];
+    if (!query || query.result !== source) {
+      continue;
+    }
+    state.queries[index] = Object.freeze({
+      aggregate: void 0,
+      belongsToHydrations: belongsToHydrations ?? query.belongsToHydrations,
+      connectionName: query.connectionName,
+      tableName: query.tableName,
+      cursorRowCount: pagination.rowCount,
+      cursorRows: pagination.rows,
+      dependencies: query.dependencies,
+      limit: pagination.perPage,
+      offset: void 0,
+      orderBy: query.orderBy,
+      patchable: query.patchable,
+      pagination: void 0,
+      predicates: query.predicates,
+      relation: query.relation,
+      result: data,
+      resultPath: query.resultPath,
+      relatedHydrations: relatedHydrations ?? query.relatedHydrations,
+      scalarColumn: void 0,
+      scalarListColumn: void 0,
+      scalarListRows: void 0,
+      selections: query.selections
+    });
+    state.queries.push(Object.freeze({
+      aggregate: void 0,
+      belongsToHydrations: void 0,
+      connectionName: query.connectionName,
+      tableName: query.tableName,
+      dependencies: query.dependencies,
+      limit: void 0,
+      offset: void 0,
+      orderBy: query.orderBy,
+      patchable: query.patchable,
+      pagination,
+      predicates: query.predicates,
+      relation: query.relation,
+      result: meta.nextCursor,
+      resultPath: Object.freeze(["nextCursor"]),
+      relatedHydrations: void 0,
+      scalarColumn: void 0,
+      scalarListColumn: void 0,
+      scalarListRows: void 0,
+      selections: query.selections
+    }));
+    return;
+  }
+}
+function disableDatabaseQueryObservationPatching(source) {
+  const state = databaseDependencyCollector.getStore();
+  if (!state) {
+    return;
+  }
+  for (let index = state.queries.length - 1; index >= 0; index -= 1) {
+    const query = state.queries[index];
+    if (!query || query.result !== source) {
+      continue;
+    }
+    state.queries[index] = Object.freeze({
+      aggregate: query.aggregate,
+      belongsToHydrations: query.belongsToHydrations,
+      connectionName: query.connectionName,
+      tableName: query.tableName,
+      dependencies: query.dependencies,
+      limit: query.limit,
+      offset: query.offset,
+      orderBy: query.orderBy,
+      patchable: false,
+      pagination: query.pagination,
+      predicates: query.predicates,
+      relation: query.relation,
+      result: query.result,
+      resultPath: query.resultPath,
+      relatedHydrations: query.relatedHydrations,
+      scalarColumn: query.scalarColumn,
+      scalarListColumn: query.scalarListColumn,
+      scalarListRows: query.scalarListRows,
+      selections: query.selections
+    });
+    return;
+  }
+}
+function rebindDatabaseQueryObservationAggregate(source, result, aggregate) {
+  rebindDatabaseQueryObservation(source, result, aggregate);
+}
+function rebindDatabaseQueryObservationScalar(source, result, column2) {
+  rebindDatabaseQueryObservation(source, result, void 0, column2);
+}
+function rebindDatabaseQueryObservationScalarList(rows, result, column2) {
+  rebindDatabaseQueryObservation(rows, result, void 0, void 0, column2, rows);
+}
+function rebindDatabaseQueryObservation(source, result, aggregate, scalarColumn, scalarListColumn, scalarListRows, belongsToHydrations, relatedHydrations) {
+  const state = databaseDependencyCollector.getStore();
+  if (!state) {
+    return;
+  }
+  for (let index = state.queries.length - 1; index >= 0; index -= 1) {
+    const query = state.queries[index];
+    if (!query || query.result !== source) {
+      continue;
+    }
+    state.queries[index] = Object.freeze({
+      aggregate,
+      belongsToHydrations,
+      connectionName: query.connectionName,
+      tableName: query.tableName,
+      dependencies: query.dependencies,
+      limit: query.limit,
+      offset: query.offset,
+      orderBy: query.orderBy,
+      patchable: query.patchable,
+      pagination: query.pagination,
+      predicates: query.predicates,
+      relation: query.relation,
+      result,
+      resultPath: query.resultPath,
+      relatedHydrations,
+      scalarColumn,
+      scalarListColumn,
+      scalarListRows,
+      selections: query.selections
+    });
+    return;
   }
 }
 function hasDatabaseDependencyInvalidationListeners() {
@@ -239,15 +471,173 @@ function resolveQueryCacheKey(statement, connectionName, config) {
 function createTableCacheDependency(connectionName, tableName) {
   return `db:${connectionName}:${tableName}`;
 }
+function encodeDependencyValue(value) {
+  return encodeURIComponent(JSON.stringify(value));
+}
+function createPredicateMetadata(connectionName, tableName, columnName, value) {
+  if (typeof value === "undefined") {
+    return void 0;
+  }
+  return Object.freeze({
+    tableKey: createTableCacheDependency(connectionName, tableName),
+    columnName: getColumnName(columnName),
+    encodedValue: encodeDependencyValue(value)
+  });
+}
+function createPredicateDependencyFromMetadata(metadata, exact) {
+  return `${metadata.tableKey}:${exact ? WHERE_EXACT_DEPENDENCY_PREFIX : WHERE_DEPENDENCY_PREFIX}${metadata.columnName}:${metadata.encodedValue}`;
+}
+function createPredicateDependencyEntry(connectionName, tableName, columnName, value, exact = false) {
+  const metadata = createPredicateMetadata(connectionName, tableName, columnName, value);
+  if (!metadata) {
+    return void 0;
+  }
+  return {
+    dependency: createPredicateDependencyFromMetadata(metadata, exact),
+    metadata
+  };
+}
+function readExactPredicateValues(predicate) {
+  if (predicate.kind !== "comparison") {
+    return Object.freeze([]);
+  }
+  if (predicate.operator === "=") {
+    return Object.freeze([predicate.value]);
+  }
+  if (predicate.operator === "in" && Array.isArray(predicate.value)) {
+    return Object.freeze([...predicate.value]);
+  }
+  return Object.freeze([]);
+}
 function createTableRowCacheDependency(connectionName, tableName, columnName, value) {
   if (typeof value === "undefined") {
     return void 0;
   }
-  return `db:${connectionName}:${tableName}:row:${columnName}:${encodeURIComponent(JSON.stringify(value))}`;
+  return `db:${connectionName}:${tableName}:row:${columnName}:${encodeDependencyValue(value)}`;
 }
 function createTableRowWildcardCacheDependency(connectionName, tableName) {
   return `db:${connectionName}:${tableName}:row:*`;
 }
+function createTablePredicateCacheDependency(connectionName, tableName, columnName, value) {
+  return createPredicateDependencyEntry(connectionName, tableName, columnName, value)?.dependency;
+}
+function createTableMutationCacheDependency(connectionName, tableName) {
+  return `db:${connectionName}:${tableName}:mutation`;
+}
+function createTableExactPredicateCacheDependency(connectionName, tableName, columnName, value) {
+  return createPredicateDependencyEntry(connectionName, tableName, columnName, value, true)?.dependency;
+}
+function parseDatabaseDependency(dependency) {
+  if (!dependency.startsWith(DATABASE_DEPENDENCY_PREFIX)) {
+    return void 0;
+  }
+  const connectionEnd = dependency.indexOf(":", DATABASE_DEPENDENCY_PREFIX.length);
+  if (connectionEnd <= DATABASE_DEPENDENCY_PREFIX.length) {
+    return void 0;
+  }
+  const tableStart = connectionEnd + 1;
+  const tableEnd = dependency.indexOf(":", tableStart);
+  if (tableEnd < 0) {
+    return tableStart === dependency.length ? void 0 : { tableKey: dependency };
+  }
+  if (tableEnd === tableStart) {
+    return void 0;
+  }
+  const suffixStart = tableEnd + 1;
+  return {
+    suffix: suffixStart === dependency.length ? "" : dependency.slice(suffixStart),
+    tableKey: dependency.slice(0, tableEnd)
+  };
+}
+function parsePredicateDependencySuffix(tableKey, suffix, prefix) {
+  if (!suffix.startsWith(prefix)) {
+    return void 0;
+  }
+  const columnStart = prefix.length;
+  const valueSeparator = suffix.indexOf(":", columnStart);
+  if (valueSeparator <= columnStart || valueSeparator === suffix.length - 1) {
+    return void 0;
+  }
+  return Object.freeze({
+    tableKey,
+    columnName: suffix.slice(columnStart, valueSeparator),
+    encodedValue: suffix.slice(valueSeparator + 1)
+  });
+}
+function createDatabaseDependencyInvalidationMetadata(dependencies, mutations) {
+  const directDependencies = [];
+  const exactPredicates = [];
+  const predicates = [];
+  const tableDependencyCandidates = [];
+  let hasMutationDependency = mutations.some((mutation) => mutation.kind === "upsert");
+  for (const dependency of dependencies) {
+    const parsed = parseDatabaseDependency(dependency);
+    if (!parsed) {
+      directDependencies.push(dependency);
+      continue;
+    }
+    if (parsed.suffix === void 0) {
+      tableDependencyCandidates.push(parsed.tableKey);
+      continue;
+    }
+    if (parsed.suffix === MUTATION_DEPENDENCY_SUFFIX) {
+      hasMutationDependency = true;
+      directDependencies.push(dependency);
+      continue;
+    }
+    const exactPredicate = parsePredicateDependencySuffix(
+      parsed.tableKey,
+      parsed.suffix,
+      WHERE_EXACT_DEPENDENCY_PREFIX
+    );
+    if (exactPredicate) {
+      exactPredicates.push(exactPredicate);
+      directDependencies.push(dependency);
+      continue;
+    }
+    const predicate = parsePredicateDependencySuffix(
+      parsed.tableKey,
+      parsed.suffix,
+      WHERE_DEPENDENCY_PREFIX
+    );
+    if (predicate) {
+      predicates.push(predicate);
+      directDependencies.push(dependency);
+      continue;
+    }
+    directDependencies.push(dependency);
+  }
+  const exactPredicateTables = new Set(exactPredicates.map((predicate) => predicate.tableKey));
+  const tableDependencies = [];
+  for (const tableKey of tableDependencyCandidates) {
+    if (exactPredicateTables.has(tableKey)) {
+      tableDependencies.push(tableKey);
+      continue;
+    }
+    directDependencies.push(tableKey);
+  }
+  return Object.freeze({
+    directDependencies: Object.freeze(directDependencies),
+    exactPredicates: Object.freeze(exactPredicates),
+    hasMutationDependency,
+    predicates: Object.freeze(predicates),
+    tableDependencies: Object.freeze(tableDependencies)
+  });
+}
+function createDatabaseDependencyInvalidationEvent(connectionName, dependencies, mutations, metadata) {
+  const event = {
+    connectionName,
+    dependencies,
+    mutations
+  };
+  Object.defineProperty(event, DATABASE_DEPENDENCY_METADATA_KEY, {
+    configurable: false,
+    enumerable: false,
+    value: metadata ?? createDatabaseDependencyInvalidationMetadata(dependencies, mutations),
+    writable: false
+  });
+  return Object.freeze(event);
+}
 function normalizeQueryCacheDependencies(connectionName, dependencies) {
   return Object.freeze(dependencies.map((dependency) => {
     return dependency.startsWith("db:") ? dependency : createTableCacheDependency(connectionName, dependency);
@@ -309,8 +699,367 @@ function findExactPrimaryKeyValue(predicates, primaryKeyColumn) {
   }
   return void 0;
 }
+function collectExactPredicateDependencies(predicates, connectionName, tableName, exact = false) {
+  const dependencies = /* @__PURE__ */ new Set();
+  for (const predicate of predicates) {
+    const values = readExactPredicateValues(predicate);
+    if (values.length > 0 && predicate.kind === "comparison") {
+      for (const value of values) {
+        const dependency = exact ? createTableExactPredicateCacheDependency(
+          connectionName,
+          tableName,
+          getColumnName(predicate.column),
+          value
+        ) : createTablePredicateCacheDependency(
+          connectionName,
+          tableName,
+          getColumnName(predicate.column),
+          value
+        );
+        if (dependency) {
+          dependencies.add(dependency);
+        }
+      }
+      continue;
+    }
+    if (predicate.kind === "group" && !predicate.negated && predicate.boolean !== "or") {
+      for (const dependency of collectExactPredicateDependencies(predicate.predicates, connectionName, tableName, exact)) {
+        dependencies.add(dependency);
+      }
+    }
+  }
+  return Object.freeze([...dependencies]);
+}
+function appendExactPredicateDependencyEntries(target, predicates, connectionName, tableName, exact = false) {
+  for (const predicate of predicates) {
+    const values = readExactPredicateValues(predicate);
+    if (values.length > 0 && predicate.kind === "comparison") {
+      for (const value of values) {
+        const entry = createPredicateDependencyEntry(
+          connectionName,
+          tableName,
+          getColumnName(predicate.column),
+          value,
+          exact
+        );
+        if (entry) {
+          target.set(entry.dependency, entry);
+        }
+      }
+      continue;
+    }
+    if (predicate.kind === "group" && !predicate.negated && predicate.boolean !== "or") {
+      appendExactPredicateDependencyEntries(target, predicate.predicates, connectionName, tableName, exact);
+    }
+  }
+}
+function collectRecordPredicateDependencies(connectionName, tableName, record, exact = false) {
+  const dependencies = /* @__PURE__ */ new Set();
+  for (const [columnName, value] of Object.entries(record)) {
+    const dependency = exact ? createTableExactPredicateCacheDependency(connectionName, tableName, getColumnName(columnName), value) : createTablePredicateCacheDependency(connectionName, tableName, getColumnName(columnName), value);
+    if (dependency) {
+      dependencies.add(dependency);
+    }
+  }
+  return Object.freeze([...dependencies]);
+}
+function appendRecordPredicateDependencyEntries(target, connectionName, tableName, record, exact = false) {
+  for (const [columnName, value] of Object.entries(record)) {
+    const entry = createPredicateDependencyEntry(connectionName, tableName, getColumnName(columnName), value, exact);
+    if (entry) {
+      target.set(entry.dependency, entry);
+    }
+  }
+}
+function createInvalidationMetadataFromParts(directDependencies, exactPredicates, predicates, tableDependencyCandidates, hasMutationDependency) {
+  const exactPredicateTables = new Set(exactPredicates.map((predicate) => predicate.tableKey));
+  const nextDirectDependencies = [...directDependencies];
+  const tableDependencies = [];
+  for (const tableKey of tableDependencyCandidates) {
+    if (exactPredicateTables.has(tableKey)) {
+      tableDependencies.push(tableKey);
+      continue;
+    }
+    nextDirectDependencies.push(tableKey);
+  }
+  return Object.freeze({
+    directDependencies: Object.freeze(nextDirectDependencies),
+    exactPredicates: Object.freeze([...exactPredicates]),
+    hasMutationDependency,
+    predicates: Object.freeze([...predicates]),
+    tableDependencies: Object.freeze(tableDependencies)
+  });
+}
+function collectQueryPredicateObservations(predicates) {
+  const observations = [];
+  for (const predicate of predicates) {
+    if (predicate.kind === "comparison") {
+      observations.push(Object.freeze({
+        column: getColumnName(predicate.column),
+        operator: predicate.operator,
+        value: predicate.value
+      }));
+      continue;
+    }
+    if (predicate.kind === "group" && !predicate.negated && predicate.boolean !== "or") {
+      observations.push(...collectQueryPredicateObservations(predicate.predicates));
+    }
+  }
+  return Object.freeze(observations);
+}
+function collectQueryOrderObservations(plan) {
+  return Object.freeze(plan.orderBy.flatMap((order) => {
+    if (order.kind !== "column") {
+      return [];
+    }
+    return [Object.freeze({
+      column: getColumnName(order.column),
+      direction: order.direction
+    })];
+  }));
+}
+function collectQuerySelectionObservations(plan) {
+  return Object.freeze(plan.selections.flatMap((selection) => {
+    if (selection.kind !== "column") {
+      return [];
+    }
+    const column2 = getColumnName(selection.column);
+    return [Object.freeze({
+      column: column2,
+      resultKey: selection.alias ?? column2
+    })];
+  }));
+}
+function isPatchablePredicateObservation(predicate) {
+  if (predicate.kind === "comparison" && predicate.boolean !== "or") {
+    return true;
+  }
+  if (predicate.kind !== "group" || predicate.negated || predicate.boolean === "or") {
+    return false;
+  }
+  return predicate.predicates.every((child) => isPatchablePredicateObservation(child));
+}
+function isColumnSelection(selection) {
+  return selection.kind === "column";
+}
+function hasRequiredProjectionSelection(selections, column2) {
+  return selections.some((selection) => selection.column === column2 && selection.resultKey === column2);
+}
+function isExactPrimaryKeySingleResultProjection(plan) {
+  return plan.limit === 1 && typeof findExactPrimaryKeyValue(plan.predicates, getPrimaryKeyColumn(plan)) !== "undefined";
+}
+function isPatchableProjectionObservation(plan, selections, predicates, orderBy) {
+  if (plan.selections.length === 0) {
+    return true;
+  }
+  if (plan.selections.every((selection) => selection.kind === "aggregate")) {
+    return true;
+  }
+  if (!plan.selections.every((selection) => isColumnSelection(selection))) {
+    return false;
+  }
+  const needsProjectedPrimaryKey = !isExactPrimaryKeySingleResultProjection(plan);
+  const requiredColumns = /* @__PURE__ */ new Set([
+    ...orderBy.map((order) => order.column)
+  ]);
+  if (needsProjectedPrimaryKey) {
+    requiredColumns.add(getPrimaryKeyColumn(plan));
+  }
+  for (const column2 of requiredColumns) {
+    if (!hasRequiredProjectionSelection(selections, column2)) {
+      return false;
+    }
+  }
+  return true;
+}
+function isPatchableOffsetObservation(plan, orderBy) {
+  return typeof plan.offset === "undefined" || typeof plan.limit === "number" && plan.offset > 0 && orderBy.length > 0;
+}
+function findGroupedAggregateObservation(plan, averageStates, aggregateStates) {
+  if (plan.groupBy.length !== 1 || plan.selections.length !== 2) {
+    return void 0;
+  }
+  const groupColumn = getColumnName(plan.groupBy[0]);
+  const groupSelection = plan.selections.find((selection) => {
+    return selection.kind === "column" && getColumnName(selection.column) === groupColumn;
+  });
+  const aggregateSelection = plan.selections.find((selection) => {
+    return selection.kind === "aggregate" && (selection.aggregate === "count" && selection.column === "*" || selection.aggregate === "avg" && selection.column !== "*" || selection.aggregate === "sum" && selection.column !== "*" || selection.aggregate === "min" && selection.column !== "*" || selection.aggregate === "max" && selection.column !== "*");
+  });
+  if (!groupSelection || !aggregateSelection) {
+    return void 0;
+  }
+  const orderBy = collectQueryOrderObservations(plan);
+  if (orderBy.some((order) => order.column !== groupColumn)) {
+    return void 0;
+  }
+  const aggregateKind = aggregateSelection.aggregate === "count" ? "count" : aggregateSelection.aggregate;
+  const having = readGroupedCountHavingObservation(plan);
+  if (plan.having.length > 0 && !isSupportedGroupedCountHaving(plan)) {
+    return void 0;
+  }
+  const groupedAggregate = {
+    aggregateColumn: aggregateKind === "count" ? void 0 : getColumnName(aggregateSelection.column),
+    aggregateResultKey: aggregateSelection.alias,
+    ...(aggregateKind === "count" || aggregateKind === "sum" || aggregateKind === "min" || aggregateKind === "max") && aggregateStates ? { aggregateStates: Object.freeze([...aggregateStates]) } : {},
+    ...aggregateKind === "avg" && averageStates ? { averageStates: Object.freeze([...averageStates]) } : {},
+    groupColumn,
+    groupResultKey: groupSelection.alias ?? groupColumn,
+    having,
+    kind: aggregateKind
+  };
+  return Object.freeze(groupedAggregate);
+}
+function isSupportedGroupedCountHaving(plan) {
+  if (plan.having.length === 0) {
+    return true;
+  }
+  if (plan.groupBy.length === 0 || plan.having.length !== 1) {
+    return false;
+  }
+  const clause = plan.having[0];
+  return typeof clause !== "undefined" && clause.expression.replace(/\s+/g, "").toLowerCase() === "count(*)" && typeof clause.value === "number" && Number.isFinite(clause.value) && isGroupedCountHavingOperator(clause.operator);
+}
+function readGroupedCountHavingObservation(plan) {
+  if (!isSupportedGroupedCountHaving(plan) || hasOnlyRedundantGroupedCountHaving(plan)) {
+    return void 0;
+  }
+  const clause = plan.having[0];
+  if (!clause || !isGroupedCountHavingOperator(clause.operator) || typeof clause.value !== "number" || !Number.isFinite(clause.value)) {
+    return void 0;
+  }
+  return Object.freeze({
+    operator: clause.operator,
+    value: clause.value
+  });
+}
+function isGroupedCountHavingOperator(operator) {
+  return operator === "<" || operator === "<=" || operator === "=" || operator === ">" || operator === ">=";
+}
+function hasOnlyRedundantGroupedCountHaving(plan) {
+  if (plan.having.length === 0) {
+    return true;
+  }
+  if (plan.groupBy.length === 0 || plan.having.length !== 1) {
+    return false;
+  }
+  const clause = plan.having[0];
+  return typeof clause !== "undefined" && clause.expression.replace(/\s+/g, "").toLowerCase() === "count(*)" && clause.operator === ">=" && clause.value === 1;
+}
+function isPatchableGroupedAggregateObservation(plan) {
+  return supportsAutomaticQueryCacheInvalidation(plan) && Boolean(findGroupedAggregateObservation(plan)) && !plan.distinct && !plan.lockMode && !plan.source.alias && plan.joins.length === 0 && typeof plan.limit === "undefined" && typeof plan.offset === "undefined" && plan.unions.length === 0 && plan.orderBy.every((order) => order.kind === "column") && plan.predicates.every((predicate) => isPatchablePredicateObservation(predicate));
+}
+function isPatchableQueryObservation(plan) {
+  const predicates = collectQueryPredicateObservations(plan.predicates);
+  const orderBy = collectQueryOrderObservations(plan);
+  const selections = collectQuerySelectionObservations(plan);
+  return isPatchableGroupedAggregateObservation(plan) || supportsAutomaticQueryCacheInvalidation(plan) && !plan.distinct && !plan.lockMode && !plan.source.alias && plan.groupBy.length === 0 && plan.having.length === 0 && plan.joins.length === 0 && isPatchableOffsetObservation(plan, orderBy) && isPatchableProjectionObservation(plan, selections, predicates, orderBy) && plan.unions.length === 0 && plan.orderBy.every((order) => order.kind === "column") && plan.predicates.every((predicate) => isPatchablePredicateObservation(predicate));
+}
+function appendObservableQueryDependencies(plan, connectionName, dependencies, seen) {
+  if (seen.has(plan)) {
+    return;
+  }
+  seen.add(plan);
+  dependencies.add(createTableCacheDependency(connectionName, plan.source.tableName));
+  for (const join of plan.joins) {
+    if (join.table) {
+      dependencies.add(createTableCacheDependency(connectionName, join.table));
+    }
+    if (join.subquery) {
+      appendObservableQueryDependencies(join.subquery, connectionName, dependencies, seen);
+    }
+  }
+  for (const union of plan.unions) {
+    appendObservableQueryDependencies(union.query, connectionName, dependencies, seen);
+  }
+  for (const selection of plan.selections) {
+    if (selection.kind === "subquery") {
+      appendObservableQueryDependencies(selection.query, connectionName, dependencies, seen);
+    }
+  }
+  for (const predicate of plan.predicates) {
+    appendObservablePredicateDependencies(predicate, connectionName, dependencies, seen);
+  }
+}
+function appendObservablePredicateDependencies(predicate, connectionName, dependencies, seen) {
+  if (predicate.kind === "group") {
+    for (const child of predicate.predicates) {
+      appendObservablePredicateDependencies(child, connectionName, dependencies, seen);
+    }
+    return;
+  }
+  if (predicate.kind === "exists" || predicate.kind === "subquery") {
+    appendObservableQueryDependencies(predicate.subquery, connectionName, dependencies, seen);
+  }
+}
+function hasObservationDependencyFallbackPredicate(predicate) {
+  if (predicate.kind === "group") {
+    return predicate.predicates.some((child) => hasObservationDependencyFallbackPredicate(child));
+  }
+  return predicate.kind === "exists" || predicate.kind === "subquery" || predicate.kind === "raw" || predicate.kind === "vector" || predicate.kind === "fulltext";
+}
+function hasObservationDependencyFallbackShape(plan) {
+  return plan.joins.length > 0 || plan.unions.length > 0 || !isSupportedGroupedCountHaving(plan) || plan.selections.some((selection) => selection.kind === "raw" || selection.kind === "subquery") || plan.orderBy.some((order) => order.kind === "raw") || plan.predicates.some((predicate) => hasObservationDependencyFallbackPredicate(predicate));
+}
+function inferDatabaseQueryObservationDependencies(plan, connectionName) {
+  if (!hasObservationDependencyFallbackShape(plan)) {
+    return void 0;
+  }
+  const dependencies = /* @__PURE__ */ new Set();
+  appendObservableQueryDependencies(plan, connectionName, dependencies, /* @__PURE__ */ new Set());
+  return Object.freeze([...dependencies]);
+}
+function createDatabaseQueryObservationFromPlan(plan, connectionName, dependencies, result, patchable = isPatchableQueryObservation(plan), groupedAverageStates, groupedAggregateStates) {
+  return Object.freeze({
+    connectionName,
+    belongsToHydrations: void 0,
+    relatedHydrations: void 0,
+    tableName: plan.source.tableName,
+    dependencies: Object.freeze([...dependencies]),
+    groupedAggregate: findGroupedAggregateObservation(plan, groupedAverageStates, groupedAggregateStates),
+    limit: plan.limit,
+    offset: plan.offset,
+    orderBy: collectQueryOrderObservations(plan),
+    patchable,
+    pagination: void 0,
+    predicates: collectQueryPredicateObservations(plan.predicates),
+    result,
+    selections: collectQuerySelectionObservations(plan)
+  });
+}
+function createDatabaseQueryObservation(plan, connectionName, dependencies, result, groupedAverageStates, groupedAggregateStates) {
+  if (!supportsAutomaticQueryCacheInvalidation(plan)) {
+    return void 0;
+  }
+  return createDatabaseQueryObservationFromPlan(
+    plan,
+    connectionName,
+    dependencies,
+    result,
+    void 0,
+    groupedAverageStates,
+    groupedAggregateStates
+  );
+}
+function createDatabaseQueryFallbackObservation(plan, connectionName, dependencies, result) {
+  if (dependencies.length === 0) {
+    return void 0;
+  }
+  return createDatabaseQueryObservationFromPlan(plan, connectionName, dependencies, result, false);
+}
+function createDatabaseMutationEvent(kind, connectionName, tableName, predicates = [], values, rows, previousRows) {
+  return Object.freeze({
+    connectionName,
+    tableName,
+    kind,
+    predicates: collectQueryPredicateObservations(predicates),
+    previousRows: previousRows ? Object.freeze([...previousRows]) : void 0,
+    rows: rows ? Object.freeze([...rows]) : void 0,
+    values
+  });
+}
 function supportsAutomaticQueryCacheInvalidation(plan) {
-  if (plan.joins.length > 0 || plan.unions.length > 0 || plan.having.length > 0) {
+  if (plan.joins.length > 0 || plan.unions.length > 0 || !isSupportedGroupedCountHaving(plan)) {
     return false;
   }
   if (plan.selections.some((selection) => selection.kind === "raw" || selection.kind === "subquery")) {
@@ -341,18 +1090,48 @@ function inferAutomaticQueryCacheDependencies(plan, connectionName) {
       ]);
     }
   }
+  if (!hasDisjunctivePredicate(plan.predicates)) {
+    const predicateDependencies = collectExactPredicateDependencies(
+      plan.predicates,
+      connectionName,
+      plan.source.tableName
+    );
+    if (predicateDependencies.length > 0) {
+      return Object.freeze([
+        createTableCacheDependency(connectionName, plan.source.tableName),
+        ...predicateDependencies
+      ]);
+    }
+  }
   return Object.freeze([
     createTableCacheDependency(connectionName, plan.source.tableName)
   ]);
 }
-function inferAutomaticQueryCacheInvalidationDependencies(plan, connectionName) {
-  const dependencies = [
-    createTableCacheDependency(connectionName, plan.source.tableName)
-  ];
+function inferAutomaticQueryCacheInvalidationDependencies(plan, connectionName, values = {}) {
+  return inferAutomaticQueryCacheInvalidationPlan(plan, connectionName, values).dependencies;
+}
+function inferAutomaticQueryCacheInvalidationPlan(plan, connectionName, values = {}, includeMetadata = false) {
+  const tableKey = createTableCacheDependency(connectionName, plan.source.tableName);
+  const dependencies = [tableKey];
   if (hasDisjunctivePredicate(plan.predicates)) {
     dependencies.push(createTableRowWildcardCacheDependency(connectionName, plan.source.tableName));
-    return Object.freeze(dependencies);
+    return Object.freeze({
+      dependencies: Object.freeze(dependencies),
+      metadata: includeMetadata ? createInvalidationMetadataFromParts(
+        dependencies,
+        Object.freeze([]),
+        Object.freeze([]),
+        Object.freeze([]),
+        false
+      ) : void 0
+    });
   }
+  const directDependencies = [];
+  const exactPredicates = [];
+  const predicates = [];
+  const mutationDependency = createTableMutationCacheDependency(connectionName, plan.source.tableName);
+  dependencies.push(mutationDependency);
+  directDependencies.push(mutationDependency);
   const primaryKeyColumn = getPrimaryKeyColumn(plan);
   const primaryKeyValue = findExactPrimaryKeyValue(plan.predicates, primaryKeyColumn);
   const primaryKeyDependency = createTableRowCacheDependency(
@@ -361,27 +1140,118 @@ function inferAutomaticQueryCacheInvalidationDependencies(plan, connectionName)
     primaryKeyColumn,
     primaryKeyValue
   );
-  dependencies.push(primaryKeyDependency ?? createTableRowWildcardCacheDependency(connectionName, plan.source.tableName));
-  return Object.freeze(dependencies);
+  const rowDependency = primaryKeyDependency ?? createTableRowWildcardCacheDependency(connectionName, plan.source.tableName);
+  dependencies.push(rowDependency);
+  directDependencies.push(rowDependency);
+  if (includeMetadata) {
+    const predicateEntries = /* @__PURE__ */ new Map();
+    appendExactPredicateDependencyEntries(predicateEntries, plan.predicates, connectionName, plan.source.tableName);
+    for (const entry of predicateEntries.values()) {
+      dependencies.push(entry.dependency);
+      directDependencies.push(entry.dependency);
+      predicates.push(entry.metadata);
+    }
+    const exactPredicateEntries = /* @__PURE__ */ new Map();
+    appendExactPredicateDependencyEntries(exactPredicateEntries, plan.predicates, connectionName, plan.source.tableName, true);
+    for (const entry of exactPredicateEntries.values()) {
+      dependencies.push(entry.dependency);
+      directDependencies.push(entry.dependency);
+      exactPredicates.push(entry.metadata);
+    }
+    const recordPredicateEntries = /* @__PURE__ */ new Map();
+    appendRecordPredicateDependencyEntries(recordPredicateEntries, connectionName, plan.source.tableName, values);
+    for (const entry of recordPredicateEntries.values()) {
+      dependencies.push(entry.dependency);
+      directDependencies.push(entry.dependency);
+      predicates.push(entry.metadata);
+    }
+    const exactRecordPredicateEntries = /* @__PURE__ */ new Map();
+    appendRecordPredicateDependencyEntries(exactRecordPredicateEntries, connectionName, plan.source.tableName, values, true);
+    for (const entry of exactRecordPredicateEntries.values()) {
+      dependencies.push(entry.dependency);
+      directDependencies.push(entry.dependency);
+      exactPredicates.push(entry.metadata);
+    }
+    return Object.freeze({
+      dependencies: Object.freeze(dependencies),
+      metadata: createInvalidationMetadataFromParts(
+        directDependencies,
+        exactPredicates,
+        predicates,
+        Object.freeze([tableKey]),
+        true
+      )
+    });
+  }
+  dependencies.push(...collectExactPredicateDependencies(plan.predicates, connectionName, plan.source.tableName));
+  dependencies.push(...collectExactPredicateDependencies(plan.predicates, connectionName, plan.source.tableName, true));
+  dependencies.push(...collectRecordPredicateDependencies(connectionName, plan.source.tableName, values));
+  dependencies.push(...collectRecordPredicateDependencies(connectionName, plan.source.tableName, values, true));
+  return Object.freeze({
+    dependencies: Object.freeze(dependencies)
+  });
 }
 function inferAutomaticInsertCacheInvalidationDependencies(connectionName, tableName, rows, lastInsertId) {
+  return inferAutomaticInsertCacheInvalidationPlan(connectionName, tableName, rows, lastInsertId).dependencies;
+}
+function inferAutomaticInsertCacheInvalidationPlan(connectionName, tableName, rows, lastInsertId, includeMetadata = false) {
+  const tableKey = createTableCacheDependency(connectionName, tableName);
   const dependencies = /* @__PURE__ */ new Set([
-    createTableCacheDependency(connectionName, tableName)
+    tableKey
   ]);
+  const directDependencies = /* @__PURE__ */ new Set();
+  const exactPredicates = /* @__PURE__ */ new Map();
+  const predicates = /* @__PURE__ */ new Map();
   for (const row of rows) {
     const dependency = createTableRowCacheDependency(connectionName, tableName, "id", row.id);
     if (dependency) {
       dependencies.add(dependency);
+      directDependencies.add(dependency);
+    }
+    if (includeMetadata) {
+      const rowPredicateEntries = /* @__PURE__ */ new Map();
+      appendRecordPredicateDependencyEntries(rowPredicateEntries, connectionName, tableName, row);
+      for (const entry of rowPredicateEntries.values()) {
+        dependencies.add(entry.dependency);
+        directDependencies.add(entry.dependency);
+        predicates.set(entry.dependency, entry);
+      }
+      const rowExactPredicateEntries = /* @__PURE__ */ new Map();
+      appendRecordPredicateDependencyEntries(rowExactPredicateEntries, connectionName, tableName, row, true);
+      for (const entry of rowExactPredicateEntries.values()) {
+        dependencies.add(entry.dependency);
+        directDependencies.add(entry.dependency);
+        exactPredicates.set(entry.dependency, entry);
+      }
+      continue;
+    }
+    for (const dependency2 of collectRecordPredicateDependencies(connectionName, tableName, row)) {
+      dependencies.add(dependency2);
+    }
+    for (const dependency2 of collectRecordPredicateDependencies(connectionName, tableName, row, true)) {
+      dependencies.add(dependency2);
     }
   }
   const lastInsertDependency = createTableRowCacheDependency(connectionName, tableName, "id", lastInsertId);
   if (lastInsertDependency) {
     dependencies.add(lastInsertDependency);
+    directDependencies.add(lastInsertDependency);
   }
   if (dependencies.size === 1) {
-    dependencies.add(createTableRowWildcardCacheDependency(connectionName, tableName));
+    const rowWildcardDependency = createTableRowWildcardCacheDependency(connectionName, tableName);
+    dependencies.add(rowWildcardDependency);
+    directDependencies.add(rowWildcardDependency);
   }
-  return Object.freeze([...dependencies]);
+  return Object.freeze({
+    dependencies: Object.freeze([...dependencies]),
+    metadata: includeMetadata ? createInvalidationMetadataFromParts(
+      [...directDependencies],
+      [...exactPredicates.values()].map((entry) => entry.metadata),
+      [...predicates.values()].map((entry) => entry.metadata),
+      Object.freeze([tableKey]),
+      false
+    ) : void 0
+  });
 }
 function resolveQueryCacheDependencies(plan, connectionName, explicit) {
   if (explicit && explicit.length > 0) {
@@ -389,17 +1259,18 @@ function resolveQueryCacheDependencies(plan, connectionName, explicit) {
   }
   return inferAutomaticQueryCacheDependencies(plan, connectionName);
 }
-async function invalidateQueryCacheDependencies(connection, dependencies) {
+async function invalidateQueryCacheDependencies(connection, dependencies, mutations = [], plan) {
   if (dependencies.length === 0) {
     return;
   }
   const invalidate = async () => {
     const bridge = getDatabaseQueryCacheBridge();
     await bridge?.invalidateDependencies(dependencies);
-    await notifyDatabaseDependencyInvalidationListeners({
-      connectionName: connection.getConnectionName(),
-      dependencies
-    });
+    if (hasDatabaseDependencyInvalidationListeners()) {
+      await notifyDatabaseDependencyInvalidationListeners(
+        createDatabaseDependencyInvalidationEvent(connection.getConnectionName(), dependencies, mutations, plan?.metadata)
+      );
+    }
   };
   if (connection.getScope().kind === "root") {
     await invalidate();
@@ -408,9 +1279,12 @@ async function invalidateQueryCacheDependencies(connection, dependencies) {
   connection.afterCommit(invalidate);
 }
 var queryCacheInternals = {
-  collectDatabaseQueryDependencies,
+  collectDatabaseQueryDependencies: collectDatabaseQueryDependenciesInternal,
   configureDatabaseQueryCacheBridge,
+  createDatabaseMutationEvent,
+  createDatabaseQueryObservation,
   createDeterministicQueryCacheKey,
+  createTablePredicateCacheDependency,
   createTableCacheDependency,
   createTableRowCacheDependency,
   createTableRowWildcardCacheDependency,
@@ -418,13 +1292,20 @@ var queryCacheInternals = {
   hasActiveDatabaseDependencyCollector,
   hasDatabaseDependencyInvalidationListeners,
   inferAutomaticInsertCacheInvalidationDependencies,
+  inferAutomaticInsertCacheInvalidationPlan,
   inferAutomaticQueryCacheDependencies,
   inferAutomaticQueryCacheInvalidationDependencies,
+  inferAutomaticQueryCacheInvalidationPlan,
   normalizeQueryCacheConfig,
   normalizeQueryCacheDependencies,
   notifyDatabaseDependencyInvalidationListeners,
+  disableDatabaseQueryObservationPatching,
+  rebindDatabaseQueryObservationResult,
+  rebindDatabaseQueryObservationScalar,
+  rebindDatabaseQueryObservationScalarList,
   onDatabaseDependencyInvalidated,
   recordDatabaseQueryDependencies,
+  recordDatabaseQueryObservation,
   resolveQueryCacheDependencies,
   resolveQueryCacheKey,
   resetDatabaseDependencyInvalidationListeners,
@@ -800,34 +1681,47 @@ function createInsertQueryPlan(source, values, options = {}) {
     kind: "insert",
     source,
     ignoreConflicts: options.ignoreConflicts ?? false,
+    returning: options.returning === true,
     values: Object.freeze(values.map((value) => Object.freeze({ ...value })))
   });
 }
-function createUpsertQueryPlan(source, values, uniqueBy, updateColumns) {
+function createUpsertQueryPlan(source, values, uniqueBy, updateColumns, options = {}) {
   return Object.freeze({
     kind: "upsert",
     source,
+    returning: options.returning === true,
     values: Object.freeze(values.map((value) => Object.freeze({ ...value }))),
     uniqueBy: Object.freeze([...uniqueBy]),
     updateColumns: Object.freeze([...updateColumns])
   });
 }
-function createUpdateQueryPlan(source, predicates, values) {
+function createUpdateQueryPlan(source, predicates, values, options = {}) {
   return Object.freeze({
     kind: "update",
     source,
     predicates: Object.freeze([...predicates]),
+    returning: options.returning === true,
     values: Object.freeze({ ...values })
   });
 }
-function createDeleteQueryPlan(source, predicates) {
+function createDeleteQueryPlan(source, predicates, options = {}) {
   return Object.freeze({
     kind: "delete",
     source,
-    predicates: Object.freeze([...predicates])
+    predicates: Object.freeze([...predicates]),
+    returning: options.returning === true
   });
 }
 
+// src/query/aggregateValueCounts.ts
+function createAggregateValueCounts(values) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const value of values) {
+    counts.set(value, (counts.get(value) ?? 0) + 1);
+  }
+  return Object.freeze([...counts.entries()].sort(([left], [right]) => left - right).map(([value, count]) => Object.freeze({ count, value })));
+}
+
 // src/query/validator.ts
 var IDENTIFIER_PATTERN = /^[A-Z_]\w*$/i;
 var OPERATORS = /* @__PURE__ */ new Set([
@@ -1464,8 +2358,9 @@ var SQLQueryCompiler = class {
       return `${this.quoteIdentifier(column2)} = ${this.compileUpdateValue(column2, plan.values[column2], bindings)}`;
     }).join(", ");
     const whereClause = this.compilePredicates(plan.predicates, bindings);
+    const returningClause = this.compileReturningClause(plan.returning === true);
     return this.withMetadata({
-      sql: `UPDATE ${this.quoteIdentifier(plan.source.tableName)} SET ${assignments}${whereClause}`,
+      sql: `UPDATE ${this.quoteIdentifier(plan.source.tableName)} SET ${assignments}${whereClause}${returningClause}`,
       bindings,
       source: `query:update:${plan.source.tableName}`
     }, this.createWriteMetadata("update", plan.source.tableName, this.calculatePlanComplexity(plan)));
@@ -1473,8 +2368,9 @@ var SQLQueryCompiler = class {
   compileDelete(plan) {
     const bindings = [];
     const whereClause = this.compilePredicates(plan.predicates, bindings);
+    const returningClause = this.compileReturningClause(plan.returning === true);
     return this.withMetadata({
-      sql: `DELETE FROM ${this.quoteIdentifier(plan.source.tableName)}${whereClause}`,
+      sql: `DELETE FROM ${this.quoteIdentifier(plan.source.tableName)}${whereClause}${returningClause}`,
       bindings,
       source: `query:delete:${plan.source.tableName}`
     }, this.createWriteMetadata("delete", plan.source.tableName, this.calculatePlanComplexity(plan)));
@@ -1751,15 +2647,19 @@ var SQLQueryCompiler = class {
     return "INSERT INTO";
   }
   compileInsertSuffix(_plan) {
-    return "";
+    return _plan.returning === true ? " RETURNING *" : "";
   }
   compileUpsertSuffix(plan, _insertColumns) {
     const conflictColumns = plan.uniqueBy.map((column2) => this.quoteIdentifier(column2)).join(", ");
+    const returning = plan.returning === true ? " RETURNING *" : "";
     if (plan.updateColumns.length === 0) {
-      return ` ON CONFLICT (${conflictColumns}) DO NOTHING`;
+      return ` ON CONFLICT (${conflictColumns}) DO NOTHING${returning}`;
     }
     const updates = plan.updateColumns.map((column2) => `${this.quoteIdentifier(column2)} = EXCLUDED.${this.quoteIdentifier(column2)}`).join(", ");
-    return ` ON CONFLICT (${conflictColumns}) DO UPDATE SET ${updates}`;
+    return ` ON CONFLICT (${conflictColumns}) DO UPDATE SET ${updates}${returning}`;
+  }
+  compileReturningClause(returning) {
+    return returning ? " RETURNING *" : "";
   }
   compileHavingExpression(expression) {
     const aggregateMatch = expression.match(/^(count|sum|avg|min|max)\((\*|[A-Z_]\w*)\)$/i);
@@ -1941,12 +2841,18 @@ var PostgresQueryCompiler = class extends SQLQueryCompiler {
     return lockMode === "update" ? "FOR UPDATE" : "FOR SHARE";
   }
   compileInsertSuffix(plan) {
+    if (plan.returning === true) {
+      return `${plan.ignoreConflicts ? " ON CONFLICT DO NOTHING" : ""} RETURNING *`;
+    }
     const primaryKey = Object.values(plan.source.table?.columns ?? {}).find((column2) => column2.primaryKey)?.name;
     const returning = primaryKey ? ` RETURNING ${this.quoteIdentifier(primaryKey)}` : "";
     return `${plan.ignoreConflicts ? " ON CONFLICT DO NOTHING" : ""}${returning}`;
   }
   compileUpsertSuffix(plan, insertColumns) {
     const suffix = super.compileUpsertSuffix(plan, insertColumns);
+    if (plan.returning === true) {
+      return suffix;
+    }
     const primaryKey = Object.values(plan.source.table?.columns ?? {}).find((column2) => column2.primaryKey)?.name;
     return primaryKey ? `${suffix} RETURNING ${this.quoteIdentifier(primaryKey)}` : suffix;
   }
@@ -2224,6 +3130,15 @@ function normalizeDialectWriteValue(dialect, column2, value) {
 }
 
 // src/query/TableQueryBuilder.ts
+var GROUPED_AVERAGE_COUNT_KEY = "__holo_grouped_average_count";
+var GROUPED_AVERAGE_ROW_COUNT_KEY = "__holo_grouped_average_row_count";
+var GROUPED_AVERAGE_SUM_KEY = "__holo_grouped_average_sum";
+var GROUPED_AVERAGE_GROUP_KEY = "__holo_grouped_average_group";
+var GROUPED_AGGREGATE_VALUE_KEY = "__holo_grouped_aggregate_state_value";
+var GROUPED_AGGREGATE_ROW_COUNT_KEY = "__holo_grouped_aggregate_state_row_count";
+var GROUPED_AGGREGATE_GROUP_KEY = "__holo_grouped_aggregate_state_group";
+var GROUPED_AGGREGATE_VALUE_COUNT_VALUE_KEY = "__holo_grouped_aggregate_state_count_value";
+var GROUPED_AGGREGATE_VALUE_COUNT_KEY = "__holo_grouped_aggregate_state_value_count";
 function normalizeAtomicQueryCacheTtl(ttl) {
   if (ttl instanceof Date) {
     const expiresAt = ttl.getTime();
@@ -2921,14 +3836,23 @@ var TableQueryBuilder = class _TableQueryBuilder {
   async get() {
     const statement = this.toSQL();
     const cacheConfig = this.queryCacheConfig;
-    const dependencies = this.plan.lockMode || !cacheConfig && !hasActiveDatabaseDependencyCollector() ? void 0 : resolveQueryCacheDependencies(
+    const activeDependencyCollector = hasActiveDatabaseDependencyCollector();
+    const dependencies = this.plan.lockMode || !cacheConfig && !activeDependencyCollector ? void 0 : resolveQueryCacheDependencies(
       this.plan,
       this.connection.getConnectionName(),
       cacheConfig?.invalidate
     );
-    recordDatabaseQueryDependencies(dependencies);
+    const observationDependencies = activeDependencyCollector && !this.plan.lockMode ? dependencies ?? inferDatabaseQueryObservationDependencies(this.plan, this.connection.getConnectionName()) : dependencies;
+    const createObservation = dependencies ? createDatabaseQueryObservation : createDatabaseQueryFallbackObservation;
+    recordDatabaseQueryDependencies(observationDependencies);
     if (!cacheConfig || this.plan.lockMode) {
       const result = await this.connection.queryCompiled(statement);
+      await this.recordCollectedQueryObservation(
+        activeDependencyCollector,
+        observationDependencies,
+        createObservation,
+        result.rows
+      );
       return result.rows;
     }
     const bridge = getDatabaseQueryCacheBridge();
@@ -2937,7 +3861,7 @@ var TableQueryBuilder = class _TableQueryBuilder {
     }
     const cacheKey = resolveQueryCacheKey(statement, this.connection.getConnectionName(), cacheConfig);
     if (cacheConfig.flexible) {
-      return bridge.flexible(
+      const rows2 = await bridge.flexible(
         cacheKey,
         cacheConfig.flexible,
         async () => {
@@ -2949,11 +3873,18 @@ var TableQueryBuilder = class _TableQueryBuilder {
           dependencies
         }
       );
+      await this.recordCollectedQueryObservation(
+        activeDependencyCollector,
+        observationDependencies,
+        createObservation,
+        rows2
+      );
+      return rows2;
     }
     if (typeof cacheConfig.ttl === "undefined") {
       throw new ConfigurationError('[@holo-js/db] Query cache config requires "ttl" or "flexible".');
     }
-    return bridge.flexible(
+    const rows = await bridge.flexible(
       cacheKey,
       normalizeAtomicQueryCacheTtl(cacheConfig.ttl),
       async () => {
@@ -2965,17 +3896,227 @@ var TableQueryBuilder = class _TableQueryBuilder {
         dependencies
       }
     );
+    await this.recordCollectedQueryObservation(
+      activeDependencyCollector,
+      observationDependencies,
+      createObservation,
+      rows
+    );
+    return rows;
+  }
+  async recordCollectedQueryObservation(activeDependencyCollector, observationDependencies, createObservation, rows) {
+    if (!activeDependencyCollector || !observationDependencies) {
+      return;
+    }
+    const observation = createObservation(
+      this.plan,
+      this.connection.getConnectionName(),
+      observationDependencies,
+      rows
+    );
+    const groupedAggregate = observation?.groupedAggregate;
+    if (!observation?.patchable || !groupedAggregate) {
+      recordDatabaseQueryObservation(observation);
+      return;
+    }
+    const averageStates = groupedAggregate.kind === "avg" && groupedAggregate.aggregateColumn ? await this.readGroupedAverageStates(groupedAggregate) : void 0;
+    const aggregateStates = (groupedAggregate.kind === "count" || groupedAggregate.kind === "sum" || groupedAggregate.kind === "min" || groupedAggregate.kind === "max") && groupedAggregate.having ? await this.readGroupedAggregateStates(groupedAggregate) : void 0;
+    recordDatabaseQueryObservation(averageStates || aggregateStates ? createObservation(
+      this.plan,
+      this.connection.getConnectionName(),
+      observationDependencies,
+      rows,
+      averageStates,
+      aggregateStates
+    ) : observation);
+  }
+  async readGroupedAverageStates(groupedAggregate) {
+    const aggregateColumn = groupedAggregate.aggregateColumn;
+    if (!aggregateColumn) {
+      return void 0;
+    }
+    const selections = [
+      Object.freeze({
+        alias: GROUPED_AVERAGE_GROUP_KEY,
+        column: groupedAggregate.groupColumn,
+        kind: "column"
+      }),
+      this.createAggregateSelection("count", GROUPED_AVERAGE_COUNT_KEY, aggregateColumn),
+      this.createAggregateSelection("count", GROUPED_AVERAGE_ROW_COUNT_KEY, "*"),
+      this.createAggregateSelection("sum", GROUPED_AVERAGE_SUM_KEY, aggregateColumn)
+    ];
+    const metadataPlan = Object.freeze({
+      ...this.plan,
+      having: Object.freeze([]),
+      selections: Object.freeze(selections)
+    });
+    const result = await this.connection.queryCompiled(this.getCompiler().compile(metadataPlan));
+    const states = [];
+    for (const row of result.rows) {
+      const count = this.normalizeAggregateMetadataNumber(row[GROUPED_AVERAGE_COUNT_KEY]);
+      const rowCount = this.normalizeAggregateMetadataNumber(row[GROUPED_AVERAGE_ROW_COUNT_KEY]);
+      const sum = this.normalizeAggregateMetadataNumber(row[GROUPED_AVERAGE_SUM_KEY] ?? 0);
+      if (typeof count === "undefined" || typeof rowCount === "undefined" || typeof sum === "undefined" || count < 0 || rowCount < 0) {
+        return void 0;
+      }
+      states.push(Object.freeze({
+        count,
+        groupValue: row[GROUPED_AVERAGE_GROUP_KEY],
+        rowCount,
+        sum
+      }));
+    }
+    return Object.freeze(states);
+  }
+  async readGroupedAggregateStates(groupedAggregate) {
+    const aggregateSelection = this.createGroupedAggregateStateValueSelection(groupedAggregate);
+    if (!aggregateSelection) {
+      return void 0;
+    }
+    const valueCounts = await this.readGroupedAggregateValueCounts(groupedAggregate);
+    const selections = [
+      Object.freeze({
+        alias: GROUPED_AGGREGATE_GROUP_KEY,
+        column: groupedAggregate.groupColumn,
+        kind: "column"
+      }),
+      aggregateSelection,
+      this.createAggregateSelection("count", GROUPED_AGGREGATE_ROW_COUNT_KEY, "*")
+    ];
+    const metadataPlan = Object.freeze({
+      ...this.plan,
+      having: Object.freeze([]),
+      selections: Object.freeze(selections)
+    });
+    const result = await this.connection.queryCompiled(this.getCompiler().compile(metadataPlan));
+    const states = [];
+    for (const row of result.rows) {
+      const aggregateValue = this.normalizeGroupedAggregateStateValue(
+        groupedAggregate,
+        row[GROUPED_AGGREGATE_VALUE_KEY]
+      );
+      const rowCount = this.normalizeAggregateMetadataNumber(row[GROUPED_AGGREGATE_ROW_COUNT_KEY]);
+      if (typeof aggregateValue === "undefined" || typeof rowCount === "undefined" || rowCount < 0) {
+        return void 0;
+      }
+      states.push(Object.freeze({
+        aggregateValue,
+        groupValue: row[GROUPED_AGGREGATE_GROUP_KEY],
+        rowCount,
+        ...valueCounts ? { valueCounts: this.readGroupedAggregateValueCountsForGroup(valueCounts, row[GROUPED_AGGREGATE_GROUP_KEY]) } : {}
+      }));
+    }
+    return Object.freeze(states);
+  }
+  async readGroupedAggregateValueCounts(groupedAggregate) {
+    if (groupedAggregate.kind !== "min" && groupedAggregate.kind !== "max") {
+      return void 0;
+    }
+    const aggregateColumn = groupedAggregate.aggregateColumn;
+    if (!aggregateColumn) {
+      return void 0;
+    }
+    const metadataPlan = Object.freeze({
+      ...this.plan,
+      groupBy: Object.freeze([groupedAggregate.groupColumn, aggregateColumn]),
+      having: Object.freeze([]),
+      selections: Object.freeze([
+        Object.freeze({
+          alias: GROUPED_AGGREGATE_GROUP_KEY,
+          column: groupedAggregate.groupColumn,
+          kind: "column"
+        }),
+        Object.freeze({
+          alias: GROUPED_AGGREGATE_VALUE_COUNT_VALUE_KEY,
+          column: aggregateColumn,
+          kind: "column"
+        }),
+        this.createAggregateSelection("count", GROUPED_AGGREGATE_VALUE_COUNT_KEY, "*")
+      ])
+    });
+    const result = await this.connection.queryCompiled(this.getCompiler().compile(metadataPlan));
+    const groups = [];
+    for (const row of result.rows) {
+      const groupValue = row[GROUPED_AGGREGATE_GROUP_KEY];
+      const value = this.normalizeGroupedAggregateStateValue(
+        groupedAggregate,
+        row[GROUPED_AGGREGATE_VALUE_COUNT_VALUE_KEY]
+      );
+      const count = this.normalizeAggregateMetadataNumber(row[GROUPED_AGGREGATE_VALUE_COUNT_KEY]);
+      if (typeof value === "undefined" || typeof count === "undefined" || count <= 0) {
+        return void 0;
+      }
+      this.pushGroupedAggregateValueCount(groups, groupValue, Object.freeze({ count, value }));
+    }
+    return Object.freeze(groups.map((group) => Object.freeze({
+      groupValue: group.groupValue,
+      valueCounts: [...group.valueCounts].sort((left, right) => left.value - right.value)
+    })));
+  }
+  pushGroupedAggregateValueCount(groups, groupValue, valueCount) {
+    const group = groups.find((candidate) => Object.is(candidate.groupValue, groupValue));
+    if (group) {
+      group.valueCounts.push(valueCount);
+      return;
+    }
+    groups.push({
+      groupValue,
+      valueCounts: [valueCount]
+    });
+  }
+  readGroupedAggregateValueCountsForGroup(groups, groupValue) {
+    return groups.find((group) => Object.is(group.groupValue, groupValue))?.valueCounts ?? Object.freeze([]);
+  }
+  createGroupedAggregateStateValueSelection(groupedAggregate) {
+    if (groupedAggregate.kind === "count") {
+      return this.createAggregateSelection("count", GROUPED_AGGREGATE_VALUE_KEY, "*");
+    }
+    if ((groupedAggregate.kind === "sum" || groupedAggregate.kind === "min" || groupedAggregate.kind === "max") && groupedAggregate.aggregateColumn) {
+      return this.createAggregateSelection(
+        groupedAggregate.kind,
+        GROUPED_AGGREGATE_VALUE_KEY,
+        groupedAggregate.aggregateColumn
+      );
+    }
+    return void 0;
+  }
+  normalizeGroupedAggregateStateValue(groupedAggregate, value) {
+    if ((groupedAggregate.kind === "min" || groupedAggregate.kind === "max") && value === null) {
+      return void 0;
+    }
+    return this.normalizeAggregateMetadataNumber(value);
+  }
+  normalizeAggregateMetadataNumber(value) {
+    if (value === null) {
+      return 0;
+    }
+    if (typeof value === "number") {
+      return Number.isFinite(value) ? value : void 0;
+    }
+    if (typeof value === "bigint") {
+      const numericValue = Number(value);
+      return Number.isSafeInteger(numericValue) ? numericValue : void 0;
+    }
+    if (typeof value === "string" && value.trim()) {
+      const numericValue = Number(value);
+      return Number.isFinite(numericValue) ? numericValue : void 0;
+    }
+    return void 0;
   }
   async first() {
     const rows = await this.limit(1).get();
-    return rows[0];
+    const row = rows[0];
+    rebindDatabaseQueryObservationResult(rows, row);
+    return row;
   }
   async sole() {
     const rows = await this.limit(2).get();
     if (rows.length !== 1) {
       throw new CompilerError(`Query expected exactly one row but found ${rows.length}.`);
     }
-    return rows[0];
+    const row = rows[0];
+    rebindDatabaseQueryObservationResult(rows, row);
+    return row;
   }
   async paginate(perPage = 15, page = 1, options = {}) {
     assertPositiveInteger(perPage, "Per-page value", (message) => new SecurityError(message));
@@ -2987,7 +4128,7 @@ var TableQueryBuilder = class _TableQueryBuilder {
     const data = rows.slice(offset, offset + perPage);
     const from = data.length === 0 ? null : offset + 1;
     const to = data.length === 0 ? null : offset + data.length;
-    return createPaginator(data, {
+    const result = createPaginator(data, {
       total,
       perPage,
       pageName,
@@ -2997,6 +4138,14 @@ var TableQueryBuilder = class _TableQueryBuilder {
       to,
       hasMorePages: offset + data.length < total
     });
+    rebindDatabaseQueryObservationPagination(rows, result.data, result.meta, Object.freeze({
+      currentPage: page,
+      kind: "standard",
+      pageName,
+      perPage,
+      total
+    }), offset);
+    return result;
   }
   async simplePaginate(perPage = 15, page = 1, options = {}) {
     assertPositiveInteger(perPage, "Per-page value", (message) => new SecurityError(message));
@@ -3009,7 +4158,7 @@ var TableQueryBuilder = class _TableQueryBuilder {
     const data = hasMorePages ? pageRows.slice(0, perPage) : pageRows;
     const from = data.length === 0 ? null : offset + 1;
     const to = data.length === 0 ? null : offset + data.length;
-    return createSimplePaginator(data, {
+    const result = createSimplePaginator(data, {
       perPage,
       pageName,
       currentPage: page,
@@ -3017,6 +4166,15 @@ var TableQueryBuilder = class _TableQueryBuilder {
       to,
       hasMorePages
     });
+    rebindDatabaseQueryObservationPagination(rows, result.data, result.meta, Object.freeze({
+      currentPage: page,
+      hasMorePages,
+      kind: "simple",
+      pageName,
+      perPage,
+      rowCount: rows.length
+    }), offset);
+    return result;
   }
   async cursorPaginate(perPage = 15, cursor = null, options = {}) {
     assertPositiveInteger(perPage, "Per-page value", (message) => new SecurityError(message));
@@ -3034,12 +4192,32 @@ var TableQueryBuilder = class _TableQueryBuilder {
     const hasMorePages = pageRows.length > perPage;
     const data = hasMorePages ? pageRows.slice(0, perPage) : pageRows;
     const lastRow = data.at(-1);
-    return createCursorPaginator(data, {
+    const result = createCursorPaginator(data, {
       perPage,
       cursorName,
       nextCursor: hasMorePages && lastRow ? encodeValueCursor(cursorOrders.map((order) => orderedQuery.readCursorColumnValue(lastRow, order.column))) : null,
       prevCursor: cursor
     });
+    if (cursor === null) {
+      rebindDatabaseQueryObservationCursorPagination(rows, result.data, {
+        cursorName: result.cursorName,
+        nextCursor: result.nextCursor,
+        perPage: result.perPage,
+        prevCursor: result.prevCursor
+      }, Object.freeze({
+        cursorName: result.cursorName,
+        hasMorePages,
+        kind: "cursor",
+        nextCursor: result.nextCursor,
+        perPage: result.perPage,
+        prevCursor: result.prevCursor,
+        rows: pageRows,
+        rowCount: rows.length
+      }));
+    } else {
+      rebindDatabaseQueryObservationResult(rows, data);
+    }
+    return result;
   }
   async chunk(size, callback) {
     assertPositiveInteger(size, "Chunk size", (message) => new SecurityError(message));
@@ -3103,35 +4281,66 @@ var TableQueryBuilder = class _TableQueryBuilder {
     }
   }
   async count() {
-    return (await this.get()).length;
+    const rows = await this.get();
+    const result = rows.length;
+    if (hasActiveDatabaseDependencyCollector()) {
+      rebindDatabaseQueryObservationAggregate(rows, result, Object.freeze({ kind: "count" }));
+    }
+    return result;
   }
   async exists() {
-    return await this.count() > 0;
+    const count = await this.count();
+    const result = count > 0;
+    if (hasActiveDatabaseDependencyCollector()) {
+      rebindDatabaseQueryObservationAggregate(count, result, Object.freeze({
+        count,
+        kind: "count",
+        output: "boolean"
+      }));
+    }
+    return result;
   }
   async doesntExist() {
-    return !await this.exists();
+    const count = await this.count();
+    const result = count === 0;
+    if (hasActiveDatabaseDependencyCollector()) {
+      rebindDatabaseQueryObservationAggregate(count, result, Object.freeze({
+        count,
+        kind: "count",
+        output: "inverseBoolean"
+      }));
+    }
+    return result;
   }
   async pluck(column2) {
     const rows = await this.get();
-    return rows.map((row) => row[column2]);
+    const result = rows.map((row) => row[column2]);
+    rebindDatabaseQueryObservationScalarList(rows, result, column2);
+    return result;
   }
   async value(column2) {
     const row = await this.first();
-    return row?.[column2];
+    const result = row?.[column2];
+    rebindDatabaseQueryObservationScalar(row, result, column2);
+    return result;
   }
   async valueOrFail(column2) {
     const row = await this.first();
     if (!row || typeof row[column2] === "undefined") {
       throw new CompilerError(`Query returned no value for column "${column2}".`);
     }
-    return row[column2];
+    const result = row[column2];
+    rebindDatabaseQueryObservationScalar(row, result, column2);
+    return result;
   }
   async soleValue(column2) {
     const row = await this.sole();
     if (typeof row[column2] === "undefined") {
       throw new CompilerError(`Query returned no value for column "${column2}".`);
     }
-    return row[column2];
+    const result = row[column2];
+    rebindDatabaseQueryObservationScalar(row, result, column2);
+    return result;
   }
   async sum(column2) {
     return this.aggregateNumeric(column2, "sum");
@@ -3139,45 +4348,95 @@ var TableQueryBuilder = class _TableQueryBuilder {
   async avg(column2) {
     const rows = await this.get();
     if (rows.length === 0) {
+      if (hasActiveDatabaseDependencyCollector()) {
+        rebindDatabaseQueryObservationAggregate(rows, null, Object.freeze({ column: column2, count: 0, kind: "avg", sum: 0 }));
+      }
       return null;
     }
     const values = this.extractNumericValues(rows, column2, "avg");
-    return values.reduce((sum, value) => sum + value, 0) / values.length;
+    const sum = values.reduce((total, value) => total + value, 0);
+    const result = sum / values.length;
+    if (hasActiveDatabaseDependencyCollector()) {
+      rebindDatabaseQueryObservationAggregate(rows, result, Object.freeze({ column: column2, count: values.length, kind: "avg", sum }));
+    }
+    return result;
   }
   async min(column2) {
     const rows = await this.get();
     if (rows.length === 0) {
+      if (hasActiveDatabaseDependencyCollector()) {
+        rebindDatabaseQueryObservationAggregate(rows, null, Object.freeze({ column: column2, kind: "min" }));
+      }
       return null;
     }
     const values = this.extractNumericValues(rows, column2, "min");
-    return Math.min(...values);
+    const result = Math.min(...values);
+    if (hasActiveDatabaseDependencyCollector()) {
+      rebindDatabaseQueryObservationAggregate(rows, result, Object.freeze({
+        column: column2,
+        currentValueCount: values.filter((value) => value === result).length,
+        kind: "min",
+        valueCounts: createAggregateValueCounts(values)
+      }));
+    }
+    return result;
   }
   async max(column2) {
     const rows = await this.get();
     if (rows.length === 0) {
+      if (hasActiveDatabaseDependencyCollector()) {
+        rebindDatabaseQueryObservationAggregate(rows, null, Object.freeze({ column: column2, kind: "max" }));
+      }
       return null;
     }
     const values = this.extractNumericValues(rows, column2, "max");
-    return Math.max(...values);
+    const result = Math.max(...values);
+    if (hasActiveDatabaseDependencyCollector()) {
+      rebindDatabaseQueryObservationAggregate(rows, result, Object.freeze({
+        column: column2,
+        currentValueCount: values.filter((value) => value === result).length,
+        kind: "max",
+        valueCounts: createAggregateValueCounts(values)
+      }));
+    }
+    return result;
   }
   async find(value, column2 = "id") {
     return this.where(column2, value).limit(1).first();
   }
   async insert(values) {
     const rows = Array.isArray(values) ? values.map((value) => this.normalizeWriteRecord(value)) : [this.normalizeWriteRecord(values)];
-    const result = await this.connection.executeCompiled(this.getCompiler().compile(
+    const hasInvalidationListeners = hasDatabaseDependencyInvalidationListeners();
+    const useReturningRows = this.shouldUseReturningMutationRows(hasInvalidationListeners);
+    const result = useReturningRows ? await this.queryReturningMutationRows(
+      createInsertQueryPlan(this.source, rows, { returning: true }),
+      true
+    ) : await this.connection.executeCompiled(this.getCompiler().compile(
       createInsertQueryPlan(this.source, rows)
     ));
-    await this.invalidateInsertQueries(rows, result.lastInsertId);
-    return result;
+    await this.invalidateInsertQueries("insert", result.rows?.rows ?? rows, result.lastInsertId);
+    return {
+      affectedRows: result.affectedRows,
+      lastInsertId: result.lastInsertId
+    };
   }
   async insertOrIgnore(values) {
     const rows = Array.isArray(values) ? values.map((value) => this.normalizeWriteRecord(value)) : [this.normalizeWriteRecord(values)];
-    const result = await this.connection.executeCompiled(this.getCompiler().compile(
+    const hasInvalidationListeners = hasDatabaseDependencyInvalidationListeners();
+    const useReturningRows = this.shouldUseReturningMutationRows(hasInvalidationListeners);
+    const result = useReturningRows ? await this.queryReturningMutationRows(
+      createInsertQueryPlan(this.source, rows, { ignoreConflicts: true, returning: true }),
+      true
+    ) : await this.connection.executeCompiled(this.getCompiler().compile(
       createInsertQueryPlan(this.source, rows, { ignoreConflicts: true })
     ));
-    await this.invalidateInsertQueries(rows, result.lastInsertId);
-    return result;
+    if (!useReturningRows || result.affectedRows !== 0) {
+      await this.invalidateInsertQueries("insert", result.rows?.rows ?? rows, result.lastInsertId);
+    }
+    return {
+      affectedRows: result.affectedRows,
+      lastInsertId: result.lastInsertId
+    };
   }
   async insertGetId(values) {
     const result = await this.insert(values);
@@ -3185,78 +4444,272 @@ var TableQueryBuilder = class _TableQueryBuilder {
   }
   async upsert(values, uniqueBy, updateColumns = []) {
     const rows = Array.isArray(values) ? values.map((value) => this.normalizeWriteRecord(value)) : [this.normalizeWriteRecord(values)];
-    const result = await this.connection.executeCompiled(this.getCompiler().compile(
+    const hasInvalidationListeners = hasDatabaseDependencyInvalidationListeners();
+    const previousRows = hasInvalidationListeners ? await this.captureUpsertPreviousRows(rows, uniqueBy) : void 0;
+    const useReturningRows = this.shouldUseReturningMutationRows(hasInvalidationListeners);
+    const result = useReturningRows ? await this.queryReturningMutationRows(
+      createUpsertQueryPlan(this.source, rows, uniqueBy, updateColumns, { returning: true }),
+      true
+    ) : await this.connection.executeCompiled(this.getCompiler().compile(
       createUpsertQueryPlan(this.source, rows, uniqueBy, updateColumns)
     ));
-    await this.invalidateInsertQueries(rows, result.lastInsertId);
-    return result;
+    if (!useReturningRows || result.affectedRows !== 0) {
+      await this.invalidateInsertQueries("upsert", result.rows?.rows ?? rows, result.lastInsertId, previousRows);
+    }
+    return {
+      affectedRows: result.affectedRows,
+      lastInsertId: result.lastInsertId
+    };
   }
   async increment(column2, amount = 1, extraValues = {}) {
     return this.adjustNumericColumn(column2, amount, extraValues);
   }
-  async decrement(column2, amount = 1, extraValues = {}) {
-    return this.adjustNumericColumn(column2, -amount, extraValues);
+  async decrement(column2, amount = 1, extraValues = {}) {
+    return this.adjustNumericColumn(column2, -amount, extraValues);
+  }
+  async update(values) {
+    const normalizedValues = this.normalizeUpdateValues(values);
+    const hasInvalidationListeners = hasDatabaseDependencyInvalidationListeners();
+    const useReturningRows = this.shouldUseReturningMutationRows(hasInvalidationListeners);
+    const mutationRows = hasInvalidationListeners && !useReturningRows ? await this.captureUpdatedMutationRows(normalizedValues) : void 0;
+    const result = useReturningRows ? await this.queryReturningMutationRows(
+      createUpdateQueryPlan(this.source, this.plan.predicates, normalizedValues, { returning: true })
+    ) : await this.connection.executeCompiled(this.getCompiler().compile(
+      createUpdateQueryPlan(this.source, this.plan.predicates, normalizedValues)
+    ));
+    const capturedRows = result.rows ?? mutationRows;
+    if (result.affectedRows !== 0) {
+      await this.invalidateMutationQueries(normalizedValues, capturedRows);
+    }
+    return {
+      affectedRows: result.affectedRows,
+      lastInsertId: result.lastInsertId
+    };
+  }
+  async updateJson(columnPath, value) {
+    return this.update({ [columnPath]: value });
+  }
+  async delete() {
+    const hasInvalidationListeners = hasDatabaseDependencyInvalidationListeners();
+    const useReturningRows = this.shouldUseReturningMutationRows(hasInvalidationListeners);
+    const mutationRows = hasInvalidationListeners && !useReturningRows ? await this.captureDeletedMutationRows() : void 0;
+    const result = useReturningRows ? await this.queryReturningMutationRows(
+      createDeleteQueryPlan(this.source, this.plan.predicates, { returning: true })
+    ) : await this.connection.executeCompiled(this.getCompiler().compile(
+      createDeleteQueryPlan(this.source, this.plan.predicates)
+    ));
+    const capturedRows = result.rows ?? mutationRows;
+    if (result.affectedRows !== 0) {
+      await this.invalidateMutationQueries({}, capturedRows);
+    }
+    return {
+      affectedRows: result.affectedRows,
+      lastInsertId: result.lastInsertId
+    };
+  }
+  async unsafeQuery(statement) {
+    return this.connection.unsafeQuery({
+      ...statement,
+      unsafe: true,
+      source: `table:${this.source.tableName}`
+    });
+  }
+  async unsafeExecute(statement) {
+    return this.connection.unsafeExecute({
+      ...statement,
+      unsafe: true,
+      source: `table:${this.source.tableName}`
+    });
+  }
+  clone(plan) {
+    const table = this.source.table ?? this.source.tableName;
+    return new _TableQueryBuilder(table, this.connection, plan, this.queryCacheConfig);
+  }
+  async captureUpdatedMutationRows(values) {
+    const plan = Object.freeze({
+      ...createSelectQueryPlan(this.source),
+      predicates: this.plan.predicates
+    });
+    const result = await this.connection.queryCompiled(this.getCompiler().compile(plan));
+    if (result.rows.length === 0) {
+      return void 0;
+    }
+    const previousRows = Object.freeze(result.rows.map((row) => Object.freeze({ ...row })));
+    const rows = Object.freeze(previousRows.map((row) => Object.freeze(
+      this.applyCapturedUpdateValues(row, values)
+    )));
+    return Object.freeze({
+      previousRows,
+      rows
+    });
+  }
+  async captureDeletedMutationRows() {
+    const plan = Object.freeze({
+      ...createSelectQueryPlan(this.source),
+      predicates: this.plan.predicates
+    });
+    const result = await this.connection.queryCompiled(this.getCompiler().compile(plan));
+    if (result.rows.length === 0) {
+      return void 0;
+    }
+    return Object.freeze({
+      rows: Object.freeze(result.rows.map((row) => Object.freeze({ ...row })))
+    });
+  }
+  applyCapturedUpdateValues(row, values) {
+    const nextRow = { ...row };
+    for (const [column2, value] of Object.entries(values)) {
+      nextRow[column2] = this.applyCapturedUpdateValue(row[column2], value);
+    }
+    return nextRow;
+  }
+  applyCapturedUpdateValue(currentValue, value) {
+    if (!Array.isArray(value) || !value.every((item) => this.isCapturedJsonUpdateOperation(item))) {
+      return value;
+    }
+    let nextValue = currentValue;
+    for (const operation of value) {
+      nextValue = this.applyCapturedJsonUpdateOperation(nextValue, operation);
+    }
+    return nextValue;
+  }
+  applyCapturedJsonUpdateOperation(currentValue, operation) {
+    return this.applyCapturedJsonPathValue(currentValue, operation.path, operation.value);
+  }
+  isCapturedJsonUpdateOperation(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) && value.kind === "json-set" && Array.isArray(value.path);
   }
-  async update(values) {
-    const result = await this.connection.executeCompiled(this.getCompiler().compile(
-      createUpdateQueryPlan(this.source, this.plan.predicates, this.normalizeUpdateValues(values))
-    ));
-    if (result.affectedRows !== 0) {
-      await this.invalidateMutationQueries();
+  applyCapturedJsonPathValue(currentValue, path, value) {
+    const segment = path[0];
+    if (typeof segment === "undefined") {
+      return value;
     }
-    return result;
+    const currentRecord = this.isJsonRecord(currentValue) ? currentValue : {};
+    const childValue = this.applyCapturedJsonPathValue(currentRecord[segment], path.slice(1), value);
+    return Object.freeze({
+      ...currentRecord,
+      [segment]: childValue
+    });
   }
-  async updateJson(columnPath, value) {
-    return this.update({ [columnPath]: value });
+  isJsonRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
   }
-  async delete() {
-    const result = await this.connection.executeCompiled(this.getCompiler().compile(
-      createDeleteQueryPlan(this.source, this.plan.predicates)
-    ));
-    if (result.affectedRows !== 0) {
-      await this.invalidateMutationQueries();
+  async captureUpsertPreviousRows(rows, uniqueBy) {
+    const firstUniqueColumn = uniqueBy[0];
+    if (!firstUniqueColumn || rows.length === 0 || !rows.every((row) => this.hasUniqueByValues(row, uniqueBy))) {
+      return void 0;
     }
-    return result;
+    const firstColumnValues = Object.freeze([...new Set(rows.map((row) => row[firstUniqueColumn]))]);
+    const query = new _TableQueryBuilder(this.source.tableName, this.connection).whereIn(firstUniqueColumn, firstColumnValues);
+    const result = await this.connection.queryCompiled(this.getCompiler().compile(query.getPlan()));
+    const previousRows = [];
+    const usedResultIndexes = /* @__PURE__ */ new Set();
+    for (const row of rows) {
+      const resultIndex = result.rows.findIndex((candidate, index) => {
+        return !usedResultIndexes.has(index) && this.rowsMatchUniqueBy(candidate, row, uniqueBy);
+      });
+      if (resultIndex < 0) {
+        continue;
+      }
+      const previousRow = result.rows[resultIndex];
+      if (!previousRow) {
+        continue;
+      }
+      usedResultIndexes.add(resultIndex);
+      previousRows.push(Object.freeze({ ...previousRow }));
+    }
+    return Object.freeze(previousRows);
   }
-  async unsafeQuery(statement) {
-    return this.connection.unsafeQuery({
-      ...statement,
-      unsafe: true,
-      source: `table:${this.source.tableName}`
-    });
+  hasUniqueByValues(row, uniqueBy) {
+    return uniqueBy.every((column2) => Object.prototype.hasOwnProperty.call(row, column2));
   }
-  async unsafeExecute(statement) {
-    return this.connection.unsafeExecute({
-      ...statement,
-      unsafe: true,
-      source: `table:${this.source.tableName}`
-    });
+  rowsMatchUniqueBy(left, right, uniqueBy) {
+    return uniqueBy.every((column2) => left[column2] === right[column2]);
   }
-  clone(plan) {
-    const table = this.source.table ?? this.source.tableName;
-    return new _TableQueryBuilder(table, this.connection, plan, this.queryCacheConfig);
+  shouldUseReturningMutationRows(hasInvalidationListeners) {
+    return hasInvalidationListeners && this.connection.getCapabilities().returning;
+  }
+  async queryReturningMutationRows(plan, includeLastInsertId = false) {
+    const result = await this.connection.queryCompiled(this.getCompiler().compile(plan));
+    const rows = this.freezeMutationRows(result.rows);
+    return {
+      affectedRows: result.rowCount,
+      lastInsertId: includeLastInsertId ? this.readReturnedLastInsertId(rows) : void 0,
+      rows: rows.length === 0 ? void 0 : Object.freeze({
+        rows
+      })
+    };
+  }
+  freezeMutationRows(rows) {
+    return Object.freeze(rows.map((row) => Object.freeze({ ...row })));
+  }
+  readReturnedLastInsertId(rows) {
+    if (rows.length !== 1) {
+      return void 0;
+    }
+    const value = rows[0]?.[this.resolvePrimaryKeyColumn()];
+    return typeof value === "number" || typeof value === "string" ? value : void 0;
   }
-  async invalidateInsertQueries(rows, lastInsertId) {
-    if (!getDatabaseQueryCacheBridge() && !hasDatabaseDependencyInvalidationListeners()) {
+  async invalidateInsertQueries(kind, rows, lastInsertId, previousRows) {
+    const hasInvalidationListeners = hasDatabaseDependencyInvalidationListeners();
+    if (!getDatabaseQueryCacheBridge() && !hasInvalidationListeners) {
       return;
     }
-    await invalidateQueryCacheDependencies(
-      this.connection,
-      inferAutomaticInsertCacheInvalidationDependencies(
+    const mutations = hasInvalidationListeners ? [
+      createDatabaseMutationEvent(
+        kind,
         this.connection.getConnectionName(),
         this.source.tableName,
-        rows,
-        lastInsertId
+        [],
+        void 0,
+        rows.length === 1 && typeof lastInsertId !== "undefined" && !Object.prototype.hasOwnProperty.call(rows[0], "id") ? Object.freeze([Object.freeze({
+          ...rows[0],
+          id: lastInsertId
+        })]) : rows,
+        previousRows
       )
+    ] : [];
+    const invalidation = inferAutomaticInsertCacheInvalidationPlan(
+      this.connection.getConnectionName(),
+      this.source.tableName,
+      rows,
+      lastInsertId,
+      hasInvalidationListeners
+    );
+    await invalidateQueryCacheDependencies(
+      this.connection,
+      invalidation.dependencies,
+      mutations,
+      invalidation
     );
   }
-  async invalidateMutationQueries() {
-    if (!getDatabaseQueryCacheBridge() && !hasDatabaseDependencyInvalidationListeners()) {
+  async invalidateMutationQueries(values = {}, capturedRows) {
+    const hasInvalidationListeners = hasDatabaseDependencyInvalidationListeners();
+    if (!getDatabaseQueryCacheBridge() && !hasInvalidationListeners) {
       return;
     }
+    const hasValues = Object.keys(values).length > 0;
+    const invalidation = inferAutomaticQueryCacheInvalidationPlan(
+      this.plan,
+      this.connection.getConnectionName(),
+      values,
+      hasInvalidationListeners
+    );
     await invalidateQueryCacheDependencies(
       this.connection,
-      inferAutomaticQueryCacheInvalidationDependencies(this.plan, this.connection.getConnectionName())
+      invalidation.dependencies,
+      hasInvalidationListeners ? [
+        createDatabaseMutationEvent(
+          hasValues ? "update" : "delete",
+          this.connection.getConnectionName(),
+          this.source.tableName,
+          this.plan.predicates,
+          hasValues ? values : void 0,
+          capturedRows?.rows,
+          capturedRows?.previousRows
+        )
+      ] : [],
+      invalidation
     );
   }
   getCompiler() {
@@ -3400,10 +4853,11 @@ var TableQueryBuilder = class _TableQueryBuilder {
   }
   async aggregateNumeric(column2, kind) {
     const rows = await this.get();
-    if (rows.length === 0) {
-      return 0;
+    const result = rows.length === 0 ? 0 : this.extractNumericValues(rows, column2, kind).reduce((sum, value) => sum + value, 0);
+    if (hasActiveDatabaseDependencyCollector()) {
+      rebindDatabaseQueryObservationAggregate(rows, result, Object.freeze({ column: column2, kind }));
     }
-    return this.extractNumericValues(rows, column2, kind).reduce((sum, value) => sum + value, 0);
+    return result;
   }
   extractNumericValues(rows, column2, kind) {
     return rows.map((row) => {
@@ -8219,6 +9673,13 @@ var ModelQueryBuilder = class _ModelQueryBuilder {
   }
   async get() {
     const rows = await this.tableQuery.get();
+    const collection = await this.hydrateRows(rows);
+    this.recordCollectionRelationObservations(collection);
+    this.recordCollectionRelationAggregateObservations(collection);
+    this.rebindRowsToSerializedResult(rows, collection);
+    return collection;
+  }
+  async hydrateRows(rows) {
     const hasQueryCasts = Object.keys(this.queryCasts).length > 0;
     let entities = await Promise.all(
       rows.map((row) => hasQueryCasts ? this.repository.retrieveWithCasts(row, this.queryCasts) : this.repository.retrieve(row))
@@ -8230,39 +9691,76 @@ var ModelQueryBuilder = class _ModelQueryBuilder {
     return this.repository.createCollection(entities);
   }
   async getJson() {
-    return (await this.get()).toJSON();
+    const rows = await this.tableQuery.get();
+    const collection = await this.hydrateRows(rows);
+    this.recordCollectionRelationObservations(collection);
+    this.recordCollectionRelationAggregateObservations(collection);
+    const data = collection.toJSON();
+    this.rebindRowsToSerializedResult(rows, data);
+    return data;
   }
   async first() {
-    const [entity] = await this.limit(1).get();
+    const query = this.limit(1);
+    const { collection, rows } = await query.getRowsAndEntities();
+    const entity = collection[0];
+    query.recordSingleRelationObservations(entity);
+    query.recordSingleRelationAggregateObservations(entity);
+    query.rebindRowsToSerializedResult(rows, entity);
     return entity;
   }
   async firstJson() {
-    return (await this.first())?.toJSON();
+    const query = this.limit(1);
+    const { collection, rows } = await query.getRowsAndEntities();
+    const data = collection[0]?.toJSON();
+    query.recordSingleRelationObservations(collection[0]);
+    query.recordSingleRelationAggregateObservations(collection[0]);
+    query.rebindRowsToSerializedResult(rows, data);
+    return data;
   }
   async sole() {
-    const entities = await this.limit(2).get();
-    if (entities.length === 0) {
+    const query = this.limit(2);
+    const { collection, rows } = await query.getRowsAndEntities();
+    if (collection.length === 0) {
       throw new ModelNotFoundException(this.repository.definition.name, `${this.repository.definition.name} query expected exactly one result but found 0.`);
     }
-    if (entities.length !== 1) {
-      throw new HydrationError(`${this.repository.definition.name} query expected exactly one result but found ${entities.length}.`);
+    if (collection.length !== 1) {
+      throw new HydrationError(`${this.repository.definition.name} query expected exactly one result but found ${collection.length}.`);
     }
-    return entities[0];
+    const entity = collection[0];
+    query.recordSingleRelationObservations(entity);
+    query.recordSingleRelationAggregateObservations(entity);
+    query.rebindRowsToSerializedResult(rows, entity);
+    return entity;
   }
   async soleJson() {
-    return (await this.sole()).toJSON();
+    const query = this.limit(2);
+    const { collection, rows } = await query.getRowsAndEntities();
+    if (collection.length === 0) {
+      throw new ModelNotFoundException(this.repository.definition.name, `${this.repository.definition.name} query expected exactly one result but found 0.`);
+    }
+    if (collection.length !== 1) {
+      throw new HydrationError(`${this.repository.definition.name} query expected exactly one result but found ${collection.length}.`);
+    }
+    const data = collection[0].toJSON();
+    query.recordSingleRelationObservations(collection[0]);
+    query.recordSingleRelationAggregateObservations(collection[0]);
+    query.rebindRowsToSerializedResult(rows, data);
+    return data;
   }
   async paginate(perPage = 15, page = 1, options = {}) {
     assertPositiveInteger(perPage, "Per-page value", (message) => new HydrationError(message));
     assertPositiveInteger(page, "Page", (message) => new HydrationError(message));
     const pageName = normalizePaginationParameterName(options.pageName, "page", (message) => new HydrationError(message));
-    const entities = await this.getUnpaginatedEntities();
+    const { collection: entities, rows } = await this.getUnpaginatedRowsAndEntities();
     const total = entities.length;
     const offset = (page - 1) * perPage;
     const data = entities.slice(offset, offset + perPage);
     const from = data.length === 0 ? null : offset + 1;
     const to = data.length === 0 ? null : offset + data.length;
-    return createPaginator(this.repository.createCollection(data), {
+    const collection = this.repository.createCollection(data);
+    this.recordPaginatedRelationObservations(collection);
+    this.recordPaginatedRelationAggregateObservations(collection);
+    const result = createPaginator(collection, {
       total,
       perPage,
       pageName,
@@ -8272,22 +9770,50 @@ var ModelQueryBuilder = class _ModelQueryBuilder {
       to,
       hasMorePages: offset + data.length < total
     });
+    this.rebindRowsToPaginatedResult(rows, result.data, result.meta, page, pageName, perPage, total, offset);
+    return result;
   }
   async paginateJson(perPage = 15, page = 1, options = {}) {
-    return (await this.paginate(perPage, page, options)).toJSON();
+    assertPositiveInteger(perPage, "Per-page value", (message) => new HydrationError(message));
+    assertPositiveInteger(page, "Page", (message) => new HydrationError(message));
+    const pageName = normalizePaginationParameterName(options.pageName, "page", (message) => new HydrationError(message));
+    const { collection, rows } = await this.getUnpaginatedRowsAndEntities();
+    const total = collection.length;
+    const offset = (page - 1) * perPage;
+    const pageCollection = this.repository.createCollection(collection.slice(offset, offset + perPage));
+    const data = pageCollection.toJSON();
+    this.recordPaginatedRelationObservations(pageCollection);
+    this.recordPaginatedRelationAggregateObservations(pageCollection);
+    const from = data.length === 0 ? null : offset + 1;
+    const to = data.length === 0 ? null : offset + data.length;
+    const result = createPaginator(data, {
+      total,
+      perPage,
+      pageName,
+      currentPage: page,
+      lastPage: Math.max(1, Math.ceil(total / perPage)),
+      from,
+      to,
+      hasMorePages: offset + data.length < total
+    }).toJSON();
+    this.rebindRowsToPaginatedResult(rows, result.data, result.meta, page, pageName, perPage, total, offset);
+    return result;
   }
   async simplePaginate(perPage = 15, page = 1, options = {}) {
     assertPositiveInteger(perPage, "Per-page value", (message) => new HydrationError(message));
     assertPositiveInteger(page, "Page", (message) => new HydrationError(message));
     const pageName = normalizePaginationParameterName(options.pageName, "page", (message) => new HydrationError(message));
-    const entities = await this.getUnpaginatedEntities();
+    const { collection: entities, rows } = await this.getUnpaginatedRowsAndEntities();
     const offset = (page - 1) * perPage;
     const pageEntities = entities.slice(offset, offset + perPage + 1);
     const hasMorePages = pageEntities.length > perPage;
     const data = hasMorePages ? pageEntities.slice(0, perPage) : pageEntities;
     const from = data.length === 0 ? null : offset + 1;
     const to = data.length === 0 ? null : offset + data.length;
-    return createSimplePaginator(this.repository.createCollection(data), {
+    const collection = this.repository.createCollection(data);
+    this.recordPaginatedRelationObservations(collection);
+    this.recordPaginatedRelationAggregateObservations(collection);
+    const result = createSimplePaginator(collection, {
       perPage,
       pageName,
       currentPage: page,
@@ -8295,9 +9821,33 @@ var ModelQueryBuilder = class _ModelQueryBuilder {
       to,
       hasMorePages
     });
+    this.rebindRowsToSimplePaginatedResult(rows, result.data, result.meta, page, pageName, perPage, entities.length, hasMorePages, offset);
+    return result;
   }
   async simplePaginateJson(perPage = 15, page = 1, options = {}) {
-    return (await this.simplePaginate(perPage, page, options)).toJSON();
+    assertPositiveInteger(perPage, "Per-page value", (message) => new HydrationError(message));
+    assertPositiveInteger(page, "Page", (message) => new HydrationError(message));
+    const pageName = normalizePaginationParameterName(options.pageName, "page", (message) => new HydrationError(message));
+    const { collection, rows } = await this.getUnpaginatedRowsAndEntities();
+    const offset = (page - 1) * perPage;
+    const pageEntities = collection.slice(offset, offset + perPage + 1);
+    const hasMorePages = pageEntities.length > perPage;
+    const pageCollection = this.repository.createCollection(hasMorePages ? pageEntities.slice(0, perPage) : pageEntities);
+    const data = pageCollection.toJSON();
+    this.recordPaginatedRelationObservations(pageCollection);
+    this.recordPaginatedRelationAggregateObservations(pageCollection);
+    const from = data.length === 0 ? null : offset + 1;
+    const to = data.length === 0 ? null : offset + data.length;
+    const result = createSimplePaginator(data, {
+      perPage,
+      pageName,
+      currentPage: page,
+      from,
+      to,
+      hasMorePages
+    }).toJSON();
+    this.rebindRowsToSimplePaginatedResult(rows, result.data, result.meta, page, pageName, perPage, collection.length, hasMorePages, offset);
+    return result;
   }
   async cursorPaginate(perPage = 15, cursor = null, options = {}) {
     assertPositiveInteger(perPage, "Per-page value", (message) => new HydrationError(message));
@@ -8305,7 +9855,7 @@ var ModelQueryBuilder = class _ModelQueryBuilder {
     const decodedCursor = decodeValueCursor(cursor, (message) => new HydrationError(message));
     const orderedQuery = this.prepareCursorPaginationQuery();
     const cursorOrders = orderedQuery.resolveCursorOrders();
-    const entities = await orderedQuery.getUnpaginatedEntities();
+    const { collection: entities, rows } = await orderedQuery.getUnpaginatedRowsAndEntities();
     const filteredEntities = decodedCursor ? entities.filter((entity) => isRowAfterCursor(
       cursorOrders.map((order) => orderedQuery.readCursorColumnValue(entity, order.column)),
       decodedCursor.values,
@@ -8315,15 +9865,65 @@ var ModelQueryBuilder = class _ModelQueryBuilder {
     const hasMorePages = pageEntities.length > perPage;
     const data = hasMorePages ? pageEntities.slice(0, perPage) : pageEntities;
     const lastEntity = data.at(-1);
-    return createCursorPaginator(this.repository.createCollection(data), {
+    const collection = orderedQuery.repository.createCollection(data);
+    const observedPageRows = orderedQuery.repository.createCollection(pageEntities).toJSON();
+    orderedQuery.recordPaginatedRelationObservations(collection);
+    orderedQuery.recordPaginatedRelationAggregateObservations(collection);
+    const result = createCursorPaginator(collection, {
       perPage,
       cursorName,
       nextCursor: hasMorePages && lastEntity ? encodeValueCursor(cursorOrders.map((order) => orderedQuery.readCursorColumnValue(lastEntity, order.column))) : null,
       prevCursor: cursor
     });
+    if (cursor === null) {
+      orderedQuery.rebindRowsToCursorPaginatedResult(rows, result.data, {
+        cursorName: result.cursorName,
+        nextCursor: result.nextCursor,
+        perPage: result.perPage,
+        prevCursor: result.prevCursor
+      }, observedPageRows, entities.length, hasMorePages);
+    } else {
+      orderedQuery.rebindRowsToSerializedResult(rows, collection);
+    }
+    return result;
   }
   async cursorPaginateJson(perPage = 15, cursor = null, options = {}) {
-    return (await this.cursorPaginate(perPage, cursor, options)).toJSON();
+    assertPositiveInteger(perPage, "Per-page value", (message) => new HydrationError(message));
+    const cursorName = normalizePaginationParameterName(options.cursorName, "cursor", (message) => new HydrationError(message));
+    const decodedCursor = decodeValueCursor(cursor, (message) => new HydrationError(message));
+    const orderedQuery = this.prepareCursorPaginationQuery();
+    const cursorOrders = orderedQuery.resolveCursorOrders();
+    const { collection, rows } = await orderedQuery.getUnpaginatedRowsAndEntities();
+    const filteredEntities = decodedCursor ? collection.filter((entity) => isRowAfterCursor(
+      cursorOrders.map((order) => orderedQuery.readCursorColumnValue(entity, order.column)),
+      decodedCursor.values,
+      cursorOrders
+    )) : collection;
+    const pageEntities = filteredEntities.slice(0, perPage + 1);
+    const hasMorePages = pageEntities.length > perPage;
+    const pageCollection = orderedQuery.repository.createCollection(hasMorePages ? pageEntities.slice(0, perPage) : pageEntities);
+    const data = pageCollection.toJSON();
+    const observedPageRows = orderedQuery.repository.createCollection(pageEntities).toJSON();
+    const lastEntity = pageCollection.at(-1);
+    orderedQuery.recordPaginatedRelationObservations(pageCollection);
+    orderedQuery.recordPaginatedRelationAggregateObservations(pageCollection);
+    const result = createCursorPaginator(data, {
+      perPage,
+      cursorName,
+      nextCursor: hasMorePages && lastEntity ? encodeValueCursor(cursorOrders.map((order) => orderedQuery.readCursorColumnValue(lastEntity, order.column))) : null,
+      prevCursor: cursor
+    }).toJSON();
+    if (cursor === null) {
+      orderedQuery.rebindRowsToCursorPaginatedResult(rows, result.data, {
+        cursorName: result.cursorName,
+        nextCursor: result.nextCursor,
+        perPage: result.perPage,
+        prevCursor: result.prevCursor
+      }, observedPageRows, collection.length, hasMorePages);
+    } else {
+      orderedQuery.rebindRowsToSerializedResult(rows, result.data);
+    }
+    return result;
   }
   async chunk(size, callback) {
     assertPositiveInteger(size, "Chunk size", (message) => new HydrationError(message));
@@ -8387,21 +9987,42 @@ var ModelQueryBuilder = class _ModelQueryBuilder {
     }
   }
   async count() {
-    return (await this.get()).length;
+    const collection = await this.get();
+    const result = collection.length;
+    rebindDatabaseQueryObservationAggregate(collection, result, Object.freeze({ kind: "count" }));
+    return result;
   }
   async exists() {
-    return await this.count() > 0;
+    const count = await this.count();
+    const result = count > 0;
+    rebindDatabaseQueryObservationAggregate(count, result, Object.freeze({
+      count,
+      kind: "count",
+      output: "boolean"
+    }));
+    return result;
   }
   async doesntExist() {
-    return !await this.exists();
+    const count = await this.count();
+    const result = count === 0;
+    rebindDatabaseQueryObservationAggregate(count, result, Object.freeze({
+      count,
+      kind: "count",
+      output: "inverseBoolean"
+    }));
+    return result;
   }
   async pluck(column2) {
-    const entities = await this.get();
-    return entities.map((entity) => entity.get(column2));
+    const { collection, rows } = await this.getRowsAndEntities();
+    const result = collection.map((entity) => entity.get(column2));
+    rebindDatabaseQueryObservationScalarList(rows, result, column2);
+    return result;
   }
   async value(column2) {
     const entity = await this.first();
-    return entity?.get(column2);
+    const value = entity?.get(column2);
+    rebindDatabaseQueryObservationScalar(entity, value, column2);
+    return value;
   }
   async valueOrFail(column2) {
     const entity = await this.first();
@@ -8412,6 +10033,7 @@ var ModelQueryBuilder = class _ModelQueryBuilder {
     if (typeof value === "undefined") {
       throw new HydrationError(`${this.repository.definition.name} query returned no value for column "${column2}".`);
     }
+    rebindDatabaseQueryObservationScalar(entity, value, column2);
     return value;
   }
   async soleValue(column2) {
@@ -8420,36 +10042,78 @@ var ModelQueryBuilder = class _ModelQueryBuilder {
     if (typeof value === "undefined") {
       throw new HydrationError(`${this.repository.definition.name} query returned no value for column "${column2}".`);
     }
+    rebindDatabaseQueryObservationScalar(entity, value, column2);
     return value;
   }
   async sum(column2) {
     const entities = await this.get();
     if (entities.length === 0) {
+      if (hasActiveDatabaseDependencyCollector()) {
+        rebindDatabaseQueryObservationAggregate(entities, 0, Object.freeze({ column: column2, kind: "sum" }));
+      }
       return 0;
     }
-    return this.extractNumericValues(entities, column2, "sum").reduce((sum, value) => sum + value, 0);
+    const result = this.extractNumericValues(entities, column2, "sum").reduce((sum, value) => sum + value, 0);
+    if (hasActiveDatabaseDependencyCollector()) {
+      rebindDatabaseQueryObservationAggregate(entities, result, Object.freeze({ column: column2, kind: "sum" }));
+    }
+    return result;
   }
   async avg(column2) {
     const entities = await this.get();
     if (entities.length === 0) {
+      if (hasActiveDatabaseDependencyCollector()) {
+        rebindDatabaseQueryObservationAggregate(entities, null, Object.freeze({ column: column2, count: 0, kind: "avg", sum: 0 }));
+      }
       return null;
     }
     const values = this.extractNumericValues(entities, column2, "avg");
-    return values.reduce((sum, value) => sum + value, 0) / values.length;
+    const sum = values.reduce((total, value) => total + value, 0);
+    const result = sum / values.length;
+    if (hasActiveDatabaseDependencyCollector()) {
+      rebindDatabaseQueryObservationAggregate(entities, result, Object.freeze({ column: column2, count: values.length, kind: "avg", sum }));
+    }
+    return result;
   }
   async min(column2) {
     const entities = await this.get();
     if (entities.length === 0) {
+      if (hasActiveDatabaseDependencyCollector()) {
+        rebindDatabaseQueryObservationAggregate(entities, null, Object.freeze({ column: column2, kind: "min" }));
+      }
       return null;
     }
-    return Math.min(...this.extractNumericValues(entities, column2, "min"));
+    const values = this.extractNumericValues(entities, column2, "min");
+    const result = Math.min(...values);
+    if (hasActiveDatabaseDependencyCollector()) {
+      rebindDatabaseQueryObservationAggregate(entities, result, Object.freeze({
+        column: column2,
+        currentValueCount: values.filter((value) => value === result).length,
+        kind: "min",
+        valueCounts: createAggregateValueCounts(values)
+      }));
+    }
+    return result;
   }
   async max(column2) {
     const entities = await this.get();
     if (entities.length === 0) {
+      if (hasActiveDatabaseDependencyCollector()) {
+        rebindDatabaseQueryObservationAggregate(entities, null, Object.freeze({ column: column2, kind: "max" }));
+      }
       return null;
     }
-    return Math.max(...this.extractNumericValues(entities, column2, "max"));
+    const values = this.extractNumericValues(entities, column2, "max");
+    const result = Math.max(...values);
+    if (hasActiveDatabaseDependencyCollector()) {
+      rebindDatabaseQueryObservationAggregate(entities, result, Object.freeze({
+        column: column2,
+        currentValueCount: values.filter((value) => value === result).length,
+        kind: "max",
+        valueCounts: createAggregateValueCounts(values)
+      }));
+    }
+    return result;
   }
   async firstOrFail() {
     const entity = await this.first();
@@ -8722,68 +10386,296 @@ var ModelQueryBuilder = class _ModelQueryBuilder {
       column: column2
     }));
   }
-  parseAggregateRelation(spec) {
-    const [relationPart, aliasPart] = spec.split(/\s+as\s+/i);
-    const relation = relationPart?.trim();
-    const alias = aliasPart?.trim();
-    if (!relation) {
-      throw new HydrationError("Aggregate relation names cannot be empty.");
+  parseAggregateRelation(spec) {
+    const [relationPart, aliasPart] = spec.split(/\s+as\s+/i);
+    const relation = relationPart?.trim();
+    const alias = aliasPart?.trim();
+    if (!relation) {
+      throw new HydrationError("Aggregate relation names cannot be empty.");
+    }
+    if (typeof aliasPart !== "undefined" && !alias) {
+      throw new HydrationError("Aggregate relation aliases cannot be empty.");
+    }
+    return alias ? { relation, alias } : { relation };
+  }
+  resolveBelongsToRelation(relatedEntity, relationName) {
+    const resolvedName = this.resolveBelongsToRelationName(relatedEntity, relationName);
+    const relation = this.repository.getRelationDefinition(resolvedName);
+    if (relation.kind !== "belongsTo") {
+      throw new RelationError(`Relation "${resolvedName}" on model "${this.repository.definition.name}" is not a belongs-to relation.`);
+    }
+    return relation;
+  }
+  applyBelongsToFilter(relatedEntity, relationName, boolean) {
+    const resolvedRelationName = this.resolveBelongsToRelationName(relatedEntity, relationName);
+    const relation = this.resolveBelongsToRelation(relatedEntity, resolvedRelationName);
+    const ownerValue = relatedEntity.get(relation.ownerKey);
+    if (ownerValue === null || typeof ownerValue === "undefined") {
+      return boolean === "and" ? this.whereDoesntHave(resolvedRelationName) : this.orWhereDoesntHave(resolvedRelationName);
+    }
+    return boolean === "and" ? this.whereHas(resolvedRelationName, (query) => query.where(relation.ownerKey, ownerValue)) : this.orWhereHas(resolvedRelationName, (query) => query.where(relation.ownerKey, ownerValue));
+  }
+  resolveBelongsToRelationName(relatedEntity, relationName) {
+    if (relationName) {
+      return relationName;
+    }
+    const relatedDefinition = relatedEntity.getRepository().definition;
+    const candidates = Object.entries(this.repository.definition.relations).filter(([, relation]) => relation.kind === "belongsTo").map(([name, relation]) => [name, relation]).filter(([, relation]) => {
+      const ref = relation.related();
+      const definition = "definition" in ref ? ref.definition : ref;
+      return definition.table.tableName === relatedDefinition.table.tableName;
+    }).map(([name]) => name);
+    if (candidates.length === 1) {
+      return candidates[0];
+    }
+    if (candidates.length === 0) {
+      throw new RelationError(
+        `No belongs-to relation on model "${this.repository.definition.name}" matches related model "${relatedDefinition.name}".`
+      );
+    }
+    throw new RelationError(
+      `Multiple belongs-to relations on model "${this.repository.definition.name}" match related model "${relatedDefinition.name}". Specify the relation name explicitly.`
+    );
+  }
+  extractNumericValues(entities, column2, kind) {
+    return entities.map((entity) => {
+      const value = entity.get(column2);
+      if (typeof value !== "number" || Number.isNaN(value)) {
+        throw new HydrationError(`Model aggregate "${kind}" requires numeric values for column "${column2}".`);
+      }
+      return value;
+    });
+  }
+  async getUnpaginatedEntities() {
+    return this.clone(this.tableQuery.limit(void 0).offset(void 0)).get();
+  }
+  async getUnpaginatedRowsAndEntities() {
+    const query = this.clone(this.tableQuery.limit(void 0).offset(void 0));
+    return await query.getRowsAndEntities();
+  }
+  async getRowsAndEntities() {
+    const rows = await this.tableQuery.get();
+    return {
+      collection: await this.hydrateRows(rows),
+      rows
+    };
+  }
+  recordCollectionRelationAggregateObservations(collection) {
+    this.repository.recordRelationAggregateObservations(
+      collection,
+      this.aggregateLoads,
+      (index, key) => Object.freeze([index, key])
+    );
+  }
+  recordCollectionRelationObservations(collection) {
+    this.repository.recordRelationObservations(
+      collection,
+      this.eagerLoads,
+      (index, relationName) => Object.freeze([index, relationName])
+    );
+  }
+  recordSingleRelationObservations(entity) {
+    if (!entity) {
+      return;
+    }
+    this.repository.recordRelationObservations(
+      [entity],
+      this.eagerLoads,
+      (_index, relationName) => Object.freeze([relationName])
+    );
+  }
+  recordPaginatedRelationObservations(collection) {
+    this.repository.recordRelationObservations(
+      collection,
+      this.eagerLoads,
+      (index, relationName) => Object.freeze(["data", index, relationName])
+    );
+  }
+  recordSingleRelationAggregateObservations(entity) {
+    if (!entity) {
+      return;
+    }
+    this.repository.recordRelationAggregateObservations(
+      [entity],
+      this.aggregateLoads,
+      (_index, key) => Object.freeze([key])
+    );
+  }
+  recordPaginatedRelationAggregateObservations(collection) {
+    this.repository.recordRelationAggregateObservations(
+      collection,
+      this.aggregateLoads,
+      (index, key) => Object.freeze(["data", index, key])
+    );
+  }
+  canBindRowsToSerializedResultBase() {
+    return Object.keys(this.repository.definition.accessors).length === 0 && Object.keys(this.repository.definition.casts).length === 0 && Object.keys(this.queryCasts).length === 0 && this.repository.definition.appended.length === 0 && this.repository.definition.hidden.length === 0 && this.repository.definition.visible.length === 0 && this.relationFilters.length === 0 && this.aggregateLoads.length === 0;
+  }
+  canBindRowsToSerializedResult() {
+    return this.canBindRowsToSerializedResultBase() && this.eagerLoads.length === 0;
+  }
+  createPatchableEagerRelationHydrations() {
+    if (!this.canBindRowsToSerializedResultBase() || this.eagerLoads.length === 0) {
+      return void 0;
+    }
+    const belongsToHydrations = [];
+    const relatedHydrations = [];
+    for (const load of this.eagerLoads) {
+      if (load.relation.includes(".")) {
+        return void 0;
+      }
+      const relation = this.repository.getRelationDefinition(load.relation);
+      if (relation.kind === "belongsTo") {
+        if (relation.constraint || load.constraint) {
+          return void 0;
+        }
+        const related = relation.related();
+        const relatedDefinition = "definition" in related ? related.definition : related;
+        belongsToHydrations.push(Object.freeze({
+          foreignKey: relation.foreignKey,
+          ownerKey: relation.ownerKey,
+          relationKey: load.relation,
+          relatedConnectionName: relatedDefinition.connectionName ?? this.getConnectionName(),
+          relatedTableName: relatedDefinition.table.tableName
+        }));
+        continue;
+      }
+      if (relation.kind === "hasMany" || relation.kind === "hasOne") {
+        const hydrationQuery = this.createPatchableRelatedHydrationQuery(relation, load.constraint);
+        if (!hydrationQuery) {
+          return void 0;
+        }
+        const related = relation.related();
+        const relatedDefinition = "definition" in related ? related.definition : related;
+        relatedHydrations.push(Object.freeze({
+          foreignKey: relation.foreignKey,
+          kind: relation.kind,
+          localKey: relation.localKey,
+          orderBy: hydrationQuery.orderBy,
+          predicates: hydrationQuery.predicates,
+          relationKey: load.relation,
+          relatedConnectionName: relatedDefinition.connectionName ?? this.getConnectionName(),
+          relatedTableName: relatedDefinition.table.tableName
+        }));
+        continue;
+      }
+      return void 0;
+    }
+    return Object.freeze({
+      belongsToHydrations: belongsToHydrations.length > 0 ? Object.freeze(belongsToHydrations) : void 0,
+      relatedHydrations: relatedHydrations.length > 0 ? Object.freeze(relatedHydrations) : void 0
+    });
+  }
+  createPatchableRelatedHydrationQuery(relation, constraint) {
+    if (!relation.constraint && !constraint) {
+      return Object.freeze({
+        orderBy: Object.freeze([]),
+        predicates: Object.freeze([])
+      });
     }
-    if (typeof aliasPart !== "undefined" && !alias) {
-      throw new HydrationError("Aggregate relation aliases cannot be empty.");
+    const related = relation.related();
+    if (!this.isQueryableModelReference(related)) {
+      return void 0;
     }
-    return alias ? { relation, alias } : { relation };
-  }
-  resolveBelongsToRelation(relatedEntity, relationName) {
-    const resolvedName = this.resolveBelongsToRelationName(relatedEntity, relationName);
-    const relation = this.repository.getRelationDefinition(resolvedName);
-    if (relation.kind !== "belongsTo") {
-      throw new RelationError(`Relation "${resolvedName}" on model "${this.repository.definition.name}" is not a belongs-to relation.`);
+    let query = related.query();
+    const relationResult = relation.constraint?.(query);
+    query = relationResult instanceof _ModelQueryBuilder ? relationResult : query;
+    if (constraint) {
+      const result = constraint(query);
+      query = result instanceof _ModelQueryBuilder ? result : query;
+    }
+    const plan = query.getTableQueryBuilder().getPlan();
+    const relatedDefinition = "definition" in related ? related.definition : related;
+    const observation = createDatabaseQueryObservation(
+      plan,
+      relatedDefinition.connectionName ?? this.getConnectionName(),
+      Object.freeze([])
+    );
+    if (!observation?.patchable || typeof observation.limit !== "undefined" || typeof observation.offset !== "undefined") {
+      return void 0;
     }
-    return relation;
+    return Object.freeze({
+      orderBy: observation.orderBy,
+      predicates: observation.predicates
+    });
   }
-  applyBelongsToFilter(relatedEntity, relationName, boolean) {
-    const resolvedRelationName = this.resolveBelongsToRelationName(relatedEntity, relationName);
-    const relation = this.resolveBelongsToRelation(relatedEntity, resolvedRelationName);
-    const ownerValue = relatedEntity.get(relation.ownerKey);
-    if (ownerValue === null || typeof ownerValue === "undefined") {
-      return boolean === "and" ? this.whereDoesntHave(resolvedRelationName) : this.orWhereDoesntHave(resolvedRelationName);
-    }
-    return boolean === "and" ? this.whereHas(resolvedRelationName, (query) => query.where(relation.ownerKey, ownerValue)) : this.orWhereHas(resolvedRelationName, (query) => query.where(relation.ownerKey, ownerValue));
+  isQueryableModelReference(value) {
+    return "query" in value && typeof value.query === "function";
   }
-  resolveBelongsToRelationName(relatedEntity, relationName) {
-    if (relationName) {
-      return relationName;
+  rebindRowsToSerializedResult(rows, result) {
+    if (!hasActiveDatabaseDependencyCollector()) {
+      return;
     }
-    const relatedDefinition = relatedEntity.getRepository().definition;
-    const candidates = Object.entries(this.repository.definition.relations).filter(([, relation]) => relation.kind === "belongsTo").map(([name, relation]) => [name, relation]).filter(([, relation]) => {
-      const ref = relation.related();
-      const definition = "definition" in ref ? ref.definition : ref;
-      return definition.table.tableName === relatedDefinition.table.tableName;
-    }).map(([name]) => name);
-    if (candidates.length === 1) {
-      return candidates[0];
+    if (this.canBindRowsToSerializedResult()) {
+      rebindDatabaseQueryObservationResult(rows, result);
+      return;
     }
-    if (candidates.length === 0) {
-      throw new RelationError(
-        `No belongs-to relation on model "${this.repository.definition.name}" matches related model "${relatedDefinition.name}".`
+    const hydrations = this.createPatchableEagerRelationHydrations();
+    if (hydrations) {
+      rebindDatabaseQueryObservationHydratedResult(
+        rows,
+        result,
+        hydrations.belongsToHydrations ?? Object.freeze([]),
+        hydrations.relatedHydrations
       );
+      return;
     }
-    throw new RelationError(
-      `Multiple belongs-to relations on model "${this.repository.definition.name}" match related model "${relatedDefinition.name}". Specify the relation name explicitly.`
-    );
+    disableDatabaseQueryObservationPatching(rows);
   }
-  extractNumericValues(entities, column2, kind) {
-    return entities.map((entity) => {
-      const value = entity.get(column2);
-      if (typeof value !== "number" || Number.isNaN(value)) {
-        throw new HydrationError(`Model aggregate "${kind}" requires numeric values for column "${column2}".`);
-      }
-      return value;
-    });
+  rebindRowsToPaginatedResult(rows, data, meta, currentPage, pageName, perPage, total, offset) {
+    if (!hasActiveDatabaseDependencyCollector()) {
+      return;
+    }
+    const hydrations = this.createPatchableEagerRelationHydrations();
+    if (!this.canBindRowsToSerializedResult() && !hydrations) {
+      disableDatabaseQueryObservationPatching(rows);
+      return;
+    }
+    rebindDatabaseQueryObservationPagination(rows, data, meta, Object.freeze({
+      currentPage,
+      kind: "standard",
+      pageName,
+      perPage,
+      total
+    }), offset, hydrations?.belongsToHydrations, hydrations?.relatedHydrations);
   }
-  async getUnpaginatedEntities() {
-    return this.clone(this.tableQuery.limit(void 0).offset(void 0)).get();
+  rebindRowsToSimplePaginatedResult(rows, data, meta, currentPage, pageName, perPage, rowCount, hasMorePages, offset) {
+    if (!hasActiveDatabaseDependencyCollector()) {
+      return;
+    }
+    const hydrations = this.createPatchableEagerRelationHydrations();
+    if (!this.canBindRowsToSerializedResult() && !hydrations) {
+      disableDatabaseQueryObservationPatching(rows);
+      return;
+    }
+    rebindDatabaseQueryObservationPagination(rows, data, meta, Object.freeze({
+      currentPage,
+      hasMorePages,
+      kind: "simple",
+      pageName,
+      perPage,
+      rowCount
+    }), offset, hydrations?.belongsToHydrations, hydrations?.relatedHydrations);
+  }
+  rebindRowsToCursorPaginatedResult(rows, data, meta, pageRows, rowCount, hasMorePages) {
+    if (!hasActiveDatabaseDependencyCollector()) {
+      return;
+    }
+    const hydrations = this.createPatchableEagerRelationHydrations();
+    if (!this.canBindRowsToSerializedResult() && !hydrations) {
+      disableDatabaseQueryObservationPatching(rows);
+      return;
+    }
+    rebindDatabaseQueryObservationCursorPagination(rows, data, meta, Object.freeze({
+      cursorName: meta.cursorName,
+      hasMorePages,
+      kind: "cursor",
+      nextCursor: meta.nextCursor,
+      perPage: meta.perPage,
+      prevCursor: meta.prevCursor,
+      rows: pageRows,
+      rowCount
+    }), hydrations?.belongsToHydrations, hydrations?.relatedHydrations);
   }
   prepareCursorPaginationQuery() {
     const plan = this.tableQuery.getPlan();
@@ -8846,6 +10738,8 @@ function setAutomaticEagerLoading(definition, value) {
 }
 
 // src/model/ModelRepository.ts
+var relationAggregateObservationMetadata = /* @__PURE__ */ new WeakMap();
+var relationQueryObservationMetadata = /* @__PURE__ */ new WeakMap();
 function hasDefinition(reference) {
   return "definition" in reference;
 }
@@ -9190,6 +11084,7 @@ var ModelRepository = class _ModelRepository {
     if (entities.length === 0 || aggregates.length === 0) {
       return;
     }
+    const observationCount = hasActiveDatabaseDependencyCollector() ? readDatabaseQueryObservationCount() : void 0;
     for (const aggregate of aggregates) {
       if (aggregate.relation.includes(".")) {
         throw new SecurityError("Nested relation aggregates are not supported yet.");
@@ -9202,6 +11097,12 @@ var ModelRepository = class _ModelRepository {
           const parentKey = this.getRelationParentValue(entity, relation);
           const count = counts.get(parentKey) ?? 0;
           entity.setComputed(key, aggregate.kind === "count" ? count : count > 0);
+          if (aggregate.kind === "exists" && typeof observationCount === "number") {
+            this.setRelationAggregateObservationMetadata(entity, key, Object.freeze({
+              count,
+              kind: "count"
+            }));
+          }
         }
         continue;
       }
@@ -9211,8 +11112,489 @@ var ModelRepository = class _ModelRepository {
       const values = await this.getRelationAggregateValues(entities, relation, aggregate);
       for (const entity of entities) {
         const parentKey = this.getRelationParentValue(entity, relation);
-        entity.setComputed(key, values.get(parentKey) ?? null);
+        const computation = values.get(parentKey);
+        entity.setComputed(key, computation?.value ?? null);
+        if (computation?.metadata && typeof observationCount === "number") {
+          this.setRelationAggregateObservationMetadata(entity, key, computation.metadata);
+        }
+      }
+    }
+    if (typeof observationCount === "number") {
+      truncateDatabaseQueryObservations(observationCount);
+    }
+  }
+  recordRelationAggregateObservations(entities, aggregates, createPath) {
+    if (!hasActiveDatabaseDependencyCollector() || entities.length === 0 || aggregates.length === 0) {
+      return;
+    }
+    for (const aggregate of aggregates) {
+      if (aggregate.relation.includes(".")) {
+        continue;
+      }
+      const relation = this.getRelationDefinition(aggregate.relation);
+      const key = this.getAggregateAttributeKey(aggregate);
+      for (let index = 0; index < entities.length; index += 1) {
+        const entity = entities[index];
+        if (!entity) {
+          continue;
+        }
+        const target = this.createRelationAggregateObservationTarget(entity, relation);
+        if (!target) {
+          continue;
+        }
+        const aggregateObservation = this.createRelationAggregateObservation(aggregate, entity, key);
+        if (!aggregateObservation) {
+          continue;
+        }
+        const predicateDependency = createTablePredicateCacheDependency(
+          target.connectionName,
+          target.tableName,
+          target.column,
+          target.value
+        );
+        const dependencies = predicateDependency ? Object.freeze([
+          createTableCacheDependency(target.connectionName, target.tableName),
+          predicateDependency
+        ]) : Object.freeze([createTableCacheDependency(target.connectionName, target.tableName)]);
+        const resultPath = createPath(index, key);
+        const data = entity.toJSON();
+        recordDatabaseQueryObservation(Object.freeze({
+          aggregate: aggregate.kind === "exists" ? Object.freeze({
+            ...aggregateObservation,
+            output: "boolean"
+          }) : aggregateObservation,
+          connectionName: target.connectionName,
+          dependencies,
+          orderBy: [],
+          patchable: true,
+          predicates: Object.freeze([Object.freeze({
+            column: target.column,
+            operator: "=",
+            value: target.value
+          })]),
+          result: data[key],
+          resultPath,
+          selections: [],
+          tableName: target.tableName
+        }));
+      }
+    }
+  }
+  recordRelationObservations(entities, relations, createPath) {
+    if (!hasActiveDatabaseDependencyCollector() || entities.length === 0 || relations.length === 0) {
+      return;
+    }
+    for (const entry of this.normalizeEagerLoads(relations)) {
+      if (entry.relation.includes(".")) {
+        continue;
+      }
+      const relationName = entry.relation;
+      const relation = this.getRelationDefinition(relationName);
+      if (relation.kind === "hasMany") {
+        this.recordHasManyRelationObservations(entities, relationName, relation, createPath);
+        continue;
+      }
+      if (relation.kind === "hasOne") {
+        this.recordHasOneRelationObservations(entities, relationName, relation, createPath);
+        continue;
+      }
+      if (relation.kind === "belongsTo") {
+        this.recordBelongsToRelationObservations(entities, relationName, relation, createPath);
+        continue;
+      }
+      if (relation.constraint) {
+        continue;
+      }
+      if (relation.kind === "belongsToMany") {
+        this.recordBelongsToManyRelationObservations(entities, relationName, relation, createPath);
+      }
+    }
+  }
+  recordHasManyRelationObservations(entities, relationName, relation, createPath) {
+    const related = this.resolveRelatedRepository(relation.related);
+    for (let index = 0; index < entities.length; index += 1) {
+      const entity = entities[index];
+      if (!entity || !entity.hasRelation(relationName)) {
+        continue;
+      }
+      const observed = this.getRelationQueryObservation(entity, relationName);
+      if (observed) {
+        recordDatabaseQueryObservation(Object.freeze({
+          ...observed,
+          resultPath: createPath(index, relationName)
+        }));
+        continue;
+      }
+      if (relation.constraint) {
+        continue;
       }
+      const parentKey = this.getRelationParentValue(entity, relation);
+      const predicateDependency = createTablePredicateCacheDependency(
+        related.getConnectionName(),
+        related.definition.table.tableName,
+        relation.foreignKey,
+        parentKey
+      );
+      const dependencies = predicateDependency ? Object.freeze([
+        createTableCacheDependency(related.getConnectionName(), related.definition.table.tableName),
+        predicateDependency
+      ]) : Object.freeze([createTableCacheDependency(related.getConnectionName(), related.definition.table.tableName)]);
+      recordDatabaseQueryObservation(Object.freeze({
+        connectionName: related.getConnectionName(),
+        dependencies,
+        orderBy: [],
+        patchable: true,
+        predicates: Object.freeze([Object.freeze({
+          column: relation.foreignKey,
+          operator: "=",
+          value: parentKey
+        })]),
+        resultPath: createPath(index, relationName),
+        selections: [],
+        tableName: related.definition.table.tableName
+      }));
+    }
+  }
+  recordHasOneRelationObservations(entities, relationName, relation, createPath) {
+    const related = this.resolveRelatedRepository(relation.related);
+    for (let index = 0; index < entities.length; index += 1) {
+      const entity = entities[index];
+      if (!entity || !entity.hasRelation(relationName)) {
+        continue;
+      }
+      const resultPath = createPath(index, relationName);
+      const observed = this.getRelationQueryObservation(entity, relationName);
+      if (observed) {
+        recordDatabaseQueryObservation(this.createNullableSingleRecordRelationObservation(observed, resultPath));
+        continue;
+      }
+      if (relation.constraint) {
+        continue;
+      }
+      const parentKey = this.getRelationParentValue(entity, relation);
+      const predicateDependency = createTablePredicateCacheDependency(
+        related.getConnectionName(),
+        related.definition.table.tableName,
+        relation.foreignKey,
+        parentKey
+      );
+      const dependencies = predicateDependency ? Object.freeze([
+        createTableCacheDependency(related.getConnectionName(), related.definition.table.tableName),
+        predicateDependency
+      ]) : Object.freeze([createTableCacheDependency(related.getConnectionName(), related.definition.table.tableName)]);
+      recordDatabaseQueryObservation(this.createNullableSingleRecordRelationObservation(Object.freeze({
+        connectionName: related.getConnectionName(),
+        dependencies,
+        orderBy: [],
+        patchable: true,
+        predicates: Object.freeze([Object.freeze({
+          column: relation.foreignKey,
+          operator: "=",
+          value: parentKey
+        })]),
+        selections: [],
+        tableName: related.definition.table.tableName
+      }), resultPath));
+    }
+  }
+  recordBelongsToRelationObservations(entities, relationName, relation, createPath) {
+    const related = this.resolveRelatedRepository(relation.related);
+    for (let index = 0; index < entities.length; index += 1) {
+      const entity = entities[index];
+      if (!entity || !entity.hasRelation(relationName)) {
+        continue;
+      }
+      const resultPath = createPath(index, relationName);
+      const observed = this.getRelationQueryObservation(entity, relationName);
+      recordDatabaseQueryObservation(this.createBelongsToParentKeyRelationObservation(
+        entity,
+        relationName,
+        relation,
+        resultPath.slice(0, -1),
+        !relation.constraint
+      ));
+      if (observed) {
+        recordDatabaseQueryObservation(this.createNullableSingleRecordRelationObservation(observed, resultPath));
+        continue;
+      }
+      if (relation.constraint) {
+        continue;
+      }
+      const ownerKey = this.getRelationParentValue(entity, relation);
+      if (ownerKey === null || typeof ownerKey === "undefined") {
+        continue;
+      }
+      const predicateDependency = createTablePredicateCacheDependency(
+        related.getConnectionName(),
+        related.definition.table.tableName,
+        relation.ownerKey,
+        ownerKey
+      );
+      const dependencies = predicateDependency ? Object.freeze([
+        createTableCacheDependency(related.getConnectionName(), related.definition.table.tableName),
+        predicateDependency
+      ]) : Object.freeze([createTableCacheDependency(related.getConnectionName(), related.definition.table.tableName)]);
+      recordDatabaseQueryObservation(this.createNullableSingleRecordRelationObservation(Object.freeze({
+        connectionName: related.getConnectionName(),
+        dependencies,
+        orderBy: [],
+        patchable: true,
+        predicates: Object.freeze([Object.freeze({
+          column: relation.ownerKey,
+          operator: "=",
+          value: ownerKey
+        })]),
+        selections: [],
+        tableName: related.definition.table.tableName
+      }), resultPath));
+    }
+  }
+  createBelongsToParentKeyRelationObservation(entity, relationName, relation, resultPath, patchable) {
+    const parentKey = entity.toAttributes()[this.definition.primaryKey];
+    if (parentKey === null || typeof parentKey === "undefined") {
+      return void 0;
+    }
+    const predicateDependency = createTablePredicateCacheDependency(
+      this.getConnectionName(),
+      this.definition.table.tableName,
+      this.definition.primaryKey,
+      parentKey
+    );
+    const dependencies = predicateDependency ? Object.freeze([
+      createTableCacheDependency(this.getConnectionName(), this.definition.table.tableName),
+      predicateDependency
+    ]) : Object.freeze([createTableCacheDependency(this.getConnectionName(), this.definition.table.tableName)]);
+    const related = this.resolveRelatedRepository(relation.related);
+    return Object.freeze({
+      connectionName: this.getConnectionName(),
+      dependencies,
+      orderBy: [],
+      patchable,
+      predicates: Object.freeze([Object.freeze({
+        column: this.definition.primaryKey,
+        operator: "=",
+        value: parentKey
+      })]),
+      relation: Object.freeze({
+        foreignKey: relation.foreignKey,
+        kind: "belongsToParentKey",
+        ownerKey: relation.ownerKey,
+        relationKey: relationName,
+        relatedConnectionName: related.getConnectionName(),
+        relatedTableName: related.definition.table.tableName
+      }),
+      resultPath,
+      selections: Object.freeze([Object.freeze({
+        column: relation.foreignKey,
+        resultKey: relation.foreignKey
+      })]),
+      tableName: this.definition.table.tableName
+    });
+  }
+  createNullableSingleRecordRelationObservation(observation, resultPath) {
+    return Object.freeze({
+      ...observation,
+      emptyRecordValue: null,
+      limit: 1,
+      resultPath,
+      rowWindowMode: "single"
+    });
+  }
+  rememberHasManyRelationObservation(entity, relationName, relation, related, constrainedPlan, parentKey) {
+    const observation = this.createHasManyRelationObservation(relation, related, constrainedPlan, parentKey);
+    if (!observation) {
+      return;
+    }
+    const observations = relationQueryObservationMetadata.get(entity) ?? /* @__PURE__ */ new Map();
+    observations.set(relationName, observation);
+    relationQueryObservationMetadata.set(entity, observations);
+  }
+  rememberBelongsToRelationObservation(entity, relationName, relation, related, constrainedPlan, ownerKey) {
+    const observation = this.createBelongsToRelationObservation(relation, related, constrainedPlan, ownerKey);
+    if (!observation) {
+      return;
+    }
+    const observations = relationQueryObservationMetadata.get(entity) ?? /* @__PURE__ */ new Map();
+    observations.set(relationName, observation);
+    relationQueryObservationMetadata.set(entity, observations);
+  }
+  getRelationQueryObservation(entity, relationName) {
+    return relationQueryObservationMetadata.get(entity)?.get(relationName);
+  }
+  createHasManyRelationObservation(relation, related, constrainedPlan, parentKey) {
+    if (parentKey === null || typeof parentKey === "undefined") {
+      return void 0;
+    }
+    const parentPlan = withPredicate(constrainedPlan, {
+      kind: "comparison",
+      column: relation.foreignKey,
+      operator: "=",
+      value: parentKey
+    });
+    const dependencies = resolveQueryCacheDependencies(parentPlan, related.getConnectionName());
+    return dependencies ? createDatabaseQueryObservation(parentPlan, related.getConnectionName(), dependencies) : void 0;
+  }
+  createBelongsToRelationObservation(relation, related, constrainedPlan, ownerKey) {
+    if (ownerKey === null || typeof ownerKey === "undefined") {
+      return void 0;
+    }
+    const ownerPlan = withPredicate(constrainedPlan, {
+      kind: "comparison",
+      column: relation.ownerKey,
+      operator: "=",
+      value: ownerKey
+    });
+    const dependencies = resolveQueryCacheDependencies(ownerPlan, related.getConnectionName());
+    return dependencies ? createDatabaseQueryObservation(ownerPlan, related.getConnectionName(), dependencies) : void 0;
+  }
+  recordBelongsToManyRelationObservations(entities, relationName, relation, createPath) {
+    const related = this.resolveRelatedRepository(relation.related);
+    const pivotTableName = this.resolvePivotTableName(relation.pivotTable);
+    for (let index = 0; index < entities.length; index += 1) {
+      const entity = entities[index];
+      if (!entity || !entity.hasRelation(relationName)) {
+        continue;
+      }
+      const parentKey = this.getRelationParentValue(entity, relation);
+      const predicateDependency = createTablePredicateCacheDependency(
+        this.getConnectionName(),
+        pivotTableName,
+        relation.foreignPivotKey,
+        parentKey
+      );
+      const relatedMetadata = this.createBelongsToManyRelatedObservationMetadata(entity, relationName, relation, related);
+      const dependencies = predicateDependency ? Object.freeze([
+        createTableCacheDependency(this.getConnectionName(), pivotTableName),
+        predicateDependency,
+        ...relatedMetadata.dependencies
+      ]) : Object.freeze([
+        createTableCacheDependency(this.getConnectionName(), pivotTableName),
+        ...relatedMetadata.dependencies
+      ]);
+      const relationObservation = Object.freeze({
+        foreignPivotKey: relation.foreignPivotKey,
+        kind: "belongsToMany",
+        pivotAccessor: relation.pivotAccessor,
+        pivotColumns: relation.pivotColumns,
+        pivotOrderBy: relation.pivotOrderBy,
+        relatedConnectionName: related.getConnectionName(),
+        relatedKey: relation.relatedKey,
+        relatedPivotKey: relation.relatedPivotKey,
+        relatedTableName: related.definition.table.tableName
+      });
+      recordDatabaseQueryObservation(Object.freeze({
+        connectionName: this.getConnectionName(),
+        dependencies,
+        orderBy: relation.pivotOrderBy,
+        patchable: relation.pivotWheres.length === 0,
+        predicates: Object.freeze([Object.freeze({
+          column: relation.foreignPivotKey,
+          operator: "=",
+          value: parentKey
+        })]),
+        relation: relationObservation,
+        resultPath: createPath(index, relationName),
+        selections: [],
+        tableName: pivotTableName
+      }));
+      if (relatedMetadata.values.length === 0) {
+        continue;
+      }
+      recordDatabaseQueryObservation(Object.freeze({
+        connectionName: related.getConnectionName(),
+        dependencies: Object.freeze([
+          createTableCacheDependency(related.getConnectionName(), related.definition.table.tableName),
+          ...relatedMetadata.dependencies
+        ]),
+        orderBy: [],
+        patchable: true,
+        predicates: Object.freeze([Object.freeze({
+          column: relation.relatedKey,
+          operator: "in",
+          value: relatedMetadata.values
+        })]),
+        relation: relationObservation,
+        resultPath: createPath(index, relationName),
+        selections: [],
+        tableName: related.definition.table.tableName
+      }));
+    }
+  }
+  createBelongsToManyRelatedObservationMetadata(entity, relationName, relation, related) {
+    const loaded = entity.getRelation(relationName);
+    const dependencies = [];
+    const values = [];
+    for (const relatedEntity of loaded) {
+      if (!isEntity2(relatedEntity)) {
+        continue;
+      }
+      const relatedValue = relatedEntity.get(relation.relatedKey);
+      values.push(relatedValue);
+      const dependency = createTablePredicateCacheDependency(
+        related.getConnectionName(),
+        related.definition.table.tableName,
+        relation.relatedKey,
+        relatedValue
+      );
+      if (dependency) {
+        dependencies.push(dependency);
+      }
+    }
+    return Object.freeze({
+      dependencies: Object.freeze(dependencies),
+      values: Object.freeze(values)
+    });
+  }
+  createRelationAggregateObservation(aggregate, entity, key) {
+    const metadata = this.getRelationAggregateObservationMetadata(entity, key);
+    if (metadata) {
+      return metadata;
+    }
+    if (aggregate.kind === "count" || aggregate.kind === "exists") {
+      return Object.freeze({
+        kind: "count"
+      });
+    }
+    if (!aggregate.column) {
+      return void 0;
+    }
+    return Object.freeze({
+      column: aggregate.column,
+      kind: aggregate.kind
+    });
+  }
+  setRelationAggregateObservationMetadata(entity, key, metadata) {
+    const byKey = relationAggregateObservationMetadata.get(entity) ?? /* @__PURE__ */ new Map();
+    byKey.set(key, metadata);
+    relationAggregateObservationMetadata.set(entity, byKey);
+  }
+  getRelationAggregateObservationMetadata(entity, key) {
+    return relationAggregateObservationMetadata.get(entity)?.get(key);
+  }
+  createRelationAggregateObservationTarget(entity, relation) {
+    switch (relation.kind) {
+      case "belongsTo": {
+        const related = this.resolveRelatedRepository(relation.related);
+        return {
+          column: relation.ownerKey,
+          connectionName: related.getConnectionName(),
+          tableName: related.definition.table.tableName,
+          value: this.getRelationParentValue(entity, relation)
+        };
+      }
+      case "hasMany":
+      case "hasOne":
+      case "hasOneOfMany": {
+        const related = this.resolveRelatedRepository(relation.related);
+        return {
+          column: relation.foreignKey,
+          connectionName: related.getConnectionName(),
+          tableName: related.definition.table.tableName,
+          value: this.getRelationParentValue(entity, relation)
+        };
+      }
+      default:
+        return void 0;
     }
   }
   async create(values) {
@@ -9901,13 +12283,22 @@ var ModelRepository = class _ModelRepository {
       return;
     }
     const related = this.resolveRelatedRepository(relation.related);
-    const relatedEntities = await this.applyRelationConstraint(relation, related, constraint).where(relation.ownerKey, "in", foreignKeys).get();
+    const observationCount = hasActiveDatabaseDependencyCollector() ? readDatabaseQueryObservationCount() : void 0;
+    const constrainedQuery = this.applyRelationConstraint(relation, related, constraint);
+    const constrainedPlan = typeof observationCount === "number" ? constrainedQuery.getTableQueryBuilder().getPlan() : void 0;
+    const relatedEntities = await constrainedQuery.where(relation.ownerKey, "in", foreignKeys).get();
+    if (typeof observationCount === "number") {
+      truncateDatabaseQueryObservations(observationCount);
+    }
     const relatedMap = new Map(
       relatedEntities.map((entity) => [entity.get(relation.ownerKey), entity])
     );
     for (const entity of entities) {
       const foreignKey = entity.toAttributes()[relation.foreignKey];
       entity.setRelation(relationName, relatedMap.get(foreignKey) ?? null);
+      if (constrainedPlan) {
+        this.rememberBelongsToRelationObservation(entity, relationName, relation, related, constrainedPlan, foreignKey);
+      }
     }
   }
   async loadHasManyRelation(entities, relationName, relation, constraint) {
@@ -9921,7 +12312,13 @@ var ModelRepository = class _ModelRepository {
       return;
     }
     const related = this.resolveRelatedRepository(relation.related);
-    const relatedEntities = await this.applyRelationConstraint(relation, related, constraint).where(relation.foreignKey, "in", localKeys).get();
+    const observationCount = hasActiveDatabaseDependencyCollector() ? readDatabaseQueryObservationCount() : void 0;
+    const constrainedQuery = this.applyRelationConstraint(relation, related, constraint);
+    const constrainedPlan = typeof observationCount === "number" ? constrainedQuery.getTableQueryBuilder().getPlan() : void 0;
+    const relatedEntities = await constrainedQuery.where(relation.foreignKey, "in", localKeys).get();
+    if (typeof observationCount === "number") {
+      truncateDatabaseQueryObservations(observationCount);
+    }
     const grouped = /* @__PURE__ */ new Map();
     for (const relatedEntity of relatedEntities) {
       const foreignKey = relatedEntity.get(relation.foreignKey);
@@ -9932,6 +12329,9 @@ var ModelRepository = class _ModelRepository {
     for (const entity of entities) {
       const localKey = entity.toAttributes()[relation.localKey];
       entity.setRelation(relationName, grouped.get(localKey) ?? []);
+      if (constrainedPlan) {
+        this.rememberHasManyRelationObservation(entity, relationName, relation, related, constrainedPlan, localKey);
+      }
     }
   }
   async loadHasOneRelation(entities, relationName, relation, constraint) {
@@ -10003,8 +12403,12 @@ var ModelRepository = class _ModelRepository {
       }
       return;
     }
+    const observationCount = hasActiveDatabaseDependencyCollector() ? readDatabaseQueryObservationCount() : void 0;
     const pivotRows = await this.createBelongsToManyPivotQuery(relation, this.getConnection()).where(relation.foreignPivotKey, "in", parentKeys).get();
     if (pivotRows.length === 0) {
+      if (typeof observationCount === "number") {
+        truncateDatabaseQueryObservations(observationCount);
+      }
       for (const entity of entities) {
         entity.setRelation(relationName, []);
       }
@@ -10014,6 +12418,9 @@ var ModelRepository = class _ModelRepository {
       pivotRows.map((row) => row[relation.relatedPivotKey]).filter((value) => value !== null && typeof value !== "undefined")
     )];
     if (relatedIds.length === 0) {
+      if (typeof observationCount === "number") {
+        truncateDatabaseQueryObservations(observationCount);
+      }
       for (const entity of entities) {
         entity.setRelation(relationName, []);
       }
@@ -10021,6 +12428,9 @@ var ModelRepository = class _ModelRepository {
     }
     const related = this.resolveRelatedRepository(relation.related);
     const relatedEntities = await this.applyRelationConstraint(relation, related, constraint).where(relation.relatedKey, "in", relatedIds).get();
+    if (typeof observationCount === "number") {
+      truncateDatabaseQueryObservations(observationCount);
+    }
     const relatedMap = new Map(
       relatedEntities.map((entity) => [entity.get(relation.relatedKey), entity])
     );
@@ -10333,31 +12743,53 @@ var ModelRepository = class _ModelRepository {
     switch (kind) {
       case "sum": {
         const numbers = values.map((value) => this.assertNumericAggregateValue(value, kind, column2));
-        return numbers.reduce((sum, value) => sum + value, 0);
+        return Object.freeze({
+          value: numbers.reduce((sum, value) => sum + value, 0)
+        });
       }
       case "avg": {
         const numbers = values.map((value) => this.assertNumericAggregateValue(value, kind, column2));
+        const sum = numbers.reduce((total, value) => total + value, 0);
+        const metadata = Object.freeze({
+          column: column2,
+          count: numbers.length,
+          kind,
+          sum
+        });
         if (numbers.length === 0) {
-          return null;
+          return Object.freeze({
+            metadata,
+            value: null
+          });
         }
-        return numbers.reduce((sum, value) => sum + value, 0) / numbers.length;
+        return Object.freeze({
+          metadata,
+          value: sum / numbers.length
+        });
       }
       case "min": {
         const numbers = values.map((value) => this.assertNumericAggregateValue(value, kind, column2));
-        if (numbers.length === 0) {
-          return null;
-        }
-        return Math.min(...numbers);
+        return this.computeExtremeAggregateValue(kind, column2, numbers);
       }
       case "max": {
         const numbers = values.map((value) => this.assertNumericAggregateValue(value, kind, column2));
-        if (numbers.length === 0) {
-          return null;
-        }
-        return Math.max(...numbers);
+        return this.computeExtremeAggregateValue(kind, column2, numbers);
       }
     }
   }
+  computeExtremeAggregateValue(kind, column2, numbers) {
+    const value = numbers.length === 0 ? null : kind === "min" ? Math.min(...numbers) : Math.max(...numbers);
+    const metadata = Object.freeze({
+      column: column2,
+      currentValueCount: typeof value === "number" ? numbers.filter((number) => number === value).length : 0,
+      kind,
+      valueCounts: createAggregateValueCounts(numbers)
+    });
+    return Object.freeze({
+      metadata,
+      value
+    });
+  }
   assertNumericAggregateValue(value, kind, column2) {
     if (typeof value !== "number" || Number.isNaN(value)) {
       throw new DatabaseError(`Relation aggregate "${kind}" requires numeric values for column "${column2}".`);
@@ -10925,6 +13357,9 @@ var ModelRepository = class _ModelRepository {
   createBelongsToManyPivotQuery(relation, connection) {
     return this.applyPivotQueryConfig(new TableQueryBuilder(relation.pivotTable, connection), relation);
   }
+  resolvePivotTableName(pivotTable) {
+    return typeof pivotTable === "string" ? pivotTable : pivotTable.tableName;
+  }
   createMorphToManyPivotQuery(relation, connection) {
     return this.applyPivotQueryConfig(new TableQueryBuilder(relation.pivotTable, connection), relation);
   }
@@ -14428,14 +16863,14 @@ function getHoloModelReferenceRegistry() {
 
 // src/model/serialize.ts
 function isSerializableModel(value) {
-  return Boolean(value && typeof value === "object" && typeof value.toJSON === "function");
+  return typeof value.toJSON === "function";
 }
 function serializeModels(value) {
   if (value instanceof Date || value === null || typeof value !== "object") {
     return value;
   }
   if (isSerializableModel(value)) {
-    return value.toJSON();
+    return serializeModels(value.toJSON());
   }
   if (Array.isArray(value)) {
     return value.map((item) => serializeModels(item));