@livestore/react 0.4.0-dev.2 → 0.4.0-dev.21

package/src/experimental/multi-store/StoreRegistry.ts

@@ -0,0 +1,253 @@
+import { OtelLiveDummy, UnknownError } from '@livestore/common'
+import type { LiveStoreSchema } from '@livestore/common/schema'
+import { createStore, type Store } from '@livestore/livestore'
+import {
+  Cause,
+  Effect,
+  Equal,
+  Exit,
+  Fiber,
+  Hash,
+  Layer,
+  ManagedRuntime,
+  type OtelTracer,
+  RcMap,
+  Runtime,
+  type Scope,
+} from '@livestore/utils/effect'
+import type { CachedStoreOptions } from './types.ts'
+
+/**
+ * Default time to keep unused stores in cache.
+ *
+ * - Browser: 60 seconds (60,000ms)
+ * - SSR: Infinity (disables disposal to avoid disposing stores before server render completes)
+ *
+ * @internal Exported primarily for testing purposes.
+ */
+export const DEFAULT_UNUSED_CACHE_TIME = typeof window === 'undefined' ? Number.POSITIVE_INFINITY : 60_000
+
+type DefaultStoreOptions = Partial<
+  Pick<
+    CachedStoreOptions,
+    'batchUpdates' | 'disableDevtools' | 'confirmUnsavedChanges' | 'syncPayload' | 'debug' | 'otelOptions'
+  >
+> & {
+  /**
+   * The time in milliseconds that unused stores remain in memory.
+   * When a store becomes unused (no active retentions), it will be disposed
+   * after this duration.
+   *
+   * Stores transition to the unused state as soon as they have no
+   * active retentions, so when all components which use that store
+   * have unmounted.
+   *
+   * @remarks
+   * - If set to `Infinity`, will disable disposal
+   * - The maximum allowed time is about {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/setTimeout#maximum_delay_value | 24 days}
+   *
+   * @defaultValue `60_000` (60 seconds) or `Infinity` during SSR to avoid
+   * disposing stores before server render completes.
+   */
+  unusedCacheTime?: number
+  /**
+   * Optionally, pass a custom runtime that will be used to run all operations (loading, caching, etc.).
+   */
+  runtime?: Runtime.Runtime<Scope.Scope | OtelTracer.OtelTracer>
+}
+
+/**
+ * RcMap cache key that uses storeId for equality/hashing but carries full options.
+ * This allows RcMap to deduplicate by storeId while the lookup function has access to all options.
+ *
+ * @remarks
+ * Only `storeId` is used for equality and hashing. This means if `getOrLoadPromise` is called
+ * with different options (e.g., different `adapter`) but the same `storeId`, the cached store
+ * from the first call will be returned. This is intentional - a store's identity is determined
+ * solely by its `storeId`, and callers should not expect to get different stores by varying
+ * other options while keeping the same `storeId`.
+ */
+class StoreCacheKey<TSchema extends LiveStoreSchema = LiveStoreSchema.Any> implements Equal.Equal {
+  readonly options: CachedStoreOptions<TSchema>
+
+  constructor(options: CachedStoreOptions<TSchema>) {
+    this.options = options
+  }
+
+  /**
+   * Equality is based solely on `storeId`. Other options in `CachedStoreOptions` are ignored
+   * for cache key comparison. The first options used for a given `storeId` determine the
+   * store's configuration.
+   */
+  [Equal.symbol](that: Equal.Equal): boolean {
+    return that instanceof StoreCacheKey && this.options.storeId === that.options.storeId
+  }
+
+  [Hash.symbol](): number {
+    return Hash.string(this.options.storeId)
+  }
+}
+
+/**
+ * Store Registry coordinating store loading, caching, and retention
+ *
+ * @public
+ */
+export class StoreRegistry {
+  /**
+   * Reference-counted cache mapping storeId to Store instances.
+   * Stores are created on first access and disposed after `unusedCacheTime` when all references are released.
+   */
+  #rcMap: RcMap.RcMap<StoreCacheKey<any>, Store, UnknownError>
+
+  /**
+   * Effect runtime providing Scope and OtelTracer for all registry operations.
+   * When the runtime's scope closes, all managed stores are automatically shut down.
+   */
+  #runtime: Runtime.Runtime<Scope.Scope | OtelTracer.OtelTracer>
+
+  /**
+   * In-flight loading promises keyed by storeId.
+   * Ensures concurrent `getOrLoadPromise` calls receive the same Promise reference.
+   */
+  #loadingPromises: Map<string, Promise<Store<any>>> = new Map()
+
+  /**
+   * Creates a new StoreRegistry instance.
+   *
+   * @param params.defaultOptions - Default options applied to all stores managed by this registry when they are loaded.
+   *
+   * @example
+   * ```ts
+   * const registry = new StoreRegistry({
+   *   defaultOptions: {
+   *     batchUpdates,
+   *     unusedCacheTime: 30_000,
+   *   }
+   * })
+   * ```
+   */
+  constructor(params: { defaultOptions?: DefaultStoreOptions } = {}) {
+    this.#runtime =
+      params.defaultOptions?.runtime ??
+      ManagedRuntime.make(Layer.mergeAll(Layer.scope, OtelLiveDummy)).runtimeEffect.pipe(Effect.runSync)
+
+    this.#rcMap = RcMap.make({
+      lookup: (key: StoreCacheKey) =>
+        Effect.gen(this, function* () {
+          const { options } = key
+
+          return yield* createStore(options).pipe(Effect.catchAllDefect((cause) => UnknownError.make({ cause })))
+        }).pipe(Effect.withSpan(`StoreRegistry.lookup:${key.options.storeId}`)),
+      // TODO: Make idleTimeToLive vary for each store when Effect supports per-resource TTL
+      // See https://github.com/livestorejs/livestore/issues/917
+      idleTimeToLive: params.defaultOptions?.unusedCacheTime ?? DEFAULT_UNUSED_CACHE_TIME,
+    }).pipe(Runtime.runSync(this.#runtime))
+  }
+
+  /**
+   * Gets a cached store or loads a new one, with the store lifetime scoped to the caller.
+   *
+   * @typeParam TSchema - The schema type for the store
+   * @returns An Effect that yields the store, scoped to the provided Scope
+   *
+   * @remarks
+   * - Stores are kept in cache and reused while any scope holds them
+   * - When the scope closes, the reference is released; the store is disposed after `unusedCacheTime`
+   *   if no other scopes retain it
+   * - Concurrent calls with the same storeId share the same store instance
+   */
+  getOrLoad = <TSchema extends LiveStoreSchema>(
+    options: CachedStoreOptions<TSchema>,
+  ): Effect.Effect<Store<TSchema>, UnknownError, Scope.Scope> =>
+    Effect.gen(this, function* () {
+      const key = new StoreCacheKey(options)
+      const store = yield* RcMap.get(this.#rcMap, key)
+
+      return store as unknown as Store<TSchema>
+    }).pipe(Effect.withSpan(`StoreRegistry.getOrLoad:${options.storeId}`))
+
+  /**
+   * Get or load a store, returning it directly if already loaded or a promise if loading.
+   *
+   * @typeParam TSchema - The schema type for the store
+   * @returns The loaded store if available, or a Promise that resolves to the loaded store
+   * @throws unknown loading error
+   *
+   * @remarks
+   * - Returns the store instance directly (synchronous) when already loaded
+   * - Returns a stable Promise reference when loading is in progress or needs to be initiated
+   * - Throws with the same error instance on subsequent calls after failure
+   * - Applies default options from registry config, with call-site options taking precedence
+   * - Concurrent calls with the same storeId share the same store instance
+   */
+  getOrLoadPromise = <TSchema extends LiveStoreSchema>(
+    options: CachedStoreOptions<TSchema>,
+  ): Store<TSchema> | Promise<Store<TSchema>> => {
+    const exit = this.getOrLoad<TSchema>(options).pipe(Effect.scoped, Runtime.runSyncExit(this.#runtime))
+
+    if (Exit.isSuccess(exit)) return exit.value as Store<TSchema>
+
+    // Check if the failure is due to async work
+    const defect = Cause.dieOption(exit.cause)
+    if (defect._tag === 'Some' && Runtime.isAsyncFiberException(defect.value)) {
+      const { storeId } = options
+
+      // Return cached promise if one exists (ensures concurrent calls get the same Promise reference)
+      const cached = this.#loadingPromises.get(storeId)
+      if (cached) return cached as Promise<Store<TSchema>>
+
+      // Create and cache the promise
+      const fiber = defect.value.fiber
+      const promise = Fiber.join(fiber)
+        .pipe(Runtime.runPromise(this.#runtime))
+        .finally(() => this.#loadingPromises.delete(storeId)) as Promise<Store<TSchema>>
+
+      this.#loadingPromises.set(storeId, promise)
+      return promise
+    }
+
+    // Handle synchronous failure
+    throw Cause.squash(exit.cause)
+  }
+
+  /**
+   * Retains the store in cache until the returned release function is called.
+   *
+   * @returns A release function that, when called, removes this retention hold
+   *
+   * @remarks
+   * - Multiple retains on the same store are independent; each must be released separately
+   * - If the store isn't cached yet, it will be loaded and then retained
+   */
+  retain = (options: CachedStoreOptions<any>): (() => void) => {
+    const release = Effect.gen(this, function* () {
+      const key = new StoreCacheKey(options)
+      yield* RcMap.get(this.#rcMap, key)
+      // Effect.never suspends indefinitely, keeping the RcMap reference alive.
+      // When `release()` is called, the fiber is interrupted, closing the scope
+      // and releasing the RcMap entry (which may trigger disposal after idleTimeToLive).
+      yield* Effect.never
+    }).pipe(Effect.scoped, Runtime.runCallback(this.#runtime))
+
+    return () => release()
+  }
+
+  /**
+   * Warms the cache for a store without adding a retention.
+   *
+   * @typeParam TSchema - The schema of the store to preload
+   * @returns A promise that resolves when the loading is complete (success or failure)
+   *
+   * @remarks
+   * - We don't return the store or throw as this is a fire-and-forget operation.
+   * - If the entry remains unused after preload resolves/rejects, it is scheduled for disposal.
+   */
+  preload = async <TSchema extends LiveStoreSchema>(options: CachedStoreOptions<TSchema>): Promise<void> => {
+    try {
+      await this.getOrLoadPromise(options)
+    } catch {
+      // Do nothing; preload is best-effort
+    }
+  }
+}

package/src/experimental/multi-store/StoreRegistryContext.tsx

@@ -0,0 +1,23 @@
+import * as React from 'react'
+import type { StoreRegistry } from './StoreRegistry.ts'
+
+export const StoreRegistryContext = React.createContext<StoreRegistry | undefined>(undefined)
+
+export type StoreRegistryProviderProps = {
+  storeRegistry: StoreRegistry
+  children: React.ReactNode
+}
+
+export const StoreRegistryProvider = ({ storeRegistry, children }: StoreRegistryProviderProps): React.JSX.Element => {
+  return <StoreRegistryContext value={storeRegistry}>{children}</StoreRegistryContext>
+}
+
+export const useStoreRegistry = (override?: StoreRegistry) => {
+  if (override) return override
+
+  const storeRegistry = React.use(StoreRegistryContext)
+
+  if (!storeRegistry) throw new Error('useStoreRegistry() must be used within <StoreRegistryProvider>')
+
+  return storeRegistry
+}

package/src/experimental/multi-store/mod.ts

@@ -0,0 +1,5 @@
+export * from './StoreRegistry.ts'
+export * from './StoreRegistryContext.tsx'
+export * from './storeOptions.ts'
+export * from './types.ts'
+export * from './useStore.ts'

package/src/experimental/multi-store/storeOptions.ts

@@ -0,0 +1,8 @@
+import type { LiveStoreSchema } from '@livestore/common/schema'
+import type { CachedStoreOptions } from './types.ts'
+
+export function storeOptions<TSchema extends LiveStoreSchema>(
+  options: CachedStoreOptions<TSchema>,
+): CachedStoreOptions<TSchema> {
+  return options
+}

package/src/experimental/multi-store/types.ts

@@ -0,0 +1,37 @@
+import type { LiveStoreSchema } from '@livestore/common/schema'
+import type { CreateStoreOptions, OtelOptions } from '@livestore/livestore'
+
+export type CachedStoreOptions<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TContext = {}> = Pick<
+  CreateStoreOptions<TSchema, TContext>,
+  | 'storeId'
+  | 'schema'
+  | 'adapter'
+  | 'boot'
+  | 'batchUpdates'
+  | 'disableDevtools'
+  | 'confirmUnsavedChanges'
+  | 'syncPayload'
+  | 'debug'
+  | 'shutdownDeferred'
+> & {
+  signal?: AbortSignal
+  otelOptions?: Partial<OtelOptions>
+  /**
+   * The time in milliseconds that this store should remain
+   * in memory after becoming unused. When this store becomes
+   * unused (no active retentions), it will be disposed after this duration.
+   *
+   * Stores transition to the unused state as soon as they have no
+   * active retentions, so when all components which use that store
+   * have unmounted.
+   *
+   * @remarks
+   * - When different `unusedCacheTime` values are used for the same store, the longest one will be used.
+   * - If set to `Infinity`, will disable automatic disposal
+   * - The maximum allowed time is about {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/setTimeout#maximum_delay_value | 24 days}
+   *
+   * @defaultValue `60_000` (60 seconds) or `Infinity` during SSR to avoid
+   * disposing stores before server render completes.
+   */
+  unusedCacheTime?: number
+}

package/src/experimental/multi-store/useStore.test.tsx

@@ -0,0 +1,269 @@
+import { makeInMemoryAdapter } from '@livestore/adapter-web'
+import type { Store } from '@livestore/livestore'
+import { StoreInternalsSymbol } from '@livestore/livestore'
+import { shouldNeverHappen } from '@livestore/utils'
+import { act, type RenderHookResult, type RenderResult, render, renderHook, waitFor } from '@testing-library/react'
+import * as React from 'react'
+import { describe, expect, it } from 'vitest'
+import { schema } from '../../__tests__/fixture.tsx'
+import { StoreRegistry } from './StoreRegistry.ts'
+import { StoreRegistryProvider } from './StoreRegistryContext.tsx'
+import { storeOptions } from './storeOptions.ts'
+import type { CachedStoreOptions } from './types.ts'
+import { useStore } from './useStore.ts'
+
+describe('experimental useStore', () => {
+  it('should return the same promise instance for concurrent getOrLoadStore calls', async () => {
+    const registry = new StoreRegistry()
+    const options = testStoreOptions()
+
+    // Make two concurrent calls during loading
+    const firstStore = registry.getOrLoadPromise(options)
+    const secondStore = registry.getOrLoadPromise(options)
+
+    // Both should be promises (store is loading)
+    expect(firstStore).toBeInstanceOf(Promise)
+    expect(secondStore).toBeInstanceOf(Promise)
+
+    // EXPECTED BEHAVIOR: Same promise instance for React.use() compatibility
+    // ACTUAL BEHAVIOR: Different promise instances (Effect.runPromise creates new wrapper)
+    expect(firstStore).toBe(secondStore)
+
+    // Cleanup
+    await firstStore
+    await cleanupAfterUnmount(() => {})
+  })
+
+  it('works with Suspense boundary', async () => {
+    const registry = new StoreRegistry()
+    const options = testStoreOptions()
+
+    let view: RenderResult | undefined
+    await act(async () => {
+      view = render(
+        <StoreRegistryProvider storeRegistry={registry}>
+          <React.Suspense fallback={<div data-testid="fallback" />}>
+            <StoreConsumer options={options} />
+          </React.Suspense>
+        </StoreRegistryProvider>,
+      )
+    })
+    const renderedView = view ?? shouldNeverHappen('render failed')
+
+    // After loading completes, should show the actual content
+    await waitForSuspenseResolved(renderedView)
+    expect(renderedView.getByTestId('ready')).toBeDefined()
+
+    await cleanupAfterUnmount(() => renderedView.unmount())
+  })
+
+  it('does not re-suspend on subsequent renders when store is already loaded', async () => {
+    const registry = new StoreRegistry()
+    const options = testStoreOptions()
+
+    const Wrapper = ({ opts }: { opts: CachedStoreOptions<typeof schema> }) => (
+      <StoreRegistryProvider storeRegistry={registry}>
+        <React.Suspense fallback={<div data-testid="fallback" />}>
+          <StoreConsumer options={opts} />
+        </React.Suspense>
+      </StoreRegistryProvider>
+    )
+
+    let view: RenderResult | undefined
+    await act(async () => {
+      view = render(<Wrapper opts={options} />)
+    })
+    const renderedView = view ?? shouldNeverHappen('render failed')
+
+    // Wait for initial load
+    await waitForSuspenseResolved(renderedView)
+    expect(renderedView.getByTestId('ready')).toBeDefined()
+
+    // Rerender with new options object (but same storeId)
+    await act(async () => {
+      renderedView.rerender(<Wrapper opts={{ ...options }} />)
+    })
+
+    // Should not show fallback
+    expect(renderedView.queryByTestId('fallback')).toBeNull()
+    expect(renderedView.getByTestId('ready')).toBeDefined()
+
+    await cleanupAfterUnmount(() => renderedView.unmount())
+  })
+
+  it('throws when store loading fails', async () => {
+    const registry = new StoreRegistry()
+    const badOptions = testStoreOptions({
+      // @ts-expect-error - intentionally passing invalid adapter to trigger error
+      adapter: null,
+    })
+
+    // Pre-load the store to cache the error (error happens synchronously)
+    expect(() => registry.getOrLoadPromise(badOptions)).toThrow()
+
+    // Now when useStore tries to get it, it should throw synchronously
+    expect(() =>
+      renderHook(() => useStore(badOptions), {
+        wrapper: makeProvider(registry),
+      }),
+    ).toThrow()
+  })
+
+  it.each([
+    { label: 'non-strict mode', strictMode: false },
+    { label: 'strict mode', strictMode: true },
+  ])('works in $label', async ({ strictMode }) => {
+    const registry = new StoreRegistry()
+    const options = testStoreOptions()
+
+    let hook: RenderHookResult<Store<typeof schema>, CachedStoreOptions<typeof schema>> | undefined
+    await act(async () => {
+      hook = renderHook(() => useStore(options), {
+        wrapper: makeProvider(registry, { suspense: true }),
+        reactStrictMode: strictMode,
+      })
+    })
+    const { result, unmount } = hook ?? shouldNeverHappen('renderHook failed')
+
+    // Wait for store to be ready
+    await waitForStoreReady(result)
+    expect(result.current[StoreInternalsSymbol].clientSession).toBeDefined()
+
+    await cleanupAfterUnmount(unmount)
+  })
+
+  it('handles switching between different storeId values', async () => {
+    const registry = new StoreRegistry()
+
+    const optionsA = testStoreOptions({ storeId: 'store-a' })
+    const optionsB = testStoreOptions({ storeId: 'store-b' })
+
+    let hook: RenderHookResult<Store<typeof schema>, CachedStoreOptions<typeof schema>> | undefined
+    await act(async () => {
+      hook = renderHook((opts) => useStore(opts), {
+        initialProps: optionsA,
+        wrapper: makeProvider(registry, { suspense: true }),
+      })
+    })
+    const { result, rerender, unmount } = hook ?? shouldNeverHappen('renderHook failed')
+
+    // Wait for first store to load
+    await waitForStoreReady(result)
+    const storeA = result.current
+    expect(storeA[StoreInternalsSymbol].clientSession).toBeDefined()
+
+    // Switch to different storeId
+    await act(async () => {
+      rerender(optionsB)
+    })
+
+    // Wait for second store to load and verify it's different from the first
+    await waitFor(() => {
+      expect(result.current).not.toBe(storeA)
+      expect(result.current?.[StoreInternalsSymbol].clientSession).toBeDefined()
+    })
+
+    const storeB = result.current
+    expect(storeB[StoreInternalsSymbol].clientSession).toBeDefined()
+    expect(storeB).not.toBe(storeA)
+
+    await cleanupAfterUnmount(unmount)
+  })
+
+  // useStore doesn't handle unusedCacheTime=0 correctly because retain is called in useEffect (after render)
+  // See https://github.com/livestorejs/livestore/issues/916
+  it.skip('should load store with unusedCacheTime set to 0', async () => {
+    const registry = new StoreRegistry({ defaultOptions: { unusedCacheTime: 0 } })
+    const options = testStoreOptions({ unusedCacheTime: 0 })
+
+    const StoreConsumerWithVerification = ({ opts }: { opts: CachedStoreOptions<typeof schema> }) => {
+      const store = useStore(opts)
+      // Verify store is usable - access internals to confirm it's not disposed
+      const clientSession = store[StoreInternalsSymbol].clientSession
+      return <div data-testid="ready" data-has-session={String(clientSession !== undefined)} />
+    }
+
+    let view: RenderResult | undefined
+    await act(async () => {
+      view = render(
+        <StoreRegistryProvider storeRegistry={registry}>
+          <React.Suspense fallback={<div data-testid="fallback" />}>
+            <StoreConsumerWithVerification opts={options} />
+          </React.Suspense>
+        </StoreRegistryProvider>,
+      )
+    })
+    const renderedView = view ?? shouldNeverHappen('render failed')
+
+    await waitForSuspenseResolved(renderedView)
+
+    // Store should be usable while component is mounted
+    const readyElement = renderedView.getByTestId('ready')
+    expect(readyElement.getAttribute('data-has-session')).toBe('true')
+
+    // Allow some time to pass to ensure store isn't prematurely disposed
+    await new Promise((resolve) => setTimeout(resolve, 50))
+
+    // Store should still be usable after waiting
+    expect(readyElement.getAttribute('data-has-session')).toBe('true')
+
+    await cleanupAfterUnmount(() => renderedView.unmount())
+  })
+})
+
+const StoreConsumer = ({ options }: { options: CachedStoreOptions<any> }) => {
+  useStore(options)
+  return <div data-testid="ready" />
+}
+
+const makeProvider =
+  (registry: StoreRegistry, { suspense = false }: { suspense?: boolean } = {}) =>
+  ({ children }: { children: React.ReactNode }) => {
+    let content = <StoreRegistryProvider storeRegistry={registry}>{children}</StoreRegistryProvider>
+
+    if (suspense) {
+      content = <React.Suspense fallback={null}>{content}</React.Suspense>
+    }
+
+    return content
+  }
+
+let testStoreCounter = 0
+
+const testStoreOptions = (overrides: Partial<CachedStoreOptions<typeof schema>> = {}) =>
+  storeOptions({
+    storeId: overrides.storeId ?? `test-store-${testStoreCounter++}`,
+    schema,
+    adapter: makeInMemoryAdapter(),
+    ...overrides,
+  })
+
+/**
+ * Cleans up after component unmount and waits for pending operations to settle.
+ *
+ * When components using stores unmount, the StoreRegistry schedules garbage collection
+ * timers for inactive stores. This helper waits for those timers to complete naturally.
+ */
+const cleanupAfterUnmount = async (cleanup: () => void): Promise<void> => {
+  cleanup()
+  // Allow any pending microtasks/timers to settle
+  await new Promise((resolve) => setTimeout(resolve, 100))
+}
+
+/**
+ * Waits for React Suspense fallback to resolve and the actual content to render.
+ */
+const waitForSuspenseResolved = async (view: RenderResult): Promise<void> => {
+  await waitFor(() => expect(view.queryByTestId('fallback')).toBeNull())
+}
+
+/**
+ * Waits for a store to be fully loaded and ready to use.
+ * The store is considered ready when it has a defined clientSession.
+ */
+const waitForStoreReady = async (result: { current: Store<any> }): Promise<void> => {
+  await waitFor(() => {
+    expect(result.current).not.toBeNull()
+    expect(result.current[StoreInternalsSymbol].clientSession).toBeDefined()
+  })
+}

package/src/experimental/multi-store/useStore.ts

@@ -0,0 +1,26 @@
+import type { LiveStoreSchema } from '@livestore/common/schema'
+import type { Store } from '@livestore/livestore'
+import * as React from 'react'
+import type { ReactApi } from '../../LiveStoreContext.ts'
+import { withReactApi } from '../../useStore.ts'
+import { useStoreRegistry } from './StoreRegistryContext.tsx'
+import type { CachedStoreOptions } from './types.ts'
+
+/**
+ * Suspense and Error Boundary friendly hook.
+ * - Returns data or throws (Promise|Error).
+ * - No loading or error states are returned.
+ */
+export const useStore = <TSchema extends LiveStoreSchema>(
+  options: CachedStoreOptions<TSchema>,
+): Store<TSchema> & ReactApi => {
+  const storeRegistry = useStoreRegistry()
+
+  React.useEffect(() => storeRegistry.retain(options), [storeRegistry, options])
+
+  const storeOrPromise = React.useMemo(() => storeRegistry.getOrLoadPromise(options), [storeRegistry, options])
+
+  const store = storeOrPromise instanceof Promise ? React.use(storeOrPromise) : storeOrPromise
+
+  return withReactApi(store)
+}

package/src/mod.ts

@@ -3,8 +3,9 @@ export { LiveStoreProvider } from './LiveStoreProvider.tsx'
 export {
   type Dispatch,
   type SetStateAction,
+  type SetStateActionPartial,
   type StateSetters,
-  type UseRowResult as UseStateResult,
+  type UseClientDocumentResult,
   useClientDocument,
 } from './useClientDocument.ts'
 export { useQuery, useQueryRef } from './useQuery.ts'