@livestore/react 0.3.0-dev.9 → 0.3.0

package/src/useClientDocument.ts

@@ -0,0 +1,157 @@
+import type { RowQuery } from '@livestore/common'
+import { SessionIdSymbol } from '@livestore/common'
+import { State } from '@livestore/common/schema'
+import type { LiveQuery, LiveQueryDef, Store } from '@livestore/livestore'
+import { queryDb } from '@livestore/livestore'
+import { shouldNeverHappen } from '@livestore/utils'
+import React from 'react'
+
+import { LiveStoreContext } from './LiveStoreContext.js'
+import { useQueryRef } from './useQuery.js'
+
+export type UseRowResult<TTableDef extends State.SQLite.ClientDocumentTableDef.TraitAny> = [
+  row: TTableDef['Value'],
+  setRow: StateSetters<TTableDef>,
+  id: string,
+  query$: LiveQuery<TTableDef['Value']>,
+]
+
+/**
+ * Similar to `React.useState` but returns a tuple of `[state, setState, id, query$]` for a given table where ...
+ *
+ *   - `state` is the current value of the row (fully decoded according to the table schema)
+ *   - `setState` is a function that can be used to update the document
+ *   - `id` is the id of the document
+ *   - `query$` is a `LiveQuery` that e.g. can be used to subscribe to changes to the document
+ *
+ * `useClientDocument` only works for client-document tables:
+ *
+ * ```tsx
+ * const MyState = State.SQLite.clientDocument({
+ *   name: 'MyState',
+ *   schema: Schema.Struct({
+ *     showSidebar: Schema.Boolean,
+ *   }),
+ *   default: { id: SessionIdSymbol, value: { showSidebar: true } },
+ * })
+ *
+ * const MyComponent = () => {
+ *   const [{ showSidebar }, setState] = useClientDocument(MyState)
+ *   return (
+ *     <div onClick={() => setState({ showSidebar: !showSidebar })}>
+ *       {showSidebar ? 'Sidebar is open' : 'Sidebar is closed'}
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * If the table has a default id, `useClientDocument` can be called without an `id` argument. Otherwise, the `id` argument is required.
+ */
+export const useClientDocument: {
+  // case: with default id
+  <
+    TTableDef extends State.SQLite.ClientDocumentTableDef.Trait<
+      any,
+      any,
+      any,
+      { partialSet: boolean; default: { id: string | SessionIdSymbol; value: any } }
+    >,
+  >(
+    table: TTableDef,
+    id?: State.SQLite.ClientDocumentTableDef.DefaultIdType<TTableDef> | SessionIdSymbol,
+    options?: Partial<RowQuery.GetOrCreateOptions<TTableDef>>,
+  ): UseRowResult<TTableDef>
+
+  // case: no default id → id arg is required
+  <
+    TTableDef extends State.SQLite.ClientDocumentTableDef.Trait<
+      any,
+      any,
+      any,
+      { partialSet: boolean; default: { id: string | SessionIdSymbol | undefined; value: any } }
+    >,
+  >(
+    table: TTableDef,
+    // TODO adjust so it works with arbitrary primary keys or unique constraints
+    id: State.SQLite.ClientDocumentTableDef.DefaultIdType<TTableDef> | string | SessionIdSymbol,
+    options?: Partial<RowQuery.GetOrCreateOptions<TTableDef>>,
+  ): UseRowResult<TTableDef>
+} = <TTableDef extends State.SQLite.ClientDocumentTableDef.Any>(
+  table: TTableDef,
+  idOrOptions?: string | SessionIdSymbol,
+  options_?: Partial<RowQuery.GetOrCreateOptions<TTableDef>>,
+  storeArg?: { store?: Store },
+): UseRowResult<TTableDef> => {
+  const id =
+    typeof idOrOptions === 'string' || idOrOptions === SessionIdSymbol
+      ? idOrOptions
+      : table[State.SQLite.ClientDocumentTableDefSymbol].options.default.id
+
+  const options: Partial<RowQuery.GetOrCreateOptions<TTableDef>> | undefined =
+    typeof idOrOptions === 'string' || idOrOptions === SessionIdSymbol ? options_ : idOrOptions
+
+  const { default: defaultValues } = options ?? {}
+
+  React.useMemo(() => validateTableOptions(table), [table])
+
+  const tableName = table.sqliteDef.name
+
+  const store =
+    storeArg?.store ??
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    React.useContext(LiveStoreContext)?.store ??
+    shouldNeverHappen(`No store provided to useClientDocument`)
+
+  // console.debug('useClientDocument', tableName, id)
+
+  const idStr: string = id === SessionIdSymbol ? store.clientSession.sessionId : id
+
+  type QueryDef = LiveQueryDef<TTableDef['Value']>
+  const queryDef: QueryDef = React.useMemo(
+    () =>
+      queryDb(table.get(id!, { default: defaultValues! }), {
+        deps: [idStr!, table.sqliteDef.name, JSON.stringify(defaultValues)],
+      }),
+    [table, id, defaultValues, idStr],
+  )
+
+  const queryRef = useQueryRef(queryDef, {
+    otelSpanName: `LiveStore:useClientDocument:${tableName}:${idStr}`,
+    store: storeArg?.store,
+  })
+
+  const setState = React.useMemo<StateSetters<TTableDef>>(
+    () => (newValueOrFn: TTableDef['Value']) => {
+      const newValue = typeof newValueOrFn === 'function' ? newValueOrFn(queryRef.valueRef.current) : newValueOrFn
+      if (queryRef.valueRef.current === newValue) return
+
+      store.commit(table.set(removeUndefinedValues(newValue), id as any))
+    },
+    [id, queryRef.valueRef, store, table],
+  )
+
+  return [queryRef.valueRef.current, setState, idStr, queryRef.queryRcRef.value]
+}
+
+export type Dispatch<A> = (action: A) => void
+export type SetStateAction<S> = Partial<S> | ((previousValue: S) => Partial<S>)
+
+export type StateSetters<TTableDef extends State.SQLite.ClientDocumentTableDef.TraitAny> = Dispatch<
+  SetStateAction<TTableDef['Value']>
+>
+
+const validateTableOptions = (table: State.SQLite.TableDef<any, any>) => {
+  if (State.SQLite.tableIsClientDocumentTable(table) === false) {
+    return shouldNeverHappen(
+      `useClientDocument called on table "${table.sqliteDef.name}" which is not a client document table`,
+    )
+  }
+}
+
+const removeUndefinedValues = (value: any) => {
+  if (typeof value === 'object' && value !== null) {
+    return Object.fromEntries(Object.entries(value).filter(([_, v]) => v !== undefined))
+  }
+
+  return value
+}

package/src/useQuery.test.tsx

@@ -1,82 +1,193 @@
-import { queryDb } from '@livestore/livestore'
+import '@livestore/utils-dev/node-vitest-polyfill'
+
+import { queryDb, signal } 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-dev/node-vitest'
+import * as ReactTesting from '@testing-library/react'
 import React from 'react'
-import { describe, expect, it } from 'vitest'
-
-import { makeTodoMvcReact, tables, todos } from './__tests__/fixture.js'
-import * as LiveStoreReact from './mod.js'
-
-describe('useQuery', () => {
-  it('simple', () =>
-    Effect.gen(function* () {
-      const { wrapper, store, makeRenderCount } = yield* makeTodoMvcReact()
-
-      const renderCount = makeRenderCount()
-
-      const allTodos$ = queryDb({ query: `select * from todos`, schema: Schema.Array(tables.todos.schema) })
-
-      const { result } = renderHook(
-        () => {
-          renderCount.inc()
-
-          return LiveStoreReact.useQuery(allTodos$)
-        },
-        { wrapper },
-      )
-
-      expect(result.current.length).toBe(0)
-      expect(renderCount.val).toBe(1)
-
-      React.act(() => store.mutate(todos.insert({ id: 't1', text: 'buy milk', completed: false })))
-
-      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))
-
-  it('same `useQuery` hook invoked with different queries', () =>
-    Effect.gen(function* () {
-      const { wrapper, store, makeRenderCount } = yield* makeTodoMvcReact()
-
-      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' },
-      )
+// @ts-expect-error no types
+import * as ReactWindow from 'react-window'
+import { expect } from 'vitest'
+
+import { events, makeTodoMvcReact, tables } from './__tests__/fixture.js'
+import { __resetUseRcResourceCache } from './useRcResource.js'
 
-      store.mutate(
-        todos.insert({ id: 't1', text: 'buy milk', completed: false }),
-        todos.insert({ id: 't2', text: 'buy eggs', completed: false }),
-      )
+Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
+  'useQuery (strictMode=%s)',
+  ({ strictMode }) => {
+    Vitest.afterEach(() => {
+      RG.__resetIds()
+      __resetUseRcResourceCache()
+    })
+
+    Vitest.scopedLive('simple', () =>
+      Effect.gen(function* () {
+        const { wrapper, store, renderCount } = yield* makeTodoMvcReact({ strictMode })
 
-      const { result, rerender } = renderHook(
-        (todoId: string) => {
-          renderCount.inc()
+        const allTodos$ = queryDb({ query: `select * from todos`, schema: Schema.Array(tables.todos.rowSchema) })
+
+        const { result } = ReactTesting.renderHook(
+          () => {
+            renderCount.inc()
 
-          const query$ = React.useMemo(() => (todoId === 't1' ? todo1$ : todo2$), [todoId])
+            return store.useQuery(allTodos$)
+          },
+          { wrapper },
+        )
 
-          return LiveStoreReact.useQuery(query$)[0]!.text
-        },
-        { wrapper, initialProps: 't1' },
-      )
+        expect(result.current.length).toBe(0)
+        expect(renderCount.val).toBe(1)
+        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+
+        ReactTesting.act(() => store.commit(events.todoCreated({ id: 't1', text: 'buy milk', completed: false })))
+
+        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.rowSchema) },
+          { label: 'libraryTracksView1' },
+        )
+        const todo2$ = queryDb(
+          { query: `select * from todos where id = 't2'`, schema: Schema.Array(tables.todos.rowSchema) },
+          { label: 'libraryTracksView2' },
+        )
+
+        store.commit(
+          events.todoCreated({ id: 't1', text: 'buy milk', completed: false }),
+          events.todoCreated({ 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 store.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.commit(events.todoUpdated({ id: 't1', 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 commit')
+
+        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$ = signal('t1', { label: 'id-filter' })
+
+        const todo$ = queryDb((get) => tables.todos.where('id', get(filter$)), { label: 'todo' })
+
+        store.commit(
+          events.todoCreated({ id: 't1', text: 'buy milk', completed: false }),
+          events.todoCreated({ id: 't2', text: 'buy eggs', completed: false }),
+        )
+
+        const { result } = ReactTesting.renderHook(
+          () => {
+            renderCount.inc()
+
+            return store.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.commit(events.todoUpdated({ id: 't1', 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.setSignal(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, store } = 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 = store.useQuery(LiveStore.computed(() => id, { label: `ListItem.${id}`, deps: id }))
+          // biome-ignore lint/a11y/useSemanticElements: <explanation>
+          return <div role="listitem">{res}</div>
+        }
 
-      expect(result.current).toBe('buy milk')
-      expect(renderCount.val).toBe(1)
+        const renderResult = ReactTesting.render(<ListWrapper numItems={1} />, { wrapper })
 
-      React.act(() => store.mutate(todos.update({ where: { id: 't1' }, values: { text: 'buy soy milk' } })))
+        expect(renderResult.container.textContent).toBe('0')
 
-      expect(result.current).toBe('buy soy milk')
-      expect(renderCount.val).toBe(2)
+        renderResult.rerender(<ListWrapper numItems={2} />)
 
-      rerender('t2')
+        expect(renderResult.container.textContent).toBe('10')
+      }),
+    )
+
+    Vitest.scopedLive('should work with signal', () =>
+      Effect.gen(function* () {
+        const { wrapper, store } = yield* makeTodoMvcReact({ strictMode })
+        const num$ = signal(0)
+
+        const { result } = ReactTesting.renderHook(() => store.useQuery(num$), { wrapper })
 
-      expect(result.current).toBe('buy eggs')
-      expect(renderCount.val).toBe(3)
-    }).pipe(Effect.scoped, Effect.tapCauseLogPretty, Effect.runPromise))
-})
+        expect(result.current).toBe(0)
+
+        ReactTesting.act(() => store.setSignal(num$, 1))
+
+        expect(result.current).toBe(1)
+      }),
+    )
+  },
+)

package/src/useQuery.ts

@@ -1,38 +1,52 @@
-import type { GetResult, LiveQueryAny } from '@livestore/livestore'
+/* eslint-disable react-hooks/rules-of-hooks */
+import type { LiveQuery, LiveQueryDef, Store } from '@livestore/livestore'
 import { extractStackInfoFromStackTrace, stackInfoToString } from '@livestore/livestore'
-import { deepEqual, indent } from '@livestore/utils'
+import type { LiveQueries } from '@livestore/livestore/internal'
+import { deepEqual, indent, shouldNeverHappen } from '@livestore/utils'
 import * as otel from '@opentelemetry/api'
 import React from 'react'
 
-import { useStore } from './LiveStoreContext.js'
+import { LiveStoreContext } 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 LiveQueryAny>(query: TQuery): GetResult<TQuery> => useQueryRef(query).current
+export const useQuery = <TQuery extends LiveQueryDef.Any>(
+  queryDef: TQuery,
+  options?: { store?: Store },
+): LiveQueries.GetResult<TQuery> => useQueryRef(queryDef, options).valueRef.current
 
 /**
- *
  */
-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 LiveQueryDef.Any>(
+  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<LiveQueries.GetResult<TQuery>>
+  queryRcRef: LiveQueries.RcRef<LiveQuery<LiveQueries.GetResult<TQuery>>>
+} => {
+  const store =
+    options?.store ?? React.useContext(LiveStoreContext)?.store ?? shouldNeverHappen(`No store provided to useQuery`)
+
+  // It's important to use all "aspects" of a store instance here, otherwise we get unexpected cache mappings
+  const rcRefKey = `${store.storeId}_${store.clientId}_${store.sessionId}_${queryDef.hash}`
 
   const stackInfo = React.useMemo(() => {
     Error.stackTraceLimit = 10
@@ -42,33 +56,50 @@ 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(
-      `LiveStore:useQuery:${query$.label}`,
-      { attributes: { label: query$.label, stackInfo: JSON.stringify(stackInfo) } },
-      parentOtelContext ?? store.otel.queriesSpanContext,
-    )
+      const span = store.otel.tracer.startSpan(
+        options?.otelSpanName ?? `LiveStore:useQuery:${queryDefLabel}`,
+        { attributes: { label: queryDefLabel, firstStackInfo: JSON.stringify(stackInfo) } },
+        options?.otelContext ?? store.otel.queriesSpanContext,
+      )
 
-    const otelContext = otel.trace.setSpan(otel.context.active(), span)
+      const otelContext = otel.trace.setSpan(otel.context.active(), span)
 
-    spanAlreadyStartedCache.set(query$, { span, otelContext })
+      const queryRcRef = queryDef.make(store.reactivityGraph.context!, otelContext)
 
-    return { span, otelContext }
-  }, [parentOtelContext, query$, stackInfo, store.otel.queriesSpanContext, store.otel.tracer])
+      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
+    () => {},
+  )
+
+  // if (queryRcRef.value._tag === 'signal') {
+  //   const  queryRcRef.value.get()
+  // }
+
+  const query$ = queryRcRef.value as LiveQuery<LiveQueries.GetResult<TQuery>>
+
+  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) {
+      console.error('[@livestore/react:useQuery] Error running query', cause)
       throw new Error(
         `\
 [@livestore/react:useQuery] Error running query: ${cause.name}
@@ -87,27 +118,22 @@ Stack trace:
   }, [otelContext, query$, stackInfo])
 
   // 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)
+  const [valueRef, setValue] = useStateRefWithReactiveInput<LiveQueries.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 +141,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 }
 }