TanStack / TanStack/db

Public hook or event for live-query graph runs (for performance attribution)

Open
#1,827 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
3.9k
Forks
266
Avg merge
1d 4h
Merged PRs (30d)
55

Description

Problem

We attribute main-thread long tasks to the sync stage that caused them using performance.mark pairs around our own collection commits (co:sync:commit:start/end). The other half of the picture, the time a commit spends re-running dependent live queries, has no public seam: CollectionConfigBuilder.executeGraphRun / maybeRunGraph run synchronously inside the source collection's commit and are private, and CollectionConfigBuilder is not re-exported from @tanstack/db.

What exists publicly today does not cover it:

  • createLiveQueryObserver subscribes to changes and status, not to the run itself.
  • createEffect's per-graph-run callback fires per effect query, so instrumenting it does not cover useLiveQuery / createLiveQueryCollection sites (we have ~65).
  • Collection events are status:change, subscribers:change, index:added, index:removed.

Patching the dist to wrap executeGraphRun works but is a vendor carry we do not want to maintain for a metric.

Request

A public, opt-in event around a live query's graph run, for example on the live query collection:

collection.on('graph:run', ({ id, durationMs, changes }) => { /* mark / measure */ })

or a global hook (onLiveQueryRun(listener)) that fires with { id, startTime, endTime } per executeGraphRun. Either lets consumers emit performance.mark pairs with detail: { collection: id } and lets DevTools-style tooling attribute long tasks to specific queries without touching internals.

Context

@tanstack/db 0.7.2. Related to the offset-regression issue we filed against electric-sql/electric#4806 in the same instrumentation effort.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing CollectionConfigBuilder.executeGraphRun and maybeRunGraph, then compare the proposed live-query collection event with the global onLiveQueryRun hook. Done means an opt-in public seam reports each graph run with timing and collection identity, covers useLiveQuery and createLiveQueryCollection, and avoids patching dist internals.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
observability, performance
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.