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

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

@@ -1,9 +1,10 @@
 import { makeInMemoryAdapter } from '@livestore/adapter-web'
 import type { Store } from '@livestore/livestore'
 import { StoreInternalsSymbol } from '@livestore/livestore'
-import { type RenderResult, render, renderHook, waitFor } from '@testing-library/react'
+import { shouldNeverHappen } from '@livestore/utils'
+import { act, type RenderHookResult, type RenderResult, render, renderHook, waitFor } from '@testing-library/react'
 import * as React from 'react'
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { describe, expect, it } from 'vitest'
 import { schema } from '../../__tests__/fixture.tsx'
 import { StoreRegistry } from './StoreRegistry.ts'
 import { StoreRegistryProvider } from './StoreRegistryContext.tsx'
@@ -12,31 +13,48 @@ import type { CachedStoreOptions } from './types.ts'
 import { useStore } from './useStore.ts'
 
 describe('experimental useStore', () => {
-  afterEach(() => {
-    vi.clearAllTimers()
-    vi.useRealTimers()
+  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('suspends when the store is loading', async () => {
+  it('works with Suspense boundary', async () => {
     const registry = new StoreRegistry()
     const options = testStoreOptions()
 
-    const view = render(
-      <StoreRegistryProvider storeRegistry={registry}>
-        <React.Suspense fallback={<div data-testid="fallback" />}>
-          <StoreConsumer options={options} />
-        </React.Suspense>
-      </StoreRegistryProvider>,
-    )
-
-    // Should show fallback while loading
-    expect(view.getByTestId('fallback')).toBeDefined()
+    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')
 
-    // Wait for store to load and component to render
-    await waitForSuspenseResolved(view)
-    expect(view.getByTestId('ready')).toBeDefined()
+    // After loading completes, should show the actual content
+    await waitForSuspenseResolved(renderedView)
+    expect(renderedView.getByTestId('ready')).toBeDefined()
 
-    cleanupWithPendingTimers(() => view.unmount())
+    await cleanupAfterUnmount(() => renderedView.unmount())
   })
 
   it('does not re-suspend on subsequent renders when store is already loaded', async () => {
@@ -51,20 +69,26 @@ describe('experimental useStore', () => {
       </StoreRegistryProvider>
     )
 
-    const view = render(<Wrapper opts={options} />)
+    let view: RenderResult | undefined
+    await act(async () => {
+      view = render(<Wrapper opts={options} />)
+    })
+    const renderedView = view ?? shouldNeverHappen('render failed')
 
     // Wait for initial load
-    await waitForSuspenseResolved(view)
-    expect(view.getByTestId('ready')).toBeDefined()
+    await waitForSuspenseResolved(renderedView)
+    expect(renderedView.getByTestId('ready')).toBeDefined()
 
     // Rerender with new options object (but same storeId)
-    view.rerender(<Wrapper opts={{ ...options }} />)
+    await act(async () => {
+      renderedView.rerender(<Wrapper opts={{ ...options }} />)
+    })
 
     // Should not show fallback
-    expect(view.queryByTestId('fallback')).toBeNull()
-    expect(view.getByTestId('ready')).toBeDefined()
+    expect(renderedView.queryByTestId('fallback')).toBeNull()
+    expect(renderedView.getByTestId('ready')).toBeDefined()
 
-    cleanupWithPendingTimers(() => view.unmount())
+    await cleanupAfterUnmount(() => renderedView.unmount())
   })
 
   it('throws when store loading fails', async () => {
@@ -74,8 +98,8 @@ describe('experimental useStore', () => {
       adapter: null,
     })
 
-    // Pre-load the store to cache the error
-    await expect(registry.getOrLoad(badOptions)).rejects.toThrow()
+    // 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(() =>
@@ -92,16 +116,20 @@ describe('experimental useStore', () => {
     const registry = new StoreRegistry()
     const options = testStoreOptions()
 
-    const { result, unmount } = renderHook(() => useStore(options), {
-      wrapper: makeProvider(registry, { suspense: true }),
-      reactStrictMode: strictMode,
+    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()
 
-    cleanupWithPendingTimers(unmount)
+    await cleanupAfterUnmount(unmount)
   })
 
   it('handles switching between different storeId values', async () => {
@@ -110,10 +138,14 @@ describe('experimental useStore', () => {
     const optionsA = testStoreOptions({ storeId: 'store-a' })
     const optionsB = testStoreOptions({ storeId: 'store-b' })
 
-    const { result, rerender, unmount } = renderHook((opts) => useStore(opts), {
-      initialProps: optionsA,
-      wrapper: makeProvider(registry, { suspense: true }),
+    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)
@@ -121,7 +153,9 @@ describe('experimental useStore', () => {
     expect(storeA[StoreInternalsSymbol].clientSession).toBeDefined()
 
     // Switch to different storeId
-    rerender(optionsB)
+    await act(async () => {
+      rerender(optionsB)
+    })
 
     // Wait for second store to load and verify it's different from the first
     await waitFor(() => {
@@ -133,7 +167,47 @@ describe('experimental useStore', () => {
     expect(storeB[StoreInternalsSymbol].clientSession).toBeDefined()
     expect(storeB).not.toBe(storeA)
 
-    cleanupWithPendingTimers(unmount)
+    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())
   })
 })
 
@@ -154,28 +228,26 @@ const makeProvider =
     return content
   }
 
+let testStoreCounter = 0
+
 const testStoreOptions = (overrides: Partial<CachedStoreOptions<typeof schema>> = {}) =>
   storeOptions({
-    storeId: 'test-store',
+    storeId: overrides.storeId ?? `test-store-${testStoreCounter++}`,
     schema,
     adapter: makeInMemoryAdapter(),
     ...overrides,
   })
 
 /**
- * Cleans up after component unmount by synchronously executing any pending GC timers.
+ * 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. Without this cleanup, those timers may fire during
- * subsequent tests, causing cross-test pollution and flaky failures.
- *
- * This helper switches to fake timers, executes only the already-pending timers
- * (allowing stores to shut down cleanly), then restores real timers for the next test.
+ * timers for inactive stores. This helper waits for those timers to complete naturally.
  */
-const cleanupWithPendingTimers = (cleanup: () => void): void => {
-  vi.useFakeTimers()
+const cleanupAfterUnmount = async (cleanup: () => void): Promise<void> => {
   cleanup()
-  vi.runOnlyPendingTimers()
+  // Allow any pending microtasks/timers to settle
+  await new Promise((resolve) => setTimeout(resolve, 100))
 }
 
 /**

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

@@ -7,7 +7,7 @@ import { useStoreRegistry } from './StoreRegistryContext.tsx'
 import type { CachedStoreOptions } from './types.ts'
 
 /**
- * Suspense + Error Boundary friendly hook.
+ * Suspense and Error Boundary friendly hook.
  * - Returns data or throws (Promise|Error).
  * - No loading or error states are returned.
  */
@@ -16,19 +16,11 @@ export const useStore = <TSchema extends LiveStoreSchema>(
 ): Store<TSchema> & ReactApi => {
   const storeRegistry = useStoreRegistry()
 
-  const subscribe = React.useCallback(
-    (onChange: () => void) => storeRegistry.subscribe(options.storeId, onChange),
-    [storeRegistry, options.storeId],
-  )
-  const getSnapshot = React.useCallback(() => {
-    const storeOrPromise = storeRegistry.getOrLoad(options)
+  React.useEffect(() => storeRegistry.retain(options), [storeRegistry, options])
 
-    if (storeOrPromise instanceof Promise) throw storeOrPromise
+  const storeOrPromise = React.useMemo(() => storeRegistry.getOrLoadPromise(options), [storeRegistry, options])
 
-    return storeOrPromise
-  }, [storeRegistry, options])
+  const store = storeOrPromise instanceof Promise ? React.use(storeOrPromise) : storeOrPromise
 
-  const loadedStore = React.useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
-
-  return withReactApi(loadedStore)
+  return withReactApi(store)
 }

package/src/useClientDocument.ts

@@ -9,6 +9,17 @@ import React from 'react'
 import { LiveStoreContext } from './LiveStoreContext.ts'
 import { useQueryRef } from './useQuery.ts'
 
+/**
+ * Return type of `useClientDocument` hook.
+ *
+ * A tuple providing React-style state access to a client-document table row:
+ * - `[0]` row: The current value (decoded according to the table schema)
+ * - `[1]` setRow: Setter function to update the document
+ * - `[2]` id: The document's ID (resolved from `SessionIdSymbol` if applicable)
+ * - `[3]` query$: The underlying `LiveQuery` for advanced use cases
+ *
+ * @typeParam TTableDef - The client-document table definition type
+ */
 export type UseClientDocumentResult<TTableDef extends State.SQLite.ClientDocumentTableDef.TraitAny> = [
   row: TTableDef['Value'],
   setRow: StateSetters<TTableDef>,
@@ -140,10 +151,34 @@ export const useClientDocument: {
   return [queryRef.valueRef.current, setState, idStr, queryRef.queryRcRef.value]
 }
 
+/**
+ * A function that dispatches an action. Mirrors React's `Dispatch` type.
+ * @typeParam A - The action type
+ */
 export type Dispatch<A> = (action: A) => void
+
+/**
+ * A state update that can be either a partial value or a function returning a partial value.
+ * Used when the client-document table has `partialSet: true`.
+ * @typeParam S - The state type
+ */
 export type SetStateActionPartial<S> = Partial<S> | ((previousValue: S) => Partial<S>)
+
+/**
+ * A state update that can be either a full value or a function returning a full value.
+ * Mirrors React's `SetStateAction` type.
+ * @typeParam S - The state type
+ */
 export type SetStateAction<S> = S | ((previousValue: S) => S)
 
+/**
+ * The setter function type for `useClientDocument`, determined by the table's `partialSet` option.
+ *
+ * - If `partialSet: false` (default), requires full state replacement
+ * - If `partialSet: true`, accepts partial updates merged with existing state
+ *
+ * @typeParam TTableDef - The client-document table definition type
+ */
 export type StateSetters<TTableDef extends State.SQLite.ClientDocumentTableDef.TraitAny> = Dispatch<
   TTableDef[State.SQLite.ClientDocumentTableDefSymbol]['options']['partialSet'] extends false
     ? SetStateAction<TTableDef['Value']>

package/src/useStore.ts

@@ -7,6 +7,19 @@ import { LiveStoreContext } from './LiveStoreContext.ts'
 import { useClientDocument } from './useClientDocument.ts'
 import { useQuery } from './useQuery.ts'
 
+/**
+ * Augments a Store instance with React-specific methods (`useQuery`, `useClientDocument`).
+ *
+ * This is called automatically by `useStore()` and `LiveStoreProvider`. You typically
+ * don't need to call it directly unless you're building custom integrations.
+ *
+ * @example
+ * ```ts
+ * // Usually not needed—useStore() does this automatically
+ * const store = withReactApi(myStore)
+ * const todos = store.useQuery(tables.todos.all())
+ * ```
+ */
 export const withReactApi = <TSchema extends LiveStoreSchema>(store: Store<TSchema>): Store<TSchema> & ReactApi => {
   // @ts-expect-error TODO properly implement this
 
@@ -17,6 +30,44 @@ export const withReactApi = <TSchema extends LiveStoreSchema>(store: Store<TSche
   return store as Store<TSchema> & ReactApi
 }
 
+/**
+ * Returns the current Store instance from React context, augmented with React-specific methods.
+ *
+ * Use this hook when you need direct access to the Store for operations like
+ * `store.commit()`, `store.subscribe()`, or accessing `store.sessionId`.
+ *
+ * For reactive queries, prefer `useQuery()` or `useClientDocument()` which handle
+ * subscriptions and re-renders automatically.
+ *
+ * @example
+ * ```ts
+ * const MyComponent = () => {
+ *   const { store } = useStore()
+ *
+ *   const handleClick = () => {
+ *     store.commit(events.todoCreated({ id: nanoid(), text: 'New todo' }))
+ *   }
+ *
+ *   return <button onClick={handleClick}>Add Todo</button>
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Access store metadata
+ * const { store } = useStore()
+ * console.log('Session ID:', store.sessionId)
+ * console.log('Client ID:', store.clientId)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Use with an explicit store instance (bypasses context)
+ * const { store } = useStore({ store: myExternalStore })
+ * ```
+ *
+ * @throws Error if called outside of `<LiveStoreProvider>` or before the store is running
+ */
 export const useStore = (options?: { store?: Store }): { store: Store & ReactApi } => {
   if (options?.store !== undefined) {
     return { store: withReactApi(options.store) }