@livestore/react 0.4.0-dev.2 → 0.4.0-dev.20

package/src/useClientDocument.test.tsx

@@ -1,7 +1,8 @@
 /** biome-ignore-all lint/a11y/useValidAriaRole: not needed for testing */
 /** biome-ignore-all lint/a11y/noStaticElementInteractions: not needed for testing */
 import * as LiveStore from '@livestore/livestore'
-import { getSimplifiedRootSpan } from '@livestore/livestore/internal/testing-utils'
+import { StoreInternalsSymbol } from '@livestore/livestore'
+import { getAllSimplifiedRootSpans, getSimplifiedRootSpan } from '@livestore/livestore/internal/testing-utils'
 import { Effect, ReadonlyRecord, Schema } from '@livestore/utils/effect'
 import { Vitest } from '@livestore/utils-dev/node-vitest'
 import * as otel from '@opentelemetry/api'
@@ -10,9 +11,9 @@ import * as ReactTesting from '@testing-library/react'
 import type React from 'react'
 import { beforeEach, expect, it } from 'vitest'
 
-import { events, makeTodoMvcReact, tables } from './__tests__/fixture.js'
-import type * as LiveStoreReact from './mod.js'
-import { __resetUseRcResourceCache } from './useRcResource.js'
+import { events, makeTodoMvcReact, tables } from './__tests__/fixture.tsx'
+import type * as LiveStoreReact from './mod.ts'
+import { __resetUseRcResourceCache } from './useRcResource.ts'
 
 // const strictMode = process.env.REACT_STRICT_MODE !== undefined
 
@@ -39,12 +40,12 @@ Vitest.describe('useClientDocument', () => {
       expect(result.current.id).toBe('u1')
       expect(result.current.state.username).toBe('')
       expect(renderCount.val).toBe(1)
-      expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+      expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
       store.commit(tables.userInfo.set({ username: 'username_u2' }, 'u2'))
 
       rerender('u2')
 
-      expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+      expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
       expect(result.current.id).toBe('u2')
       expect(result.current.state.username).toBe('username_u2')
       expect(renderCount.val).toBe(2)
@@ -224,81 +225,110 @@ Vitest.describe('useClientDocument', () => {
     }),
   )
 
-  Vitest.describe('otel', () => {
-    it.each([{ strictMode: true }, { strictMode: false }])(
-      'should update the data based on component key strictMode=%s',
-      async ({ strictMode }) => {
-        const exporter = new InMemorySpanExporter()
+  Vitest.scopedLive('kv client document overwrites value (Schema.Any, no partial merge)', () =>
+    Effect.gen(function* () {
+      const { wrapper, store, renderCount } = yield* makeTodoMvcReact({})
 
-        const provider = new BasicTracerProvider({
-          spanProcessors: [new SimpleSpanProcessor(exporter)],
-        })
+      const { result } = ReactTesting.renderHook(
+        (id: string) => {
+          renderCount.inc()
+
+          const [state, setState] = store.useClientDocument(tables.kv, id)
+          return { state, setState, id }
+        },
+        { wrapper, initialProps: 'k1' },
+      )
+
+      expect(result.current.id).toBe('k1')
+      expect(result.current.state).toBe(null)
+      expect(renderCount.val).toBe(1)
 
-        const otelTracer = provider.getTracer(`testing-${strictMode ? 'strict' : 'non-strict'}`)
+      ReactTesting.act(() => result.current.setState(1))
+      expect(result.current.state).toEqual(1)
+      expect(renderCount.val).toBe(2)
+
+      ReactTesting.act(() => result.current.setState({ b: 2 }))
+      expect(result.current.state).toEqual({ b: 2 })
+      expect(renderCount.val).toBe(3)
+    }),
+  )
+
+  Vitest.describe('otel', () => {
+    it.each([
+      { strictMode: true },
+      { strictMode: false },
+    ])('should update the data based on component key strictMode=%s', async ({ strictMode }) => {
+      const exporter = new InMemorySpanExporter()
+
+      const provider = new BasicTracerProvider({
+        spanProcessors: [new SimpleSpanProcessor(exporter)],
+      })
+
+      const otelTracer = provider.getTracer(`testing-${strictMode ? 'strict' : 'non-strict'}`)
+
+      const span = otelTracer.startSpan('test-root')
+      const otelContext = otel.trace.setSpan(otel.context.active(), span)
+
+      await Effect.gen(function* () {
+        const { wrapper, store, renderCount } = yield* makeTodoMvcReact({
+          otelContext,
+          otelTracer,
+          strictMode,
+        })
 
-        const span = otelTracer.startSpan('test-root')
-        const otelContext = otel.trace.setSpan(otel.context.active(), span)
+        const { result, rerender, unmount } = ReactTesting.renderHook(
+          (userId: string) => {
+            renderCount.inc()
 
-        await Effect.gen(function* () {
-          const { wrapper, store, renderCount } = yield* makeTodoMvcReact({
-            otelContext,
-            otelTracer,
-            strictMode,
-          })
+            const [state, setState, id] = store.useClientDocument(tables.userInfo, userId)
+            return { state, setState, id }
+          },
+          { wrapper, initialProps: 'u1' },
+        )
 
-          const { result, rerender, unmount } = ReactTesting.renderHook(
-            (userId: string) => {
-              renderCount.inc()
+        expect(result.current.id).toBe('u1')
+        expect(result.current.state.username).toBe('')
+        expect(renderCount.val).toBe(1)
+
+        // For u2 we'll make sure that the row already exists,
+        // so the lazy `insert` will be skipped
+        ReactTesting.act(() => store.commit(events.UserInfoSet({ username: 'username_u2' }, 'u2')))
+
+        rerender('u2')
+
+        expect(result.current.id).toBe('u2')
+        expect(result.current.state.username).toBe('username_u2')
+        expect(renderCount.val).toBe(2)
+
+        unmount()
+        span.end()
+      }).pipe(Effect.scoped, Effect.tapCauseLogPretty, Effect.runPromise)
+
+      await provider.forceFlush()
+
+      const mapAttributes = (attributes: otel.Attributes) => {
+        return ReadonlyRecord.map(attributes, (val, key) => {
+          if (key === 'code.stacktrace') {
+            return '<STACKTRACE>'
+          } else if (key === 'firstStackInfo') {
+            const stackInfo = JSON.parse(val as string) as LiveStore.StackInfo
+            // stackInfo.frames.shift() // Removes `renderHook.wrapper` from the stack
+            stackInfo.frames.forEach((_) => {
+              if (_.name.includes('renderHook.wrapper')) {
+                _.name = 'renderHook.wrapper'
+              }
+              _.filePath = '__REPLACED_FOR_SNAPSHOT__'
+            })
+            return JSON.stringify(stackInfo)
+          }
+          return val
+        })
+      }
 
-              const [state, setState, id] = store.useClientDocument(tables.userInfo, userId)
-              return { state, setState, id }
-            },
-            { wrapper, initialProps: 'u1' },
-          )
+      expect(getSimplifiedRootSpan(exporter, 'createStore', mapAttributes)).toMatchSnapshot()
+      expect(getAllSimplifiedRootSpans(exporter, 'LiveStore:commit', mapAttributes)).toMatchSnapshot()
 
-          expect(result.current.id).toBe('u1')
-          expect(result.current.state.username).toBe('')
-          expect(renderCount.val).toBe(1)
-
-          // For u2 we'll make sure that the row already exists,
-          // so the lazy `insert` will be skipped
-          ReactTesting.act(() => store.commit(events.UserInfoSet({ username: 'username_u2' }, 'u2')))
-
-          rerender('u2')
-
-          expect(result.current.id).toBe('u2')
-          expect(result.current.state.username).toBe('username_u2')
-          expect(renderCount.val).toBe(2)
-
-          unmount()
-          span.end()
-        }).pipe(Effect.scoped, Effect.tapCauseLogPretty, Effect.runPromise)
-
-        await provider.forceFlush()
-
-        const mapAttributes = (attributes: otel.Attributes) => {
-          return ReadonlyRecord.map(attributes, (val, key) => {
-            if (key === 'code.stacktrace') {
-              return '<STACKTRACE>'
-            } else if (key === 'firstStackInfo') {
-              const stackInfo = JSON.parse(val as string) as LiveStore.StackInfo
-              // stackInfo.frames.shift() // Removes `renderHook.wrapper` from the stack
-              stackInfo.frames.forEach((_) => {
-                if (_.name.includes('renderHook.wrapper')) {
-                  _.name = 'renderHook.wrapper'
-                }
-                _.filePath = '__REPLACED_FOR_SNAPSHOT__'
-              })
-              return JSON.stringify(stackInfo)
-            }
-            return val
-          })
-        }
-
-        expect(getSimplifiedRootSpan(exporter, mapAttributes)).toMatchSnapshot()
-
-        await provider.shutdown()
-      },
-    )
+      await provider.shutdown()
+    })
   })
 })

package/src/useClientDocument.ts

@@ -3,13 +3,13 @@ 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 { omitUndefineds, shouldNeverHappen } from '@livestore/utils'
 import React from 'react'
 
 import { LiveStoreContext } from './LiveStoreContext.ts'
 import { useQueryRef } from './useQuery.ts'
 
-export type UseRowResult<TTableDef extends State.SQLite.ClientDocumentTableDef.TraitAny> = [
+export type UseClientDocumentResult<TTableDef extends State.SQLite.ClientDocumentTableDef.TraitAny> = [
   row: TTableDef['Value'],
   setRow: StateSetters<TTableDef>,
   id: string,
@@ -54,13 +54,17 @@ export const useClientDocument: {
       any,
       any,
       any,
-      { partialSet: boolean; default: { id: string | SessionIdSymbol; value: any } }
+      {
+        partialSet: boolean
+        /** Default value to use instead of the default value from the table definition */
+        default: any
+      }
     >,
   >(
     table: TTableDef,
     id?: State.SQLite.ClientDocumentTableDef.DefaultIdType<TTableDef> | SessionIdSymbol,
     options?: Partial<RowQuery.GetOrCreateOptions<TTableDef>>,
-  ): UseRowResult<TTableDef>
+  ): UseClientDocumentResult<TTableDef>
 
   // case: no default id → id arg is required
   <
@@ -68,20 +72,24 @@ export const useClientDocument: {
       any,
       any,
       any,
-      { partialSet: boolean; default: { id: string | SessionIdSymbol | undefined; value: any } }
+      {
+        partialSet: boolean
+        /** Default value to use instead of the default value from the table definition */
+        default: 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>
+  ): UseClientDocumentResult<TTableDef>
 } = <TTableDef extends State.SQLite.ClientDocumentTableDef.Any>(
   table: TTableDef,
   idOrOptions?: string | SessionIdSymbol,
   options_?: Partial<RowQuery.GetOrCreateOptions<TTableDef>>,
   storeArg?: { store?: Store },
-): UseRowResult<TTableDef> => {
+): UseClientDocumentResult<TTableDef> => {
   const id =
     typeof idOrOptions === 'string' || idOrOptions === SessionIdSymbol
       ? idOrOptions
@@ -97,14 +105,13 @@ export const useClientDocument: {
   const tableName = table.sqliteDef.name
 
   const store =
-    storeArg?.store ??
-    // biome-ignore lint/correctness/useHookAtTopLevel: store is stable
+    storeArg?.store ?? // biome-ignore lint/correctness/useHookAtTopLevel: store is stable
     React.useContext(LiveStoreContext)?.store ??
     shouldNeverHappen(`No store provided to useClientDocument`)
 
   // console.debug('useClientDocument', tableName, id)
 
-  const idStr: string = id === SessionIdSymbol ? store.clientSession.sessionId : id
+  const idStr: string = id === SessionIdSymbol ? store.sessionId : id
 
   type QueryDef = LiveQueryDef<TTableDef['Value']>
   const queryDef: QueryDef = React.useMemo(
@@ -117,7 +124,7 @@ export const useClientDocument: {
 
   const queryRef = useQueryRef(queryDef, {
     otelSpanName: `LiveStore:useClientDocument:${tableName}:${idStr}`,
-    store: storeArg?.store,
+    ...omitUndefineds({ store: storeArg?.store }),
   })
 
   const setState = React.useMemo<StateSetters<TTableDef>>(
@@ -134,10 +141,13 @@ export const useClientDocument: {
 }
 
 export type Dispatch<A> = (action: A) => void
-export type SetStateAction<S> = Partial<S> | ((previousValue: S) => Partial<S>)
+export type SetStateActionPartial<S> = Partial<S> | ((previousValue: S) => Partial<S>)
+export type SetStateAction<S> = S | ((previousValue: S) => S)
 
 export type StateSetters<TTableDef extends State.SQLite.ClientDocumentTableDef.TraitAny> = Dispatch<
-  SetStateAction<TTableDef['Value']>
+  TTableDef[State.SQLite.ClientDocumentTableDefSymbol]['options']['partialSet'] extends false
+    ? SetStateAction<TTableDef['Value']>
+    : SetStateActionPartial<TTableDef['Value']>
 >
 
 const validateTableOptions = (table: State.SQLite.TableDef<any, any>) => {

package/src/useQuery.test.tsx

@@ -1,6 +1,6 @@
 /** biome-ignore-all lint/a11y: test */
 import * as LiveStore from '@livestore/livestore'
-import { queryDb, signal } from '@livestore/livestore'
+import { queryDb, StoreInternalsSymbol, signal } from '@livestore/livestore'
 import { RG } from '@livestore/livestore/internal/testing-utils'
 import { Effect, Schema } from '@livestore/utils/effect'
 import { Vitest } from '@livestore/utils-dev/node-vitest'
@@ -10,8 +10,8 @@ import React from 'react'
 import * as ReactWindow from 'react-window'
 import { expect } from 'vitest'
 
-import { events, makeTodoMvcReact, tables } from './__tests__/fixture.js'
-import { __resetUseRcResourceCache } from './useRcResource.js'
+import { events, makeTodoMvcReact, tables } from './__tests__/fixture.tsx'
+import { __resetUseRcResourceCache } from './useRcResource.ts'
 
 Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
   'useQuery (strictMode=%s)',
@@ -38,14 +38,14 @@ Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
 
         expect(result.current.length).toBe(0)
         expect(renderCount.val).toBe(1)
-        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+        expect(store[StoreInternalsSymbol].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()
+        expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
       }),
     )
 
@@ -80,19 +80,25 @@ Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
 
         expect(result.current).toBe('buy milk')
         expect(renderCount.val).toBe(1)
-        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot('1: after first render')
+        expect(store[StoreInternalsSymbol].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')
+        expect(store[StoreInternalsSymbol].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')
+        expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot(
+          '3: after forced rerender',
+        )
       }),
     )
 
@@ -120,19 +126,19 @@ Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
 
         expect(result.current).toBe('buy milk')
         expect(renderCount.val).toBe(1)
-        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+        expect(store[StoreInternalsSymbol].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()
+        expect(store[StoreInternalsSymbol].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()
+        expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
       }),
     )
 
@@ -187,5 +193,50 @@ Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
         expect(result.current).toBe(1)
       }),
     )
+
+    Vitest.scopedLive('supports query builders directly', () =>
+      Effect.gen(function* () {
+        const { wrapper, store } = yield* makeTodoMvcReact({ strictMode })
+
+        store.commit(
+          events.todoCreated({ id: 't1', text: 'buy milk', completed: false }),
+          events.todoCreated({ id: 't2', text: 'buy eggs', completed: true }),
+        )
+
+        const todosWhereIncomplete = tables.todos.where({ completed: false })
+
+        const { result } = ReactTesting.renderHook(() => store.useQuery(todosWhereIncomplete).map((todo) => todo.id), {
+          wrapper,
+        })
+
+        expect(result.current).toEqual(['t1'])
+      }),
+    )
+
+    Vitest.scopedLive('union of different result types with useQuery', () =>
+      Effect.gen(function* () {
+        const { wrapper, store, renderCount } = yield* makeTodoMvcReact({ strictMode })
+
+        const str$ = signal('hello', { label: 'str' })
+        const num$ = signal(123, { label: 'num' })
+
+        const { result, rerender } = ReactTesting.renderHook(
+          (useNum: boolean) => {
+            renderCount.inc()
+            const query$ = React.useMemo(() => (useNum ? num$ : str$), [useNum])
+            return store.useQuery(query$)
+          },
+          { wrapper, initialProps: false },
+        )
+
+        expect(result.current).toBe('hello')
+        expect(renderCount.val).toBe(1)
+
+        rerender(true)
+
+        expect(result.current).toBe(123)
+        expect(renderCount.val).toBe(2)
+      }),
+    )
   },
 )

package/src/useQuery.ts

@@ -1,5 +1,14 @@
+import { isQueryBuilder } from '@livestore/common'
 import type { LiveQuery, LiveQueryDef, Store } from '@livestore/livestore'
-import { extractStackInfoFromStackTrace, stackInfoToString } from '@livestore/livestore'
+import {
+  extractStackInfoFromStackTrace,
+  isQueryable,
+  type Queryable,
+  queryDb,
+  type SignalDef,
+  StoreInternalsSymbol,
+  stackInfoToString,
+} from '@livestore/livestore'
 import type { LiveQueries } from '@livestore/livestore/internal'
 import { deepEqual, indent, shouldNeverHappen } from '@livestore/utils'
 import * as otel from '@opentelemetry/api'
@@ -21,15 +30,36 @@ import { useStateRefWithReactiveInput } from './utils/useStateRefWithReactiveInp
  * }
  * ```
  */
-export const useQuery = <TQuery extends LiveQueryDef.Any>(
-  queryDef: TQuery,
+export const useQuery = <TQueryable extends Queryable<any>>(
+  queryable: TQueryable,
   options?: { store?: Store },
-): LiveQueries.GetResult<TQuery> => useQueryRef(queryDef, options).valueRef.current
+): Queryable.Result<TQueryable> => useQueryRef(queryable, options).valueRef.current
 
 /**
+ * Like `useQuery`, but also returns a reference to the underlying LiveQuery instance.
+ *
+ * Usage
+ * - Accepts any `Queryable<TResult>`: a `LiveQueryDef`, `SignalDef`, a `LiveQuery` instance
+ *   or a SQL `QueryBuilder`. Unions of queryables are supported and the result type is
+ *   inferred via `Queryable.Result<TQueryable>`.
+ * - Creates an OpenTelemetry span per unique query, reusing it while the ref-counted
+ *   resource is alive. The span name is updated once the dynamic label is known.
+ * - Manages a reference-counted resource under-the-hood so query instances are shared
+ *   across re-renders and properly disposed once no longer referenced.
+ *
+ * Parameters
+ * - `queryable`: The query definition/instance/builder to run and subscribe to.
+ * - `options.store`: Optional store to use; by default the store from `LiveStoreContext` is used.
+ * - `options.otelContext`: Optional parent otel context for the query span.
+ * - `options.otelSpanName`: Optional explicit span name; otherwise derived from the query label.
+ *
+ * Returns
+ * - `valueRef`: A React ref whose `current` holds the latest query result. The type is
+ *   `Queryable.Result<TQueryable>` with full inference for unions.
+ * - `queryRcRef`: The underlying reference-counted `LiveQuery` instance used by the store.
  */
-export const useQueryRef = <TQuery extends LiveQueryDef.Any>(
-  queryDef: TQuery,
+export const useQueryRef = <TQueryable extends Queryable<any>>(
+  queryable: TQueryable,
   options?: {
     store?: Store
     /** Parent otel context for the query */
@@ -38,17 +68,50 @@ export const useQueryRef = <TQuery extends LiveQueryDef.Any>(
     otelSpanName?: string
   },
 ): {
-  valueRef: React.RefObject<LiveQueries.GetResult<TQuery>>
-  queryRcRef: LiveQueries.RcRef<LiveQuery<LiveQueries.GetResult<TQuery>>>
+  valueRef: React.RefObject<Queryable.Result<TQueryable>>
+  queryRcRef: LiveQueries.RcRef<LiveQuery<Queryable.Result<TQueryable>>>
 } => {
   const store =
-    options?.store ??
-    // biome-ignore lint/correctness/useHookAtTopLevel: store is stable
+    options?.store ?? // biome-ignore lint/correctness/useHookAtTopLevel: store is stable
     React.useContext(LiveStoreContext)?.store ??
     shouldNeverHappen(`No store provided to useQuery`)
 
+  type TResult = Queryable.Result<TQueryable>
+  type NormalizedQueryable =
+    | { _tag: 'definition'; def: LiveQueryDef<TResult> | SignalDef<TResult> }
+    | { _tag: 'live-query'; query$: LiveQuery<TResult> }
+
+  const normalized = React.useMemo<NormalizedQueryable>(() => {
+    if (!isQueryable(queryable)) {
+      return shouldNeverHappen('useQuery expected a Queryable value')
+    }
+
+    if (isQueryBuilder(queryable)) {
+      return { _tag: 'definition', def: queryDb(queryable) }
+    }
+
+    if (
+      (queryable as LiveQueryDef<TResult> | SignalDef<TResult>)._tag === 'def' ||
+      (queryable as LiveQueryDef<TResult> | SignalDef<TResult>)._tag === 'signal-def'
+    ) {
+      return { _tag: 'definition', def: queryable as LiveQueryDef<TResult> | SignalDef<TResult> }
+    }
+
+    return { _tag: 'live-query', query$: queryable as LiveQuery<TResult> }
+  }, [queryable])
+
   // 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 rcRefKey = React.useMemo(() => {
+    const base = `${store.storeId}_${store.clientId}_${store.sessionId}`
+
+    if (normalized._tag === 'definition') {
+      return `${base}:def:${normalized.def.hash}`
+    }
+
+    return `${base}:instance:${normalized.query$.id}`
+  }, [normalized, store.clientId, store.sessionId, store.storeId])
+
+  const resourceLabel = normalized._tag === 'definition' ? normalized.def.label : normalized.query$.label
 
   const stackInfo = React.useMemo(() => {
     Error.stackTraceLimit = 10
@@ -60,17 +123,22 @@ export const useQueryRef = <TQuery extends LiveQueryDef.Any>(
   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[StoreInternalsSymbol].otel.tracer.startSpan(
+        options?.otelSpanName ?? `LiveStore:useQuery:${resourceLabel}`,
+        { attributes: { label: resourceLabel, firstStackInfo: JSON.stringify(stackInfo) } },
+        options?.otelContext ?? store[StoreInternalsSymbol].otel.queriesSpanContext,
       )
 
       const otelContext = otel.trace.setSpan(otel.context.active(), span)
 
-      const queryRcRef = queryDef.make(store.reactivityGraph.context!, otelContext)
+      const queryRcRef =
+        normalized._tag === 'definition'
+          ? normalized.def.make(store[StoreInternalsSymbol].reactivityGraph.context!, otelContext)
+          : ({
+              value: normalized.query$,
+              deref: () => {},
+              rc: Number.POSITIVE_INFINITY,
+            } satisfies LiveQueries.RcRef<LiveQuery<TResult>>)
 
       return { queryRcRef, span, otelContext }
     },
@@ -83,7 +151,7 @@ export const useQueryRef = <TQuery extends LiveQueryDef.Any>(
   //   const  queryRcRef.value.get()
   // }
 
-  const query$ = queryRcRef.value as LiveQuery<LiveQueries.GetResult<TQuery>>
+  const query$ = queryRcRef.value as LiveQuery<TResult>
 
   React.useDebugValue(`LiveStore:useQuery:${query$.id}:${query$.label}`)
   // console.debug(`LiveStore:useQuery:${query$.id}:${query$.label}`)
@@ -119,7 +187,7 @@ 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<LiveQueries.GetResult<TQuery>>(initialResult)
+  const [valueRef, setValue] = useStateRefWithReactiveInput<TResult>(initialResult)
 
   // 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
@@ -133,8 +201,9 @@ Stack trace:
     // so we're also updating the span name here.
     span.updateName(options?.otelSpanName ?? `LiveStore:useQuery:${query$.label}`)
 
-    return store.subscribe(query$, {
-      onUpdate: (newValue) => {
+    return store.subscribe(
+      query$,
+      (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.
@@ -142,12 +211,14 @@ Stack trace:
           setValue(newValue)
         }
       },
-      onUnsubsubscribe: () => {
-        query$.activeSubscriptions.delete(stackInfo)
+      {
+        onUnsubsubscribe: () => {
+          query$.activeSubscriptions.delete(stackInfo)
+        },
+        label: query$.label,
+        otelContext,
       },
-      label: query$.label,
-      otelContext,
-    })
+    )
   }, [stackInfo, query$, setValue, store, valueRef, otelContext, span, options?.otelSpanName])
 
   useRcResource(

package/src/useRcResource.test.tsx

@@ -2,7 +2,7 @@ import * as ReactTesting from '@testing-library/react'
 import * as React from 'react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
-import { __resetUseRcResourceCache, useRcResource } from './useRcResource.js'
+import { __resetUseRcResourceCache, useRcResource } from './useRcResource.ts'
 
 describe.each([{ strictMode: true }, { strictMode: false }])('useRcResource (strictMode=%s)', ({ strictMode }) => {
   beforeEach(() => {