@livestore/react 0.0.0-snapshot-8d3edf87cb1e88c7b67c5f3ea9d0b307253c33df

package/src/useRow.ts

@@ -0,0 +1,182 @@
+import type { QueryInfo } from '@livestore/common'
+import { SessionIdSymbol } from '@livestore/common'
+import { DbSchema } from '@livestore/common/schema'
+import type { SqliteDsl } from '@livestore/db-schema'
+import type { LiveQuery, ReactivityGraph, RowResult } from '@livestore/livestore'
+import { rowQuery } from '@livestore/livestore'
+import { shouldNeverHappen } from '@livestore/utils'
+import { ReadonlyRecord } from '@livestore/utils/effect'
+import React from 'react'
+
+import { useStore } from './LiveStoreContext.js'
+import { useQueryRef } from './useQuery.js'
+import { useMakeTemporaryQuery } from './useTemporaryQuery.js'
+
+export type UseRowResult<TTableDef extends DbSchema.TableDef> = [
+  row: RowResult<TTableDef>,
+  setRow: StateSetters<TTableDef>,
+  query$: LiveQuery<RowResult<TTableDef>, QueryInfo>,
+]
+
+export type UseRowOptionsDefaulValues<TTableDef extends DbSchema.TableDef> = {
+  defaultValues?: Partial<RowResult<TTableDef>>
+}
+
+export type UseRowOptionsBase = {
+  reactivityGraph?: ReactivityGraph
+}
+
+/**
+ * Similar to `React.useState` but returns a tuple of `[row, setRow, query$]` for a given table where ...
+ *
+ *   - `row` is the current value of the row (fully decoded according to the table schema)
+ *   - `setRow` is a function that can be used to update the row (values will be encoded according to the table schema)
+ *   - `query$` is a `LiveQuery` that e.g. can be used to subscribe to changes to the row
+ *
+ * If the table is a singleton table, `useRow` can be called without an `id` argument. Otherwise, the `id` argument is required.
+ */
+export const useRow: {
+  <
+    TTableDef extends DbSchema.TableDef<
+      DbSchema.DefaultSqliteTableDef,
+      boolean,
+      DbSchema.TableOptions & { isSingleton: true; deriveMutations: { enabled: true } }
+    >,
+  >(
+    table: TTableDef,
+    options?: UseRowOptionsBase,
+  ): UseRowResult<TTableDef>
+  <
+    TTableDef extends DbSchema.TableDef<
+      DbSchema.DefaultSqliteTableDef,
+      boolean,
+      DbSchema.TableOptions & { isSingleton: false; deriveMutations: { enabled: true } }
+    >,
+  >(
+    table: TTableDef,
+    // TODO adjust so it works with arbitrary primary keys or unique constraints
+    id: string | SessionIdSymbol,
+    options?: UseRowOptionsBase & UseRowOptionsDefaulValues<TTableDef>,
+  ): UseRowResult<TTableDef>
+} = <
+  TTableDef extends DbSchema.TableDef<
+    DbSchema.DefaultSqliteTableDefConstrained,
+    boolean,
+    DbSchema.TableOptions & { deriveMutations: { enabled: true } }
+  >,
+>(
+  table: TTableDef,
+  idOrOptions?: string | SessionIdSymbol | UseRowOptionsBase,
+  options_?: UseRowOptionsBase & UseRowOptionsDefaulValues<TTableDef>,
+): UseRowResult<TTableDef> => {
+  const sqliteTableDef = table.sqliteDef
+  const id = typeof idOrOptions === 'string' || idOrOptions === SessionIdSymbol ? idOrOptions : undefined
+  const options: (UseRowOptionsBase & UseRowOptionsDefaulValues<TTableDef>) | undefined =
+    typeof idOrOptions === 'string' || idOrOptions === SessionIdSymbol ? options_ : idOrOptions
+  const { defaultValues, reactivityGraph } = options ?? {}
+
+  type TComponentState = SqliteDsl.FromColumns.RowDecoded<TTableDef['sqliteDef']['columns']>
+
+  const tableName = table.sqliteDef.name
+
+  if (DbSchema.tableHasDerivedMutations(table) === false) {
+    shouldNeverHappen(`useRow called on table "${tableName}" which does not have 'deriveMutations: true' set`)
+  }
+
+  const { store } = useStore()
+
+  if (
+    store.schema.tables.has(table.sqliteDef.name) === false &&
+    table.sqliteDef.name.startsWith('__livestore') === false
+  ) {
+    shouldNeverHappen(`Table "${table.sqliteDef.name}" not found in schema`)
+  }
+
+  // console.debug('useRow', tableName, id)
+
+  const idStr = id === SessionIdSymbol ? 'session' : id
+
+  const { query$, otelContext } = useMakeTemporaryQuery(
+    (otelContext) =>
+      DbSchema.tableIsSingleton(table)
+        ? (rowQuery(table, { otelContext, reactivityGraph }) as LiveQuery<RowResult<TTableDef>, QueryInfo>)
+        : (rowQuery(table as TTableDef & { options: { isSingleton: false } }, id!, {
+            otelContext,
+            defaultValues: defaultValues!,
+            reactivityGraph,
+          }) as any as LiveQuery<RowResult<TTableDef>, QueryInfo>),
+    [idStr!, tableName],
+    {
+      otel: {
+        spanName: `LiveStore:useRow:${tableName}${idStr === undefined ? '' : `:${idStr}`}`,
+        attributes: { id: idStr },
+      },
+    },
+  )
+
+  const query$Ref = useQueryRef(query$, otelContext) as React.MutableRefObject<RowResult<TTableDef>>
+
+  const setState = React.useMemo<StateSetters<TTableDef>>(() => {
+    if (table.isSingleColumn) {
+      return (newValueOrFn: RowResult<TTableDef>) => {
+        const newValue = typeof newValueOrFn === 'function' ? newValueOrFn(query$Ref.current) : newValueOrFn
+        if (query$Ref.current === newValue) return
+
+        // NOTE we need to account for the short-hand syntax for single-column+singleton tables
+        if (table.options.isSingleton) {
+          store.mutate(table.update(newValue))
+        } else {
+          store.mutate(table.update({ where: { id }, values: { value: newValue } }))
+        }
+        // store.mutate(updateMutationForQueryInfo(query$.queryInfo!, { value: newValue }))
+      }
+    } else {
+      const setState = // TODO: do we have a better type for the values that can go in SQLite?
+        ReadonlyRecord.map(sqliteTableDef.columns, (column, columnName) => (newValueOrFn: any) => {
+          const newValue =
+            // @ts-expect-error TODO fix typing
+            typeof newValueOrFn === 'function' ? newValueOrFn(query$Ref.current[columnName]) : newValueOrFn
+
+          // 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 (query$Ref.current[columnName] === newValue) return
+
+          store.mutate(table.update({ where: { id: id ?? 'singleton' }, values: { [columnName]: newValue } }))
+          // store.mutate(updateMutationForQueryInfo(query$.queryInfo!, { [columnName]: newValue }))
+        })
+
+      setState.setMany = (columnValuesOrFn: Partial<TComponentState>) => {
+        const columnValues =
+          // @ts-expect-error TODO fix typing
+          typeof columnValuesOrFn === 'function' ? columnValuesOrFn(query$Ref.current) : columnValuesOrFn
+
+        // TODO use hashing instead
+        // Don't update the state if it's the same as the value already seen in the component
+        if (
+          // @ts-expect-error TODO fix typing
+          Object.entries(columnValues).every(([columnName, value]) => query$Ref.current[columnName] === value)
+        ) {
+          return
+        }
+
+        store.mutate(table.update({ where: { id: id ?? 'singleton' }, values: columnValues }))
+        // store.mutate(updateMutationForQueryInfo(query$.queryInfo!, columnValues))
+      }
+
+      return setState as any
+    }
+  }, [id, query$Ref, sqliteTableDef.columns, store, table])
+
+  return [query$Ref.current, setState, query$]
+}
+
+export type Dispatch<A> = (action: A) => void
+export type SetStateAction<S> = S | ((previousValue: S) => S)
+
+export type StateSetters<TTableDef extends DbSchema.TableDef> = TTableDef['isSingleColumn'] extends true
+  ? Dispatch<SetStateAction<RowResult<TTableDef>>>
+  : {
+      [K in keyof RowResult<TTableDef>]: Dispatch<SetStateAction<RowResult<TTableDef>[K]>>
+    } & {
+      setMany: Dispatch<SetStateAction<Partial<RowResult<TTableDef>>>>
+    }

package/src/useTemporaryQuery.test.tsx

@@ -0,0 +1,98 @@
+import * as LiveStore from '@livestore/livestore'
+import { querySQL } from '@livestore/livestore'
+import { Effect, Schema } from '@livestore/utils/effect'
+import { render, renderHook } from '@testing-library/react'
+import React from 'react'
+// @ts-expect-error no types
+import * as ReactWindow from 'react-window'
+import { describe, expect, it } from 'vitest'
+
+import { makeTodoMvcReact, tables, todos } from './__tests__/fixture.js'
+import * as LiveStoreReact from './mod.js'
+
+describe('useTemporaryQuery', () => {
+  it('simple', () =>
+    Effect.gen(function* () {
+      const { wrapper, store, makeRenderCount } = yield* makeTodoMvcReact()
+
+      const renderCount = makeRenderCount()
+
+      store.mutate(
+        todos.insert({ id: 't1', text: 'buy milk', completed: false }),
+        todos.insert({ id: 't2', text: 'buy bread', completed: false }),
+      )
+
+      const queryMap = new Map<string, LiveStore.LiveQuery<any>>()
+
+      const { rerender, result, unmount } = renderHook(
+        (id: string) => {
+          renderCount.inc()
+
+          return LiveStoreReact.useTemporaryQuery(() => {
+            const query$ = querySQL(`select * from todos where id = '${id}'`, {
+              schema: Schema.Array(tables.todos.schema),
+            })
+            queryMap.set(id, query$)
+            return query$
+          }, id)
+        },
+        { wrapper, initialProps: 't1' },
+      )
+
+      expect(result.current.length).toBe(1)
+      expect(result.current[0]!.text).toBe('buy milk')
+      expect(renderCount.val).toBe(1)
+      expect(queryMap.get('t1')!.runs).toBe(1)
+
+      rerender('t2')
+
+      expect(result.current.length).toBe(1)
+      expect(result.current[0]!.text).toBe('buy bread')
+      expect(renderCount.val).toBe(2)
+      expect(queryMap.get('t1')!.runs).toBe(1)
+      expect(queryMap.get('t2')!.runs).toBe(1)
+
+      unmount()
+
+      expect(queryMap.get('t2')!.runs).toBe(1)
+    }).pipe(Effect.scoped, Effect.tapCauseLogPretty, Effect.runPromise))
+
+  // NOTE this test covers some special react lifecyle paths which I couldn't easily reproduce without react-window
+  // it basically causes a "query swap" in the `useMemo` and both a `useEffect` cleanup call.
+  // To handle this properly we introduced the `_tag: 'destroyed'` state in the `spanAlreadyStartedCache`.
+  it('should work for a list with react-window', () =>
+    Effect.gen(function* () {
+      const { wrapper } = yield* makeTodoMvcReact()
+
+      const ListWrapper: React.FC<{ numItems: number }> = ({ numItems }) => {
+        return (
+          <ReactWindow.FixedSizeList
+            height={100}
+            width={100}
+            itemSize={10}
+            itemCount={numItems}
+            itemData={Array.from({ length: numItems }, (_, i) => i).reverse()}
+          >
+            {ListItem}
+          </ReactWindow.FixedSizeList>
+        )
+      }
+
+      const ListItem: React.FC<{ data: ReadonlyArray<number>; index: number }> = ({ data: ids, index }) => {
+        const id = ids[index]!
+        const res = LiveStoreReact.useTemporaryQuery(
+          () => LiveStore.computed(() => id, { label: `ListItem.${id}` }),
+          id,
+        )
+        return <div role="listitem">{res}</div>
+      }
+
+      const renderResult = render(<ListWrapper numItems={1} />, { wrapper })
+
+      expect(renderResult.container.textContent).toBe('0')
+
+      renderResult.rerender(<ListWrapper numItems={2} />)
+
+      expect(renderResult.container.textContent).toBe('10')
+    }).pipe(Effect.scoped, Effect.tapCauseLogPretty, Effect.runPromise))
+})

package/src/useTemporaryQuery.ts

@@ -0,0 +1,131 @@
+import type { QueryInfo } from '@livestore/common'
+import type { LiveQuery } from '@livestore/livestore'
+import * as otel from '@opentelemetry/api'
+import React from 'react'
+
+import { useStore } from './LiveStoreContext.js'
+import { useQueryRef } from './useQuery.js'
+
+// NOTE Given `useMemo` will be called multiple times (e.g. when using React Strict mode or Fast Refresh),
+// we are using this cache to avoid starting multiple queries/spans for the same component.
+// This is somewhat against some recommended React best practices, but it should be fine in our case below.
+// Please definitely open an issue if you see or run into any problems with this approach!
+const cache = new Map<
+  string,
+  | {
+      _tag: 'active'
+      rc: number
+      query$: LiveQuery<any, any>
+      span: otel.Span
+      otelContext: otel.Context
+    }
+  | {
+      _tag: 'destroyed'
+    }
+>()
+
+export type DepKey = string | number | ReadonlyArray<string | number>
+
+/**
+ * Creates a query, subscribes and destroys it when the component unmounts.
+ *
+ * The `key` is used to determine whether the a new query should be created or if the existing one should be reused.
+ */
+export const useTemporaryQuery = <TResult>(makeQuery: () => LiveQuery<TResult>, key: DepKey): TResult =>
+  useTemporaryQueryRef(makeQuery, key).current
+
+export const useTemporaryQueryRef = <TResult>(
+  makeQuery: () => LiveQuery<TResult>,
+  key: DepKey,
+): React.MutableRefObject<TResult> => {
+  const { query$ } = useMakeTemporaryQuery(makeQuery, key)
+
+  return useQueryRef(query$)
+}
+
+export const useMakeTemporaryQuery = <TResult, TQueryInfo extends QueryInfo>(
+  makeQuery: (otelContext: otel.Context) => LiveQuery<TResult, TQueryInfo>,
+  key: DepKey,
+  options?: {
+    otel?: {
+      spanName?: string
+      attributes?: otel.Attributes
+    }
+  },
+): { query$: LiveQuery<TResult, TQueryInfo>; otelContext: otel.Context } => {
+  const { store } = useStore()
+  const fullKey = React.useMemo(
+    // NOTE We're using the `makeQuery` function body string to make sure the key is unique across the app
+    // TODO we should figure out whether this could cause some problems and/or if there's a better way to do this
+    () => (Array.isArray(key) ? key.join('-') : key) + '-' + store.reactivityGraph.id + '-' + makeQuery.toString(),
+    [key, makeQuery, store.reactivityGraph.id],
+  )
+  const fullKeyRef = React.useRef<string>()
+
+  const { query$, otelContext } = React.useMemo(() => {
+    if (fullKeyRef.current !== undefined && fullKeyRef.current !== fullKey) {
+      // console.debug('fullKey changed', 'prev', fullKeyRef.current.split('-')[0]!, '-> new', fullKey.split('-')[0]!)
+
+      const cachedItem = cache.get(fullKeyRef.current)
+      if (cachedItem !== undefined && cachedItem._tag === 'active') {
+        cachedItem.rc--
+
+        if (cachedItem.rc === 0) {
+          // console.debug('rc=0-changed', cachedItem.query$.id, cachedItem.query$.label)
+          cachedItem.query$.destroy()
+          cachedItem.span.end()
+          cache.set(fullKeyRef.current, { _tag: 'destroyed' })
+        }
+      }
+    }
+
+    const cachedItem = cache.get(fullKey)
+    if (cachedItem !== undefined && cachedItem._tag === 'active') {
+      // console.debug('rc++', cachedItem.query$.id, cachedItem.query$.label)
+      cachedItem.rc++
+
+      return cachedItem
+    }
+
+    const spanName = options?.otel?.spanName ?? `LiveStore:useTemporaryQuery:${key}`
+
+    const span = store.otel.tracer.startSpan(
+      spanName,
+      { attributes: options?.otel?.attributes },
+      store.otel.queriesSpanContext,
+    )
+
+    const otelContext = otel.trace.setSpan(otel.context.active(), span)
+
+    const query$ = makeQuery(otelContext)
+
+    cache.set(fullKey, { _tag: 'active', rc: 1, query$, span, otelContext })
+
+    return { query$, otelContext }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [fullKey])
+
+  fullKeyRef.current = fullKey
+
+  React.useEffect(() => {
+    return () => {
+      const fullKey = fullKeyRef.current!
+      const cachedItem = cache.get(fullKey)
+      // NOTE in case the fullKey changed then the query was already destroyed in the useMemo above
+      if (cachedItem === undefined || cachedItem._tag === 'destroyed') return
+
+      // console.debug('rc--', cachedItem.query$.id, cachedItem.query$.label)
+
+      cachedItem.rc--
+
+      if (cachedItem.rc === 0) {
+        // console.debug('rc=0', cachedItem.query$.id, cachedItem.query$.label)
+        cachedItem.query$.destroy()
+        cachedItem.span.end()
+        cache.delete(fullKey)
+      }
+    }
+  }, [])
+
+  return { query$, otelContext }
+}

package/src/utils/stack-info.ts

@@ -0,0 +1,13 @@
+import { extractStackInfoFromStackTrace, type StackInfo } from '@livestore/livestore'
+import React from 'react'
+
+export const originalStackLimit = Error.stackTraceLimit
+
+export const useStackInfo = (): StackInfo =>
+  React.useMemo(() => {
+    Error.stackTraceLimit = 10
+    // eslint-disable-next-line unicorn/error-message
+    const stack = new Error().stack!
+    Error.stackTraceLimit = originalStackLimit
+    return extractStackInfoFromStackTrace(stack)
+  }, [])

package/src/utils/useStateRefWithReactiveInput.ts

@@ -0,0 +1,51 @@
+import React from 'react'
+
+/**
+ * A variant of `React.useState` which allows the `inputState` to change over time as well.
+ * Important: This hook is synchronous / single-render-pass (i.e. doesn't use `useEffect` or `setState` directly).
+ *
+ * Notes:
+ * - The output state is always reset to the input state in case the input state changes (i.e. the previous "external" `setStateAndRerender` call is forgotten)
+ * - This hook might not work properly with React Suspense
+ * - Also see this Tweet for more potential problems: https://twitter.com/schickling/status/1677317711104278528
+ *
+ */
+export const useStateRefWithReactiveInput = <T>(
+  inputState: T,
+): [React.MutableRefObject<T>, (newState: T | ((prev: T) => T)) => void] => {
+  const [_, rerender] = React.useState(0)
+
+  const lastKnownInputStateRef = React.useRef<T>(inputState)
+  const stateRef = React.useRef<T>(inputState)
+
+  if (lastKnownInputStateRef.current !== inputState) {
+    lastKnownInputStateRef.current = inputState
+
+    // NOTE we don't need to re-render here, because the component is already re-rendering due to the `inputState` change
+    stateRef.current = inputState
+  }
+
+  const setStateAndRerender = React.useCallback(
+    (newState: ((prev: T) => T) | T) => {
+      // @ts-expect-error https://github.com/microsoft/TypeScript/issues/37663
+      const val = typeof newState === 'function' ? newState(stateRef.current) : newState
+      stateRef.current = val
+      rerender((c) => c + 1)
+    },
+    [rerender],
+  )
+
+  return [stateRef, setStateAndRerender]
+}
+
+// Down-side of this implementation: Double render pass due to `setState` call (which forces a re-render)
+// Keeping around for now in case `useStateRefWithReactiveInput` doesn't work out
+// const _useStateWithReactiveInput = <T>(inputState: T): [T, (newState: T | ((prev: T) => T)) => void] => {
+//   const [externalState, setExternalState] = React.useState(inputState)
+
+//   if (externalState !== inputState) {
+//     setExternalState(inputState)
+//   }
+
+//   return [externalState, setExternalState]
+// }

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "jsx": "react",
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    // "jsx": "preserve",
+    "tsBuildInfoFile": "./dist/.tsbuildinfo"
+  },
+  "include": ["./src"],
+  "references": [
+    { "path": "../db-schema" },
+    { "path": "../common" },
+    { "path": "../web" },
+    { "path": "../livestore" },
+    { "path": "../utils" }
+  ]
+}

package/vitest.config.js

@@ -0,0 +1,17 @@
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  test: {
+    // Needed for React hook tests
+    environment: 'jsdom',
+  },
+  esbuild: {
+    // TODO remove once `using` keyword supported OOTB with Vite https://github.com/vitejs/vite/issues/15464#issuecomment-1872485703
+    target: 'es2020',
+  },
+  resolve: {
+    alias: {
+      '@livestore/wa-sqlite/dist/wa-sqlite.mjs': '@livestore/wa-sqlite/dist/wa-sqlite.node.mjs',
+    },
+  },
+})