@livestore/livestore 0.0.19 → 0.0.22

package/src/react/{useLiveStoreComponent.ts → useComponentState.ts}

@@ -1,5 +1,4 @@
-import type { TypedDocumentNode as DocumentNode } from '@graphql-typed-document-node/core'
-import type { LiteralUnion, PrettifyFlat } from '@livestore/utils'
+import type { LiteralUnion } from '@livestore/utils'
 import { omit, shouldNeverHappen } from '@livestore/utils'
 import { Schema } from '@livestore/utils/effect'
 import * as otel from '@opentelemetry/api'
@@ -12,63 +11,21 @@ import { v4 as uuid } from 'uuid'
 import type { ComponentKey } from '../componentKey.js'
 import { labelForKey, tableNameForComponentKey } from '../componentKey.js'
 import { migrateTable } from '../migrations.js'
-import type { LiveStoreGraphQLQuery } from '../reactiveQueries/graphql.js'
-import type { LiveStoreJSQuery } from '../reactiveQueries/js.js'
-import type { LiveStoreSQLQuery } from '../reactiveQueries/sql.js'
+import { LiveStoreJSQuery } from '../reactiveQueries/js.js'
+import { LiveStoreSQLQuery } from '../reactiveQueries/sql.js'
 import { SCHEMA_META_TABLE } from '../schema.js'
-import type { BaseGraphQLContext, GetAtomResult, LiveStoreQuery, QueryResult, Store } from '../store.js'
-import type { Bindable } from '../util.js'
+import type { BaseGraphQLContext, LiveStoreQuery, Store } from '../store.js'
 import { sql } from '../util.js'
 import { useStore } from './LiveStoreContext.js'
+import { extractStackInfoFromStackTrace, originalStackLimit } from './utils/stack-info.js'
 import { useStateRefWithReactiveInput } from './utils/useStateRefWithReactiveInput.js'
 
 export interface QueryDefinitions {
   [queryName: string]: LiveStoreQuery
 }
 
-export type QueryResults<TQuery> = { [queryName in keyof TQuery]: PrettifyFlat<QueryResult<TQuery[queryName]>> }
-
-export type ReactiveSQL = <TResult>(
-  query: string | ((get: GetAtomResult) => string),
-  queriedTables: string[],
-  bindValues?: Bindable | undefined,
-) => LiveStoreSQLQuery<TResult>
-
-export type ReactiveJS = <TResult>(query: (get: GetAtomResult) => TResult) => LiveStoreJSQuery<TResult>
-
-export type ReactiveGraphQL = <
-  TResult extends Record<string, any>,
-  TVariables extends Record<string, any>,
-  TContext extends BaseGraphQLContext,
->(
-  query: DocumentNode<TResult, TVariables>,
-  variableValues: TVariables | ((get: GetAtomResult) => TVariables),
-  label?: string,
-) => LiveStoreGraphQLQuery<TResult, TVariables, TContext>
-
-type RegisterSubscription = <TQuery extends LiveStoreQuery>(
-  query: TQuery,
-  onNewValue: (value: QueryResult<TQuery>) => void,
-  onUnsubscribe?: () => void,
-) => void
-
-type GenQueries<TQueries, TStateResult> = (args: {
-  rxSQL: ReactiveSQL
-  rxGraphQL: ReactiveGraphQL
-  rxJS: ReactiveJS
-  state$: LiveStoreJSQuery<TStateResult>
-  /**
-   * Registers a subscription.
-   *
-   * Passed down for some manual subscribing. Use carefully.
-   */
-  subscribe: RegisterSubscription
-  isTemporaryQuery: boolean
-}) => TQueries
-
-export type UseLiveStoreComponentProps<TQueries, TStateColumns extends ComponentColumns> = {
-  stateSchema?: SqliteDsl.TableDefinition<string, TStateColumns>
-  queries?: GenQueries<TQueries, SqliteDsl.FromColumns.RowDecoded<TStateColumns>>
+export type UseComponentStateProps<TStateColumns extends ComponentColumns> = {
+  schema?: SqliteDsl.TableDefinition<string, TStateColumns>
   reactDeps?: React.DependencyList
   componentKey: ComponentKeyConfig
 }
@@ -119,13 +76,12 @@ export type GetStateTypeEncoded<TTableDef extends SqliteDsl.TableDefinition<any,
  * @param config.componentKey A function that returns a unique key for this component.
  * @param config.reactDeps A list of React-level dependencies that will refresh the queries.
  */
-export const useLiveStoreComponent = <TStateColumns extends ComponentColumns, TQueries extends QueryDefinitions>({
-  stateSchema: stateSchema_,
-  queries = () => ({}) as TQueries,
+export const useComponentState = <TStateColumns extends ComponentColumns>({
+  schema: stateSchema_,
   componentKey: componentKeyConfig,
   reactDeps = [],
-}: UseLiveStoreComponentProps<TQueries, TStateColumns>): {
-  queryResults: QueryResults<TQueries>
+}: UseComponentStateProps<TStateColumns>): {
+  state$: LiveStoreJSQuery<SqliteDsl.FromColumns.RowDecoded<TStateColumns>>
   state: SqliteDsl.FromColumns.RowDecoded<TStateColumns>
   setState: Setters<SqliteDsl.FromColumns.RowDecoded<TStateColumns>>
   useLiveStoreJsonState: UseLiveStoreJsonState<SqliteDsl.FromColumns.RowDecoded<TStateColumns>>
@@ -139,20 +95,27 @@ export const useLiveStoreComponent = <TStateColumns extends ComponentColumns, TQ
     [stateSchema_],
   )
 
-  // performance.mark('useLiveStoreComponent:start')
   const componentKey = useComponentKey(componentKeyConfig, reactDeps)
   const { store } = useStore()
 
   const componentKeyLabel = React.useMemo(() => labelForKey(componentKey), [componentKey])
 
+  const stackInfo = React.useMemo(() => {
+    Error.stackTraceLimit = 10
+    // eslint-disable-next-line unicorn/error-message
+    const stack = new Error().stack!
+    Error.stackTraceLimit = originalStackLimit
+    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(componentKeyLabel)
     if (existingSpan !== undefined) return existingSpan
 
     const span = store.otel.tracer.startSpan(
-      `LiveStore:useLiveStoreComponent:${componentKeyLabel}`,
-      {},
+      `LiveStore:useComponentState:${componentKeyLabel}`,
+      { attributes: { stackInfo: JSON.stringify(stackInfo) } },
       store.otel.queriesSpanContext,
     )
 
@@ -161,7 +124,7 @@ export const useLiveStoreComponent = <TStateColumns extends ComponentColumns, TQ
     spanAlreadyStartedCache.set(componentKeyLabel, { span, otelContext })
 
     return { span, otelContext }
-  }, [componentKeyLabel, store.otel.queriesSpanContext, store.otel.tracer])
+  }, [componentKeyLabel, stackInfo, store.otel.queriesSpanContext, store.otel.tracer])
 
   React.useEffect(
     () => () => {
@@ -171,44 +134,6 @@ export const useLiveStoreComponent = <TStateColumns extends ComponentColumns, TQ
     [componentKeyLabel, span],
   )
 
-  const generateQueries = React.useCallback(
-    ({
-      state$,
-      otelContext,
-      registerSubscription,
-      isTemporaryQuery,
-    }: {
-      state$: LiveStoreJSQuery<TComponentState>
-      otelContext: otel.Context
-      registerSubscription: RegisterSubscription
-      isTemporaryQuery: boolean
-    }) =>
-      queries({
-        rxSQL: <T>(
-          genQuery: string | ((get: GetAtomResult) => string),
-          queriedTables: string[],
-          bindValues?: Bindable,
-        ) => store.querySQL<T>(genQuery, { queriedTables, bindValues, otelContext, componentKey }),
-        rxGraphQL: <Result extends Record<string, any>, Variables extends Record<string, any>>(
-          query: DocumentNode<Result, Variables>,
-          genVariableValues: Variables | ((get: GetAtomResult) => Variables),
-          label?: string,
-        ) => store.queryGraphQL(query, genVariableValues, { componentKey, label, otelContext }),
-        rxJS: <T>(genQuery: (get: GetAtomResult) => T) => store.queryJS(genQuery, { componentKey, otelContext }),
-        state$,
-        subscribe: registerSubscription,
-        isTemporaryQuery,
-      }),
-
-    // NOTE: we don't include the queries function passed in by the user here;
-    // the reason is that we don't want to force them to memoize that function.
-    // Instead, we just assume that the function always has the same contents.
-    // This makes sense for LiveStore because the component config should be static.
-    // TODO: document this and consider whether it's the right API surface.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [store, componentKey],
-  )
-
   const defaultComponentState = React.useMemo(() => {
     const defaultState = (
       stateSchema === undefined ? {} : mapValues(stateSchema.columns, (c) => c.default)
@@ -225,100 +150,70 @@ export const useLiveStoreComponent = <TStateColumns extends ComponentColumns, TQ
     [stateSchema],
   )
 
-  // Step 1:
-  // Synchronously create state and queries for initial render pass.
-  // We do this in a temporary query context which cleans up after itself, making it idempotent
-  // TODO get rid of the temporary query workaround
-  const { initialComponentState, initialQueryResults } = React.useMemo(() => {
-    return store.otel.tracer.startActiveSpan('LiveStore:useLiveStoreComponent:initial', {}, otelContext, (span) => {
-      const otelContext = otel.trace.setSpan(otel.context.active(), span)
-
-      // NOTE `inTempQueryContext` automatically destroys the queries once the callback is done
-      return store.inTempQueryContext(() => {
-        try {
-          // create state query
-          let state$: LiveStoreJSQuery<TComponentState>
-          if (stateSchema === undefined) {
-            // TODO don't set up a query if there's no state schema (keeps the graph more clean)
-            state$ = store.queryJS(() => ({}), {
-              componentKey,
-              otelContext,
-            }) as unknown as LiveStoreJSQuery<TComponentState>
-          } else {
-            const componentTableName = tableNameForComponentKey(componentKey)
-            const whereClause = componentKey._tag === 'singleton' ? '' : `where id = '${componentKey.id}'`
-
-            // TODO find a better solution for this
-            if (store.tableRefs[componentTableName] === undefined) {
-              const schemaHash = SqliteAst.hash(stateSchema.ast)
-              const res = store.inMemoryDB.select<{ schemaHash: number }>(
-                sql`SELECT schemaHash FROM ${SCHEMA_META_TABLE} WHERE tableName = '${componentTableName}'`,
-              )
-              if (res.length === 0 || res[0]!.schemaHash !== schemaHash) {
-                migrateTable({ db: store._proxyDb, tableDef: stateSchema.ast, otelContext, schemaHash })
-              }
+  const state$ = React.useMemo(() => {
+    // create state query
+    if (stateSchema === undefined) {
+      // TODO don't set up a query if there's no state schema (keeps the graph more clean)
+      return new LiveStoreJSQuery({
+        fn: () => ({}) as TComponentState,
+        label: 'empty-component-state',
+        // otelContext,
+        // otelTracer: store.otel.tracer,
+      })
+    } else {
+      const componentTableName = tableNameForComponentKey(componentKey)
+      const whereClause = componentKey._tag === 'singleton' ? '' : `where id = '${componentKey.id}'`
+
+      // TODO find a better solution for this
+      if (store.tableRefs[componentTableName] === undefined) {
+        const schemaHash = SqliteAst.hash(stateSchema.ast)
+        const res = store.inMemoryDB.select<{ schemaHash: number }>(
+          sql`SELECT schemaHash FROM ${SCHEMA_META_TABLE} WHERE tableName = '${componentTableName}'`,
+        )
+        if (res.length === 0 || res[0]!.schemaHash !== schemaHash) {
+          migrateTable({ db: store._proxyDb, tableDef: stateSchema.ast, otelContext, schemaHash })
+        }
 
-              store.tableRefs[componentTableName] = store.graph.makeRef(null, {
-                equal: () => false,
-                label: componentTableName,
-                meta: { liveStoreRefType: 'table' },
-              })
-            }
-
-            state$ = store
-              .querySQL(() => sql`select * from ${componentTableName} ${whereClause} limit 1`, {
-                queriedTables: [componentTableName],
-                componentKey,
-                label: `localState:query:${componentKeyLabel}`,
-                otelContext,
-              })
-              // TODO consider to instead of just returning the default value, to write the default component state to the DB
-              .pipe<TComponentState>((results) =>
-                results.length === 1
-                  ? Schema.parseSync(componentStateEffectSchema)(results[0]!)
-                  : defaultComponentState,
-              )
-          }
-          const initialComponentState = state$.results$.result
+        store.tableRefs[componentTableName] = store.graph.makeRef(null, {
+          equal: () => false,
+          label: componentTableName,
+          meta: { liveStoreRefType: 'table' },
+        })
+      }
 
-          const queries = generateQueries({
-            state$: state$,
-            otelContext,
-            registerSubscription: () => {},
-            isTemporaryQuery: true,
-          })
-          for (const [name, query] of Object.entries(queries)) {
-            query.label = name
-          }
-          const initialQueryResults = mapValues(
-            queries,
-            (query) => query.results$.result,
-            // TODO improve typing
-          ) as unknown as QueryResults<TQueries>
-
-          return { initialComponentState, initialQueryResults }
-        } finally {
-          span.end()
-        }
-      })
-    })
+      return (
+        new LiveStoreSQLQuery({
+          label: `localState:query:${componentKeyLabel}`,
+          genQueryString: () => sql`select * from ${componentTableName} ${whereClause} limit 1`,
+          queriedTables: [componentTableName],
+        })
+          // TODO consider to instead of just returning the default value, to write the default component state to the DB
+          .pipe<TComponentState>((results) =>
+            results.length === 1 ? Schema.parseSync(componentStateEffectSchema)(results[0]!) : defaultComponentState,
+          )
+      )
+    }
   }, [
-    store,
-    otelContext,
-    stateSchema,
-    generateQueries,
     componentKey,
     componentKeyLabel,
     componentStateEffectSchema,
     defaultComponentState,
+    otelContext,
+    stateSchema,
+    store,
   ])
 
+  // Step 1:
+  // Synchronously create state and queries for initial render pass.
+  const initialComponentState = React.useMemo(
+    () => state$.run(otelContext, { _tag: 'react', api: 'useComponentState', label: state$.label, stackInfo }),
+    [otelContext, stackInfo, state$],
+  )
+
   // Now that we've computed the initial state synchronously,
   // we can set up our useState calls w/ a default value populated...
   const [componentStateRef, setComponentState_] = useStateRefWithReactiveInput<TComponentState>(initialComponentState)
 
-  const [queryResultsRef, setQueryResults_] = useStateRefWithReactiveInput<QueryResults<TQueries>>(initialQueryResults)
-
   const setState = (
     stateSchema === undefined
       ? {}
@@ -359,40 +254,19 @@ export const useLiveStoreComponent = <TStateColumns extends ComponentColumns, TQ
   // time to set up our long-running queries in an effect
   React.useEffect(() => {
     return store.otel.tracer.startActiveSpan(
-      'LiveStore:useLiveStoreComponent:long-running',
+      'LiveStore:useComponentState:long-running',
       { attributes: {} },
       otelContext,
       (span) => {
-        const otelContext = otel.trace.setSpan(otel.context.active(), span)
         const unsubs: (() => void)[] = []
 
-        // create state query
-        let state$: LiveStoreJSQuery<TComponentState>
-        if (stateSchema === undefined) {
-          // TODO remove this query
-          state$ = store.queryJS(() => ({}) as TComponentState, {
-            componentKey,
-            otelContext,
-            label: 'empty-component-state',
-          })
-        } else {
-          const componentTableName = tableNameForComponentKey(componentKey)
-          insertRowForComponentInstance({ store, componentKey, stateSchema })
-
-          const whereClause = componentKey._tag === 'singleton' ? '' : `where id = '${componentKey.id}'`
-          state$ = store
-            .querySQL<TComponentState>(() => sql`select * from ${componentTableName} ${whereClause} limit 1`, {
-              queriedTables: [componentTableName],
-              componentKey,
-              label: `localState:query:${componentKeyLabel}`,
-              otelContext,
-            })
-            // TODO consider to instead of just returning the default value, to write the default component state to the DB
-            .pipe<TComponentState>((results) =>
-              results.length === 1 ? Schema.parseSync(componentStateEffectSchema)(results[0]!) : defaultComponentState,
-            )
+        const otelContext = otel.trace.setSpan(otel.context.active(), span)
+        if (stateSchema !== undefined) {
+          insertRowForComponentInstance({ store, componentKey, stateSchema, otelContext })
         }
 
+        state$.activeSubscriptions.add(stackInfo)
+
         unsubs.push(
           store.subscribe(
             state$,
@@ -402,44 +276,11 @@ export const useLiveStoreComponent = <TStateColumns extends ComponentColumns, TQ
               }
             },
             undefined,
-            { label: `useLiveStoreComponent:localState:subscribe:${state$.label}` },
+            { label: `useComponentState:localState:subscribe:${state$.label}`, otelContext },
           ),
+          () => state$.activeSubscriptions.delete(stackInfo),
         )
 
-        const registerSubscription: RegisterSubscription = (query$, callback, onUnsubscribe) => {
-          unsubs.push(
-            store.subscribe(
-              query$,
-              (results) => {
-                callback(results)
-              },
-              onUnsubscribe,
-              { label: `useLiveStoreComponent:query:manual-subscribe:${query$.label}` },
-            ),
-          )
-        }
-
-        const queries = generateQueries({ state$, otelContext, registerSubscription, isTemporaryQuery: false })
-
-        for (const [key, query] of Object.entries(queries)) {
-          // Use the field name given to this query in the useQueries hook as its label
-          query.label = key
-
-          unsubs.push(
-            store.subscribe(
-              query,
-              (results) => {
-                const newQueryResults = { ...queryResultsRef.current, [key]: results }
-                if (isEqual(newQueryResults, queryResultsRef.current) === false) {
-                  setQueryResults_(newQueryResults)
-                }
-              },
-              undefined,
-              { label: `useLiveStoreComponent:query:subscribe:${query.label}` },
-            ),
-          )
-        }
-
         return () => {
           for (const unsub of unsubs) {
             unsub()
@@ -449,26 +290,19 @@ export const useLiveStoreComponent = <TStateColumns extends ComponentColumns, TQ
         }
       },
     )
-    // NOTE excluding `setComponentState_` and `setQueryResults_` from the deps array as it seems to cause an infinite loop
-    // This should probably be improved
-    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [
     store,
-    componentKey,
+    stackInfo,
     stateSchema,
     defaultComponentState,
-    generateQueries,
     otelContext,
     componentStateRef,
-    // setComponentState_,
-    // setQueryResults_,
+    state$,
+    setComponentState_,
+    componentKey,
   ])
 
-  // Very important: remove any queries / other resources associated w/ this component
-  React.useEffect(() => () => store.unmountComponent(componentKey), [store, componentKey])
-
-  // performance.mark('useLiveStoreComponent:end')
-  // performance.measure(`useLiveStoreComponent:${componentKey.type}`, 'useLiveStoreComponent:start', 'useLiveStoreComponent:end')
+  React.useEffect(() => () => state$.destroy(), [state$])
 
   const state = componentStateRef.current
 
@@ -498,7 +332,7 @@ export const useLiveStoreComponent = <TStateColumns extends ComponentColumns, TQ
   }
 
   return {
-    queryResults: queryResultsRef.current,
+    state$,
     state,
     setState,
     useLiveStoreJsonState,
@@ -535,10 +369,12 @@ const insertRowForComponentInstance = ({
   store,
   componentKey,
   stateSchema,
+  otelContext,
 }: {
   store: Store<BaseGraphQLContext>
   componentKey: ComponentKey
   stateSchema: SqliteDsl.TableDefinition<string, SqliteDsl.Columns>
+  otelContext: otel.Context
 }) => {
   const columnNames = ['id', ...Object.keys(stateSchema.columns)]
   const columnValues = columnNames.map((name) => `$${name}`).join(', ')
@@ -555,6 +391,7 @@ const insertRowForComponentInstance = ({
       id: componentKey.id,
     },
     [tableName],
+    otelContext,
   )
 }
 

package/src/react/useQuery.ts

@@ -1,56 +1,90 @@
+import * as otel from '@opentelemetry/api'
+import { isEqual } from 'lodash-es'
 import React from 'react'
 
-import { labelForKey } from '../componentKey.js'
-import type { QueryDefinition } from '../effect/LiveStore.js'
-import type { LiveStoreQuery, QueryResult, Store } from '../store.js'
+import type { ILiveStoreQuery } from '../reactiveQueries/base-class.js'
 import { useStore } from './LiveStoreContext.js'
+import { extractStackInfoFromStackTrace, originalStackLimit } from './utils/stack-info.js'
+import { useStateRefWithReactiveInput } from './utils/useStateRefWithReactiveInput.js'
+/**
+ * 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.
+ */
+const spanAlreadyStartedCache = new Map<ILiveStoreQuery<any>, { span: otel.Span; otelContext: otel.Context }>()
 
-// TODO get rid of the query cache in favour of the new side-effect-free query definition approach https://www.notion.so/schickling/New-query-definition-approach-1097a78ef0e9495bac25f90417374756?pvs=4
-const queryCache = new Map<QueryDefinition, LiveStoreQuery>()
-
-export const useQuery = <Q extends LiveStoreQuery>(queryDef: (store: Store) => Q): QueryResult<Q> => {
+export const useQuery = <TResult>(query: ILiveStoreQuery<TResult>): TResult => {
   const { store } = useStore()
-  const query = React.useMemo(() => {
-    if (queryCache.has(queryDef)) return queryCache.get(queryDef) as Q
 
-    const query = queryDef(store)
-    queryCache.set(queryDef, query)
-    return query
-  }, [store, queryDef])
+  const stackInfo = React.useMemo(() => {
+    Error.stackTraceLimit = 10
+    // eslint-disable-next-line unicorn/error-message
+    const stack = new Error().stack!
+    Error.stackTraceLimit = originalStackLimit
+    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 span = store.otel.tracer.startSpan(
+      `LiveStore:useQuery:${query.label}`,
+      { attributes: { label: query.label, stackInfo: JSON.stringify(stackInfo) } },
+      store.otel.queriesSpanContext,
+    )
+
+    const otelContext = otel.trace.setSpan(otel.context.active(), span)
+
+    spanAlreadyStartedCache.set(query, { span, otelContext })
+
+    return { span, otelContext }
+  }, [query, stackInfo, store.otel.queriesSpanContext, store.otel.tracer])
+
+  const initialResult = React.useMemo(
+    () =>
+      query.run(otelContext, {
+        _tag: 'react',
+        api: 'useQuery',
+        label: query.label,
+        stackInfo,
+      }),
+    [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 [value, setValue] = React.useState<QueryResult<Q>>(query.results$.result)
+  const [valueRef, setValue] = useStateRefWithReactiveInput<TResult>(initialResult)
+
+  React.useEffect(
+    () => () => {
+      spanAlreadyStartedCache.delete(query)
+      span.end()
+    },
+    [query, span],
+  )
 
   // Subscribe to future updates for this query
   React.useEffect(() => {
-    return store.otel.tracer.startActiveSpan(
-      `LiveStore:useQuery:${labelForKey(query.componentKey)}:${query.label}`,
-      { attributes: { label: query.label } },
-      query.otelContext,
-      (span) => {
-        const cancel = store.subscribe(
-          query,
-          (v) => {
-            // 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.
-            return setValue(v)
-          },
-          undefined,
-          { label: query.label },
-        )
-        return () => {
-          // // NOTE destroying the whole query will also unsubscribe it
-          // query.destroy()
-
-          // TODO for now we'll still `cancel` manually, but we should remove this once we have some kind of
-          // ARC-based system
-          cancel()
-          span.end()
+    query.activeSubscriptions.add(stackInfo)
+    const unsub = 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.
+        if (isEqual(newValue, valueRef.current) === false) {
+          setValue(newValue)
         }
       },
+      undefined,
+      { label: query.label, otelContext },
     )
-  }, [query, store])
+    return () => {
+      query.activeSubscriptions.delete(stackInfo)
+      unsub()
+    }
+  }, [stackInfo, query, setValue, store, valueRef, otelContext, span])
 
-  return value
+  return valueRef.current
 }

package/src/react/useTemporaryQuery.ts

@@ -0,0 +1,23 @@
+import React from 'react'
+
+import type { ILiveStoreQuery } from '../reactiveQueries/base-class.js'
+import { useQuery } from './useQuery.js'
+
+/**
+ * Creates a query, subscribes and destroys it when the component unmounts.
+ *
+ * Make sure `makeQuery` is a memoized function.
+ */
+export const useTemporaryQuery = <TResult>(makeQuery: () => ILiveStoreQuery<TResult>): TResult => {
+  // TODO cache the query outside of the `useMemo` since `useMemo` might be called multiple times
+  // also need to update the `useEffect` below https://stackoverflow.com/questions/66446642/react-usememo-memory-clean/77457605#77457605
+  const query = React.useMemo(() => makeQuery(), [makeQuery])
+
+  React.useEffect(() => {
+    return () => {
+      query.destroy()
+    }
+  }, [query])
+
+  return useQuery(query)
+}