@livestore/livestore 0.0.0

package/src/react/LiveStoreProvider.tsx

@@ -0,0 +1,93 @@
+import type * as otel from '@opentelemetry/api'
+import { mapValues } from 'lodash-es'
+import type { ReactElement, ReactNode } from 'react'
+import React from 'react'
+
+import type { Backend, BackendOptions } from '../backends/index.js'
+import type {
+  GlobalQueryDefs,
+  LiveStoreContext as StoreContext_,
+  LiveStoreCreateStoreOptions,
+} from '../effect/LiveStore.js'
+import type { Schema } from '../schema.js'
+import type { BaseGraphQLContext, GraphQLOptions } from '../store.js'
+import { createStore } from '../store.js'
+import { LiveStoreContext } from './LiveStoreContext.js'
+
+interface LiveStoreProviderProps<GraphQLContext> {
+  schema: Schema
+  backendOptions: BackendOptions
+  boot?: (backend: Backend, parentSpan: otel.Span) => Promise<void>
+  globalQueryDefs: GlobalQueryDefs
+  graphQLOptions?: GraphQLOptions<GraphQLContext>
+  otelTracer?: otel.Tracer
+  otelRootSpanContext?: otel.Context
+  fallback: ReactElement
+}
+
+export const LiveStoreProvider = <GraphQLContext extends BaseGraphQLContext>({
+  fallback,
+  globalQueryDefs,
+  backendOptions,
+  graphQLOptions,
+  otelTracer,
+  otelRootSpanContext,
+  children,
+  schema,
+  boot,
+}: LiveStoreProviderProps<GraphQLContext> & { children?: ReactNode }): JSX.Element => {
+  const store = useCreateStore({
+    schema,
+    globalQueryDefs,
+    backendOptions,
+    graphQLOptions,
+    otelTracer,
+    otelRootSpanContext,
+    boot,
+  })
+
+  if (store === undefined) {
+    return fallback
+  }
+
+  return <LiveStoreContext.Provider value={store}>{children}</LiveStoreContext.Provider>
+}
+
+const useCreateStore = <GraphQLContext extends BaseGraphQLContext>({
+  schema,
+  globalQueryDefs,
+  backendOptions,
+  graphQLOptions,
+  otelTracer,
+  otelRootSpanContext,
+  boot,
+}: LiveStoreCreateStoreOptions<GraphQLContext>) => {
+  const [ctxValue, setCtxValue] = React.useState<StoreContext_ | undefined>()
+
+  React.useEffect(() => {
+    void (async () => {
+      try {
+        const store = await createStore({
+          schema,
+          backendOptions,
+          graphQLOptions,
+          otelTracer,
+          otelRootSpanContext,
+          boot,
+        })
+        store.otel.tracer.startActiveSpan('LiveStore:makeGlobalQueries', {}, store.otel.queriesSpanContext, (span) => {
+          const globalQueries = mapValues(globalQueryDefs, (queryDef) => queryDef(store))
+          setCtxValue({ store, globalQueries })
+          span.end()
+        })
+      } catch (e) {
+        console.error(`Error creating LiveStore store:`, e)
+        throw e
+      }
+    })()
+
+    // TODO: do we need to return any cleanup function here?
+  }, [schema, backendOptions, globalQueryDefs, graphQLOptions, otelTracer, otelRootSpanContext, boot])
+
+  return ctxValue
+}

package/src/react/index.ts

@@ -0,0 +1,11 @@
+export type {
+  UseLiveStoreComponentProps as LiveStoreComponentConfig,
+  ReactiveGraphQL,
+  ReactiveSQL,
+  Setters,
+} from './useLiveStoreComponent.js'
+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'

package/src/react/useGlobalQuery.ts

@@ -0,0 +1,40 @@
+import { useEffect, useState } from 'react'
+
+import { labelForKey } from '../componentKey.js'
+import { TODO_REMOVE_trackLongRunningSpan } from '../otel.js'
+import type { LiveStoreQuery, QueryResult } from '../store.js'
+
+export const useGlobalQuery = <Q extends LiveStoreQuery>(query: Q): QueryResult<Q> => {
+  // We know the query has a result by the time we use it; so we can synchronously populate a default state
+  const [value, setValue] = useState<QueryResult<Q>>(query.results$.result)
+
+  // Subscribe to future updates for this query
+  useEffect(() => {
+    return query.store.otel.tracer.startActiveSpan(
+      `LiveStore:useGlobalQuery:${labelForKey(query.componentKey)}:${query.label}`,
+      {},
+      query.store.otel.queriesSpanContext,
+      (span) => {
+        TODO_REMOVE_trackLongRunningSpan(span)
+
+        const cancel = query.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 () => {
+          cancel()
+          span.end()
+        }
+      },
+    )
+  }, [query])
+
+  return value
+}

package/src/react/useGraphQL.ts

@@ -0,0 +1,113 @@
+import type { TypedDocumentNode as DocumentNode } from '@graphql-typed-document-node/core'
+import * as otel from '@opentelemetry/api'
+import { isEqual } from 'lodash-es'
+import React from 'react'
+
+import { labelForKey } from '../componentKey.js'
+import { useStore } from './LiveStoreContext.js'
+import { type ComponentKeyConfig, useComponentKey } from './useLiveStoreComponent.js'
+import { useStateRefWithReactiveInput } from './utils/useStateRefWithReactiveInput.js'
+
+export type UseLiveStoreComponentProps<TResult extends Record<string, any>, TVariables extends Record<string, any>> = {
+  query: DocumentNode<TResult, TVariables>
+  variables: TVariables
+  componentKey: ComponentKeyConfig
+  reactDeps?: React.DependencyList
+}
+
+/**
+ * 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 }>()
+
+// 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> = {}>({
+  query,
+  variables,
+  componentKey: componentKeyConfig,
+  reactDeps = [],
+}: UseLiveStoreComponentProps<TResult, TVariables>): Readonly<TResult> => {
+  const componentKey = useComponentKey(componentKeyConfig, reactDeps)
+  const { store } = 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:useGraphQL:${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 makeLiveStoreQuery = React.useCallback(
+    () => store.queryGraphQL(query, () => variables ?? ({} as TVariables), { componentKey }, otelCtx),
+    // 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
+    [componentKey, store],
+  )
+
+  // TODO get rid of the temporary query workaround
+  const initialQueryResults = React.useMemo(
+    () => store.inTempQueryContext(() => makeLiveStoreQuery().results$.result),
+    [makeLiveStoreQuery, store],
+  )
+
+  const [queryResultsRef, setQueryResults_] = useStateRefWithReactiveInput<TResult>(initialQueryResults)
+
+  React.useEffect(() => {
+    const liveStoreQuery = makeLiveStoreQuery()
+    const unsubscribe = store.subscribe(
+      liveStoreQuery,
+      (results) => {
+        if (isEqual(results, queryResultsRef.current) === false) {
+          setQueryResults_(results)
+        }
+      },
+      undefined,
+      { label: `useGraphQL:query:subscribe:${liveStoreQuery.label}` },
+    )
+
+    return () => {
+      unsubscribe()
+    }
+    // NOTE `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
+  }, [
+    otelCtx,
+    makeLiveStoreQuery,
+    // setQueryResults_,
+    store,
+  ])
+
+  // Very important: remove any queries / other resources associated w/ this component
+  React.useEffect(() => () => store.unmountComponent(componentKey), [store, componentKey])
+
+  return queryResultsRef.current
+}