@livestore/livestore 0.0.24 → 0.0.27

package/src/__tests__/reactive.test.ts

@@ -159,6 +159,77 @@ describe('a trivial graph', () => {
       graph.setRef(a, 2)
       // expect(numberOfCallsToC).toBe(2) // TODO comp caching
     })
+
+    describe('skip refresh', () => {
+      it(`defers effect execution until manual run`, () => {
+        const { graph, a, c, d, numberOfRunsForC } = makeGraph()
+
+        // using here both to track number oe effect runs and to "update the effect behavior"
+        let numberOfEffectRuns = 0
+        const effect = graph.makeEffect((get) => {
+          expect(get(c)).toBe(numberOfEffectRuns === 0 ? 3 : 4)
+          numberOfEffectRuns++
+        })
+
+        effect.doEffect()
+
+        expect(numberOfEffectRuns).toBe(1)
+        expect(numberOfRunsForC.runs).toBe(1)
+
+        graph.setRef(a, 2, { skipRefresh: true })
+
+        expect(numberOfEffectRuns).toBe(1)
+        expect(numberOfRunsForC.runs).toBe(1)
+
+        // Even setting a unrelated ref should not trigger a refresh
+        graph.setRef(d, 0)
+
+        expect(numberOfEffectRuns).toBe(1)
+        expect(numberOfRunsForC.runs).toBe(1)
+
+        graph.runDeferredEffects()
+
+        expect(numberOfEffectRuns).toBe(2)
+        expect(numberOfRunsForC.runs).toBe(2)
+      })
+
+      it(`doesn't run deferred effects which have been destroyed already`, () => {
+        const { graph, a, c, numberOfRunsForC } = makeGraph()
+
+        let numberOfEffect1Runs = 0
+        const effect1 = graph.makeEffect((get) => {
+          expect(get(c)).toBe(numberOfEffect1Runs === 0 ? 3 : 4)
+          numberOfEffect1Runs++
+        })
+
+        let numberOfEffect2Runs = 0
+        const effect2 = graph.makeEffect((get) => {
+          expect(get(c)).toBe(numberOfEffect2Runs === 0 ? 3 : 4)
+          numberOfEffect2Runs++
+        })
+
+        effect1.doEffect()
+        effect2.doEffect()
+
+        expect(numberOfEffect1Runs).toBe(1)
+        expect(numberOfEffect2Runs).toBe(1)
+        expect(numberOfRunsForC.runs).toBe(1)
+
+        graph.setRef(a, 2, { skipRefresh: true })
+
+        expect(numberOfEffect1Runs).toBe(1)
+        expect(numberOfEffect2Runs).toBe(1)
+        expect(numberOfRunsForC.runs).toBe(1)
+
+        graph.destroy(effect1)
+
+        graph.runDeferredEffects()
+
+        expect(numberOfEffect1Runs).toBe(1)
+        expect(numberOfEffect2Runs).toBe(2)
+        expect(numberOfRunsForC.runs).toBe(2)
+      })
+    })
   })
 })
 

package/src/__tests__/reactiveQueries/sql.test.ts

@@ -30,12 +30,11 @@ describe('otel', () => {
   it('otel', async () => {
     const { store, exporter, span } = await makeQuery()
 
-    const query = querySQL(`select * from todos`, { queriedTables: ['todos'] })
+    const query = querySQL(`select * from todos`, { queriedTables: new Set(['todos']) })
     expect(query.run()).toMatchInlineSnapshot('[]')
 
-    store.applyEvent('RawSql', {
+    store.applyEvent('livestore.RawSql', {
       sql: sql`INSERT INTO todos (id, text, completed) VALUES ('t1', 'buy milk', 0);`,
-      bindValues: {},
       writeTables: ['todos'],
     })
 
@@ -93,10 +92,9 @@ describe('otel', () => {
                   {
                     "_name": "LiveStore:applyEventWithoutRefresh",
                     "attributes": {
-                      "livestore.actionType": "RawSql",
+                      "livestore.actionType": "livestore.RawSql",
                       "livestore.args": "{
         \\"sql\\": \\"INSERT INTO todos (id, text, completed) VALUES ('t1', 'buy milk', 0);\\",
-        \\"bindValues\\": {},
         \\"writeTables\\": [
           \\"todos\\"
         ]
@@ -165,10 +163,7 @@ describe('otel', () => {
     const defaultTodo = { id: '', text: '', completed: 0 }
 
     const filter = queryJS(() => `where completed = 0`, { label: 'where-filter' })
-    const query = querySQL((get) => `select * from todos ${get(filter)}`, {
-      // queriedTables: ['todos'],
-      label: 'all todos',
-    }).getFirstRow({
+    const query = querySQL((get) => `select * from todos ${get(filter)}`, { label: 'all todos' }).getFirstRow({
       defaultValue: defaultTodo,
     })
 
@@ -180,9 +175,8 @@ describe('otel', () => {
       }
     `)
 
-    store.applyEvent('RawSql', {
+    store.applyEvent('livestore.RawSql', {
       sql: sql`INSERT INTO todos (id, text, completed) VALUES ('t1', 'buy milk', 0);`,
-      bindValues: {},
       writeTables: ['todos'],
     })
 
@@ -238,10 +232,9 @@ describe('otel', () => {
                   {
                     "_name": "LiveStore:applyEventWithoutRefresh",
                     "attributes": {
-                      "livestore.actionType": "RawSql",
+                      "livestore.actionType": "livestore.RawSql",
                       "livestore.args": "{
         \\"sql\\": \\"INSERT INTO todos (id, text, completed) VALUES ('t1', 'buy milk', 0);\\",
-        \\"bindValues\\": {},
         \\"writeTables\\": [
           \\"todos\\"
         ]

package/src/effect/LiveStore.ts

@@ -5,7 +5,7 @@ import type { GraphQLSchema } from 'graphql'
 import initSqlite3Wasm from 'sqlite-esm'
 
 import type { InMemoryDatabase } from '../inMemoryDatabase.js'
-import type { Schema } from '../schema.js'
+import type { LiveStoreSchema } from '../schema/index.js'
 import type { StorageInit } from '../storage/index.js'
 import type { BaseGraphQLContext, GraphQLOptions, LiveStoreQuery, Store } from '../store.js'
 import { createStore } from '../store.js'
@@ -25,7 +25,7 @@ export type LiveStoreContext = {
 export type QueryDefinition = (store: Store) => LiveStoreQuery
 
 export type LiveStoreCreateStoreOptions<GraphQLContext extends BaseGraphQLContext> = {
-  schema: Schema
+  schema: LiveStoreSchema
   loadStorage: () => StorageInit | Promise<StorageInit>
   graphQLOptions?: GraphQLOptions<GraphQLContext>
   otelTracer?: otel.Tracer
@@ -43,7 +43,7 @@ export const DeferredStoreContext = Context.Tag<DeferredStoreContext>(
 // export const DeferredStoreContext = Effect.cached(Effect.flatMap(StoreContext, (_) => Effect.succeed(_)))
 
 export type LiveStoreContextProps<GraphQLContext extends BaseGraphQLContext> = {
-  schema: Schema
+  schema: LiveStoreSchema
   loadStorage: () => StorageInit | Promise<StorageInit>
   graphQLOptions?: {
     schema: Effect.Effect<otel.Tracer, never, GraphQLSchema>
@@ -55,9 +55,9 @@ export type LiveStoreContextProps<GraphQLContext extends BaseGraphQLContext> = {
 export const LiveStoreContextLayer = <GraphQLContext extends BaseGraphQLContext>(
   props: LiveStoreContextProps<GraphQLContext>,
 ): Layer.Layer<otel.Tracer, never, LiveStoreContext> =>
-  Layer.provide(
-    LiveStoreContextDeferred,
-    Layer.scoped(LiveStoreContext, makeLiveStoreContext(props)).pipe(Layer.withSpan('LiveStore')),
+  Layer.scoped(LiveStoreContext, makeLiveStoreContext(props)).pipe(
+    Layer.withSpan('LiveStore'),
+    Layer.provide(LiveStoreContextDeferred),
   )
 
 export const LiveStoreContextDeferred = Layer.effect(DeferredStoreContext, Deferred.make<never, LiveStoreContext>())
@@ -78,7 +78,7 @@ export const makeLiveStoreContext = <GraphQLContext extends BaseGraphQLContext>(
 
       const otelRootSpanContext = otel.context.active()
 
-      const otelTracer = yield* $(OtelTracer.OtelTracer)
+      const otelTracer = yield* $(OtelTracer.Tracer)
 
       const graphQLOptions = yield* $(
         graphQLOptions_

package/src/global-state.ts

@@ -0,0 +1,26 @@
+/**
+ *
+ * LiveStore currently relies on some global state in order to simplify the end-user API.
+ * This however also has the downside that LiveStore can't be used in multiple instances in the same app.
+ * It could possibly also lead to some other problems.
+ *
+ * We should find some better way to do this and ideally remove this global state.
+ *
+ * Another approach could be to use the global state by default but provide an additional way to let the user
+ * explicitly pass instances of state below into the LiveStore constructors.
+ *
+ */
+
+import ReactDOM from 'react-dom'
+
+import { ReactiveGraph } from './reactive.js'
+import type { DbContext } from './reactiveQueries/base-class.js'
+import type { TableDef } from './schema/table-def.js'
+import type { QueryDebugInfo, RefreshReason } from './store.js'
+
+export const dbGraph = new ReactiveGraph<RefreshReason, QueryDebugInfo, DbContext>({
+  // TODO also find a better way to only use this effects wrapper when used in a React app
+  effectsWrapper: (run) => ReactDOM.unstable_batchedUpdates(() => run()),
+})
+
+export const dynamicallyRegisteredTables: Map<string, TableDef> = new Map()

package/src/inMemoryDatabase.ts

@@ -4,12 +4,12 @@ import { shouldNeverHappen } from '@livestore/utils'
 import type * as otel from '@opentelemetry/api'
 import type * as Sqlite from 'sqlite-esm'
 
-import BoundMap, { BoundArray } from './bounded-collections.js'
 // import { EVENTS_TABLE_NAME } from './events.js'
 import { sql } from './index.js'
-import { getDurationMsFromSpan, getStartTimeHighResFromSpan } from './otel.js'
 import QueryCache from './QueryCache.js'
-import type { Bindable, PreparedBindValues } from './util.js'
+import BoundMap, { BoundArray } from './utils/bounded-collections.js'
+import { getDurationMsFromSpan, getStartTimeHighResFromSpan } from './utils/otel.js'
+import type { Bindable, PreparedBindValues } from './utils/util.js'
 
 type DatabaseWithCAPI = Sqlite.Database & { capi: Sqlite.CAPI }
 
@@ -25,7 +25,7 @@ export type SlowQueryInfo = [
   bindValues: PreparedBindValues | undefined,
   durationMs: number,
   rowsCount: number | undefined,
-  queriedTables: ReadonlyArray<string>,
+  queriedTables: Set<string>,
   startTimePerfNow: DOMHighResTimeStamp,
 ]
 
@@ -39,7 +39,7 @@ export const emptyDebugInfo = (): DebugInfo => ({
 export class InMemoryDatabase {
   // TODO: how many unique active statements are expected?
   private cachedStmts = new BoundMap<string, Sqlite.PreparedStatement>(200)
-  private tablesUsedCache = new BoundMap<string, string[]>(200)
+  private tablesUsedCache = new BoundMap<string, Set<string>>(200)
   private resultCache = new QueryCache()
   private tablesUsedStmt
   public debugInfo: DebugInfo = emptyDebugInfo()
@@ -119,25 +119,27 @@ export class InMemoryDatabase {
       return cached
     }
     const stmt = this.tablesUsedStmt
-    const tablesUsed = []
+    const tablesUsed = new Set<string>()
     try {
       stmt.bind([query])
       while (stmt.step()) {
-        tablesUsed.push(stmt.get(0))
+        tablesUsed.add(stmt.get(0))
       }
     } finally {
       stmt.reset()
     }
-    this.tablesUsedCache.set(query, tablesUsed as string[])
-    return tablesUsed as string[]
+    this.tablesUsedCache.set(query, tablesUsed)
+    return tablesUsed
   }
 
   execute(
     query: string,
     bindValues?: PreparedBindValues,
-    writeTables?: string[],
+    writeTables?: ReadonlyArray<string>,
     options?: { hasNoEffects?: boolean; otelContext?: otel.Context },
   ): { durationMs: number } {
+    // console.debug('in-memory-db:execute', query, bindValues)
+
     return this.otelTracer.startActiveSpan(
       'livestore.in-memory-db:execute',
       // TODO truncate query string
@@ -192,7 +194,7 @@ export class InMemoryDatabase {
             bindValues,
             durationMs,
             undefined,
-            [],
+            new Set(),
             getStartTimeHighResFromSpan(span),
           ])
         }
@@ -205,7 +207,7 @@ export class InMemoryDatabase {
   select<T = any>(
     query: string,
     options?: {
-      queriedTables?: ReadonlyArray<string>
+      queriedTables?: Set<string>
       bindValues?: PreparedBindValues
       skipCache?: boolean
       otelContext?: otel.Context

package/src/index.ts

@@ -3,41 +3,34 @@ export type { LiveStoreQuery, BaseGraphQLContext, QueryResult, QueryDebugInfo, R
 
 export type { QueryDefinition, LiveStoreCreateStoreOptions, LiveStoreContext } from './effect/LiveStore.js'
 
-export {
-  defineComponentStateSchema,
-  defineAction,
-  defineActions,
-  defineTables,
-  defineMaterializedViews,
-  makeSchema,
-} from './schema.js'
 export { InMemoryDatabase, type DebugInfo, emptyDebugInfo } from './inMemoryDatabase.js'
+
 export type { Storage, StorageType, StorageInit } from './storage/index.js'
-export type {
-  GetAtom,
-  AtomDebugInfo,
-  RefreshDebugInfo,
-  RefreshReasonWithGenericReasons,
-  SerializedAtom,
-  SerializedEffect,
-  Atom,
-} from './reactive.js'
-export { type LiveStoreJSQuery, queryJS } from './reactiveQueries/js.js'
-export { type LiveStoreSQLQuery, querySQL } from './reactiveQueries/sql.js'
-export { type LiveStoreGraphQLQuery, queryGraphQL } from './reactiveQueries/graphql.js'
+
+export type { GetAtom, AtomDebugInfo, RefreshDebugInfo, SerializedAtom, Atom } from './reactive.js'
+export { LiveStoreJSQuery, queryJS } from './reactiveQueries/js.js'
+export { LiveStoreSQLQuery, querySQL } from './reactiveQueries/sql.js'
+export { LiveStoreGraphQLQuery, queryGraphQL } from './reactiveQueries/graphql.js'
 export { type GetAtomResult } from './reactiveQueries/base-class.js'
-export { dbGraph } from './reactiveQueries/graph.js'
 
-export { labelForKey } from './componentKey.js'
-export type { ComponentKey } from './componentKey.js'
-export type { Schema, GetActionArgs, GetApplyEventArgs, Index, ActionDefinition, ActionDefinitions } from './schema.js'
+export { dbGraph } from './global-state.js'
 
-export { SqliteAst, SqliteDsl } from 'effect-db-schema'
+export { type RowResult, type RowResultEncoded, type RowQueryArgs, rowQuery } from './row-query.js'
 
-import type { SqliteAst } from 'effect-db-schema'
-export type TableDefinition = SqliteAst.Table
+export { defineAction, defineActions, makeSchema, DbSchema } from './schema/index.js'
 
-export { SqliteDsl as DbSchema } from 'effect-db-schema'
+export type {
+  LiveStoreSchema,
+  InputSchema,
+  GetActionArgs,
+  GetApplyEventArgs,
+  ActionDefinition,
+  ActionDefinitions,
+  SQLWriteStatement,
+  SchemaMetaRow,
+} from './schema/index.js'
+
+export { SqliteAst, SqliteDsl } from 'effect-db-schema'
 
-export { prepareBindValues, sql, type Bindable, type PreparedBindValues } from './util.js'
+export { prepareBindValues, sql, type Bindable, type PreparedBindValues } from './utils/util.js'
 export { isEqual } from 'lodash-es'

package/src/migrations.ts

@@ -1,12 +1,14 @@
+import { Schema as EffectSchema } from '@livestore/utils/effect'
 import type * as otel from '@opentelemetry/api'
 import { SqliteAst } from 'effect-db-schema'
-import { memoize, omit } from 'lodash-es'
+import { memoize } from 'lodash-es'
 
+import { dynamicallyRegisteredTables } from './global-state.js'
 import type { InMemoryDatabase } from './index.js'
-import type { Schema, SchemaMetaRow } from './schema.js'
-import { componentStateTables, SCHEMA_META_TABLE, systemTables } from './schema.js'
-import type { PreparedBindValues } from './util.js'
-import { sql } from './util.js'
+import type { LiveStoreSchema, SchemaMetaRow } from './schema/index.js'
+import { SCHEMA_META_TABLE, systemTables } from './schema/index.js'
+import type { PreparedBindValues } from './utils/util.js'
+import { sql } from './utils/util.js'
 
 const getMemoizedTimestamp = memoize(() => new Date().toISOString())
 
@@ -18,7 +20,7 @@ export const migrateDb = ({
 }: {
   db: InMemoryDatabase
   otelContext: otel.Context
-  schema: Schema
+  schema: LiveStoreSchema
 }) => {
   db.execute(
     // TODO use schema migration definition from schema.ts instead
@@ -34,16 +36,18 @@ export const migrateDb = ({
     schemaMetaRows.map(({ tableName, schemaHash }) => [tableName, schemaHash]),
   )
 
-  const tableDefs = {
+  const tableDefs = new Set([
     // NOTE it's important the `SCHEMA_META_TABLE` comes first since we're writing to it below
-    [SCHEMA_META_TABLE]: systemTables[SCHEMA_META_TABLE],
-    ...omit(schema.tables, [SCHEMA_META_TABLE]),
-    ...componentStateTables,
-  }
-
-  for (const [tableName, tableDef] of Object.entries(tableDefs)) {
+    ...systemTables,
+    ...Array.from(schema.tables.values()).filter((_) => _.schema.name !== SCHEMA_META_TABLE),
+    ...dynamicallyRegisteredTables.values(),
+  ])
+
+  for (const tableDef of tableDefs) {
+    const tableAst = tableDef.schema.ast
+    const tableName = tableAst.name
     const dbSchemaHash = dbSchemaHashByTable[tableName]
-    const schemaHash = SqliteAst.hash(tableDef)
+    const schemaHash = SqliteAst.hash(tableAst)
     if (schemaHash !== dbSchemaHash) {
       if (import.meta.env.VITE_LIVESTORE_SKIP_MIGRATIONS) {
         console.log(
@@ -54,7 +58,7 @@ export const migrateDb = ({
           `Schema hash mismatch for table '${tableName}' (DB: ${dbSchemaHash}, expected: ${schemaHash}), migrating table...`,
         )
 
-        migrateTable({ db, tableDef, otelContext, schemaHash })
+        migrateTable({ db, tableAst, otelContext, schemaHash })
       }
     }
   }
@@ -62,24 +66,24 @@ export const migrateDb = ({
 
 export const migrateTable = ({
   db,
-  tableDef,
+  tableAst,
   otelContext,
   schemaHash,
 }: {
   db: InMemoryDatabase
-  tableDef: SqliteAst.Table
+  tableAst: SqliteAst.Table
   otelContext: otel.Context
   schemaHash: number
 }) => {
-  console.log(`Migrating table '${tableDef.name}'...`)
-  const tableName = tableDef.name
-  const columnSpec = makeColumnSpec(tableDef)
+  console.log(`Migrating table '${tableAst.name}'...`)
+  const tableName = tableAst.name
+  const columnSpec = makeColumnSpec(tableAst)
 
   // TODO need to possibly handle cascading deletes due to foreign keys
   db.execute(sql`drop table if exists ${tableName}`, undefined, [], { otelContext })
   db.execute(sql`create table if not exists ${tableName} (${columnSpec});`, undefined, [], { otelContext })
 
-  for (const index of tableDef.indexes) {
+  for (const index of tableAst.indexes) {
     db.execute(createIndexFromDefinition(tableName, index), undefined, [], { otelContext })
   }
 
@@ -100,9 +104,9 @@ const createIndexFromDefinition = (tableName: string, index: SqliteAst.Index) =>
   return sql`create ${uniqueStr} index ${index.name} on ${tableName} (${index.columns.join(', ')})`
 }
 
-const makeColumnSpec = (tableDef: SqliteAst.Table) => {
-  const primaryKeys = tableDef.columns.filter((_) => _.primaryKey).map((_) => _.name)
-  const columnDefStrs = tableDef.columns.map(toSqliteColumnSpec)
+const makeColumnSpec = (tableAst: SqliteAst.Table) => {
+  const primaryKeys = tableAst.columns.filter((_) => _.primaryKey).map((_) => _.name)
+  const columnDefStrs = tableAst.columns.map(toSqliteColumnSpec)
   if (primaryKeys.length > 0) {
     columnDefStrs.push(`PRIMARY KEY (${primaryKeys.join(', ')})`)
   }
@@ -110,16 +114,18 @@ const makeColumnSpec = (tableDef: SqliteAst.Table) => {
   return columnDefStrs.join(', ')
 }
 
+/** NOTE primary keys are applied on a table level not on a column level to account for multi-column primary keys */
 const toSqliteColumnSpec = (column: SqliteAst.Column) => {
-  const columnType = column.type._tag
-  // const primaryKey = column.primaryKey ? 'primary key' : ''
-  const nullable = column.nullable === false ? 'not null' : ''
-  const defaultValue =
-    column.default === undefined
-      ? ''
-      : columnType === 'text'
-      ? `default '${column.default}'`
-      : `default ${column.default}`
-
-  return `${column.name} ${columnType} ${nullable} ${defaultValue}`
+  const columnTypeStr = column.type._tag
+  const nullableStr = column.nullable === false ? 'not null' : ''
+  const defaultValueStr = (() => {
+    if (column.default === undefined) return ''
+
+    const encodeValue = EffectSchema.encodeSync(column.codec)
+    const encodedDefaultValue = encodeValue(column.default ?? null)
+
+    return columnTypeStr === 'text' ? `default '${encodedDefaultValue}'` : `default ${encodedDefaultValue}`
+  })()
+
+  return `${column.name} ${columnTypeStr} ${nullableStr} ${defaultValueStr}`
 }

package/src/react/LiveStoreProvider.tsx

@@ -6,7 +6,7 @@ import initSqlite3Wasm from 'sqlite-esm'
 // TODO refactor so the `react` module doesn't depend on `effect` module
 import type { LiveStoreContext as StoreContext_, LiveStoreCreateStoreOptions } from '../effect/LiveStore.js'
 import type { InMemoryDatabase } from '../inMemoryDatabase.js'
-import type { Schema } from '../schema.js'
+import type { LiveStoreSchema } from '../schema/index.js'
 import type { StorageInit } from '../storage/index.js'
 import type { BaseGraphQLContext, GraphQLOptions } from '../store.js'
 import { createStore } from '../store.js'
@@ -20,7 +20,7 @@ const sqlite3Promise = initSqlite3Wasm({
 })
 
 interface LiveStoreProviderProps<GraphQLContext> {
-  schema: Schema
+  schema: LiveStoreSchema
   loadStorage: () => StorageInit | Promise<StorageInit>
   boot?: (db: InMemoryDatabase, parentSpan: otel.Span) => unknown | Promise<unknown>
   graphQLOptions?: GraphQLOptions<GraphQLContext>

package/src/react/index.ts

@@ -1,17 +1,15 @@
-export type {
-  Setters,
-  ComponentKeyConfig,
-  QueryDefinitions,
-  ComponentColumns,
-  GetStateType,
-  GetStateTypeEncoded,
-} from './useComponentState.js'
 export { LiveStoreContext, useStore } from './LiveStoreContext.js'
 export { LiveStoreProvider } from './LiveStoreProvider.js'
-export { useComponentState } from './useComponentState.js'
 export { useQuery } from './useQuery.js'
 export { useTemporaryQuery } from './useTemporaryQuery.js'
 export { useStackInfo } from './utils/stack-info.js'
+export {
+  useRow,
+  type StateSetters,
+  type SetStateAction,
+  type Dispatch,
+  type UseRowResult as UseStateResult,
+} from './useRow.js'
 
 // Needed to make TS happy
 export type { TypedDocumentNode } from '@graphql-typed-document-node/core'

package/src/react/useQuery.ts

@@ -6,6 +6,7 @@ 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.
@@ -13,7 +14,12 @@ import { useStateRefWithReactiveInput } from './utils/useStateRefWithReactiveInp
  */
 const spanAlreadyStartedCache = new Map<ILiveStoreQuery<any>, { span: otel.Span; otelContext: otel.Context }>()
 
-export const useQuery = <TResult>(query: ILiveStoreQuery<TResult>): TResult => {
+export const useQuery = <TResult>(query: ILiveStoreQuery<TResult>): TResult => useQueryRef(query).current
+
+export const useQueryRef = <TResult>(
+  query: ILiveStoreQuery<TResult>,
+  parentOtelContext?: otel.Context,
+): React.MutableRefObject<TResult> => {
   const { store } = useStore()
 
   const stackInfo = React.useMemo(() => {
@@ -32,7 +38,7 @@ export const useQuery = <TResult>(query: ILiveStoreQuery<TResult>): TResult => {
     const span = store.otel.tracer.startSpan(
       `LiveStore:useQuery:${query.label}`,
       { attributes: { label: query.label, stackInfo: JSON.stringify(stackInfo) } },
-      store.otel.queriesSpanContext,
+      parentOtelContext ?? store.otel.queriesSpanContext,
     )
 
     const otelContext = otel.trace.setSpan(otel.context.active(), span)
@@ -40,7 +46,7 @@ export const useQuery = <TResult>(query: ILiveStoreQuery<TResult>): TResult => {
     spanAlreadyStartedCache.set(query, { span, otelContext })
 
     return { span, otelContext }
-  }, [query, stackInfo, store.otel.queriesSpanContext, store.otel.tracer])
+  }, [parentOtelContext, query, stackInfo, store.otel.queriesSpanContext, store.otel.tracer])
 
   const initialResult = React.useMemo(
     () =>
@@ -67,7 +73,7 @@ export const useQuery = <TResult>(query: ILiveStoreQuery<TResult>): TResult => {
   // Subscribe to future updates for this query
   React.useEffect(() => {
     query.activeSubscriptions.add(stackInfo)
-    const unsub = store.subscribe(
+    const unsubFromStore = store.subscribe(
       query,
       (newValue) => {
         // NOTE: we return a reference to the result object within LiveStore;
@@ -82,9 +88,9 @@ export const useQuery = <TResult>(query: ILiveStoreQuery<TResult>): TResult => {
     )
     return () => {
       query.activeSubscriptions.delete(stackInfo)
-      unsub()
+      unsubFromStore()
     }
   }, [stackInfo, query, setValue, store, valueRef, otelContext, span])
 
-  return valueRef.current
+  return valueRef
 }