@livestore/react 0.4.0-dev.22 → 0.4.0-dev.23

package/src/useStore.test.tsx

@@ -7,9 +7,10 @@ import {
   storeOptions,
 } from '@livestore/livestore'
 import { shouldNeverHappen } from '@livestore/utils'
-import { act, type RenderHookResult, type RenderResult, render, renderHook, waitFor } from '@testing-library/react'
+import { act, type RenderHookResult, type RenderResult, fireEvent, render, renderHook, waitFor } from '@testing-library/react'
 import * as React from 'react'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
+
 import { schema } from './__tests__/fixture.tsx'
 import { StoreRegistryProvider } from './StoreRegistryContext.tsx'
 import { useStore } from './useStore.ts'
@@ -44,7 +45,7 @@ describe('experimental useStore', () => {
     await act(async () => {
       view = render(
         <StoreRegistryProvider storeRegistry={storeRegistry}>
-          <React.Suspense fallback={<div data-testid="fallback" />}>
+          <React.Suspense fallback={makeSuspenseFallback()}>
             <StoreConsumer options={options} />
           </React.Suspense>
         </StoreRegistryProvider>,
@@ -62,10 +63,9 @@ describe('experimental useStore', () => {
   it('does not re-suspend on subsequent renders when store is already loaded', async () => {
     const storeRegistry = new StoreRegistry()
     const options = testStoreOptions()
-
     const Wrapper = ({ opts }: { opts: RegistryStoreOptions<typeof schema> }) => (
       <StoreRegistryProvider storeRegistry={storeRegistry}>
-        <React.Suspense fallback={<div data-testid="fallback" />}>
+        <React.Suspense fallback={makeSuspenseFallback()}>
           <StoreConsumer options={opts} />
         </React.Suspense>
       </StoreRegistryProvider>
@@ -82,8 +82,9 @@ describe('experimental useStore', () => {
     expect(renderedView.getByTestId('ready')).toBeDefined()
 
     // Rerender with new options object (but same storeId)
+    const rerenderOptions = cloneStoreOptions(options)
     await act(async () => {
-      renderedView.rerender(<Wrapper opts={{ ...options }} />)
+      renderedView.rerender(<Wrapper opts={rerenderOptions} />)
     })
 
     // Should not show fallback
@@ -172,12 +173,57 @@ describe('experimental useStore', () => {
     await cleanupAfterUnmount(unmount)
   })
 
+  it('does not block useActionState transitions from committing', async () => {
+    const storeRegistry = new StoreRegistry()
+    const options = testStoreOptions()
+    const getOrLoadSpy = vi.spyOn(storeRegistry, 'getOrLoadPromise')
+
+    let view: RenderResult | undefined
+    await act(async () => {
+      view = render(
+        <StoreRegistryProvider storeRegistry={storeRegistry}>
+          <React.Suspense fallback={makeSuspenseFallback()}>
+            <StoreWithActionState options={options} />
+          </React.Suspense>
+        </StoreRegistryProvider>,
+      )
+    })
+    const renderedView = view ?? shouldNeverHappen('render failed')
+
+    // Wait for store to load
+    await waitForSuspenseResolved(renderedView)
+    expect(renderedView.getByTestId('state').textContent).toBe('none')
+    expect(renderedView.getByTestId('pending').textContent).toBe('false')
+
+    // After store is loaded, clear spy to only track calls during the transition render
+    getOrLoadSpy.mockClear()
+
+    // Trigger a useActionState transition
+    await act(async () => {
+      fireEvent.click(renderedView.getByTestId('submit'))
+    })
+
+    // getOrLoadPromise must be called on each render (not cached via useMemo).
+    // When the initial Promise is cached, React.use() is called with a resolved Promise
+    // on every subsequent render, which blocks React transitions (e.g. useActionState)
+    // from ever committing in browser environments.
+    expect(getOrLoadSpy).toHaveBeenCalled()
+
+    // The transition should commit: state updates and isPending returns to false
+    await waitFor(() => {
+      expect(renderedView.getByTestId('state').textContent).toBe('updated')
+      expect(renderedView.getByTestId('pending').textContent).toBe('false')
+    })
+
+    getOrLoadSpy.mockRestore()
+    await cleanupAfterUnmount(() => renderedView.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 storeRegistry = new StoreRegistry({ defaultOptions: { unusedCacheTime: 0 } })
     const options = testStoreOptions({ unusedCacheTime: 0 })
-
     const StoreConsumerWithVerification = ({ opts }: { opts: RegistryStoreOptions<typeof schema> }) => {
       const store = useStore(opts)
       // Verify store is usable - access internals to confirm it's not disposed
@@ -189,7 +235,7 @@ describe('experimental useStore', () => {
     await act(async () => {
       view = render(
         <StoreRegistryProvider storeRegistry={storeRegistry}>
-          <React.Suspense fallback={<div data-testid="fallback" />}>
+          <React.Suspense fallback={makeSuspenseFallback()}>
             <StoreConsumerWithVerification opts={options} />
           </React.Suspense>
         </StoreRegistryProvider>,
@@ -218,12 +264,42 @@ const StoreConsumer = ({ options }: { options: RegistryStoreOptions<any> }) => {
   return <div data-testid="ready" />
 }
 
+/** Component that combines useStore with useActionState to test transition compatibility. */
+const StoreWithActionState = ({ options }: { options: RegistryStoreOptions<any> }) => {
+  useStore(options)
+
+  const [state, dispatch, isPending] = React.useActionState(
+    (_prev: string | undefined, value: string): string => value,
+    undefined,
+  )
+
+  return (
+    <div>
+      <button
+        data-testid="submit"
+        // eslint-disable-next-line react-perf/jsx-no-new-function-as-prop -- test component
+        onClick={() => React.startTransition(() => dispatch('updated'))}
+      >
+        Submit
+      </button>
+      <div data-testid="state">{state ?? 'none'}</div>
+      <div data-testid="pending">{String(isPending)}</div>
+    </div>
+  )
+}
+
+const makeSuspenseFallback = () => React.createElement('div', { 'data-testid': 'fallback' })
+
+const cloneStoreOptions = <TOptions extends object>(options: TOptions): TOptions => {
+  return { ...options }
+}
+
 const makeProvider =
   (storeRegistry: StoreRegistry, { suspense = false }: { suspense?: boolean } = {}) =>
   ({ children }: { children: React.ReactNode }) => {
     let content = <StoreRegistryProvider storeRegistry={storeRegistry}>{children}</StoreRegistryProvider>
 
-    if (suspense) {
+    if (suspense !== undefined) {
       content = <React.Suspense fallback={null}>{content}</React.Suspense>
     }
 

package/src/useStore.ts

@@ -1,10 +1,13 @@
+import React from 'react'
+
 import type { LiveStoreSchema } from '@livestore/common/schema'
-import type { RegistryStoreOptions, Store } from '@livestore/livestore'
+import type { RegistryStoreOptions, Store, SyncStatus } from '@livestore/livestore'
 import type { Schema } from '@livestore/utils/effect'
-import React from 'react'
+
 import { useStoreRegistry } from './StoreRegistryContext.tsx'
 import { useClientDocument } from './useClientDocument.ts'
 import { useQuery } from './useQuery.ts'
+import { useSyncStatus } from './useSyncStatus.ts'
 
 /**
  * Returns a store instance augmented with hooks (`store.useQuery()` and `store.useClientDocument()`) for reactive queries.
@@ -60,24 +63,28 @@ export const useStore = <
 ): Store<TSchema, TContext> & ReactApi => {
   const storeRegistry = useStoreRegistry()
 
-  // NOTE: retain() is called in useEffect (after render), while getOrLoadPromise() is called
-  // in useMemo (during render). This creates a timing gap where with very short unusedCacheTime
-  // values (e.g., 0), the store could theoretically be disposed before the effect fires.
-  // In practice, this is not an issue with the default 60s cache time, but it becomes an issue when
-  // `unusedCacheTime` is configured to values less than ~100ms.
-  // See https://github.com/livestorejs/livestore/issues/916
-  React.useEffect(() => storeRegistry.retain(options), [storeRegistry, options])
-
-  const storeOrPromise = React.useMemo(() => storeRegistry.getOrLoadPromise(options), [storeRegistry, options])
+  // Called on every render (intentionally not memoized). For already-loaded stores this returns
+  // the Store synchronously, so React.use() is skipped entirely. Caching the initial Promise via
+  // useMemo would cause React.use() to be called with a resolved Promise on subsequent renders,
+  // which blocks React transitions from committing.
+  const storeOrPromise = storeRegistry.getOrLoadPromise(options)
 
   const store = storeOrPromise instanceof Promise ? React.use(storeOrPromise) : storeOrPromise
 
-  // Expose store on the global object for browser console debugging.
-  globalThis.__debugLiveStore ??= {}
-  if (Object.keys(globalThis.__debugLiveStore).length === 0) {
-    globalThis.__debugLiveStore._ = store
-  }
-  globalThis.__debugLiveStore[options.debug?.instanceId ?? options.storeId] = store
+  // NOTE: retain() must be declared AFTER the React.use() call above. When React.use() suspends
+  // the component, any hooks declared before it get committed while hooks after the suspension
+  // point (including those in the caller) don't. On re-render when the store resolves synchronously,
+  // those late hooks appear for the first time, causing a hook-order violation in strict mode.
+  // By placing useEffect after React.use(), no effect hooks are committed during suspension,
+  // so React treats all effects as fresh mounts on the first successful render.
+  //
+  // retain() is called in useEffect (after render), while getOrLoadPromise() is called during
+  // render. This creates a timing gap where with very short unusedCacheTime values (e.g., 0),
+  // the store could theoretically be disposed before the effect fires. In practice, this is not
+  // an issue with the default 60s cache time, but it becomes an issue when `unusedCacheTime` is
+  // configured to values less than ~100ms.
+  // See https://github.com/livestorejs/livestore/issues/916
+  React.useEffect(() => storeRegistry.retain(options), [storeRegistry, options])
 
   return withReactApi(store)
 }
@@ -94,6 +101,8 @@ export type ReactApi = {
   useQuery: typeof useQuery
   /** Hook for reading and writing client-document tables with React state semantics */
   useClientDocument: typeof useClientDocument
+  /** Hook for subscribing to sync status changes */
+  useSyncStatus: () => SyncStatus
 }
 
 /**
@@ -112,5 +121,9 @@ export const withReactApi = <TSchema extends LiveStoreSchema, TContext = {}>(
 
   // @ts-expect-error TODO properly implement this
   store.useClientDocument = (table, idOrOptions, options) => useClientDocument(table, idOrOptions, options, { store })
+
+  // @ts-expect-error TODO properly implement this
+  store.useSyncStatus = () => useSyncStatus({ store })
+
   return store as Store<TSchema, TContext> & ReactApi
 }

package/src/useSyncStatus.ts

@@ -0,0 +1,34 @@
+import React from 'react'
+
+import type { Store, SyncStatus } from '@livestore/livestore'
+
+/**
+ * React hook that subscribes to sync status changes.
+ *
+ * Returns the current synchronization status between the client session and
+ * the leader thread. The component re-renders whenever the sync status changes.
+ *
+ * @example
+ * ```tsx
+ * function SyncIndicator() {
+ *   const status = store.useSyncStatus()
+ *   return <span>{status.isSynced ? '✓ Synced' : `Syncing (${status.pendingCount} pending)...`}</span>
+ * }
+ * ```
+ *
+ * @param options - Options containing the store instance
+ * @returns The current sync status
+ */
+export const useSyncStatus = (options: { store: Store<any> }): SyncStatus => {
+  const { store } = options
+
+  const [status, setStatus] = React.useState<SyncStatus>(() => store.syncStatus())
+
+  React.useEffect(() => {
+    return store.subscribeSyncStatus(setStatus)
+  }, [store])
+
+  React.useDebugValue(`LiveStore:useSyncStatus:${status.isSynced === true ? 'synced' : 'pending'}`)
+
+  return status
+}

package/dist/utils/stack-info.d.ts

@@ -1,4 +0,0 @@
-import { type StackInfo } from '@livestore/livestore';
-export declare const originalStackLimit: number;
-export declare const useStackInfo: () => StackInfo;
-//# sourceMappingURL=stack-info.d.ts.map

package/dist/utils/stack-info.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"stack-info.d.ts","sourceRoot":"","sources":["../../src/utils/stack-info.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAGrF,eAAO,MAAM,kBAAkB,QAAwB,CAAA;AAEvD,eAAO,MAAM,YAAY,QAAO,SAOxB,CAAA"}

package/dist/utils/stack-info.js

@@ -1,10 +0,0 @@
-import { extractStackInfoFromStackTrace } from '@livestore/livestore';
-import React from 'react';
-export const originalStackLimit = Error.stackTraceLimit;
-export const useStackInfo = () => React.useMemo(() => {
-    Error.stackTraceLimit = 10;
-    const stack = new Error().stack;
-    Error.stackTraceLimit = originalStackLimit;
-    return extractStackInfoFromStackTrace(stack);
-}, []);
-//# sourceMappingURL=stack-info.js.map

package/dist/utils/stack-info.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"stack-info.js","sourceRoot":"","sources":["../../src/utils/stack-info.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,8BAA8B,EAAkB,MAAM,sBAAsB,CAAA;AACrF,OAAO,KAAK,MAAM,OAAO,CAAA;AAEzB,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,CAAC,eAAe,CAAA;AAEvD,MAAM,CAAC,MAAM,YAAY,GAAG,GAAc,EAAE,CAC1C,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE;IACjB,KAAK,CAAC,eAAe,GAAG,EAAE,CAAA;IAE1B,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC,KAAM,CAAA;IAChC,KAAK,CAAC,eAAe,GAAG,kBAAkB,CAAA;IAC1C,OAAO,8BAA8B,CAAC,KAAK,CAAC,CAAA;AAC9C,CAAC,EAAE,EAAE,CAAC,CAAA"}

package/src/ambient.d.ts

@@ -1 +0,0 @@
-var __debugLiveStore: any

package/src/utils/stack-info.ts

@@ -1,13 +0,0 @@
-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
-
-    const stack = new Error().stack!
-    Error.stackTraceLimit = originalStackLimit
-    return extractStackInfoFromStackTrace(stack)
-  }, [])