@livestore/livestore 0.0.12 → 0.0.15

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

@@ -1,6 +1,9 @@
 import type { TypedDocumentNode as DocumentNode } from '@graphql-typed-document-node/core'
-import { type LiteralUnion, omit, shouldNeverHappen } from '@livestore/utils'
+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 { SqliteAst, SqliteDsl } from 'effect-db-schema'
 import { isEqual, mapValues } from 'lodash-es'
 import type { DependencyList } from 'react'
 import React from 'react'
@@ -8,12 +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 { ComponentStateSchema } from '../schema.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'
@@ -22,20 +25,24 @@ import { useStateRefWithReactiveInput } from './utils/useStateRefWithReactiveInp
 export interface QueryDefinitions {
   [queryName: string]: LiveStoreQuery
 }
-export type QueryResults<TQuery> = { [queryName in keyof TQuery]: QueryResult<TQuery[queryName]> }
+
+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>
 
@@ -48,16 +55,20 @@ type RegisterSubscription = <TQuery extends LiveStoreQuery>(
 type GenQueries<TQueries, TStateResult> = (args: {
   rxSQL: ReactiveSQL
   rxGraphQL: ReactiveGraphQL
-  globalQueries: QueryDefinitions
+  rxJS: ReactiveJS
   state$: LiveStoreJSQuery<TStateResult>
-  /** Registers a subscription */
+  /**
+   * Registers a subscription.
+   *
+   * Passed down for some manual subscribing. Use carefully.
+   */
   subscribe: RegisterSubscription
   isTemporaryQuery: boolean
 }) => TQueries
 
-export type UseLiveStoreComponentProps<TQueries, TComponentState> = {
-  stateSchema?: ComponentStateSchema<TComponentState>
-  queries?: GenQueries<TQueries, TComponentState>
+export type UseLiveStoreComponentProps<TQueries, TStateColumns extends ComponentColumns> = {
+  stateSchema?: SqliteDsl.TableDefinition<string, TStateColumns>
+  queries?: GenQueries<TQueries, SqliteDsl.FromColumns.RowDecoded<TStateColumns>>
   reactDeps?: React.DependencyList
   componentKey: ComponentKeyConfig
 }
@@ -72,12 +83,17 @@ export type ComponentKeyConfig = {
   id: LiteralUnion<'singleton' | '__ephemeral__', string>
 }
 
-type ComponentState = {
-  /** Equivalent to `componentKey.key` */
-  id: string
-  [key: string]: string | number | boolean | null
+// TODO enforce columns are non-nullable or have a default
+export interface ComponentColumns extends SqliteDsl.Columns {
+  id: SqliteDsl.ColumnDefinition<SqliteDsl.FieldType.FieldTypeText<string, string>, false>
 }
 
+// type ComponentState = {
+//   /** Equivalent to `componentKey.key` */
+//   id: string
+//   [key: string]: string | number | boolean | null
+// }
+
 /**
  * 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.
@@ -90,23 +106,33 @@ type UseLiveStoreJsonState<TState> = <TResult>(
   parse?: (_: unknown) => TResult,
 ) => [value: TResult, setValue: (newVal: TResult | ((prevVal: TResult) => TResult)) => void]
 
+export type GetStateType<TTableDef extends SqliteDsl.TableDefinition<any, any>> = SqliteDsl.FromColumns.RowDecoded<
+  TTableDef['columns']
+>
+
+export type GetStateTypeEncoded<TTableDef extends SqliteDsl.TableDefinition<any, any>> =
+  SqliteDsl.FromColumns.RowEncoded<TTableDef['columns']>
+
 /**
  * Create reactive queries within a component.
  * @param config.queries A function that returns a map of named reactive queries.
  * @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 = <TComponentState extends ComponentState, TQueries extends QueryDefinitions>({
+export const useLiveStoreComponent = <TStateColumns extends ComponentColumns, TQueries extends QueryDefinitions>({
   stateSchema: stateSchema_,
   queries = () => ({}) as TQueries,
   componentKey: componentKeyConfig,
   reactDeps = [],
-}: UseLiveStoreComponentProps<TQueries, TComponentState>): {
+}: UseLiveStoreComponentProps<TQueries, TStateColumns>): {
   queryResults: QueryResults<TQueries>
-  state: TComponentState
-  setState: Setters<TComponentState>
-  useLiveStoreJsonState: UseLiveStoreJsonState<TComponentState>
+  state: SqliteDsl.FromColumns.RowDecoded<TStateColumns>
+  setState: Setters<SqliteDsl.FromColumns.RowDecoded<TStateColumns>>
+  useLiveStoreJsonState: UseLiveStoreJsonState<SqliteDsl.FromColumns.RowDecoded<TStateColumns>>
 } => {
+  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
   const stateSchema = React.useMemo(
     () => (stateSchema_ ? { ...stateSchema_, columns: omit(stateSchema_.columns, 'id' as any) } : undefined),
@@ -115,7 +141,7 @@ export const useLiveStoreComponent = <TComponentState extends ComponentState, TQ
 
   // performance.mark('useLiveStoreComponent:start')
   const componentKey = useComponentKey(componentKeyConfig, reactDeps)
-  const { store, globalQueries } = useStore()
+  const { store } = useStore()
 
   const componentKeyLabel = React.useMemo(() => labelForKey(componentKey), [componentKey])
 
@@ -158,14 +184,17 @@ export const useLiveStoreComponent = <TComponentState extends ComponentState, TQ
       isTemporaryQuery: boolean
     }) =>
       queries({
-        rxSQL: <T>(genQuery: (get: GetAtom) => string, queriedTables: string[], bindValues?: Bindable) =>
-          store.querySQL<T>(genQuery, { queriedTables, bindValues, otelContext }),
+        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,
@@ -177,7 +206,7 @@ export const useLiveStoreComponent = <TComponentState extends ComponentState, TQ
     // 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(() => {
@@ -185,11 +214,17 @@ export const useLiveStoreComponent = <TComponentState extends ComponentState, TQ
       stateSchema === undefined ? {} : mapValues(stateSchema.columns, (c) => c.default)
     ) as TComponentState
 
+    // @ts-expect-error TODO fix typing
     defaultState.id = componentKeyConfig.id
 
     return defaultState
   }, [componentKeyConfig.id, stateSchema])
 
+  const componentStateEffectSchema = React.useMemo(
+    () => (stateSchema ? SqliteDsl.structSchemaForTable(stateSchema) : Schema.any),
+    [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
@@ -198,32 +233,56 @@ export const useLiveStoreComponent = <TComponentState extends ComponentState, TQ
     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 stateQuery: LiveStoreJSQuery<TComponentState>
+          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)
-            stateQuery = store.queryJS(() => ({}), {
+            state$ = store.queryJS(() => ({}), {
               componentKey,
               otelContext,
             }) as unknown as LiveStoreJSQuery<TComponentState>
           } else {
             const componentTableName = tableNameForComponentKey(componentKey)
             const whereClause = componentKey._tag === 'singleton' ? '' : `where id = '${componentKey.id}'`
-            stateQuery = store
-              .querySQL<TComponentState>(() => sql`select * from ${componentTableName} ${whereClause} limit 1`, {
+
+            // 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,
               })
-              .getFirstRow({ defaultValue: defaultComponentState })
+              // 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 = stateQuery.results$.result
+          const initialComponentState = state$.results$.result
 
           const queries = generateQueries({
-            state$: stateQuery,
+            state$: state$,
             otelContext,
             registerSubscription: () => {},
             isTemporaryQuery: true,
@@ -231,7 +290,11 @@ export const useLiveStoreComponent = <TComponentState extends ComponentState, TQ
           for (const [name, query] of Object.entries(queries)) {
             query.label = name
           }
-          const initialQueryResults = mapValues(queries, (query) => query.results$.result) as QueryResults<TQueries>
+          const initialQueryResults = mapValues(
+            queries,
+            (query) => query.results$.result,
+            // TODO improve typing
+          ) as unknown as QueryResults<TQueries>
 
           return { initialComponentState, initialQueryResults }
         } finally {
@@ -239,7 +302,16 @@ export const useLiveStoreComponent = <TComponentState extends ComponentState, TQ
         }
       })
     })
-  }, [store, otelContext, stateSchema, generateQueries, componentKey, componentKeyLabel, defaultComponentState])
+  }, [
+    store,
+    otelContext,
+    stateSchema,
+    generateQueries,
+    componentKey,
+    componentKeyLabel,
+    componentStateEffectSchema,
+    defaultComponentState,
+  ])
 
   // Now that we've computed the initial state synchronously,
   // we can set up our useState calls w/ a default value populated...
@@ -251,10 +323,13 @@ export const useLiveStoreComponent = <TComponentState extends ComponentState, TQ
     stateSchema === undefined
       ? {}
       : // TODO: do we have a better type for the values that can go in SQLite?
-        mapValues(stateSchema.columns, (_, columnName) => (value: string | number) => {
+        mapValues(stateSchema.columns, (column, columnName) => (value: string | number) => {
           // Don't update the state if it's the same as the value already seen in the component
+          // @ts-expect-error TODO fix typing
           if (componentStateRef.current[columnName] === value) return
 
+          const encodedValue = Schema.encodeSync(column.type.codec)(value)
+
           if (['componentKey', 'columnNames'].includes(columnName)) {
             shouldNeverHappen(`Can't use reserved column name ${columnName}`)
           }
@@ -262,7 +337,7 @@ export const useLiveStoreComponent = <TComponentState extends ComponentState, TQ
           return store.applyEvent('updateComponentState', {
             componentKey,
             columnNames: [columnName],
-            [columnName]: value,
+            [columnName]: encodedValue,
           })
         })
   ) as Setters<TComponentState>
@@ -270,6 +345,7 @@ export const useLiveStoreComponent = <TComponentState extends ComponentState, TQ
   setState.setMany = (columnValues: Partial<TComponentState>) => {
     // TODO use hashing instead
     // Don't update the state if it's the same as the value already seen in the component
+    // @ts-expect-error TODO fix typing
     if (Object.entries(columnValues).every(([columnName, value]) => componentStateRef.current[columnName] === value)) {
       return
     }
@@ -293,7 +369,12 @@ export const useLiveStoreComponent = <TComponentState extends ComponentState, TQ
         // create state query
         let state$: LiveStoreJSQuery<TComponentState>
         if (stateSchema === undefined) {
-          state$ = store.queryJS(() => ({}) as TComponentState, { componentKey, otelContext })
+          // TODO remove this query
+          state$ = store.queryJS(() => ({}) as TComponentState, {
+            componentKey,
+            otelContext,
+            label: 'empty-component-state',
+          })
         } else {
           const componentTableName = tableNameForComponentKey(componentKey)
           insertRowForComponentInstance({ store, componentKey, stateSchema })
@@ -306,7 +387,10 @@ export const useLiveStoreComponent = <TComponentState extends ComponentState, TQ
               label: `localState:query:${componentKeyLabel}`,
               otelContext,
             })
-            .getFirstRow({ defaultValue: defaultComponentState })
+            // 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,
+            )
         }
 
         unsubs.push(
@@ -322,25 +406,25 @@ export const useLiveStoreComponent = <TComponentState extends ComponentState, TQ
           ),
         )
 
-        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}` },
             ),
           )
         }
 
         const queries = generateQueries({ state$, otelContext, registerSubscription, isTemporaryQuery: false })
-        // Use the name given to this query in the useQueries hook as its label
-        for (const [name, query] of Object.entries(queries)) {
-          query.label = name
-        }
+
         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,
@@ -447,14 +531,14 @@ export const useComponentKey = ({ name, id }: ComponentKeyConfig, deps: Dependen
  * Create a row storing the state for a component instance, if none exists yet.
  * Initialized with default values, and keyed on the component key.
  */
-const insertRowForComponentInstance = <T>({
+const insertRowForComponentInstance = ({
   store,
   componentKey,
   stateSchema,
 }: {
   store: Store<BaseGraphQLContext>
   componentKey: ComponentKey
-  stateSchema: ComponentStateSchema<T>
+  stateSchema: SqliteDsl.TableDefinition<string, SqliteDsl.Columns>
 }) => {
   const columnNames = ['id', ...Object.keys(stateSchema.columns)]
   const columnValues = columnNames.map((name) => `$${name}`).join(', ')
@@ -467,8 +551,8 @@ const insertRowForComponentInstance = <T>({
   void store.execute(
     insertQuery,
     {
-      id: componentKey.id,
       ...mapValues(stateSchema.columns, (column) => prepareValueForSql(column.default ?? null)),
+      id: componentKey.id,
     },
     [tableName],
   )

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
   }
 

package/src/reactiveQueries/base-class.ts

@@ -5,13 +5,13 @@ import type { Store } from '../store.js'
 
 export type UnsubscribeQuery = () => void
 
-export abstract class LiveStoreQueryBase {
+export abstract class LiveStoreQueryBase<TResult> {
   /** The key for the associated component */
   componentKey: ComponentKey
   /** Human-readable label for the query for debugging */
   label: string
   /** A pointer back to the store containing this query */
-  store: Store<any>
+  store: Store
   /** Otel Span is started in LiveStore store but ended in this query */
   otelContext: otel.Context
 
@@ -26,7 +26,7 @@ export abstract class LiveStoreQueryBase {
   }: {
     componentKey: ComponentKey
     label: string
-    store: Store<any>
+    store: Store
     otelContext: otel.Context
   }) {
     this.componentKey = componentKey
@@ -46,4 +46,10 @@ export abstract class LiveStoreQueryBase {
       unsubscribe()
     }
   }
+
+  subscribe = (
+    onNewValue: (value: TResult) => void,
+    onSubsubscribe?: () => void,
+    options?: { label?: string } | undefined,
+  ): (() => void) => this.store.subscribe(this as any, onNewValue as any, onSubsubscribe, options)
 }

package/src/reactiveQueries/graphql.ts

@@ -2,8 +2,8 @@ import type { TypedDocumentNode as DocumentNode } from '@graphql-typed-document-
 import type * as otel from '@opentelemetry/api'
 
 import type { ComponentKey } from '../componentKey.js'
-import type { GetAtom, Thunk } from '../reactive.js'
-import type { BaseGraphQLContext, Store } from '../store.js'
+import type { Thunk } from '../reactive.js'
+import type { BaseGraphQLContext, GetAtomResult, Store } from '../store.js'
 import { LiveStoreQueryBase } from './base-class.js'
 import type { LiveStoreJSQuery } from './js.js'
 
@@ -11,7 +11,7 @@ export class LiveStoreGraphQLQuery<
   TResult extends Record<string, any>,
   VariableValues extends Record<string, any>,
   TContext extends BaseGraphQLContext,
-> extends LiveStoreQueryBase {
+> extends LiveStoreQueryBase<TResult> {
   _tag: 'graphql' = 'graphql'
 
   /** The abstract GraphQL query */
@@ -39,7 +39,7 @@ export class LiveStoreGraphQLQuery<
     this.results$ = results$
   }
 
-  pipe = <U>(f: (x: TResult, get: GetAtom) => U): LiveStoreJSQuery<U> =>
+  pipe = <U>(f: (x: TResult, get: GetAtomResult) => U): LiveStoreJSQuery<U> =>
     this.store.queryJS(
       (get) => {
         const results = get(this.results$)

package/src/reactiveQueries/js.ts

@@ -5,7 +5,7 @@ import type { GetAtom, Thunk } from '../reactive.js'
 import type { Store } from '../store.js'
 import { LiveStoreQueryBase } from './base-class.js'
 
-export class LiveStoreJSQuery<TResult> extends LiveStoreQueryBase {
+export class LiveStoreJSQuery<TResult> extends LiveStoreQueryBase<TResult> {
   _tag: 'js' = 'js'
   /** A reactive thunk representing the query results */
   results$: Thunk<TResult>
@@ -17,7 +17,7 @@ export class LiveStoreJSQuery<TResult> extends LiveStoreQueryBase {
     results$: Thunk<TResult>
     componentKey: ComponentKey
     label: string
-    store: Store<any>
+    store: Store
     otelContext: otel.Context
   }) {
     super(baseProps)