velocious 1.0.510 → 1.0.512

package/README.md

@@ -11,6 +11,7 @@
 * Controllers and views for HTTP endpoints
 * Frontend-model transport for creating, updating, querying, and subscribing to query-filtered lifecycle events over HTTP/WebSocket, with structured per-attribute validation error responses (see [docs/frontend-models.md](docs/frontend-models.md))
 * Client-side offline sync mutation logs and frontend-model optimistic queueing primitives (see [docs/offline-sync.md](docs/offline-sync.md))
+* Reactive `useLiveQuery(Model.where(...))` queries that stay current from committed local model changes across local writes, pulls, and realtime (see [docs/live-queries.md](docs/live-queries.md))
 * Server-side sync envelope replay orchestration for app-owned sync receivers (see [docs/sync-envelope-replay-service.md](docs/sync-envelope-replay-service.md))
 * SQLite web persistence that automatically prefers OPFS, then IndexedDB, and migrates legacy persisted bytes when possible (see [docs/sqlite-web-persistence.md](docs/sqlite-web-persistence.md))
 * Expo / Metro compatibility guidance and a real Expo export check (see [docs/expo-metro-compatibility.md](docs/expo-metro-compatibility.md))

package/build/database/advisory-lock-runner.js

@@ -0,0 +1,192 @@
+// @ts-check
+
+import timeout from "awaitery/build/timeout.js"
+
+/**
+ * Thrown when an advisory lock could not be acquired before `timeoutMs` elapsed.
+ */
+class AdvisoryLockTimeoutError extends Error {
+  /**
+   * Runs constructor.
+   * @param {string} message - Error message.
+   * @param {{name: string}} args - The advisory lock name that timed out.
+   */
+  constructor(message, {name}) {
+    super(message)
+    this.name = "AdvisoryLockTimeoutError"
+    this.lockName = name
+  }
+}
+
+/**
+ * Thrown when `withAdvisoryLockOrFail` finds the lock already held.
+ */
+class AdvisoryLockBusyError extends Error {
+  /**
+   * Runs constructor.
+   * @param {string} message - Error message.
+   * @param {{name: string}} args - The advisory lock name that was already held.
+   */
+  constructor(message, {name}) {
+    super(message)
+    this.name = "AdvisoryLockBusyError"
+    this.lockName = name
+  }
+}
+
+/**
+ * Thrown when a callback holds an advisory lock longer than `holdTimeoutMs`.
+ */
+class AdvisoryLockHoldTimeoutError extends Error {
+  /**
+   * Runs constructor.
+   * @param {string} message - Error message.
+   * @param {{name: string}} args - The advisory lock name whose hold timed out.
+   */
+  constructor(message, {name}) {
+    super(message)
+    this.name = "AdvisoryLockHoldTimeoutError"
+    this.lockName = name
+  }
+}
+
+/**
+ * Runs advisory locks on the caller connection by default, using a dedicated
+ * lock connection only when a positive hold timeout needs separate ownership.
+ */
+export default class AdvisoryLockRunner {
+  /**
+   * Creates an advisory-lock runner for one model database identifier.
+   * @param {{configuration: import("../configuration.js").default, connectionProvider: () => import("./drivers/base.js").default, databaseIdentifier: string}} args - Runner dependencies.
+   */
+  constructor({configuration, connectionProvider, databaseIdentifier}) {
+    this.configuration = configuration
+    this.connectionProvider = connectionProvider
+    this.databaseIdentifier = databaseIdentifier
+  }
+
+  /**
+   * Runs a callback after acquiring the advisory lock, waiting up to `timeoutMs`.
+   * @template T
+   * @param {string} name - Lock name.
+   * @param {() => Promise<T>} callback - Callback to invoke while the lock is held.
+   * @param {{timeoutMs?: number | null, holdTimeoutMs?: number | null}} [args] - Lock and hold timeout options.
+   * @returns {Promise<T>} - Resolves with the callback result.
+   */
+  async withAdvisoryLock(name, callback, args = {}) {
+    return await this.withLockConnection(args.holdTimeoutMs, async (connection) => {
+      const acquired = await connection.acquireAdvisoryLock(name, args)
+
+      if (!acquired) {
+        throw new AdvisoryLockTimeoutError(`Timed out waiting for advisory lock ${JSON.stringify(name)}`, {name})
+      }
+
+      return await this.runLockedCallback({callback, connection, holdTimeoutMs: args.holdTimeoutMs, name})
+    })
+  }
+
+  /**
+   * Runs a callback only if the advisory lock can be acquired immediately.
+   * @template T
+   * @param {string} name - Lock name.
+   * @param {() => Promise<T>} callback - Callback to invoke while the lock is held.
+   * @param {{holdTimeoutMs?: number | null}} [args] - Hold timeout options.
+   * @returns {Promise<T>} - Resolves with the callback result.
+   */
+  async withAdvisoryLockOrFail(name, callback, args = {}) {
+    return await this.withLockConnection(args.holdTimeoutMs, async (connection) => {
+      const acquired = await connection.tryAcquireAdvisoryLock(name)
+
+      if (!acquired) {
+        throw new AdvisoryLockBusyError(`Advisory lock ${JSON.stringify(name)} is already held`, {name})
+      }
+
+      return await this.runLockedCallback({callback, connection, holdTimeoutMs: args.holdTimeoutMs, name})
+    })
+  }
+
+  /**
+   * Runs the lock holder callback and releases the lock from its owning connection.
+   * @template T
+   * @param {{callback: () => Promise<T>, connection: import("./drivers/base.js").default, holdTimeoutMs?: number | null, name: string}} args - Locked callback args.
+   * @returns {Promise<T>} - Resolves with the callback result.
+   */
+  async runLockedCallback({callback, connection, holdTimeoutMs, name}) {
+    try {
+      return await AdvisoryLockRunner.runWithAdvisoryLockHoldTimeout(name, callback, holdTimeoutMs)
+    } finally {
+      await connection.releaseAdvisoryLock(name)
+    }
+  }
+
+  /**
+   * Runs lock work on the caller connection unless a positive hold timeout needs
+   * its own lock connection.
+   * @template T
+   * @param {number | null | undefined} holdTimeoutMs - Max hold time; positive values use a dedicated lock connection.
+   * @param {(connection: import("./drivers/base.js").default) => Promise<T>} callback - Callback receiving the connection that owns the advisory lock.
+   * @returns {Promise<T>} - Resolves with the callback result.
+   */
+  async withLockConnection(holdTimeoutMs, callback) {
+    if (holdTimeoutMs && holdTimeoutMs > 0) {
+      return await this.withDedicatedConnection(callback)
+    }
+
+    return await callback(this.connectionProvider())
+  }
+
+  /**
+   * Spawns a hold-timeout lock connection and closes it after lock work completes when
+   * the spawned driver owns the underlying physical connection.
+   * @template T
+   * @param {(connection: import("./drivers/base.js").default) => Promise<T>} callback - Callback that receives the dedicated lock connection.
+   * @returns {Promise<T>} - Resolves with the callback result.
+   */
+  async withDedicatedConnection(callback) {
+    const connection = await this.configuration.getDatabasePool(this.databaseIdentifier).spawnConnection()
+
+    try {
+      return await callback(connection)
+    } finally {
+      if (!connection.getArgs().getConnection) {
+        await connection.close()
+      }
+    }
+  }
+
+  /**
+   * Runs `callback`, rejecting with `AdvisoryLockHoldTimeoutError` if it has
+   * not settled within `holdTimeoutMs`. The callback is not cancelled; callers
+   * use a dedicated advisory-lock connection so the lock can still be released.
+   * @template T
+   * @param {string} name - Lock name (for the error message).
+   * @param {() => Promise<T>} callback - Callback holding the lock.
+   * @param {number | null} [holdTimeoutMs] - Max hold time; falsy disables the timeout.
+   * @returns {Promise<T>} - Resolves with the callback result.
+   */
+  static async runWithAdvisoryLockHoldTimeout(name, callback, holdTimeoutMs) {
+    if (!holdTimeoutMs || holdTimeoutMs <= 0) {
+      return await callback()
+    }
+
+    let callbackSettled = false
+
+    try {
+      return await timeout({timeout: holdTimeoutMs}, async () => {
+        try {
+          return await callback()
+        } finally {
+          callbackSettled = true
+        }
+      })
+    } catch (error) {
+      if (!callbackSettled) {
+        throw new AdvisoryLockHoldTimeoutError(`Advisory lock ${JSON.stringify(name)} held longer than ${holdTimeoutMs}ms`, {name})
+      }
+
+      throw error
+    }
+  }
+}
+
+export {AdvisoryLockBusyError, AdvisoryLockHoldTimeoutError, AdvisoryLockTimeoutError}

package/build/database/drivers/mysql/index.js

@@ -31,6 +31,9 @@ import Update from "./sql/update.js"
 const MYSQL_INDEFINITE_LOCK_TIMEOUT_SECONDS = 60 * 60 * 24 * 365
 
 export default class VelociousDatabaseDriversMysql extends Base{
+  /** @type {import("mysql").Pool | undefined} */
+  pool = undefined
+
   /** @type {string | null} */
   _desiredSessionTimeZone = "+00:00"
 

package/build/database/live-query.js

@@ -0,0 +1,244 @@
+// @ts-check
+
+import debounceFunction from "debounce"
+
+import recordChanges from "./record-changes.js"
+import restArgsError from "../utils/rest-args-error.js"
+
+/**
+ * RecordModelClass type.
+ * @typedef {typeof import("./record/index.js").default} RecordModelClass */
+
+/**
+ * The minimal query contract a live query needs: a root model class to observe
+ * for committed changes and a way to run the query and return the current rows.
+ * `Model.where({...})` (a model-class query) satisfies this directly.
+ * @template T
+ * @typedef {object} LiveQuerySource
+ * @property {() => RecordModelClass} getModelClass - Root model class the query reads.
+ * @property {() => Promise<T[]>} toArray - Runs the query and resolves the current rows.
+ */
+
+/**
+ * LiveQueryState type.
+ * @template T
+ * @typedef {object} LiveQueryState
+ * @property {T[]} results - Current query results.
+ * @property {boolean} loading - Whether the initial results are still loading.
+ * @property {Error | null} error - The last run error, or null when the last run succeeded.
+ */
+
+/**
+ * A reactive query controller: fetches once, subscribes to committed changes of
+ * its model class(es), and re-runs whenever a watched model changes. Re-runs are
+ * coalesced (microtask by default, or a trailing debounce) and protected against
+ * stale responses by a monotonically increasing request id, so an in-flight run
+ * superseded by a newer change never overwrites fresher results. Framework-level
+ * and React-free so it can be unit tested and wrapped by `useLiveQuery`.
+ *
+ * Cost model: invalidation is by model class. A change to model M schedules one
+ * re-run of every live query observing M (no per-condition matching); a batch of
+ * changes coalesces into a single re-run.
+ * @template T
+ */
+class LiveQuery {
+  /**
+   * Builds a live query controller for a query source.
+   * @param {object} args - Options.
+   * @param {LiveQuerySource<T>} args.query - Query source providing model class and `toArray`.
+   * @param {RecordModelClass[]} [args.models] - Model classes to observe. Defaults to `[query.getModelClass()]`; pass this to also react to joined models.
+   * @param {number} [args.debounce] - Trailing debounce in ms for re-runs. Defaults to microtask coalescing.
+   */
+  constructor({query, ...restArgs}) {
+    const {debounce, models, ...unknownArgs} = restArgs
+
+    restArgsError(unknownArgs)
+
+    if (!query) throw new Error("No query given to LiveQuery")
+
+    /** @type {LiveQuerySource<T>} */
+    this._query = query
+
+    /** @type {RecordModelClass[]} */
+    this._modelClasses = models ?? [query.getModelClass()]
+
+    /** @type {LiveQueryState<T>} */
+    this._state = {error: null, loading: true, results: []}
+
+    /**
+     * State-change listeners notified after every state transition.
+     * @type {Set<() => void>} */
+    this._listeners = new Set()
+
+    /**
+     * Record-change unsubscribe callbacks registered on `start`.
+     * @type {Array<() => void>} */
+    this._unsubscribes = []
+
+    /** @type {number} */
+    this._requestId = 0
+
+    /** @type {boolean} */
+    this._closed = false
+
+    /** @type {boolean} */
+    this._started = false
+
+    /** @type {boolean} */
+    this._runScheduled = false
+
+    /**
+     * Promise for the currently in-flight run, or null when idle.
+     * @type {Promise<void> | null} */
+    this._runningPromise = null
+
+    /**
+     * Schedules a coalesced re-run: a trailing debounce when configured, else microtask coalescing.
+     * @type {(() => void) & {clear?: () => void}} */
+    this._scheduleRun = typeof debounce === "number"
+      ? debounceFunction(() => this._run(), debounce)
+      : () => this._scheduleMicrotaskRun()
+
+    /**
+     * Record-change listener scheduling a re-run while the controller is open.
+     * @type {() => void} */
+    this._onRecordChange = () => {
+      if (!this._closed) this._scheduleRun()
+    }
+  }
+
+  /**
+   * Subscribes to record changes and runs the initial query. Idempotent.
+   * @returns {void}
+   */
+  start() {
+    if (this._closed || this._started) return
+
+    this._started = true
+
+    for (const modelClass of this._modelClasses) {
+      this._unsubscribes.push(recordChanges.subscribe(modelClass, this._onRecordChange))
+    }
+
+    this._run()
+  }
+
+  /**
+   * Returns the current state. The reference only changes when the state changes,
+   * so it is safe to use as a React external-store snapshot.
+   * @returns {LiveQueryState<T>} Current live-query state.
+   */
+  getState() {
+    return this._state
+  }
+
+  /**
+   * Subscribes a listener notified after every state change.
+   * @param {() => void} listener - State-change listener.
+   * @returns {() => void} Unsubscribe callback.
+   */
+  subscribe(listener) {
+    this._listeners.add(listener)
+
+    return () => {
+      this._listeners.delete(listener)
+    }
+  }
+
+  /**
+   * Unsubscribes from record changes, drops listeners, and prevents further runs.
+   * @returns {void}
+   */
+  close() {
+    if (this._closed) return
+
+    this._closed = true
+
+    for (const unsubscribe of this._unsubscribes) {
+      unsubscribe()
+    }
+
+    this._unsubscribes = []
+    this._listeners.clear()
+
+    if (this._scheduleRun.clear) this._scheduleRun.clear()
+  }
+
+  /**
+   * Awaits any scheduled or in-flight run so callers (tests) can observe settled
+   * results. Bounded so a continuous change stream cannot loop forever.
+   * @returns {Promise<void>}
+   */
+  async whenSettled() {
+    for (let attempt = 0; attempt < 100; attempt++) {
+      if (this._closed) return
+      if (!this._runScheduled && !this._runningPromise) return
+
+      if (this._runningPromise) await this._runningPromise
+
+      await new Promise((resolve) => queueMicrotask(() => resolve(undefined)))
+    }
+  }
+
+  /**
+   * Schedules a microtask-coalesced re-run, collapsing a synchronous burst of
+   * change events into a single run.
+   * @returns {void}
+   */
+  _scheduleMicrotaskRun() {
+    if (this._runScheduled) return
+
+    this._runScheduled = true
+
+    queueMicrotask(() => {
+      this._runScheduled = false
+
+      if (!this._closed) this._run()
+    })
+  }
+
+  /**
+   * Runs the query and applies its results unless a newer run superseded it or the
+   * controller was closed. A run error surfaces in state (with the previous
+   * results kept) rather than rejecting a background promise.
+   * @returns {Promise<void>}
+   */
+  _run() {
+    const requestId = ++this._requestId
+    const runningPromise = (async () => {
+      try {
+        const results = await this._query.toArray()
+
+        if (this._closed || requestId !== this._requestId) return
+
+        this._setState({error: null, loading: false, results})
+      } catch (error) {
+        if (this._closed || requestId !== this._requestId) return
+
+        this._setState({error: /** @type {Error} */ (error), loading: false, results: this._state.results})
+      }
+    })()
+
+    this._runningPromise = runningPromise
+    void runningPromise.then(() => {
+      if (this._runningPromise === runningPromise) this._runningPromise = null
+    })
+
+    return runningPromise
+  }
+
+  /**
+   * Replaces the state and notifies listeners.
+   * @param {LiveQueryState<T>} state - Next state.
+   * @returns {void}
+   */
+  _setState(state) {
+    this._state = state
+
+    for (const listener of Array.from(this._listeners)) {
+      listener()
+    }
+  }
+}
+
+export default LiveQuery

package/build/database/record/index.js

@@ -24,7 +24,7 @@
 
 /** @typedef {import("../../configuration-types.js").TenantDatabaseProviderType} TenantDatabaseProviderType */
 
-import timeout from "awaitery/build/timeout.js"
+import AdvisoryLockRunner, {AdvisoryLockBusyError, AdvisoryLockHoldTimeoutError, AdvisoryLockTimeoutError} from "../advisory-lock-runner.js"
 import BelongsToInstanceRelationship from "./instance-relationships/belongs-to.js"
 import BelongsToRelationship from "./relationships/belongs-to.js"
 import Configuration from "../../configuration.js"
@@ -41,6 +41,7 @@ import deburrColumnName from "../../utils/deburr-column-name.js"
 import ModelClassQuery from "../query/model-class-query.js"
 import Preloader from "../query/preloader.js"
 import {readPayloadAssociationCount, readPayloadComputedAbility, readPayloadQueryData, setPayloadAssociationCount, setPayloadComputedAbility, setPayloadQueryData} from "../../record-payload-values.js"
+import recordChanges from "../record-changes.js"
 import restArgsError from "../../utils/rest-args-error.js"
 import singularizeModelName from "../../utils/singularize-model-name.js"
 import {defineModelScope} from "../../utils/model-scope.js"
@@ -164,60 +165,6 @@ function buildRelatedRecordWithInverse(parent, relationshipName, attributes, all
   return record
 }
 
-/**
- * Thrown by `Record.withAdvisoryLock` when the caller supplied a
- * `timeoutMs` and the lock was not granted before it elapsed.
- */
-class AdvisoryLockTimeoutError extends Error {
-  /**
-   * Runs constructor.
-   * @param {string} message - Error message.
-   * @param {{name: string}} args - The advisory lock name that timed out.
-   */
-  constructor(message, {name}) {
-    super(message)
-    this.name = "AdvisoryLockTimeoutError"
-    this.lockName = name
-  }
-}
-
-/**
- * Thrown by `Record.withAdvisoryLockOrFail` when the lock is already held
- * by another session at the moment of the call.
- */
-class AdvisoryLockBusyError extends Error {
-  /**
-   * Runs constructor.
-   * @param {string} message - Error message.
-   * @param {{name: string}} args - The advisory lock name that was already held.
-   */
-  constructor(message, {name}) {
-    super(message)
-    this.name = "AdvisoryLockBusyError"
-    this.lockName = name
-  }
-}
-
-/**
- * Thrown by `Record.withAdvisoryLock` / `withAdvisoryLockOrFail` when the
- * caller supplied a `holdTimeoutMs` and the callback ran longer than it. The
- * lock is released before this is thrown, so a hung holder can't block other
- * sessions indefinitely. Note: the callback itself is not cancelled — pass an
- * AbortSignal to the work if it needs to stop.
- */
-class AdvisoryLockHoldTimeoutError extends Error {
-  /**
-   * Runs constructor.
-   * @param {string} message - Error message.
-   * @param {{name: string}} args - The advisory lock name whose hold timed out.
-   */
-  constructor(message, {name}) {
-    super(message)
-    this.name = "AdvisoryLockHoldTimeoutError"
-    this.lockName = name
-  }
-}
-
 class TenantDatabaseScopeError extends Error {
   /**
    * Runs constructor.
@@ -2471,6 +2418,7 @@ class VelociousDatabaseRecord {
         await this._autoSaveHasManyAndHasOneRelationships({isNewRecord})
         await this._autoSaveAttachments()
         await this._runLifecycleCallbacks("afterSave")
+        await this._emitRecordChangeAfterCommit(isNewRecord ? "create" : "update")
       })
     })
 
@@ -2675,10 +2623,13 @@ class VelociousDatabaseRecord {
   }
 
   /**
-   * Runs the callback while holding a named advisory lock on the current
-   * connection. Advisory locks are cooperative and connection-scoped: they
-   * serialize callers that opt into the same `name`, without touching row
-   * or table locks, so unrelated traffic is free to proceed.
+   * Runs the callback while holding a named advisory lock. Calls without
+   * a positive `holdTimeoutMs` use the caller connection; calls with a positive
+   * `holdTimeoutMs` use a dedicated lock connection so timeout cleanup can
+   * release the lock even when callback database work is stuck. Advisory locks
+   * are cooperative and session-scoped: they serialize callers that opt into
+   * the same `name`, without touching row or table locks, so unrelated traffic
+   * is free to proceed.
    *
    * The lock is acquired before the callback runs and released in a
    * `finally` block afterwards, so the callback's return value is
@@ -2694,18 +2645,13 @@ class VelociousDatabaseRecord {
   static async withAdvisoryLock(name, callback, args = {}) {
     await this.ensureInitialized()
 
-    const connection = this.connection()
-    const acquired = await connection.acquireAdvisoryLock(name, args)
-
-    if (!acquired) {
-      throw new AdvisoryLockTimeoutError(`Timed out waiting for advisory lock ${JSON.stringify(name)}`, {name})
-    }
+    const runner = new AdvisoryLockRunner({
+      configuration: this._getConfiguration(),
+      connectionProvider: () => this.connection(),
+      databaseIdentifier: this.getDatabaseIdentifier()
+    })
 
-    try {
-      return await this.runWithAdvisoryLockHoldTimeout(name, callback, args.holdTimeoutMs)
-    } finally {
-      await connection.releaseAdvisoryLock(name)
-    }
+    return await runner.withAdvisoryLock(name, callback, args)
   }
 
   /**
@@ -2725,31 +2671,19 @@ class VelociousDatabaseRecord {
   static async withAdvisoryLockOrFail(name, callback, args = {}) {
     await this.ensureInitialized()
 
-    const connection = this.connection()
-    const acquired = await connection.tryAcquireAdvisoryLock(name)
-
-    if (!acquired) {
-      throw new AdvisoryLockBusyError(`Advisory lock ${JSON.stringify(name)} is already held`, {name})
-    }
+    const runner = new AdvisoryLockRunner({
+      configuration: this._getConfiguration(),
+      connectionProvider: () => this.connection(),
+      databaseIdentifier: this.getDatabaseIdentifier()
+    })
 
-    try {
-      return await this.runWithAdvisoryLockHoldTimeout(name, callback, args.holdTimeoutMs)
-    } finally {
-      await connection.releaseAdvisoryLock(name)
-    }
+    return await runner.withAdvisoryLockOrFail(name, callback, args)
   }
 
   /**
    * Runs `callback`, rejecting with `AdvisoryLockHoldTimeoutError` if it has
-   * not settled within `holdTimeoutMs`. The caller's `finally` then releases
-   * the lock, so a hung holder can't block other sessions forever. The
-   * callback is not cancelled — this is a safety net, not cancellation.
-   *
-   * Uses `awaitery`'s shared `timeout` helper for the hard timeout, then
-   * translates its timeout into the typed `AdvisoryLockHoldTimeoutError` so
-   * callers can catch it like the other advisory-lock errors. A `callbackSettled`
-   * flag distinguishes the timeout from a rejection thrown by the callback
-   * itself, which is rethrown unchanged.
+   * not settled within `holdTimeoutMs`. The callback is not cancelled — this is
+   * a safety net, not cancellation.
    * @template T
    * @param {string} name - Lock name (for the error message).
    * @param {() => Promise<T>} callback - Callback holding the lock.
@@ -2757,27 +2691,7 @@ class VelociousDatabaseRecord {
    * @returns {Promise<T>}
    */
   static async runWithAdvisoryLockHoldTimeout(name, callback, holdTimeoutMs) {
-    if (!holdTimeoutMs || holdTimeoutMs <= 0) {
-      return await callback()
-    }
-
-    let callbackSettled = false
-
-    try {
-      return await timeout({timeout: holdTimeoutMs}, async () => {
-        try {
-          return await callback()
-        } finally {
-          callbackSettled = true
-        }
-      })
-    } catch (error) {
-      if (!callbackSettled) {
-        throw new AdvisoryLockHoldTimeoutError(`Advisory lock ${JSON.stringify(name)} held longer than ${holdTimeoutMs}ms`, {name})
-      }
-
-      throw error
-    }
+    return await AdvisoryLockRunner.runWithAdvisoryLockHoldTimeout(name, callback, holdTimeoutMs)
   }
 
   /**
@@ -3700,6 +3614,29 @@ class VelociousDatabaseRecord {
 
     await this._connection().query(sql, {logName: `${this.getModelClass().name} Destroy`})
     await this._runLifecycleCallbacks("afterDestroy")
+    await this._emitRecordChangeAfterCommit("destroy")
+  }
+
+  /**
+   * Emits a committed record-change event after the surrounding transaction
+   * commits, so live queries re-run uniformly for local writes, pull applies, and
+   * realtime applies (which all end as local saves/destroys). Registered through
+   * the connection's afterCommit hook so a rolled-back save emits nothing, and
+   * skipped entirely when nothing observes this model class so server-side saves
+   * stay free of live-query overhead.
+   * @param {import("../record-changes.js").RecordChangeOperation} operation - The committed operation.
+   * @returns {Promise<void>}
+   */
+  async _emitRecordChangeAfterCommit(operation) {
+    const modelClass = this.getModelClass()
+
+    if (!recordChanges.hasListeners(modelClass)) return
+
+    const record = this
+
+    await this._connection().afterCommit(() => {
+      recordChanges.emit({modelClass, operation, record})
+    })
   }
 
   /**