@livestore/react 0.3.0-dev.10 → 0.3.0-dev.12

package/src/__tests__/fixture.tsx

@@ -1,7 +1,7 @@
 import { provideOtel } from '@livestore/common'
 import { DbSchema, makeSchema } from '@livestore/common/schema'
 import type { LiveStoreContextRunning } from '@livestore/livestore'
-import { createStore, globalReactivityGraph, makeReactivityGraph } from '@livestore/livestore'
+import { createStore } from '@livestore/livestore'
 import { Effect } from '@livestore/utils/effect'
 import { makeInMemoryAdapter } from '@livestore/web'
 import type * as otel from '@opentelemetry/api'
@@ -42,7 +42,7 @@ export const app = DbSchema.table(
   { isSingleton: true },
 )
 
-export const AppComponentSchema = DbSchema.table(
+export const userInfo = DbSchema.table(
   'UserInfo',
   {
     username: DbSchema.text({ default: '' }),
@@ -59,18 +59,16 @@ export const AppRouterSchema = DbSchema.table(
   { isSingleton: true, deriveMutations: true },
 )
 
-export const tables = { todos, app, AppComponentSchema, AppRouterSchema }
+export const tables = { todos, app, userInfo, AppRouterSchema }
 export const schema = makeSchema({ tables })
 
 export const makeTodoMvcReact = ({
   otelTracer,
   otelContext,
-  useGlobalReactivityGraph = true,
   strictMode,
 }: {
   otelTracer?: otel.Tracer
   otelContext?: otel.Context
-  useGlobalReactivityGraph?: boolean
   strictMode?: boolean
 } = {}) =>
   Effect.gen(function* () {
@@ -89,13 +87,10 @@ export const makeTodoMvcReact = ({
       }
     }
 
-    const reactivityGraph = useGlobalReactivityGraph ? globalReactivityGraph : makeReactivityGraph()
-
     const store = yield* createStore({
       schema,
       storeId: 'default',
       adapter: makeInMemoryAdapter(),
-      reactivityGraph,
       debug: { instanceId: 'test' },
     })
 
@@ -112,5 +107,7 @@ export const makeTodoMvcReact = ({
       </MaybeStrictMode>
     )
 
-    return { wrapper, store, reactivityGraph, makeRenderCount }
+    const renderCount = makeRenderCount()
+
+    return { wrapper, store, renderCount }
   }).pipe(provideOtel({ parentSpanContext: otelContext, otelTracer }))

package/src/experimental/components/LiveList.tsx

@@ -1,9 +1,8 @@
-import type { LiveQuery } from '@livestore/livestore'
+import type { LiveQueryDef } from '@livestore/livestore'
 import { computed } from '@livestore/livestore'
 import React from 'react'
 
 import { useQuery } from '../../useQuery.js'
-import { useScopedQuery } from '../../useScopedQuery.js'
 
 /*
 TODO:
@@ -12,7 +11,7 @@ TODO:
 */
 
 export type LiveListProps<TItem> = {
-  items$: LiveQuery<ReadonlyArray<TItem>>
+  items$: LiveQueryDef<ReadonlyArray<TItem>>
   // TODO refactor render-flag to allow for transition animations on add/remove
   renderItem: (item: TItem, opts: { index: number; isInitialListRender: boolean }) => React.ReactNode
   /** Needs to be unique across all list items */
@@ -32,14 +31,16 @@ export const LiveList = <TItem,>({ items$, renderItem, getKey }: LiveListProps<T
 
   React.useEffect(() => setHasMounted(true), [])
 
-  const keysCb = React.useCallback(() => computed((get) => get(items$).map(getKey)), [getKey, items$])
-  const keys = useScopedQuery(keysCb, 'fixed')
+  const keys = useQuery(computed((get) => get(items$).map(getKey)))
   const arr = React.useMemo(
     () =>
       keys.map(
         (key) =>
           // TODO figure out a way so that `item$` returns an ordered lookup map to more efficiently find the item by key
-          [key, computed((get) => get(items$).find((item) => getKey(item, 0) === key)!) as LiveQuery<TItem>] as const,
+          [
+            key,
+            computed((get) => get(items$).find((item) => getKey(item, 0) === key)!) as LiveQueryDef<TItem>,
+          ] as const,
       ),
     [getKey, items$, keys],
   )
@@ -65,7 +66,7 @@ const ItemWrapper = <TItem,>({
   renderItem,
 }: {
   itemKey: string | number
-  item$: LiveQuery<TItem>
+  item$: LiveQueryDef<TItem>
   opts: { index: number; isInitialListRender: boolean }
   renderItem: (item: TItem, opts: { index: number; isInitialListRender: boolean }) => React.ReactNode
 }) => {

package/src/mod.ts

@@ -1,7 +1,6 @@
 export { LiveStoreContext, useStore } from './LiveStoreContext.js'
 export { LiveStoreProvider } from './LiveStoreProvider.js'
 export { useQuery } from './useQuery.js'
-export { useScopedQuery } from './useScopedQuery.js'
 export { useStackInfo } from './utils/stack-info.js'
 export {
   useRow,

package/src/useAtom.ts

@@ -1,7 +1,8 @@
 import type { DerivedMutationHelperFns, QueryInfo } from '@livestore/common'
 import type { DbSchema } from '@livestore/common/schema'
 import type { SqliteDsl } from '@livestore/db-schema'
-import type { LiveQuery } from '@livestore/livestore'
+import type { GetResult, LiveQueryDef, Store } from '@livestore/livestore'
+import { shouldNeverHappen } from '@livestore/utils'
 import React from 'react'
 
 import { useStore } from './LiveStoreContext.js'
@@ -10,18 +11,27 @@ import type { Dispatch, SetStateAction } from './useRow.js'
 
 export const useAtom = <
   // TODO also support colJsonValue
-  TQuery extends LiveQuery<any, QueryInfo.Row | QueryInfo.Col>,
+  TQuery extends LiveQueryDef<any, QueryInfo.Row | QueryInfo.Col>,
 >(
-  query$: TQuery,
-): [value: TQuery['__result!'], setValue: Dispatch<SetStateAction<Partial<TQuery['__result!']>>>] => {
-  const query$Ref = useQueryRef(query$)
+  queryDef: TQuery,
+  options?: {
+    store?: Store
+  },
+): [value: GetResult<TQuery>, setValue: Dispatch<SetStateAction<Partial<GetResult<TQuery>>>>] => {
+  const queryRef = useQueryRef(queryDef, { store: options?.store })
+  const query$ = queryRef.queryRcRef.value
+
+  // @ts-expect-error runtime check
+  if (query$.queryInfo._tag === 'None') {
+    shouldNeverHappen(`Can't useAtom with a query that has no queryInfo`, queryDef)
+  }
 
   const { store } = useStore()
 
   // TODO make API equivalent to useRow
-  const setValue = React.useMemo<Dispatch<SetStateAction<TQuery['__result!']>>>(() => {
-    return (newValueOrFn: any) => {
-      const newValue = typeof newValueOrFn === 'function' ? newValueOrFn(query$Ref.current) : newValueOrFn
+  const setValue = React.useMemo<Dispatch<SetStateAction<Partial<GetResult<TQuery>>>>>(
+    () => (newValueOrFn: any) => {
+      const newValue = typeof newValueOrFn === 'function' ? newValueOrFn(queryRef.valueRef.current) : newValueOrFn
       const table = query$.queryInfo.table as DbSchema.TableDef &
         DerivedMutationHelperFns<SqliteDsl.Columns, DbSchema.TableOptions>
 
@@ -45,8 +55,9 @@ export const useAtom = <
           )
         }
       }
-    }
-  }, [query$.queryInfo, query$Ref, store])
+    },
+    [query$.queryInfo, queryRef.valueRef, store],
+  )
 
-  return [query$Ref.current, setValue]
+  return [queryRef.valueRef.current, setValue]
 }

package/src/useQuery.test.tsx

@@ -1,82 +1,180 @@
-import { queryDb } from '@livestore/livestore'
+import { makeRef, queryDb } from '@livestore/livestore'
+import * as LiveStore from '@livestore/livestore'
+import { RG } from '@livestore/livestore/internal/testing-utils'
 import { Effect, Schema } from '@livestore/utils/effect'
-import { renderHook } from '@testing-library/react'
+import { Vitest } from '@livestore/utils/node-vitest'
+import * as ReactTesting from '@testing-library/react'
 import React from 'react'
-import { describe, expect, it } from 'vitest'
+// @ts-expect-error no types
+import * as ReactWindow from 'react-window'
+import { expect } from 'vitest'
 
 import { makeTodoMvcReact, tables, todos } from './__tests__/fixture.js'
 import * as LiveStoreReact from './mod.js'
+import { __resetUseRcResourceCache } from './useRcResource.js'
 
-describe('useQuery', () => {
-  it('simple', () =>
-    Effect.gen(function* () {
-      const { wrapper, store, makeRenderCount } = yield* makeTodoMvcReact()
+Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
+  'useQuery (strictMode=%s)',
+  ({ strictMode }) => {
+    Vitest.afterEach(() => {
+      RG.__resetIds()
+      __resetUseRcResourceCache()
+    })
 
-      const renderCount = makeRenderCount()
+    Vitest.scopedLive('simple', () =>
+      Effect.gen(function* () {
+        const { wrapper, store, renderCount } = yield* makeTodoMvcReact({ strictMode })
 
-      const allTodos$ = queryDb({ query: `select * from todos`, schema: Schema.Array(tables.todos.schema) })
+        const allTodos$ = queryDb({ query: `select * from todos`, schema: Schema.Array(tables.todos.schema) })
 
-      const { result } = renderHook(
-        () => {
-          renderCount.inc()
+        const { result } = ReactTesting.renderHook(
+          () => {
+            renderCount.inc()
 
-          return LiveStoreReact.useQuery(allTodos$)
-        },
-        { wrapper },
-      )
+            return LiveStoreReact.useQuery(allTodos$)
+          },
+          { wrapper },
+        )
 
-      expect(result.current.length).toBe(0)
-      expect(renderCount.val).toBe(1)
+        expect(result.current.length).toBe(0)
+        expect(renderCount.val).toBe(1)
+        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
 
-      React.act(() => store.mutate(todos.insert({ id: 't1', text: 'buy milk', completed: false })))
+        console.log('before mutation')
 
-      expect(result.current.length).toBe(1)
-      expect(result.current[0]!.text).toBe('buy milk')
-      expect(renderCount.val).toBe(2)
-    }).pipe(Effect.scoped, Effect.tapCauseLogPretty, Effect.runPromise))
+        ReactTesting.act(() => store.mutate(todos.insert({ id: 't1', text: 'buy milk', completed: false })))
 
-  it('same `useQuery` hook invoked with different queries', () =>
-    Effect.gen(function* () {
-      const { wrapper, store, makeRenderCount } = yield* makeTodoMvcReact()
+        console.log('after mutation')
 
-      const renderCount = makeRenderCount()
-
-      const todo1$ = queryDb(
-        { query: `select * from todos where id = 't1'`, schema: Schema.Array(tables.todos.schema) },
-        { label: 'libraryTracksView1' },
-      )
-      const todo2$ = queryDb(
-        { query: `select * from todos where id = 't2'`, schema: Schema.Array(tables.todos.schema) },
-        { label: 'libraryTracksView2' },
-      )
-
-      store.mutate(
-        todos.insert({ id: 't1', text: 'buy milk', completed: false }),
-        todos.insert({ id: 't2', text: 'buy eggs', completed: false }),
-      )
-
-      const { result, rerender } = renderHook(
-        (todoId: string) => {
-          renderCount.inc()
-
-          const query$ = React.useMemo(() => (todoId === 't1' ? todo1$ : todo2$), [todoId])
-
-          return LiveStoreReact.useQuery(query$)[0]!.text
-        },
-        { wrapper, initialProps: 't1' },
-      )
-
-      expect(result.current).toBe('buy milk')
-      expect(renderCount.val).toBe(1)
-
-      React.act(() => store.mutate(todos.update({ where: { id: 't1' }, values: { text: 'buy soy milk' } })))
-
-      expect(result.current).toBe('buy soy milk')
-      expect(renderCount.val).toBe(2)
-
-      rerender('t2')
-
-      expect(result.current).toBe('buy eggs')
-      expect(renderCount.val).toBe(3)
-    }).pipe(Effect.scoped, Effect.tapCauseLogPretty, Effect.runPromise))
-})
+        expect(result.current.length).toBe(1)
+        expect(result.current[0]!.text).toBe('buy milk')
+        expect(renderCount.val).toBe(2)
+        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+      }),
+    )
+
+    Vitest.scopedLive('same `useQuery` hook invoked with different queries', () =>
+      Effect.gen(function* () {
+        const { wrapper, store, renderCount } = yield* makeTodoMvcReact({ strictMode })
+
+        const todo1$ = queryDb(
+          { query: `select * from todos where id = 't1'`, schema: Schema.Array(tables.todos.schema) },
+          { label: 'libraryTracksView1' },
+        )
+        const todo2$ = queryDb(
+          { query: `select * from todos where id = 't2'`, schema: Schema.Array(tables.todos.schema) },
+          { label: 'libraryTracksView2' },
+        )
+
+        store.mutate(
+          todos.insert({ id: 't1', text: 'buy milk', completed: false }),
+          todos.insert({ id: 't2', text: 'buy eggs', completed: false }),
+        )
+
+        const { result, rerender } = ReactTesting.renderHook(
+          (todoId: string) => {
+            renderCount.inc()
+
+            const query$ = React.useMemo(() => (todoId === 't1' ? todo1$ : todo2$), [todoId])
+
+            return LiveStoreReact.useQuery(query$)[0]!.text
+          },
+          { wrapper, initialProps: 't1' },
+        )
+
+        expect(result.current).toBe('buy milk')
+        expect(renderCount.val).toBe(1)
+        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot('1: after first render')
+
+        ReactTesting.act(() => store.mutate(todos.update({ where: { id: 't1' }, values: { text: 'buy soy milk' } })))
+
+        expect(result.current).toBe('buy soy milk')
+        expect(renderCount.val).toBe(2)
+        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot('2: after first mutation')
+
+        rerender('t2')
+
+        expect(result.current).toBe('buy eggs')
+        expect(renderCount.val).toBe(3)
+        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot('3: after forced rerender')
+      }),
+    )
+
+    Vitest.scopedLive('filtered dependency query', () =>
+      Effect.gen(function* () {
+        const { wrapper, store, renderCount } = yield* makeTodoMvcReact({ strictMode })
+
+        const filter$ = makeRef('t1', { label: 'id-filter' })
+
+        const todo$ = queryDb((get) => tables.todos.query.where('id', get(filter$)), { label: 'todo' })
+
+        store.mutate(
+          todos.insert({ id: 't1', text: 'buy milk', completed: false }),
+          todos.insert({ id: 't2', text: 'buy eggs', completed: false }),
+        )
+
+        const { result } = ReactTesting.renderHook(
+          () => {
+            renderCount.inc()
+
+            return LiveStoreReact.useQuery(todo$)[0]!.text
+          },
+          { wrapper },
+        )
+
+        expect(result.current).toBe('buy milk')
+        expect(renderCount.val).toBe(1)
+        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+
+        ReactTesting.act(() => store.mutate(todos.update({ where: { id: 't1' }, values: { text: 'buy soy milk' } })))
+
+        expect(result.current).toBe('buy soy milk')
+        expect(renderCount.val).toBe(2)
+        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+
+        ReactTesting.act(() => store.setRef(filter$, 't2'))
+
+        expect(result.current).toBe('buy eggs')
+        expect(renderCount.val).toBe(3)
+        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+      }),
+    )
+
+    // NOTE this test covers some special react lifecyle paths which I couldn't easily reproduce without react-window
+    // it basically causes a "query swap" in the `useMemo` and both a `useEffect` cleanup call.
+    // To handle this properly we introduced the `_tag: 'destroyed'` state in the `spanAlreadyStartedCache`.
+    Vitest.scopedLive('should work for a list with react-window', () =>
+      Effect.gen(function* () {
+        const { wrapper } = yield* makeTodoMvcReact({ strictMode })
+
+        const ListWrapper: React.FC<{ numItems: number }> = ({ numItems }) => {
+          return (
+            <ReactWindow.FixedSizeList
+              height={100}
+              width={100}
+              itemSize={10}
+              itemCount={numItems}
+              itemData={Array.from({ length: numItems }, (_, i) => i).reverse()}
+            >
+              {ListItem}
+            </ReactWindow.FixedSizeList>
+          )
+        }
+
+        const ListItem: React.FC<{ data: ReadonlyArray<number>; index: number }> = ({ data: ids, index }) => {
+          const id = ids[index]!
+          const res = LiveStoreReact.useQuery(LiveStore.computed(() => id, { label: `ListItem.${id}`, deps: id }))
+          return <div role="listitem">{res}</div>
+        }
+
+        const renderResult = ReactTesting.render(<ListWrapper numItems={1} />, { wrapper })
+
+        expect(renderResult.container.textContent).toBe('0')
+
+        renderResult.rerender(<ListWrapper numItems={2} />)
+
+        expect(renderResult.container.textContent).toBe('10')
+      }),
+    )
+  },
+)

package/src/useQuery.ts

@@ -1,38 +1,51 @@
-import type { GetResult, LiveQueryAny } from '@livestore/livestore'
+import type { GetResult, LiveQuery, LiveQueryDef, LiveQueryDefAny, RcRef, Store } from '@livestore/livestore'
 import { extractStackInfoFromStackTrace, stackInfoToString } from '@livestore/livestore'
 import { deepEqual, indent } from '@livestore/utils'
 import * as otel from '@opentelemetry/api'
 import React from 'react'
 
 import { useStore } from './LiveStoreContext.js'
+import { useRcResource } from './useRcResource.js'
 import { originalStackLimit } from './utils/stack-info.js'
 import { useStateRefWithReactiveInput } from './utils/useStateRefWithReactiveInput.js'
 
 /**
- * NOTE Some folks have suggested to use `React.useSyncExternalStore`, however, it's not doing anything special
- * for what's needed here, so we handle everything manually.
- */
-
-/**
- * This is needed because the `React.useMemo` call below, can sometimes be called multiple times 🤷,
- * so we need to "cache" the fact that we've already started a span for this component.
- * The map entry is being removed again in the `React.useEffect` call below.
+ * Returns the result of a query and subscribes to future updates.
+ *
+ * Example:
+ * ```tsx
+ * const App = () => {
+ *   const todos = useQuery(queryDb(tables.todos.query.where({ complete: true })))
+ *   return <div>{todos.map((todo) => <div key={todo.id}>{todo.title}</div>)}</div>
+ * }
+ * ```
  */
-const spanAlreadyStartedCache = new Map<LiveQueryAny, { span: otel.Span; otelContext: otel.Context }>()
+export const useQuery = <TQuery extends LiveQueryDefAny>(
+  queryDef: TQuery,
+  options?: { store?: Store },
+): GetResult<TQuery> => useQueryRef(queryDef, options).valueRef.current
 
-export const useQuery = <TQuery extends LiveQueryAny>(query: TQuery): GetResult<TQuery> => useQueryRef(query).current
+type GetQueryInfo<TQuery extends LiveQueryDefAny> =
+  TQuery extends LiveQueryDef<infer _1, infer TQueryInfo> ? TQueryInfo : never
 
 /**
- *
  */
-export const useQueryRef = <TQuery extends LiveQueryAny>(
-  query$: TQuery,
-  parentOtelContext?: otel.Context,
-): React.RefObject<GetResult<TQuery>> => {
-  const { store } = useStore()
-
-  React.useDebugValue(`LiveStore:useQuery:${query$.id}:${query$.label}`)
-  // console.debug(`LiveStore:useQuery:${query$.id}:${query$.label}`)
+export const useQueryRef = <TQuery extends LiveQueryDefAny>(
+  queryDef: TQuery,
+  options?: {
+    store?: Store
+    /** Parent otel context for the query */
+    otelContext?: otel.Context
+    /** The name of the span to use for the query */
+    otelSpanName?: string
+  },
+): {
+  valueRef: React.RefObject<GetResult<TQuery>>
+  queryRcRef: RcRef<LiveQuery<GetResult<TQuery>, GetQueryInfo<TQuery>>>
+} => {
+  const { store } = useStore({ store: options?.store })
+
+  const rcRefKey = `${store.storeId}_${queryDef.hash}`
 
   const stackInfo = React.useMemo(() => {
     Error.stackTraceLimit = 10
@@ -42,31 +55,42 @@ export const useQueryRef = <TQuery extends LiveQueryAny>(
     return extractStackInfoFromStackTrace(stack)
   }, [])
 
-  // The following `React.useMemo` and `React.useEffect` calls are used to start and end a span for the lifetime of this component.
-  const { span, otelContext } = React.useMemo(() => {
-    const existingSpan = spanAlreadyStartedCache.get(query$)
-    if (existingSpan !== undefined) return existingSpan
+  const { queryRcRef, span, otelContext } = useRcResource(
+    rcRefKey,
+    () => {
+      const queryDefLabel = queryDef.label
+
+      const span = store.otel.tracer.startSpan(
+        options?.otelSpanName ?? `LiveStore:useQuery:${queryDefLabel}`,
+        { attributes: { label: queryDefLabel, firstStackInfo: JSON.stringify(stackInfo) } },
+        options?.otelContext ?? store.otel.queriesSpanContext,
+      )
 
-    const span = store.otel.tracer.startSpan(
-      `LiveStore:useQuery:${query$.label}`,
-      { attributes: { label: query$.label, stackInfo: JSON.stringify(stackInfo) } },
-      parentOtelContext ?? store.otel.queriesSpanContext,
-    )
+      const otelContext = otel.trace.setSpan(otel.context.active(), span)
 
-    const otelContext = otel.trace.setSpan(otel.context.active(), span)
+      const queryRcRef = queryDef.make(store.reactivityGraph.context!, otelContext)
 
-    spanAlreadyStartedCache.set(query$, { span, otelContext })
+      return { queryRcRef, span, otelContext }
+    },
+    // We need to keep the queryRcRef alive a bit longer, so we have a second `useRcResource` below
+    // which takes care of disposing the queryRcRef
+    () => {},
+  )
+  const query$ = queryRcRef.value as LiveQuery<GetResult<TQuery>, GetQueryInfo<TQuery>>
 
-    return { span, otelContext }
-  }, [parentOtelContext, query$, stackInfo, store.otel.queriesSpanContext, store.otel.tracer])
+  React.useDebugValue(`LiveStore:useQuery:${query$.id}:${query$.label}`)
+  // console.debug(`LiveStore:useQuery:${query$.id}:${query$.label}`)
 
   const initialResult = React.useMemo(() => {
     try {
-      return query$.run(otelContext, {
-        _tag: 'react',
-        api: 'useQuery',
-        label: query$.label,
-        stackInfo,
+      return query$.run({
+        otelContext,
+        debugRefreshReason: {
+          _tag: 'react',
+          api: 'useQuery',
+          label: `useQuery:initial-run:${query$.label}`,
+          stackInfo,
+        },
       })
     } catch (cause: any) {
       throw new Error(
@@ -89,25 +113,20 @@ Stack trace:
   // We know the query has a result by the time we use it; so we can synchronously populate a default state
   const [valueRef, setValue] = useStateRefWithReactiveInput<GetResult<TQuery>>(initialResult)
 
-  React.useEffect(
-    () => () => {
-      spanAlreadyStartedCache.delete(query$)
-      span.end()
-    },
-    [query$, span],
-  )
+  // TODO we probably need to change the order of `useEffect` calls, so we destroy the query at the end
+  // before calling the LS `onEffect` on it
 
   // Subscribe to future updates for this query
   React.useEffect(() => {
+    // TODO double check whether we still need `activeSubscriptions`
     query$.activeSubscriptions.add(stackInfo)
 
     // Dynamic queries only set their actual label after they've been run the first time,
     // so we're also updating the span name here.
-    span.updateName(`LiveStore:useQuery:${query$.label}`)
+    span.updateName(options?.otelSpanName ?? `LiveStore:useQuery:${query$.label}`)
 
-    return store.subscribe(
-      query$,
-      (newValue) => {
+    return store.subscribe(query$, {
+      onUpdate: (newValue) => {
         // NOTE: we return a reference to the result object within LiveStore;
         // this implies that app code must not mutate the results, or else
         // there may be weird reactivity bugs.
@@ -115,12 +134,23 @@ Stack trace:
           setValue(newValue)
         }
       },
-      () => {
+      onUnsubsubscribe: () => {
         query$.activeSubscriptions.delete(stackInfo)
       },
-      { label: query$.label, otelContext },
-    )
-  }, [stackInfo, query$, setValue, store, valueRef, otelContext, span])
+      label: query$.label,
+      otelContext,
+    })
+  }, [stackInfo, query$, setValue, store, valueRef, otelContext, span, options?.otelSpanName])
+
+  useRcResource(
+    rcRefKey,
+    () => ({ queryRcRef, span }),
+    ({ queryRcRef, span }) => {
+      // console.debug('deref', queryRcRef.value.id, queryRcRef.value.label)
+      queryRcRef.deref()
+      span.end()
+    },
+  )
 
-  return valueRef
+  return { valueRef, queryRcRef }
 }