@livestore/livestore 0.0.13 → 0.0.16

package/src/inMemoryDatabase.ts

@@ -2,28 +2,16 @@
 
 import { shouldNeverHappen } from '@livestore/utils'
 import type * as otel from '@opentelemetry/api'
-import type * as SqliteWasm from 'sqlite-esm'
+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, ParamsObject } from './util.js'
-import { prepareBindValues } from './util.js'
+import type { Bindable, PreparedBindValues } from './util.js'
 
-export enum IndexType {
-  Basic = 'Basic',
-  FullText = 'FullText',
-}
-
-export interface Index {
-  indexType: IndexType
-  name: string
-  columns: string[]
-}
-
-declare type DatabaseWithCAPI = SqliteWasm.Database & { capi: SqliteWasm.CAPI }
+type DatabaseWithCAPI = Sqlite.Database & { capi: Sqlite.CAPI }
 
 export interface DebugInfo {
   slowQueries: BoundArray<SlowQueryInfo>
@@ -34,7 +22,7 @@ export interface DebugInfo {
 
 export type SlowQueryInfo = [
   queryStr: string,
-  bindValues: Bindable | undefined,
+  bindValues: PreparedBindValues | undefined,
   durationMs: number,
   rowsCount: number | undefined,
   queriedTables: string[],
@@ -50,7 +38,7 @@ export const emptyDebugInfo = (): DebugInfo => ({
 
 export class InMemoryDatabase {
   // TODO: how many unique active statements are expected?
-  private cachedStmts = new BoundMap<string, SqliteWasm.PreparedStatement>(200)
+  private cachedStmts = new BoundMap<string, Sqlite.PreparedStatement>(200)
   private tablesUsedCache = new BoundMap<string, string[]>(200)
   private resultCache = new QueryCache()
   public debugInfo: DebugInfo = emptyDebugInfo()
@@ -59,15 +47,20 @@ export class InMemoryDatabase {
     private db: DatabaseWithCAPI,
     private otelTracer: otel.Tracer,
     private otelRootSpanContext: otel.Context,
-    public SQL: SqliteWasm.Sqlite3Static,
+    public SQL: Sqlite.Sqlite3Static,
   ) {}
 
-  static load(
-    data: Uint8Array | undefined,
-    otelTracer: otel.Tracer,
-    otelRootSpanContext: otel.Context,
-    sqlite3: SqliteWasm.Sqlite3Static,
-  ): InMemoryDatabase {
+  static load({
+    data,
+    otelTracer,
+    otelRootSpanContext,
+    sqlite3,
+  }: {
+    data: Uint8Array | undefined
+    otelTracer: otel.Tracer
+    otelRootSpanContext: otel.Context
+    sqlite3: Sqlite.Sqlite3Static
+  }): InMemoryDatabase {
     // TODO move WASM init higher up in the init process (to do some other work while it's loading)
 
     const db = new sqlite3.oo1.DB({ filename: ':memory:', flags: 'c' }) as DatabaseWithCAPI
@@ -138,7 +131,7 @@ export class InMemoryDatabase {
 
   execute(
     query: string,
-    bindValues?: ParamsObject,
+    bindValues?: PreparedBindValues,
     writeTables?: string[],
     options?: { hasNoEffects?: boolean; otelContext: otel.Context },
   ): { durationMs: number } {
@@ -155,9 +148,8 @@ export class InMemoryDatabase {
             this.cachedStmts.set(query, stmt)
           }
 
-          // TODO check whether we can remove the extra `prepareBindValues` call here (e.g. enforce proper type in API)
           if (bindValues !== undefined && Object.keys(bindValues).length > 0) {
-            stmt.bind(prepareBindValues(bindValues, query))
+            stmt.bind(bindValues)
           }
 
           if (import.meta.env.DEV) {
@@ -211,7 +203,7 @@ export class InMemoryDatabase {
     query: string,
     options?: {
       queriedTables?: string[]
-      bindValues?: Bindable
+      bindValues?: PreparedBindValues
       skipCache?: boolean
       otelContext?: otel.Context
     },

package/src/index.ts

@@ -1,11 +1,17 @@
-export { Store, createStore, RESET_DB_LOCAL_STORAGE_KEY } from './store.js'
-export type { LiveStoreQuery, BaseGraphQLContext, QueryResult, QueryDebugInfo, RefreshReason } from './store.js'
+export { Store, createStore } from './store.js'
+export type {
+  LiveStoreQuery,
+  GetAtomResult,
+  BaseGraphQLContext,
+  QueryResult,
+  QueryDebugInfo,
+  RefreshReason,
+} from './store.js'
 
 export type { QueryDefinition, LiveStoreCreateStoreOptions, LiveStoreContext } from './effect/LiveStore.js'
 
 export {
   defineComponentStateSchema,
-  EVENT_CURSOR_TABLE,
   defineAction,
   defineActions,
   defineTables,
@@ -37,5 +43,5 @@ export type TableDefinition = SqliteAst.Table
 
 export { SqliteDsl as DbSchema } from 'effect-db-schema'
 
-export { sql, type Bindable } from './util.js'
+export { prepareBindValues, sql, type Bindable, type PreparedBindValues } from './util.js'
 export { isEqual } from 'lodash-es'

package/src/migrations.ts

@@ -5,8 +5,11 @@ import { memoize, omit } from 'lodash-es'
 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'
 
+const getMemoizedTimestamp = memoize(() => new Date().toISOString())
+
 // TODO more graceful DB migration (e.g. backup DB before destructive migrations)
 export const migrateDb = ({
   db,
@@ -31,7 +34,6 @@ export const migrateDb = ({
     schemaMetaRows.map(({ tableName, schemaHash }) => [tableName, schemaHash]),
   )
 
-  const getMemoizedTimestamp = memoize(() => new Date().toISOString())
   const tableDefs = {
     // NOTE it's important the `SCHEMA_META_TABLE` comes first since we're writing to it below
     [SCHEMA_META_TABLE]: systemTables[SCHEMA_META_TABLE],
@@ -47,30 +49,46 @@ export const migrateDb = ({
         `Schema hash mismatch for table '${tableName}' (DB: ${dbSchemaHash}, expected: ${schemaHash}), migrating table...`,
       )
 
-      const columnSpec = makeColumnSpec(tableDef)
-
-      // 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) {
-        db.execute(createIndexFromDefinition(tableName, index), undefined, [], { otelContext })
-      }
-
-      const updatedAt = getMemoizedTimestamp()
-      db.execute(
-        sql`
-          INSERT INTO ${SCHEMA_META_TABLE} (tableName, schemaHash, updatedAt) VALUES ($tableName, $schemaHash, $updatedAt)
-            ON CONFLICT (tableName) DO UPDATE SET schemaHash = $schemaHash, updatedAt = $updatedAt;
-        `,
-        { tableName, schemaHash, updatedAt },
-        [],
-        { otelContext },
-      )
+      migrateTable({ db, tableDef, otelContext, schemaHash })
     }
   }
 }
 
+export const migrateTable = ({
+  db,
+  tableDef,
+  otelContext,
+  schemaHash,
+}: {
+  db: InMemoryDatabase
+  tableDef: SqliteAst.Table
+  otelContext: otel.Context
+  schemaHash: number
+}) => {
+  console.log(`Migrating table '${tableDef.name}'...`)
+  const tableName = tableDef.name
+  const columnSpec = makeColumnSpec(tableDef)
+
+  // 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) {
+    db.execute(createIndexFromDefinition(tableName, index), undefined, [], { otelContext })
+  }
+
+  const updatedAt = getMemoizedTimestamp()
+  db.execute(
+    sql`
+      INSERT INTO ${SCHEMA_META_TABLE} (tableName, schemaHash, updatedAt) VALUES ($tableName, $schemaHash, $updatedAt)
+        ON CONFLICT (tableName) DO UPDATE SET schemaHash = $schemaHash, updatedAt = $updatedAt;
+    `,
+    { $tableName: tableName, $schemaHash: schemaHash, $updatedAt: updatedAt } as unknown as PreparedBindValues,
+    [],
+    { otelContext },
+  )
+}
+
 const createIndexFromDefinition = (tableName: string, index: SqliteAst.Index) => {
   const uniqueStr = index.unique ? 'UNIQUE' : ''
   return sql`create ${uniqueStr} index ${index.name} on ${tableName} (${index.columns.join(', ')})`

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

@@ -14,7 +14,7 @@ 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 { useQuery } from './useQuery.js'
 
 // Needed to make TS happy
 export type { TypedDocumentNode } from '@graphql-typed-document-node/core'

package/src/react/useGraphQL.ts

@@ -15,6 +15,12 @@ export type UseLiveStoreComponentProps<TResult extends Record<string, any>, TVar
   reactDeps?: React.DependencyList
 }
 
+type Variables = Record<string, any>
+
+// 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
+// NOTE we're using a nested map here since we need to resolve 2 levels of object identities (query + variables)
+// const queryCache = new Map<DocumentNode<any, any>, Map<Variables, LiveStoreGraphQLQuery<any, any, any>>>()
+
 /**
  * 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.
@@ -24,7 +30,7 @@ const spanAlreadyStartedCache = new Map<string, { span: otel.Span; otelContext:
 
 // TODO 1) figure out a way to make `variables` optional if the query doesn't have any variables (probably requires positional args)
 // TODO 2) allow `.pipe` on the resulting query (possibly as a separate optional prop)
-export const useGraphQL = <TResult extends Record<string, any>, TVariables extends Record<string, any> = {}>({
+export const useGraphQL = <TResult extends Record<string, any>, TVariables extends Variables = {}>({
   query,
   variables,
   componentKey: componentKeyConfig,
@@ -62,7 +68,27 @@ export const useGraphQL = <TResult extends Record<string, any>, TVariables exten
   )
 
   const makeLiveStoreQuery = React.useCallback(
-    () => store.queryGraphQL(query, () => variables ?? ({} as TVariables), { componentKey, otelContext }),
+    () => {
+      return store.queryGraphQL(query, () => variables ?? ({} as TVariables), { componentKey, otelContext })
+
+      // NOTE I had to disable the caching below as still led to many problems
+      // We should just implement the new query definition approach instead
+
+      // const queryCacheForQuery = queryCache.get(query)
+      // if (queryCacheForQuery && queryCacheForQuery.has(variables)) {
+      //   return queryCacheForQuery.get(variables)!
+      // }
+
+      // const newQuery = store.queryGraphQL(query, () => variables ?? ({} as TVariables), { componentKey, otelContext })
+
+      // if (queryCacheForQuery) {
+      //   queryCacheForQuery.set(variables, newQuery)
+      // } else {
+      //   queryCache.set(query, new Map([[variables, newQuery]]))
+      // }
+
+      // return newQuery
+    },
     // 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.

package/src/react/useLiveStoreComponent.ts

@@ -3,7 +3,7 @@ import type { LiteralUnion, PrettifyFlat } 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,11 +11,12 @@ 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 { 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 type { BaseGraphQLContext, LiveStoreQuery, QueryResult, Store } from '../store.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 { sql } from '../util.js'
 import { useStore } from './LiveStoreContext.js'
@@ -28,17 +29,20 @@ export interface QueryDefinitions {
 export type QueryResults<TQuery> = { [queryName in keyof TQuery]: PrettifyFlat<QueryResult<TQuery[queryName]>> }
 
 export type ReactiveSQL = <TResult>(
-  genQuery: (get: GetAtom) => string,
+  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>,
-  genVariableValues: (get: GetAtom) => TVariables,
+  variableValues: TVariables | ((get: GetAtomResult) => TVariables),
   label?: string,
 ) => LiveStoreGraphQLQuery<TResult, TVariables, TContext>
 
@@ -51,7 +55,7 @@ type RegisterSubscription = <TQuery extends LiveStoreQuery>(
 type GenQueries<TQueries, TStateResult> = (args: {
   rxSQL: ReactiveSQL
   rxGraphQL: ReactiveGraphQL
-  globalQueries: QueryDefinitions
+  rxJS: ReactiveJS
   state$: LiveStoreJSQuery<TStateResult>
   /**
    * Registers a subscription.
@@ -62,9 +66,9 @@ type GenQueries<TQueries, TStateResult> = (args: {
   isTemporaryQuery: boolean
 }) => TQueries
 
-export type UseLiveStoreComponentProps<TQueries, TColumns extends ComponentColumns> = {
-  stateSchema?: SqliteDsl.TableDefinition<string, TColumns>
-  queries?: GenQueries<TQueries, SqliteDsl.FromColumns.RowDecoded<TColumns>>
+export type UseLiveStoreComponentProps<TQueries, TStateColumns extends ComponentColumns> = {
+  stateSchema?: SqliteDsl.TableDefinition<string, TStateColumns>
+  queries?: GenQueries<TQueries, SqliteDsl.FromColumns.RowDecoded<TStateColumns>>
   reactDeps?: React.DependencyList
   componentKey: ComponentKeyConfig
 }
@@ -115,18 +119,18 @@ 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>({
+export const useLiveStoreComponent = <TStateColumns extends ComponentColumns, TQueries extends QueryDefinitions>({
   stateSchema: stateSchema_,
   queries = () => ({}) as TQueries,
   componentKey: componentKeyConfig,
   reactDeps = [],
-}: UseLiveStoreComponentProps<TQueries, TColumns>): {
+}: UseLiveStoreComponentProps<TQueries, TStateColumns>): {
   queryResults: QueryResults<TQueries>
-  state: SqliteDsl.FromColumns.RowDecoded<TColumns>
-  setState: Setters<SqliteDsl.FromColumns.RowDecoded<TColumns>>
-  useLiveStoreJsonState: UseLiveStoreJsonState<SqliteDsl.FromColumns.RowDecoded<TColumns>>
+  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
@@ -137,7 +141,7 @@ export const useLiveStoreComponent = <TColumns extends ComponentColumns, TQuerie
 
   // performance.mark('useLiveStoreComponent:start')
   const componentKey = useComponentKey(componentKeyConfig, reactDeps)
-  const { store, globalQueries } = useStore()
+  const { store } = useStore()
 
   const componentKeyLabel = React.useMemo(() => labelForKey(componentKey), [componentKey])
 
@@ -180,14 +184,17 @@ export const useLiveStoreComponent = <TColumns extends ComponentColumns, TQuerie
       isTemporaryQuery: boolean
     }) =>
       queries({
-        rxSQL: <T>(genQuery: (get: GetAtom) => string, queriedTables: string[], bindValues?: Bindable) =>
-          store.querySQL<T>(genQuery, { queriedTables, bindValues, otelContext, componentKey }),
+        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: (get: GetAtom) => Variables,
+          genVariableValues: Variables | ((get: GetAtomResult) => Variables),
           label?: string,
         ) => store.queryGraphQL(query, genVariableValues, { componentKey, label, otelContext }),
-        globalQueries,
+        rxJS: <T>(genQuery: (get: GetAtomResult) => T) => store.queryJS(genQuery, { componentKey, otelContext }),
         state$,
         subscribe: registerSubscription,
         isTemporaryQuery,
@@ -199,7 +206,7 @@ export const useLiveStoreComponent = <TColumns extends ComponentColumns, TQuerie
     // 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],
+    [store, componentKey],
   )
 
   const defaultComponentState = React.useMemo(() => {
@@ -226,6 +233,7 @@ export const useLiveStoreComponent = <TColumns extends ComponentColumns, TQuerie
     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
@@ -239,6 +247,24 @@ export const useLiveStoreComponent = <TColumns extends ComponentColumns, TQuerie
           } 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],
@@ -380,15 +406,15 @@ export const useLiveStoreComponent = <TColumns extends ComponentColumns, TQuerie
           ),
         )
 
-        const registerSubscription: RegisterSubscription = (query, callback, onUnsubscribe) => {
+        const registerSubscription: RegisterSubscription = (query$, callback, onUnsubscribe) => {
           unsubs.push(
             store.subscribe(
-              query,
+              query$,
               (results) => {
                 callback(results)
               },
               onUnsubscribe,
-              { label: `useLiveStoreComponent:query:manual-subscribe:${query.label}` },
+              { label: `useLiveStoreComponent:query:manual-subscribe:${query$.label}` },
             ),
           )
         }

package/src/react/useQuery.ts

@@ -0,0 +1,56 @@
+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 { useStore } from './LiveStoreContext.js'
+
+// 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> => {
+  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])
+
+  // 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)
+
+  // 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, store])
+
+  return value
+}

package/src/reactive.ts

@@ -30,6 +30,9 @@ import { isEqual, max, uniqueId } from 'lodash-es'
 
 import { BoundArray } from './bounded-collections.js'
 
+const NOT_REFRESHED_YET = Symbol.for('NOT_REFRESHED_YET')
+type NOT_REFRESHED_YET = typeof NOT_REFRESHED_YET
+
 export type GetAtom = <T>(atom: Atom<T>) => T
 
 export type Ref<T> = {
@@ -59,7 +62,7 @@ type BaseThunk<T> = {
   equal: (a: T, b: T) => boolean
 }
 
-type UnevaluatedThunk<T> = BaseThunk<T> & { result: undefined }
+type UnevaluatedThunk<T> = BaseThunk<T> & { result: NOT_REFRESHED_YET }
 export type Thunk<T> = BaseThunk<T> & { result: T }
 
 export type Atom<T> = Ref<T> | Thunk<T>
@@ -201,7 +204,7 @@ export class ReactiveGraph<TDebugRefreshReason extends Taggable, TDebugThunkInfo
     const thunk: UnevaluatedThunk<T> = {
       _tag: 'thunk',
       id: uniqueNodeId(),
-      result: undefined,
+      result: NOT_REFRESHED_YET,
       height: 0,
       getResult,
       sub: new Set(),
@@ -342,7 +345,7 @@ export class ReactiveGraph<TDebugRefreshReason extends Taggable, TDebugThunkInfo
     this.addEdge(context, atom)
 
     const dependencyMightBeStale = context._tag !== 'effect' && context.height <= atom.height
-    const dependencyNotRefreshedYet = atom.result === undefined
+    const dependencyNotRefreshedYet = atom.result === NOT_REFRESHED_YET
 
     if (dependencyMightBeStale || dependencyNotRefreshedYet) {
       throw new DependencyNotReadyError(
@@ -350,7 +353,6 @@ export class ReactiveGraph<TDebugRefreshReason extends Taggable, TDebugThunkInfo
       )
     }
 
-    // TODO handle case when `atom.result` is undefined
     return atom.result
   }