@livestore/react 0.0.0-snapshot-8d3edf87cb1e88c7b67c5f3ea9d0b307253c33df

package/src/useQuery.test.tsx

@@ -0,0 +1,82 @@
+import { querySQL } from '@livestore/livestore'
+import { Effect, Schema } from '@livestore/utils/effect'
+import { renderHook } from '@testing-library/react'
+import React from 'react'
+import { describe, expect, it } from 'vitest'
+
+import { makeTodoMvcReact, tables, todos } from './__tests__/fixture.js'
+import * as LiveStoreReact from './mod.js'
+
+describe('useQuery', () => {
+  it('simple', () =>
+    Effect.gen(function* () {
+      const { wrapper, store, makeRenderCount } = yield* makeTodoMvcReact()
+
+      const renderCount = makeRenderCount()
+
+      const allTodos$ = querySQL(`select * from todos`, { schema: Schema.Array(tables.todos.schema) })
+
+      const { result } = renderHook(
+        () => {
+          renderCount.inc()
+
+          return LiveStoreReact.useQuery(allTodos$)
+        },
+        { wrapper },
+      )
+
+      expect(result.current.length).toBe(0)
+      expect(renderCount.val).toBe(1)
+
+      React.act(() => store.mutate(todos.insert({ id: 't1', text: 'buy milk', completed: false })))
+
+      expect(result.current.length).toBe(1)
+      expect(result.current[0]!.text).toBe('buy milk')
+      expect(renderCount.val).toBe(2)
+    }).pipe(Effect.scoped, Effect.tapCauseLogPretty, Effect.runPromise))
+
+  it('same `useQuery` hook invoked with different queries', () =>
+    Effect.gen(function* () {
+      const { wrapper, store, makeRenderCount } = yield* makeTodoMvcReact()
+
+      const renderCount = makeRenderCount()
+
+      const todo1$ = querySQL(`select * from todos where id = 't1'`, {
+        label: 'libraryTracksView1',
+        schema: Schema.Array(tables.todos.schema),
+      })
+      const todo2$ = querySQL(`select * from todos where id = 't2'`, {
+        label: 'libraryTracksView2',
+        schema: Schema.Array(tables.todos.schema),
+      })
+
+      store.mutate(
+        todos.insert({ id: 't1', text: 'buy milk', completed: false }),
+        todos.insert({ id: 't2', text: 'buy eggs', completed: false }),
+      )
+
+      const { result, rerender } = renderHook(
+        (todoId: string) => {
+          renderCount.inc()
+
+          const query$ = React.useMemo(() => (todoId === 't1' ? todo1$ : todo2$), [todoId])
+
+          return LiveStoreReact.useQuery(query$)[0]!.text
+        },
+        { wrapper, initialProps: 't1' },
+      )
+
+      expect(result.current).toBe('buy milk')
+      expect(renderCount.val).toBe(1)
+
+      React.act(() => store.mutate(todos.update({ where: { id: 't1' }, values: { text: 'buy soy milk' } })))
+
+      expect(result.current).toBe('buy soy milk')
+      expect(renderCount.val).toBe(2)
+
+      rerender('t2')
+
+      expect(result.current).toBe('buy eggs')
+      expect(renderCount.val).toBe(3)
+    }).pipe(Effect.scoped, Effect.tapCauseLogPretty, Effect.runPromise))
+})

package/src/useQuery.ts

@@ -0,0 +1,122 @@
+import type { GetResult, LiveQueryAny } from '@livestore/livestore'
+import { extractStackInfoFromStackTrace, stackInfoToString } from '@livestore/livestore'
+import { deepEqual, indent } from '@livestore/utils'
+import * as otel from '@opentelemetry/api'
+import React from 'react'
+
+import { useStore } from './LiveStoreContext.js'
+import { originalStackLimit } from './utils/stack-info.js'
+import { useStateRefWithReactiveInput } from './utils/useStateRefWithReactiveInput.js'
+
+/**
+ * NOTE Some folks have suggested to use `React.useSyncExternalStore`, however, it's not doing anything special
+ * for what's needed here, so we handle everything manually.
+ */
+
+/**
+ * This is needed because the `React.useMemo` call below, can sometimes be called multiple times 🤷,
+ * so we need to "cache" the fact that we've already started a span for this component.
+ * The map entry is being removed again in the `React.useEffect` call below.
+ */
+const spanAlreadyStartedCache = new Map<LiveQueryAny, { span: otel.Span; otelContext: otel.Context }>()
+
+export const useQuery = <TQuery extends LiveQueryAny>(query: TQuery): GetResult<TQuery> => useQueryRef(query).current
+
+/**
+ *
+ */
+export const useQueryRef = <TQuery extends LiveQueryAny>(
+  query$: TQuery,
+  parentOtelContext?: otel.Context,
+): React.MutableRefObject<GetResult<TQuery>> => {
+  const { store } = useStore()
+
+  React.useDebugValue(`LiveStore:useQuery:${query$.id}:${query$.label}`)
+  // console.debug(`LiveStore:useQuery:${query$.id}:${query$.label}`)
+
+  const stackInfo = React.useMemo(() => {
+    Error.stackTraceLimit = 10
+    // eslint-disable-next-line unicorn/error-message
+    const stack = new Error().stack!
+    Error.stackTraceLimit = originalStackLimit
+    return extractStackInfoFromStackTrace(stack)
+  }, [])
+
+  // The following `React.useMemo` and `React.useEffect` calls are used to start and end a span for the lifetime of this component.
+  const { span, otelContext } = React.useMemo(() => {
+    const existingSpan = spanAlreadyStartedCache.get(query$)
+    if (existingSpan !== undefined) return existingSpan
+
+    const span = store.otel.tracer.startSpan(
+      `LiveStore:useQuery:${query$.label}`,
+      { attributes: { label: query$.label, stackInfo: JSON.stringify(stackInfo) } },
+      parentOtelContext ?? store.otel.queriesSpanContext,
+    )
+
+    const otelContext = otel.trace.setSpan(otel.context.active(), span)
+
+    spanAlreadyStartedCache.set(query$, { span, otelContext })
+
+    return { span, otelContext }
+  }, [parentOtelContext, query$, stackInfo, store.otel.queriesSpanContext, store.otel.tracer])
+
+  const initialResult = React.useMemo(() => {
+    try {
+      return query$.run(otelContext, {
+        _tag: 'react',
+        api: 'useQuery',
+        label: query$.label,
+        stackInfo,
+      })
+    } catch (cause: any) {
+      throw new Error(
+        `\
+[@livestore/react:useQuery] Error running query: ${cause.name}
+
+Query: ${query$.label}
+
+React trace:
+
+${indent(stackInfoToString(stackInfo), 4)}
+
+Stack trace:
+`,
+        { cause },
+      )
+    }
+  }, [otelContext, query$, stackInfo])
+
+  // We know the query has a result by the time we use it; so we can synchronously populate a default state
+  const [valueRef, setValue] = useStateRefWithReactiveInput<GetResult<TQuery>>(initialResult)
+
+  React.useEffect(
+    () => () => {
+      spanAlreadyStartedCache.delete(query$)
+      span.end()
+    },
+    [query$, span],
+  )
+
+  // Subscribe to future updates for this query
+  React.useEffect(() => {
+    query$.activeSubscriptions.add(stackInfo)
+
+    return store.subscribe(
+      query$,
+      (newValue) => {
+        // NOTE: we return a reference to the result object within LiveStore;
+        // this implies that app code must not mutate the results, or else
+        // there may be weird reactivity bugs.
+        if (deepEqual(newValue, valueRef.current) === false) {
+          setValue(newValue)
+        }
+      },
+      () => {
+        query$.activeSubscriptions.delete(stackInfo)
+      },
+      { label: query$.label, otelContext },
+    )
+  }, [stackInfo, query$, setValue, store, valueRef, otelContext, span])
+
+  return valueRef
+}

package/src/useRow.test.tsx

@@ -0,0 +1,346 @@
+import * as LiveStore from '@livestore/livestore'
+import { getSimplifiedRootSpan } from '@livestore/livestore/internal/testing-utils'
+import { Effect, ReadonlyRecord, Schema } from '@livestore/utils/effect'
+import * as otel from '@opentelemetry/api'
+import { BasicTracerProvider, InMemorySpanExporter, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base'
+import { render, renderHook } from '@testing-library/react'
+import React from 'react'
+import { describe, expect, it } from 'vitest'
+
+import { AppComponentSchema, AppRouterSchema, makeTodoMvcReact, tables, todos } from './__tests__/fixture.js'
+import * as LiveStoreReact from './mod.js'
+
+// NOTE running tests concurrently doesn't work with the default global db graph
+describe('useRow', () => {
+  it('should update the data based on component key', () =>
+    Effect.gen(function* () {
+      const { wrapper, store, reactivityGraph, makeRenderCount } = yield* makeTodoMvcReact({
+        useGlobalReactivityGraph: false,
+      })
+
+      const renderCount = makeRenderCount()
+
+      const { result, rerender } = renderHook(
+        (userId: string) => {
+          renderCount.inc()
+
+          const [state, setState] = LiveStoreReact.useRow(AppComponentSchema, userId, { reactivityGraph })
+          return { state, setState }
+        },
+        { wrapper, initialProps: 'u1' },
+      )
+
+      expect(result.current.state.id).toBe('u1')
+      expect(result.current.state.username).toBe('')
+      expect(renderCount.val).toBe(1)
+
+      React.act(() =>
+        store.mutate(
+          LiveStore.rawSqlMutation({
+            sql: LiveStore.sql`INSERT INTO UserInfo (id, username) VALUES ('u2', 'username_u2')`,
+          }),
+        ),
+      )
+
+      rerender('u2')
+
+      expect(result.current.state.id).toBe('u2')
+      expect(result.current.state.username).toBe('username_u2')
+      expect(renderCount.val).toBe(2)
+    }).pipe(Effect.scoped, Effect.tapCauseLogPretty, Effect.runPromise))
+
+  // TODO add a test that makes sure React doesn't re-render when a setter is used to set the same value
+
+  it('should update the data reactively - via setState', () =>
+    Effect.gen(function* () {
+      const { wrapper, reactivityGraph, makeRenderCount } = yield* makeTodoMvcReact({
+        useGlobalReactivityGraph: false,
+      })
+
+      const renderCount = makeRenderCount()
+
+      const { result } = renderHook(
+        (userId: string) => {
+          renderCount.inc()
+
+          const [state, setState] = LiveStoreReact.useRow(AppComponentSchema, userId, { reactivityGraph })
+          return { state, setState }
+        },
+        { wrapper, initialProps: 'u1' },
+      )
+
+      expect(result.current.state.id).toBe('u1')
+      expect(result.current.state.username).toBe('')
+      expect(renderCount.val).toBe(1)
+
+      React.act(() => result.current.setState.username('username_u1_hello'))
+
+      expect(result.current.state.id).toBe('u1')
+      expect(result.current.state.username).toBe('username_u1_hello')
+      expect(renderCount.val).toBe(2)
+    }).pipe(Effect.scoped, Effect.tapCauseLogPretty, Effect.runPromise))
+
+  it('should update the data reactively - via raw store mutation', () =>
+    Effect.gen(function* () {
+      const { wrapper, store, reactivityGraph, makeRenderCount } = yield* makeTodoMvcReact({
+        useGlobalReactivityGraph: false,
+      })
+
+      const renderCount = makeRenderCount()
+
+      const { result } = renderHook(
+        (userId: string) => {
+          renderCount.inc()
+
+          const [state, setState] = LiveStoreReact.useRow(AppComponentSchema, userId, { reactivityGraph })
+          return { state, setState }
+        },
+        { wrapper, initialProps: 'u1' },
+      )
+
+      expect(result.current.state.id).toBe('u1')
+      expect(result.current.state.username).toBe('')
+      expect(renderCount.val).toBe(1)
+
+      React.act(() =>
+        store.mutate(
+          LiveStore.rawSqlMutation({
+            sql: LiveStore.sql`UPDATE UserInfo SET username = 'username_u1_hello' WHERE id = 'u1';`,
+          }),
+        ),
+      )
+
+      expect(result.current.state.id).toBe('u1')
+      expect(result.current.state.username).toBe('username_u1_hello')
+      expect(renderCount.val).toBe(2)
+    }).pipe(Effect.scoped, Effect.tapCauseLogPretty, Effect.runPromise))
+
+  it('should work for a larger app', () =>
+    Effect.gen(function* () {
+      const { wrapper, store, reactivityGraph, makeRenderCount } = yield* makeTodoMvcReact({
+        useGlobalReactivityGraph: false,
+      })
+
+      const allTodos$ = LiveStore.querySQL(`select * from todos`, {
+        label: 'allTodos',
+        schema: Schema.Array(tables.todos.schema),
+        reactivityGraph,
+      })
+
+      const appRouterRenderCount = makeRenderCount()
+      let globalSetState: LiveStoreReact.StateSetters<typeof AppRouterSchema> | undefined
+      const AppRouter: React.FC = () => {
+        appRouterRenderCount.inc()
+
+        const [state, setState] = LiveStoreReact.useRow(AppRouterSchema, { reactivityGraph })
+
+        globalSetState = setState
+
+        return (
+          <div>
+            <TasksList setTaskId={setState.currentTaskId} />
+            <div role="current-id">Current Task Id: {state.currentTaskId ?? '-'}</div>
+            {state.currentTaskId ? <TaskDetails id={state.currentTaskId} /> : <div>Click on a task to see details</div>}
+          </div>
+        )
+      }
+
+      const TasksList: React.FC<{ setTaskId: (_: string) => void }> = ({ setTaskId }) => {
+        const allTodos = LiveStoreReact.useQuery(allTodos$)
+
+        return (
+          <div>
+            {allTodos.map((_) => (
+              <div key={_.id} onClick={() => setTaskId(_.id)}>
+                {_.id}
+              </div>
+            ))}
+          </div>
+        )
+      }
+
+      const TaskDetails: React.FC<{ id: string }> = ({ id }) => {
+        const [todo] = LiveStoreReact.useRow(todos, id, { reactivityGraph })
+        return <div role="content">{JSON.stringify(todo)}</div>
+      }
+
+      const renderResult = render(<AppRouter />, { wrapper })
+
+      expect(appRouterRenderCount.val).toBe(1)
+
+      React.act(() =>
+        store.mutate(
+          LiveStore.rawSqlMutation({
+            sql: LiveStore.sql`INSERT INTO todos (id, text, completed) VALUES ('t1', 'buy milk', 0)`,
+          }),
+        ),
+      )
+
+      expect(appRouterRenderCount.val).toBe(1)
+      expect(renderResult.getByRole('current-id').innerHTML).toMatchInlineSnapshot('"Current Task Id: -"')
+
+      React.act(() => globalSetState!.currentTaskId('t1'))
+
+      expect(appRouterRenderCount.val).toBe(2)
+      expect(renderResult.getByRole('content').innerHTML).toMatchInlineSnapshot(
+        `"{"id":"t1","text":"buy milk","completed":false}"`,
+      )
+
+      expect(renderResult.getByRole('current-id').innerHTML).toMatchInlineSnapshot('"Current Task Id: t1"')
+
+      React.act(() =>
+        store.mutate(
+          LiveStore.rawSqlMutation({
+            sql: LiveStore.sql`INSERT INTO todos (id, text, completed) VALUES ('t2', 'buy eggs', 0)`,
+          }),
+          AppRouterSchema.update({ where: { id: 'singleton' }, values: { currentTaskId: 't2' } }),
+          LiveStore.rawSqlMutation({
+            sql: LiveStore.sql`INSERT INTO todos (id, text, completed) VALUES ('t3', 'buy bread', 0)`,
+          }),
+        ),
+      )
+
+      expect(appRouterRenderCount.val).toBe(3)
+      expect(renderResult.getByRole('current-id').innerHTML).toMatchInlineSnapshot('"Current Task Id: t2"')
+    }).pipe(Effect.scoped, Effect.tapCauseLogPretty, Effect.runPromise))
+
+  it('should work for a useRow query chained with a useTemporary query', () =>
+    Effect.gen(function* () {
+      const { store, wrapper, reactivityGraph, makeRenderCount } = yield* makeTodoMvcReact({
+        useGlobalReactivityGraph: false,
+      })
+      const renderCount = makeRenderCount()
+
+      store.mutate(
+        todos.insert({ id: 't1', text: 'buy milk', completed: false }),
+        todos.insert({ id: 't2', text: 'buy bread', completed: false }),
+      )
+
+      const { result, unmount, rerender } = renderHook(
+        (userId: string) => {
+          renderCount.inc()
+
+          const [_row, _setRow, rowState$] = LiveStoreReact.useRow(AppComponentSchema, userId, { reactivityGraph })
+          const todos = LiveStoreReact.useTemporaryQuery(
+            () =>
+              LiveStore.querySQL(
+                (get) => LiveStore.sql`select * from todos where text like '%${get(rowState$).text}%'`,
+                {
+                  schema: Schema.Array(tables.todos.schema),
+                  reactivityGraph,
+                  label: 'todosFiltered',
+                },
+              ),
+            userId,
+          )
+
+          return { todos }
+        },
+        { wrapper, initialProps: 'u1' },
+      )
+
+      React.act(() =>
+        store.mutate(
+          LiveStore.rawSqlMutation({
+            sql: LiveStore.sql`INSERT INTO UserInfo (id, username, text) VALUES ('u2', 'username_u2', 'milk')`,
+          }),
+        ),
+      )
+
+      expect(result.current.todos.length).toBe(2)
+      // expect(result.current.state.username).toBe('')
+      expect(renderCount.val).toBe(1)
+
+      rerender('u2')
+
+      expect(result.current.todos.length).toBe(1)
+      expect(renderCount.val).toBe(2)
+
+      unmount()
+    }).pipe(Effect.scoped, Effect.tapCauseLogPretty, Effect.runPromise))
+
+  let cachedProvider: BasicTracerProvider | undefined
+
+  describe('otel', () => {
+    const exporter = new InMemorySpanExporter()
+
+    const provider = cachedProvider ?? new BasicTracerProvider()
+    cachedProvider = provider
+    provider.addSpanProcessor(new SimpleSpanProcessor(exporter))
+    provider.register()
+
+    const otelTracer = otel.trace.getTracer('test')
+
+    const span = otelTracer.startSpan('test')
+    const otelContext = otel.trace.setSpan(otel.context.active(), span)
+
+    it('should update the data based on component key', async () => {
+      const { strictMode } = await Effect.gen(function* () {
+        const { wrapper, store, reactivityGraph, makeRenderCount, strictMode } = yield* makeTodoMvcReact({
+          useGlobalReactivityGraph: false,
+          otelContext,
+          otelTracer,
+        })
+
+        const renderCount = makeRenderCount()
+
+        const { result, rerender, unmount } = renderHook(
+          (userId: string) => {
+            renderCount.inc()
+
+            const [state, setState] = LiveStoreReact.useRow(AppComponentSchema, userId, { reactivityGraph })
+            return { state, setState }
+          },
+          { wrapper, initialProps: 'u1' },
+        )
+
+        expect(result.current.state.id).toBe('u1')
+        expect(result.current.state.username).toBe('')
+        expect(renderCount.val).toBe(1)
+
+        React.act(() =>
+          store.mutate(
+            LiveStore.rawSqlMutation({
+              sql: LiveStore.sql`INSERT INTO UserInfo (id, username) VALUES ('u2', 'username_u2')`,
+            }),
+          ),
+        )
+
+        rerender('u2')
+
+        expect(result.current.state.id).toBe('u2')
+        expect(result.current.state.username).toBe('username_u2')
+        expect(renderCount.val).toBe(2)
+
+        unmount()
+        span.end()
+
+        return { strictMode }
+      }).pipe(Effect.scoped, Effect.tapCauseLogPretty, Effect.runPromise)
+
+      const mapAttributes = (attributes: otel.Attributes) => {
+        return ReadonlyRecord.map(attributes, (val, key) => {
+          if (key === 'stackInfo') {
+            const stackInfo = JSON.parse(val as string) as LiveStore.StackInfo
+            // stackInfo.frames.shift() // Removes `renderHook.wrapper` from the stack
+            stackInfo.frames.forEach((_) => {
+              if (_.name.includes('renderHook.wrapper')) {
+                _.name = 'renderHook.wrapper'
+              }
+              _.filePath = '__REPLACED_FOR_SNAPSHOT__'
+            })
+            return JSON.stringify(stackInfo)
+          }
+          return val
+        })
+      }
+
+      // TODO improve testing setup so "obsolete" warning is avoided
+      if (strictMode) {
+        expect(getSimplifiedRootSpan(exporter, mapAttributes)).toMatchSnapshot('strictMode=true')
+      } else {
+        expect(getSimplifiedRootSpan(exporter, mapAttributes)).toMatchSnapshot('strictMode=false')
+      }
+    })
+  })
+})