velocious 1.0.511 → 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/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

@@ -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"
@@ -2417,6 +2418,7 @@ class VelociousDatabaseRecord {
         await this._autoSaveHasManyAndHasOneRelationships({isNewRecord})
         await this._autoSaveAttachments()
         await this._runLifecycleCallbacks("afterSave")
+        await this._emitRecordChangeAfterCommit(isNewRecord ? "create" : "update")
       })
     })
 
@@ -3612,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})
+    })
   }
 
   /**

package/build/database/record-changes.js

@@ -0,0 +1,135 @@
+// @ts-check
+
+import EventEmitter from "../utils/event-emitter.js"
+
+/**
+ * RecordModelClass type.
+ * @typedef {typeof import("./record/index.js").default} RecordModelClass */
+
+/**
+ * RecordChangeOperation type.
+ * @typedef {"create" | "update" | "destroy"} RecordChangeOperation */
+
+/**
+ * RecordChangeEvent type.
+ * @typedef {object} RecordChangeEvent
+ * @property {RecordModelClass} modelClass - Model class whose row changed.
+ * @property {RecordChangeOperation} operation - The committed operation.
+ * @property {InstanceType<RecordModelClass>} record - The committed record instance.
+ */
+
+/**
+ * RecordChangeListener type.
+ * @typedef {(event: RecordChangeEvent) => void} RecordChangeListener */
+
+/**
+ * Framework-level bus for committed local model changes. Records emit here once
+ * per commit (see `VelociousDatabaseRecord.save`/`destroy`), so local writes,
+ * pull applies, and realtime applies converge on one uniform signal that live
+ * queries subscribe to. Emission is keyed by model name; a `batch(...)` window
+ * coalesces a burst of commits into a single event per model class.
+ */
+class RecordChanges {
+  /**
+   * Underlying event bus keyed by model name.
+   * @type {import("eventemitter3").EventEmitter} */
+  _emitter = new EventEmitter()
+
+  /**
+   * Number of open batch windows; while positive, emits buffer instead of dispatching.
+   * @type {number} */
+  _batchDepth = 0
+
+  /**
+   * Latest buffered event per model name, dispatched once when the outermost batch ends.
+   * @type {Map<string, RecordChangeEvent>} */
+  _bufferedEvents = new Map()
+
+  /**
+   * Subscribes a listener to committed changes of a model class.
+   * @param {RecordModelClass} modelClass - Model class to observe.
+   * @param {RecordChangeListener} listener - Listener called with each change event.
+   * @returns {() => void} Unsubscribe callback.
+   */
+  subscribe(modelClass, listener) {
+    const eventName = modelClass.getModelName()
+
+    this._emitter.on(eventName, listener)
+
+    return () => {
+      this._emitter.off(eventName, listener)
+    }
+  }
+
+  /**
+   * Whether any listener is currently observing the given model class. Callers on
+   * the write path use this to skip emitting entirely when nothing is watching,
+   * keeping server-side saves free of live-query overhead.
+   * @param {RecordModelClass} modelClass - Model class to check.
+   * @returns {boolean} Whether listeners exist for the model class.
+   */
+  hasListeners(modelClass) {
+    return this._emitter.listenerCount(modelClass.getModelName()) > 0
+  }
+
+  /**
+   * Emits a committed change. While a batch window is open the event is buffered
+   * and deduplicated by model class, so a batch of N commits dispatches a single
+   * event per model class when the outermost batch ends.
+   * @param {RecordChangeEvent} event - Change event to dispatch.
+   * @returns {void}
+   */
+  emit(event) {
+    if (this._batchDepth > 0) {
+      this._bufferedEvents.set(event.modelClass.getModelName(), event)
+
+      return
+    }
+
+    this._emitter.emit(event.modelClass.getModelName(), event)
+  }
+
+  /**
+   * Runs a callback with change dispatch coalesced: every change committed while
+   * the callback runs buffers, and the outermost batch flushes a single event per
+   * changed model class after it resolves. Nested batches share one flush. Sync
+   * appliers wrap their per-row apply loop in this so a large pull or realtime
+   * push triggers one re-run per live query instead of one per applied row.
+   * @template T
+   * @param {() => Promise<T> | T} callback - Work whose committed changes should coalesce.
+   * @returns {Promise<T>} The callback result.
+   */
+  async batch(callback) {
+    this._batchDepth++
+
+    try {
+      return await callback()
+    } finally {
+      this._batchDepth--
+
+      if (this._batchDepth === 0) this._flushBufferedEvents()
+    }
+  }
+
+  /**
+   * Dispatches and clears the buffered per-model events collected during a batch.
+   * @returns {void}
+   */
+  _flushBufferedEvents() {
+    const bufferedEvents = this._bufferedEvents
+
+    this._bufferedEvents = new Map()
+
+    for (const event of bufferedEvents.values()) {
+      this._emitter.emit(event.modelClass.getModelName(), event)
+    }
+  }
+}
+
+/**
+ * Shared singleton so record commits and live queries meet on one bus.
+ * @type {RecordChanges} */
+const recordChanges = new RecordChanges()
+
+export default recordChanges
+export {RecordChanges}

package/build/database/use-live-query.js

@@ -0,0 +1,118 @@
+// @ts-check
+
+import {useCallback, useEffect, useMemo, useRef, useSyncExternalStore} from "react"
+
+import LiveQuery from "./live-query.js"
+
+/**
+ * RecordModelClass type.
+ * @typedef {typeof import("./record/index.js").default} RecordModelClass */
+
+/**
+ * LiveQuerySource type.
+ * @template T
+ * @typedef {import("./live-query.js").LiveQuerySource<T>} LiveQuerySource */
+
+/**
+ * LiveQueryState type.
+ * @template T
+ * @typedef {import("./live-query.js").LiveQueryState<T>} LiveQueryState */
+
+/**
+ * UseLiveQueryOptions type.
+ * @typedef {object} UseLiveQueryOptions
+ * @property {boolean} [active] - Whether the query is active. Default true; pass false to pause and return the empty state.
+ * @property {number} [debounce] - Trailing debounce in ms for re-runs. Defaults to microtask coalescing.
+ * @property {RecordModelClass[]} [models] - Model classes to observe. Defaults to the query's model class; pass this to also react to joined models.
+ */
+
+/**
+ * Stable empty state returned while there is no active query, so a paused hook
+ * keeps a referentially stable snapshot for `useSyncExternalStore`.
+ * @type {LiveQueryState<?>} */
+const EMPTY_STATE = {error: null, loading: false, results: []}
+
+/**
+ * Assigns and stores a stable identity key for query sources without a `toSql`.
+ * @type {WeakMap<object, string>} */
+const queryIdentityKeys = new WeakMap()
+
+/**
+ * Monotonic counter backing the queryIdentityKeys registry.
+ * @type {number} */
+let nextQueryIdentity = 0
+
+/**
+ * Builds a dependency key identifying a query's semantics so the underlying
+ * controller is rebuilt when they change. Model-class queries expose `toSql`, so
+ * distinct conditions yield distinct keys; other sources fall back to a stable
+ * per-object identity (such sources must be memoized by the caller).
+ * @param {LiveQuerySource<?> & {toSql?: () => ?}} query - Query source.
+ * @param {RecordModelClass[] | undefined} models - Explicit model classes to observe.
+ * @returns {string} Dependency key.
+ */
+function liveQueryDependencyKey(query, models) {
+  const modelNames = (models ?? [query.getModelClass()]).map((modelClass) => modelClass.getModelName()).join(",")
+
+  if (typeof query.toSql === "function") return `${modelNames}::${String(query.toSql())}`
+
+  let identityKey = queryIdentityKeys.get(query)
+
+  if (identityKey === undefined) {
+    identityKey = `#${++nextQueryIdentity}`
+    queryIdentityKeys.set(query, identityKey)
+  }
+
+  return `${modelNames}::${identityKey}`
+}
+
+/**
+ * React hook declaring what a screen shows and keeping it current from committed
+ * local model changes. Runs `query.toArray()` once, subscribes to the query's
+ * model class(es) on the record-change bus, and re-runs (coalesced, stale-safe)
+ * whenever a watched model commits — so local writes, pull applies, and realtime
+ * applies all refresh the results without any manual refresh plumbing.
+ * @template T
+ * @param {(LiveQuerySource<T> & {toSql?: () => ?}) | null | undefined} query - Query source, e.g. `Model.where({...})`.
+ * @param {UseLiveQueryOptions} [options] - Hook options.
+ * @returns {LiveQueryState<T>} Current results, loading, and last error.
+ */
+export default function useLiveQuery(query, options = {}) {
+  const {active = true, debounce, models} = options
+  const enabled = active && Boolean(query)
+  const dependencyKey = enabled && query ? liveQueryDependencyKey(query, models) : "disabled"
+
+  const queryRef = useRef(query)
+  const modelsRef = useRef(models)
+
+  queryRef.current = query
+  modelsRef.current = models
+
+  const liveQuery = useMemo(() => {
+    if (!enabled || !queryRef.current) return null
+
+    return new LiveQuery({debounce, models: modelsRef.current, query: queryRef.current})
+  }, [dependencyKey, debounce, enabled])
+
+  useEffect(() => {
+    if (!liveQuery) return undefined
+
+    liveQuery.start()
+
+    return () => liveQuery.close()
+  }, [liveQuery])
+
+  const subscribe = useCallback((/** @type {() => void} */ listener) => {
+    if (!liveQuery) return () => {}
+
+    return liveQuery.subscribe(listener)
+  }, [liveQuery])
+
+  const getSnapshot = useCallback(() => {
+    if (!liveQuery) return /** @type {LiveQueryState<T>} */ (EMPTY_STATE)
+
+    return liveQuery.getState()
+  }, [liveQuery])
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+}