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

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(() => {

package/src/useStore.ts

@@ -1,3 +1,4 @@
+import type { LiveStoreSchema } from '@livestore/common/schema'
 import type { Store } from '@livestore/livestore'
 import React from 'react'
 
@@ -6,16 +7,67 @@ import { LiveStoreContext } from './LiveStoreContext.ts'
 import { useClientDocument } from './useClientDocument.ts'
 import { useQuery } from './useQuery.ts'
 
-export const withReactApi = (store: Store): Store & ReactApi => {
+/**
+ * Augments a Store instance with React-specific methods (`useQuery`, `useClientDocument`).
+ *
+ * This is called automatically by `useStore()` and `LiveStoreProvider`. You typically
+ * don't need to call it directly unless you're building custom integrations.
+ *
+ * @example
+ * ```ts
+ * // Usually not needed—useStore() does this automatically
+ * const store = withReactApi(myStore)
+ * const todos = store.useQuery(tables.todos.all())
+ * ```
+ */
+export const withReactApi = <TSchema extends LiveStoreSchema>(store: Store<TSchema>): Store<TSchema> & ReactApi => {
   // @ts-expect-error TODO properly implement this
 
-  store.useQuery = (queryDef) => useQuery(queryDef, { store })
+  store.useQuery = (queryable) => useQuery(queryable, { store })
   // @ts-expect-error TODO properly implement this
 
   store.useClientDocument = (table, idOrOptions, options) => useClientDocument(table, idOrOptions, options, { store })
-  return store as Store & ReactApi
+  return store as Store<TSchema> & ReactApi
 }
 
+/**
+ * Returns the current Store instance from React context, augmented with React-specific methods.
+ *
+ * Use this hook when you need direct access to the Store for operations like
+ * `store.commit()`, `store.subscribe()`, or accessing `store.sessionId`.
+ *
+ * For reactive queries, prefer `useQuery()` or `useClientDocument()` which handle
+ * subscriptions and re-renders automatically.
+ *
+ * @example
+ * ```ts
+ * const MyComponent = () => {
+ *   const { store } = useStore()
+ *
+ *   const handleClick = () => {
+ *     store.commit(events.todoCreated({ id: nanoid(), text: 'New todo' }))
+ *   }
+ *
+ *   return <button onClick={handleClick}>Add Todo</button>
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Access store metadata
+ * const { store } = useStore()
+ * console.log('Session ID:', store.sessionId)
+ * console.log('Client ID:', store.clientId)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Use with an explicit store instance (bypasses context)
+ * const { store } = useStore({ store: myExternalStore })
+ * ```
+ *
+ * @throws Error if called outside of `<LiveStoreProvider>` or before the store is running
+ */
 export const useStore = (options?: { store?: Store }): { store: Store & ReactApi } => {
   if (options?.store !== undefined) {
     return { store: withReactApi(options.store) }