@livestore/livestore 0.0.0

package/src/react/useLiveStoreComponent.ts

@@ -0,0 +1,493 @@
+import type { TypedDocumentNode as DocumentNode } from '@graphql-typed-document-node/core'
+import { type LiteralUnion, omit, shouldNeverHappen } from '@livestore/utils'
+import * as otel from '@opentelemetry/api'
+import { isEqual, mapValues } from 'lodash-es'
+import type { DependencyList } from 'react'
+import React from 'react'
+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 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 { sql } from '../util.js'
+import { useStore } from './LiveStoreContext.js'
+import { useStateRefWithReactiveInput } from './utils/useStateRefWithReactiveInput.js'
+
+export interface QueryDefinitions {
+  [queryName: string]: LiveStoreQuery
+}
+export type QueryResults<TQuery> = { [queryName in keyof TQuery]: QueryResult<TQuery[queryName]> }
+
+export type ReactiveSQL = <TResult>(
+  genQuery: (get: GetAtom) => string,
+  queriedTables: string[],
+) => LiveStoreSQLQuery<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,
+  label?: string,
+) => LiveStoreGraphQLQuery<TResult, TVariables, TContext>
+
+type RegisterSubscription = <TQuery extends LiveStoreQuery>(
+  query: TQuery,
+  onNewValue: (value: QueryResult<TQuery>) => void,
+  onUnsubscribe?: () => void,
+) => void
+
+type GenQueries<TQueries, TStateResult> = (args: {
+  rxSQL: ReactiveSQL
+  rxGraphQL: ReactiveGraphQL
+  globalQueries: QueryDefinitions
+  state$: LiveStoreJSQuery<TStateResult>
+  /** Registers a subscription */
+  subscribe: RegisterSubscription
+  isTemporaryQuery: boolean
+}) => TQueries
+
+export type UseLiveStoreComponentProps<TQueries, TComponentState> = {
+  stateSchema?: ComponentStateSchema<TComponentState>
+  queries?: GenQueries<TQueries, TComponentState>
+  reactDeps?: React.DependencyList
+  componentKey: ComponentKeyConfig
+}
+
+export type ComponentKeyConfig = {
+  /**
+   * Name of the Component
+   *
+   * TODO we should eventually derive this info automatically from the component (TBD how though...)
+   */
+  name: string
+  id: LiteralUnion<'singleton' | '__ephemeral__', string>
+}
+
+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.
+ * The map entry is being removed again in the `React.useEffect` call below.
+ */
+const spanAlreadyStartedCache = new Map<string, { span: otel.Span; otelCtx: otel.Context }>()
+
+type UseLiveStoreJsonState<TState> = <TResult>(
+  jsonStringKey: keyof TState,
+  parse?: (_: unknown) => TResult,
+) => [value: TResult, setValue: (newVal: TResult | ((prevVal: TResult) => TResult)) => void]
+
+/**
+ * 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>({
+  stateSchema: stateSchema_,
+  queries = () => ({}) as TQueries,
+  componentKey: componentKeyConfig,
+  reactDeps = [],
+}: UseLiveStoreComponentProps<TQueries, TComponentState>): {
+  queryResults: QueryResults<TQueries>
+  state: TComponentState
+  setState: Setters<TComponentState>
+  useLiveStoreJsonState: UseLiveStoreJsonState<TComponentState>
+} => {
+  // 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),
+    [stateSchema_],
+  )
+
+  // performance.mark('useLiveStoreComponent:start')
+  const componentKey = useComponentKey(componentKeyConfig, reactDeps)
+  const { store, globalQueries } = useStore()
+
+  const componentKeyLabel = React.useMemo(() => labelForKey(componentKey), [componentKey])
+
+  // The following `React.useMemo` and `React.useEffect` calls are used to start and end a span for the lifetime of this component.
+  const { span, otelCtx } = React.useMemo(() => {
+    const existingSpan = spanAlreadyStartedCache.get(componentKeyLabel)
+    if (existingSpan !== undefined) return existingSpan
+
+    const span = store.otel.tracer.startSpan(
+      `LiveStore:useLiveStoreComponent:${componentKeyLabel}`,
+      {},
+      store.otel.queriesSpanContext,
+    )
+
+    const otelCtx = otel.trace.setSpan(otel.context.active(), span)
+
+    spanAlreadyStartedCache.set(componentKeyLabel, { span, otelCtx })
+
+    return { span, otelCtx }
+  }, [componentKeyLabel, store.otel.queriesSpanContext, store.otel.tracer])
+
+  React.useEffect(
+    () => () => {
+      spanAlreadyStartedCache.delete(componentKeyLabel)
+      span.end()
+    },
+    [componentKeyLabel, span],
+  )
+
+  const generateQueries = React.useCallback(
+    ({
+      state$,
+      otelCtx,
+      registerSubscription,
+      isTemporaryQuery,
+    }: {
+      state$: LiveStoreJSQuery<TComponentState>
+      otelCtx: otel.Context
+      registerSubscription: RegisterSubscription
+      isTemporaryQuery: boolean
+    }) =>
+      queries({
+        rxSQL: <T>(genQuery: (get: GetAtom) => string, queriedTables: string[]) =>
+          store.querySQL<T>(genQuery, queriedTables, undefined, componentKey, undefined, otelCtx),
+        rxGraphQL: <Result extends Record<string, any>, Variables extends Record<string, any>>(
+          query: DocumentNode<Result, Variables>,
+          genVariableValues: (get: GetAtom) => Variables,
+          label?: string,
+        ) => store.queryGraphQL(query, genVariableValues, { componentKey, label }, otelCtx),
+        globalQueries,
+        state$,
+        subscribe: registerSubscription,
+        isTemporaryQuery,
+      }),
+
+    // 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.
+    // 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],
+  )
+
+  const defaultComponentState = React.useMemo(() => {
+    const defaultState = (
+      stateSchema === undefined ? {} : mapValues(stateSchema.columns, (c) => c.default)
+    ) as TComponentState
+
+    defaultState.id = componentKeyConfig.id
+
+    return defaultState
+  }, [componentKeyConfig.id, 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
+  // TODO get rid of the temporary query workaround
+  const { initialComponentState, initialQueryResults } = React.useMemo(() => {
+    return store.otel.tracer.startActiveSpan('LiveStore:useLiveStoreComponent:initial', {}, otelCtx, (span) => {
+      const otelCtx = otel.trace.setSpan(otel.context.active(), span)
+
+      return store.inTempQueryContext(() => {
+        try {
+          // create state query
+          let stateQuery: 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(
+              () => ({}),
+              componentKey,
+              undefined,
+              otelCtx,
+            ) 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`,
+                [componentTableName],
+                undefined,
+                componentKey,
+                `localState:query:${componentKeyLabel}`,
+                otelCtx,
+              )
+              .getFirstRow({ defaultValue: defaultComponentState })
+          }
+          const initialComponentState = stateQuery.results$.result
+
+          const queries = generateQueries({
+            state$: stateQuery,
+            otelCtx,
+            registerSubscription: () => {},
+            isTemporaryQuery: true,
+          })
+          for (const [name, query] of Object.entries(queries)) {
+            query.label = name
+          }
+          const initialQueryResults = mapValues(queries, (query) => query.results$.result) as QueryResults<TQueries>
+
+          return { initialComponentState, initialQueryResults }
+        } finally {
+          span.end()
+        }
+      })
+    })
+  }, [store, otelCtx, stateSchema, generateQueries, componentKey, componentKeyLabel, defaultComponentState])
+
+  // Now that we've computed the initial state synchronously,
+  // we can set up our useState calls w/ a default value populated...
+  const [componentStateRef, setComponentState_] = useStateRefWithReactiveInput<TComponentState>(initialComponentState)
+
+  const [queryResultsRef, setQueryResults_] = useStateRefWithReactiveInput<QueryResults<TQueries>>(initialQueryResults)
+
+  const setState = (
+    stateSchema === undefined
+      ? {}
+      : // TODO: do we have a better type for the values that can go in SQLite?
+        mapValues(stateSchema.columns, (_, columnName) => (value: string | number) => {
+          // Don't update the state if it's the same as the value already seen in the component
+          if (componentStateRef.current[columnName] === value) return
+
+          if (['componentKey', 'columnNames'].includes(columnName)) {
+            shouldNeverHappen(`Can't use reserved column name ${columnName}`)
+          }
+
+          return store.applyEvent('updateComponentState', {
+            componentKey,
+            columnNames: [columnName],
+            [columnName]: value,
+          })
+        })
+  ) as Setters<TComponentState>
+
+  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
+    if (Object.entries(columnValues).every(([columnName, value]) => componentStateRef.current[columnName] === value)) {
+      return
+    }
+
+    const columnNames = Object.keys(columnValues)
+
+    return store.applyEvent('updateComponentState', { componentKey, columnNames, ...columnValues })
+  }
+
+  // OK, now all the synchronous work is done;
+  // time to set up our long-running queries in an effect
+  React.useEffect(() => {
+    return store.otel.tracer.startActiveSpan(
+      'LiveStore:useLiveStoreComponent:long-running',
+      { attributes: {} },
+      otelCtx,
+      (span) => {
+        const otelCtx = otel.trace.setSpan(otel.context.active(), span)
+        const unsubs: (() => void)[] = []
+
+        // create state query
+        let stateQuery: LiveStoreJSQuery<TComponentState>
+        if (stateSchema === undefined) {
+          stateQuery = store.queryJS(
+            () => ({}),
+            componentKey,
+            undefined,
+            otelCtx,
+          ) as unknown as LiveStoreJSQuery<TComponentState>
+        } else {
+          const componentTableName = tableNameForComponentKey(componentKey)
+          insertRowForComponentInstance({ store, componentKey, stateSchema })
+
+          const whereClause = componentKey._tag === 'singleton' ? '' : `where id = '${componentKey.id}'`
+          stateQuery = store
+            .querySQL<TComponentState>(
+              () => sql`select * from ${componentTableName} ${whereClause} limit 1`,
+              [componentTableName],
+              undefined,
+              componentKey,
+              // TODO introduce a refresh "grouping" concept to associate related refreshes in the debugger UI
+              `localState:query:${componentKeyLabel}`,
+              otelCtx,
+            )
+            .getFirstRow({ defaultValue: defaultComponentState })
+        }
+
+        unsubs.push(
+          store.subscribe(
+            stateQuery,
+            (results) => {
+              if (isEqual(results, componentStateRef.current) === false) {
+                setComponentState_(results as TComponentState)
+              }
+            },
+            undefined,
+            { label: `useLiveStoreComponent:localState:subscribe:${stateQuery.label}` },
+          ),
+        )
+
+        const registerSubscription: RegisterSubscription = (query, callback, onUnsubscribe) => {
+          unsubs.push(
+            store.subscribe(
+              query,
+              (results) => {
+                callback(results)
+              },
+              onUnsubscribe,
+              { label: `useLiveStoreComponent:query:manual-subscribe:${query.label}` },
+            ),
+          )
+        }
+
+        const queries = generateQueries({ state$: stateQuery, otelCtx, 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)) {
+          unsubs.push(
+            store.subscribe(
+              query,
+              (results) => {
+                const newQueryResults = { ...queryResultsRef.current, [key]: results }
+                if (isEqual(newQueryResults, queryResultsRef.current) === false) {
+                  setQueryResults_(newQueryResults)
+                }
+              },
+              undefined,
+              { label: `useLiveStoreComponent:query:subscribe:${query.label}` },
+            ),
+          )
+        }
+
+        return () => {
+          for (const unsub of unsubs) {
+            unsub()
+          }
+
+          span.end()
+        }
+      },
+    )
+    // NOTE excluding `setComponentState_` and `setQueryResults_` from the deps array as it seems to cause an infinite loop
+    // This should probably be improved
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    store,
+    componentKey,
+    stateSchema,
+    defaultComponentState,
+    generateQueries,
+    otelCtx,
+    componentStateRef,
+    // setComponentState_,
+    // setQueryResults_,
+  ])
+
+  // Very important: remove any queries / other resources associated w/ this component
+  React.useEffect(() => () => store.unmountComponent(componentKey), [store, componentKey])
+
+  // performance.mark('useLiveStoreComponent:end')
+  // performance.measure(`useLiveStoreComponent:${componentKey.type}`, 'useLiveStoreComponent:start', 'useLiveStoreComponent:end')
+
+  const state = componentStateRef.current
+
+  const useLiveStoreJsonState = <TResult>(
+    jsonStringKey: keyof TComponentState,
+    parse: (_: unknown) => TResult = (_) => _ as TResult,
+  ): [value: TResult, setValue: (newVal: TResult | ((prevVal: TResult) => TResult)) => void] => {
+    const value = React.useMemo<TResult>(() => {
+      return parse(JSON.parse(state[jsonStringKey] as string))
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [state[jsonStringKey], parse])
+
+    const setValue = React.useCallback(
+      (newValOrFn: TResult | ((prev: TResult) => TResult)) => {
+        const newVal =
+          typeof newValOrFn === 'function'
+            ? // NOTE we're using the ref instead of the value because we want to be sure
+              // we're using the latest value when the setter is called
+              (newValOrFn as any)(parse(JSON.parse(componentStateRef.current[jsonStringKey] as string)))
+            : newValOrFn
+        setState[jsonStringKey](JSON.stringify(newVal) as any)
+      },
+      [parse, jsonStringKey],
+    )
+
+    return [value, setValue]
+  }
+
+  return {
+    queryResults: queryResultsRef.current,
+    state,
+    setState,
+    useLiveStoreJsonState,
+  }
+}
+
+export type Setters<TComponentState> = {
+  [k in keyof TComponentState]: (newValue: TComponentState[k]) => void
+} & {
+  setMany: (newValues: Partial<TComponentState>) => void
+}
+
+export const useComponentKey = ({ name, id }: ComponentKeyConfig, deps: DependencyList = []) =>
+  React.useMemo<ComponentKey>(() => {
+    switch (id) {
+      case 'singleton': {
+        return { _tag: 'singleton', componentName: name, id: 'singleton' }
+      }
+      case '__ephemeral__': {
+        return { _tag: 'ephemeral', componentName: name, id: uuid() }
+      }
+      default: {
+        return { _tag: 'custom', componentName: name, id }
+      }
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [...deps, id, name])
+
+/**
+ * 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>({
+  store,
+  componentKey,
+  stateSchema,
+}: {
+  store: Store<BaseGraphQLContext>
+  componentKey: ComponentKey
+  stateSchema: ComponentStateSchema<T>
+}) => {
+  const columnNames = ['id', ...Object.keys(stateSchema.columns)]
+  const columnValues = columnNames.map((name) => `$${name}`).join(', ')
+
+  const tableName = tableNameForComponentKey(componentKey)
+  const insertQuery = sql`insert into ${tableName} (${columnNames.join(
+    ', ',
+  )}) select ${columnValues} where not exists(select 1 from ${tableName} where id = '${componentKey.id}')`
+
+  void store.execute(
+    insertQuery,
+    {
+      id: componentKey.id,
+      ...mapValues(stateSchema.columns, (column) => prepareValueForSql(column.default ?? null)),
+    },
+    [tableName],
+  )
+}
+
+const prepareValueForSql = (value: string | number | boolean | null) => {
+  if (typeof value === 'string' || typeof value === 'number' || value === null) {
+    return value
+  } else {
+    return value ? 1 : 0
+  }
+}

package/src/react/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]
+// }