@livestore/livestore 0.0.13 → 0.0.14

package/src/react/LiveStoreProvider.tsx

@@ -1,14 +1,10 @@
 import type * as otel from '@opentelemetry/api'
-import { mapValues } from 'lodash-es'
 import type { ReactElement, ReactNode } from 'react'
 import React from 'react'
+import initSqlite3Wasm from 'sqlite-esm'
 
 // TODO refactor so the `react` module doesn't depend on `effect` module
-import type {
-  GlobalQueryDefs,
-  LiveStoreContext as StoreContext_,
-  LiveStoreCreateStoreOptions,
-} from '../effect/LiveStore.js'
+import type { LiveStoreContext as StoreContext_, LiveStoreCreateStoreOptions } from '../effect/LiveStore.js'
 import type { InMemoryDatabase } from '../inMemoryDatabase.js'
 import type { Schema } from '../schema.js'
 import type { StorageInit } from '../storage/index.js'
@@ -16,11 +12,17 @@ import type { BaseGraphQLContext, GraphQLOptions } from '../store.js'
 import { createStore } from '../store.js'
 import { LiveStoreContext } from './LiveStoreContext.js'
 
+// NOTE we're starting to initialize the sqlite wasm binary here (already before calling `createStore`),
+// so that it's ready when we need it
+const sqlite3Promise = initSqlite3Wasm({
+  print: (message) => console.log(`[livestore sqlite] ${message}`),
+  printErr: (message) => console.error(`[livestore sqlite] ${message}`),
+})
+
 interface LiveStoreProviderProps<GraphQLContext> {
   schema: Schema
   loadStorage: () => StorageInit | Promise<StorageInit>
   boot?: (db: InMemoryDatabase, parentSpan: otel.Span) => unknown | Promise<unknown>
-  globalQueryDefs: GlobalQueryDefs
   graphQLOptions?: GraphQLOptions<GraphQLContext>
   otelTracer?: otel.Tracer
   otelRootSpanContext?: otel.Context
@@ -29,7 +31,6 @@ interface LiveStoreProviderProps<GraphQLContext> {
 
 export const LiveStoreProvider = <GraphQLContext extends BaseGraphQLContext>({
   fallback,
-  globalQueryDefs,
   loadStorage,
   graphQLOptions,
   otelTracer,
@@ -40,7 +41,6 @@ export const LiveStoreProvider = <GraphQLContext extends BaseGraphQLContext>({
 }: LiveStoreProviderProps<GraphQLContext> & { children?: ReactNode }): JSX.Element => {
   const store = useCreateStore({
     schema,
-    globalQueryDefs,
     loadStorage,
     graphQLOptions,
     otelTracer,
@@ -59,7 +59,6 @@ export const LiveStoreProvider = <GraphQLContext extends BaseGraphQLContext>({
 
 const useCreateStore = <GraphQLContext extends BaseGraphQLContext>({
   schema,
-  globalQueryDefs,
   loadStorage,
   graphQLOptions,
   otelTracer,
@@ -71,6 +70,7 @@ const useCreateStore = <GraphQLContext extends BaseGraphQLContext>({
   React.useEffect(() => {
     void (async () => {
       try {
+        const sqlite3 = await sqlite3Promise
         const store = await createStore({
           schema,
           loadStorage,
@@ -78,12 +78,9 @@ const useCreateStore = <GraphQLContext extends BaseGraphQLContext>({
           otelTracer,
           otelRootSpanContext,
           boot,
+          sqlite3,
         })
-        store.otel.tracer.startActiveSpan('LiveStore:makeGlobalQueries', {}, store.otel.queriesSpanContext, (span) => {
-          const globalQueries = mapValues(globalQueryDefs, (queryDef) => queryDef(store))
-          setCtxValue({ store, globalQueries })
-          span.end()
-        })
+        setCtxValue({ store })
       } catch (e) {
         console.error(`Error creating LiveStore store:`, e)
         throw e
@@ -91,7 +88,7 @@ const useCreateStore = <GraphQLContext extends BaseGraphQLContext>({
     })()
 
     // TODO: do we need to return any cleanup function here?
-  }, [schema, loadStorage, globalQueryDefs, graphQLOptions, otelTracer, otelRootSpanContext, boot])
+  }, [schema, loadStorage, graphQLOptions, otelTracer, otelRootSpanContext, boot])
 
   return ctxValue
 }

package/src/react/index.ts

@@ -1,20 +1,16 @@
 export type {
-  UseLiveStoreComponentProps as LiveStoreComponentConfig,
-  ReactiveGraphQL,
-  ReactiveSQL,
   Setters,
   ComponentKeyConfig,
-  QueryResults,
   QueryDefinitions,
   ComponentColumns,
   GetStateType,
   GetStateTypeEncoded,
-} from './useLiveStoreComponent.js'
+} from './useComponentState.js'
 export { LiveStoreContext, useStore } from './LiveStoreContext.js'
 export { LiveStoreProvider } from './LiveStoreProvider.js'
-export { useLiveStoreComponent } from './useLiveStoreComponent.js'
-export { useGraphQL } from './useGraphQL.js'
-export { useGlobalQuery } from './useGlobalQuery.js'
+export { useComponentState } from './useComponentState.js'
+export { useQuery } from './useQuery.js'
+export { useTemporaryQuery } from './useTemporaryQuery.js'
 
 // Needed to make TS happy
 export type { TypedDocumentNode } from '@graphql-typed-document-node/core'

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

@@ -1,9 +1,8 @@
-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'
-import { SqliteDsl } from 'effect-db-schema'
+import { SqliteAst, SqliteDsl } from 'effect-db-schema'
 import { isEqual, mapValues } from 'lodash-es'
 import type { DependencyList } from 'react'
 import React from 'react'
@@ -11,60 +10,22 @@ import { v4 as uuid } from 'uuid'
 
 import type { ComponentKey } from '../componentKey.js'
 import { labelForKey, tableNameForComponentKey } from '../componentKey.js'
-import type { GetAtom } from '../reactive.js'
-import type { LiveStoreGraphQLQuery } from '../reactiveQueries/graphql.js'
-import type { LiveStoreJSQuery } from '../reactiveQueries/js.js'
-import type { LiveStoreSQLQuery } from '../reactiveQueries/sql.js'
-import type { BaseGraphQLContext, LiveStoreQuery, QueryResult, Store } from '../store.js'
-import type { Bindable } from '../util.js'
+import { migrateTable } from '../migrations.js'
+import { LiveStoreJSQuery } from '../reactiveQueries/js.js'
+import { LiveStoreSQLQuery } from '../reactiveQueries/sql.js'
+import { SCHEMA_META_TABLE } from '../schema.js'
+import type { BaseGraphQLContext, LiveStoreQuery, Store } from '../store.js'
 import { sql } from '../util.js'
 import { useStore } from './LiveStoreContext.js'
+import { extractStackInfoFromStackTrace, originalStackLimit } from './utils/extractStackInfoFromStackTrace.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>(
-  genQuery: (get: GetAtom) => string,
-  queriedTables: string[],
-  bindValues?: Bindable | undefined,
-) => LiveStoreSQLQuery<TResult>
-export type ReactiveGraphQL = <
-  TResult extends Record<string, any>,
-  TVariables extends Record<string, any>,
-  TContext extends BaseGraphQLContext,
->(
-  query: DocumentNode<TResult, TVariables>,
-  genVariableValues: (get: GetAtom) => 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
-  globalQueries: QueryDefinitions
-  state$: LiveStoreJSQuery<TStateResult>
-  /**
-   * Registers a subscription.
-   *
-   * Passed down for some manual subscribing. Use carefully.
-   */
-  subscribe: RegisterSubscription
-  isTemporaryQuery: boolean
-}) => TQueries
-
-export type UseLiveStoreComponentProps<TQueries, TColumns extends ComponentColumns> = {
-  stateSchema?: SqliteDsl.TableDefinition<string, TColumns>
-  queries?: GenQueries<TQueries, SqliteDsl.FromColumns.RowDecoded<TColumns>>
+export type UseComponentStateProps<TStateColumns extends ComponentColumns> = {
+  schema?: SqliteDsl.TableDefinition<string, TStateColumns>
   reactDeps?: React.DependencyList
   componentKey: ComponentKeyConfig
 }
@@ -115,18 +76,17 @@ 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 = <TColumns extends ComponentColumns, TQueries extends QueryDefinitions>({
-  stateSchema: stateSchema_,
-  queries = () => ({}) as TQueries,
+export const useComponentState = <TStateColumns extends ComponentColumns>({
+  schema: stateSchema_,
   componentKey: componentKeyConfig,
   reactDeps = [],
-}: UseLiveStoreComponentProps<TQueries, TColumns>): {
-  queryResults: QueryResults<TQueries>
-  state: SqliteDsl.FromColumns.RowDecoded<TColumns>
-  setState: Setters<SqliteDsl.FromColumns.RowDecoded<TColumns>>
-  useLiveStoreJsonState: UseLiveStoreJsonState<SqliteDsl.FromColumns.RowDecoded<TColumns>>
+}: 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>>
 } => {
-  type TComponentState = SqliteDsl.FromColumns.RowDecoded<TColumns>
+  type TComponentState = SqliteDsl.FromColumns.RowDecoded<TStateColumns>
 
   // TODO validate schema to make sure each column has a default value
   // TODO we should clean up the state schema handling to remove this special handling for the `id` column
@@ -135,9 +95,8 @@ export const useLiveStoreComponent = <TColumns extends ComponentColumns, TQuerie
     [stateSchema_],
   )
 
-  // performance.mark('useLiveStoreComponent:start')
   const componentKey = useComponentKey(componentKeyConfig, reactDeps)
-  const { store, globalQueries } = useStore()
+  const { store } = useStore()
 
   const componentKeyLabel = React.useMemo(() => labelForKey(componentKey), [componentKey])
 
@@ -147,7 +106,7 @@ export const useLiveStoreComponent = <TColumns extends ComponentColumns, TQuerie
     if (existingSpan !== undefined) return existingSpan
 
     const span = store.otel.tracer.startSpan(
-      `LiveStore:useLiveStoreComponent:${componentKeyLabel}`,
+      `LiveStore:useComponentState:${componentKeyLabel}`,
       {},
       store.otel.queriesSpanContext,
     )
@@ -167,41 +126,6 @@ export const useLiveStoreComponent = <TColumns extends ComponentColumns, TQuerie
     [componentKeyLabel, span],
   )
 
-  const generateQueries = React.useCallback(
-    ({
-      state$,
-      otelContext,
-      registerSubscription,
-      isTemporaryQuery,
-    }: {
-      state$: LiveStoreJSQuery<TComponentState>
-      otelContext: otel.Context
-      registerSubscription: RegisterSubscription
-      isTemporaryQuery: boolean
-    }) =>
-      queries({
-        rxSQL: <T>(genQuery: (get: GetAtom) => 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: (get: GetAtom) => Variables,
-          label?: string,
-        ) => store.queryGraphQL(query, genVariableValues, { componentKey, label, otelContext }),
-        globalQueries,
-        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, globalQueries],
-  )
-
   const defaultComponentState = React.useMemo(() => {
     const defaultState = (
       stateSchema === undefined ? {} : mapValues(stateSchema.columns, (c) => c.default)
@@ -218,81 +142,68 @@ export const useLiveStoreComponent = <TColumns extends ComponentColumns, TQuerie
     [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)
-
-      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}'`
-            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
-
-          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()
-        }
+  const state$ = React.useMemo(() => {
+    console.log('useComponentState make state$', labelForKey(componentKey))
+    // 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' },
+        })
+      }
+
+      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), [otelContext, 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
       ? {}
@@ -329,44 +240,30 @@ export const useLiveStoreComponent = <TColumns extends ComponentColumns, TQuerie
     return store.applyEvent('updateComponentState', { componentKey, columnNames, ...columnValues })
   }
 
+  const subscriptionInfo = React.useMemo(() => {
+    Error.stackTraceLimit = 10
+    // eslint-disable-next-line unicorn/error-message
+    const stack = new Error().stack!
+    Error.stackTraceLimit = originalStackLimit
+    return { stack: extractStackInfoFromStackTrace(stack) }
+  }, [])
+
   // OK, now all the synchronous work is done;
   // 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)
+        if (stateSchema !== undefined) {
           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,
-            )
         }
 
+        state$.activeSubscriptions.add(subscriptionInfo)
+
         unsubs.push(
           store.subscribe(
             state$,
@@ -376,44 +273,11 @@ export const useLiveStoreComponent = <TColumns extends ComponentColumns, TQuerie
               }
             },
             undefined,
-            { label: `useLiveStoreComponent:localState:subscribe:${state$.label}` },
+            { label: `useComponentState:localState:subscribe:${state$.label}` },
           ),
+          () => state$.activeSubscriptions.delete(subscriptionInfo),
         )
 
-        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()
@@ -425,24 +289,28 @@ export const useLiveStoreComponent = <TColumns extends ComponentColumns, TQuerie
     )
     // 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
+    // TODO is this still true?
+    // // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [
     store,
-    componentKey,
+    subscriptionInfo,
     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(
+    () => () => {
+      console.log('useComponentState destroy', labelForKey(componentKey))
+      return state$.destroy()
+    },
+    [state$],
+  )
 
   const state = componentStateRef.current
 
@@ -472,7 +340,7 @@ export const useLiveStoreComponent = <TColumns extends ComponentColumns, TQuerie
   }
 
   return {
-    queryResults: queryResultsRef.current,
+    state$,
     state,
     setState,
     useLiveStoreJsonState,

package/src/react/useQuery.ts

@@ -0,0 +1,58 @@
+import { isEqual } from 'lodash-es'
+import React from 'react'
+
+import type { ILiveStoreQuery } from '../reactiveQueries/base-class.js'
+import { useStore } from './LiveStoreContext.js'
+import { extractStackInfoFromStackTrace, originalStackLimit } from './utils/extractStackInfoFromStackTrace.js'
+import { useStateRefWithReactiveInput } from './utils/useStateRefWithReactiveInput.js'
+
+export const useQuery = <TResult>(query: ILiveStoreQuery<TResult>): TResult => {
+  const { store } = useStore()
+
+  // TODO proper otel context
+  const initialResult = React.useMemo(() => query.run(), [query])
+
+  // 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<TResult>(initialResult)
+
+  const subscriptionInfo = React.useMemo(() => {
+    Error.stackTraceLimit = 10
+    // eslint-disable-next-line unicorn/error-message
+    const stack = new Error().stack!
+    Error.stackTraceLimit = originalStackLimit
+    return { stack: extractStackInfoFromStackTrace(stack) }
+  }, [])
+
+  // Subscribe to future updates for this query
+  React.useEffect(() => {
+    return store.otel.tracer.startActiveSpan(
+      `LiveStore:useQuery:${query.label}`,
+      // `LiveStore:useQuery:${labelForKey(query.componentKey)}:${query.label}`,
+      { attributes: { label: query.label } },
+      store.otel.queriesSpanContext,
+      (span) => {
+        query.activeSubscriptions.add(subscriptionInfo)
+        const unsub = 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.
+            if (isEqual(v, valueRef.current) === false) {
+              setValue(v)
+            }
+          },
+          undefined,
+          { label: query.label },
+        )
+        return () => {
+          query.activeSubscriptions.delete(subscriptionInfo)
+          unsub()
+          span.end()
+        }
+      },
+    )
+  }, [subscriptionInfo, query, setValue, store, valueRef])
+
+  return valueRef.current
+}

package/src/react/useTemporaryQuery.ts

@@ -0,0 +1,21 @@
+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 => {
+  const query = React.useMemo(() => makeQuery(), [makeQuery])
+
+  React.useEffect(() => {
+    return () => {
+      query.destroy()
+    }
+  }, [query])
+
+  return useQuery(query)
+}