@livestore/react 0.4.0-dev.15 → 0.4.0-dev.17

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

@@ -9,24 +9,62 @@ type StoreEntryState<TSchema extends LiveStoreSchema> =
   | { status: 'error'; error: unknown }
 
 /**
- * Minimal cache entry that tracks store state and subscribers.
+ * Default garbage collection time for inactive stores.
  *
+ * - Browser: 60 seconds (60,000ms)
+ * - SSR: Infinity (disables GC to avoid disposing stores before server render completes)
+ *
+ * @internal Exported primarily for testing purposes.
+ */
+export const DEFAULT_GC_TIME = typeof window === 'undefined' ? Number.POSITIVE_INFINITY : 60_000
+
+/**
  * @typeParam TSchema - The schema for this entry's store.
  * @internal
  */
 class StoreEntry<TSchema extends LiveStoreSchema = LiveStoreSchema> {
+  readonly #storeId: StoreId
+  readonly #cache: StoreCache
+
   #state: StoreEntryState<TSchema> = { status: 'idle' }
 
+  #gcTime?: number
+  #gcTimeout?: ReturnType<typeof setTimeout> | null
+
   /**
    * Set of subscriber callbacks to notify on state changes.
    */
-  #subscribers = new Set<() => void>()
+  readonly #subscribers = new Set<() => void>()
 
-  /**
-   * The number of active subscribers for this entry.
-   */
-  get subscriberCount() {
-    return this.#subscribers.size
+  constructor(storeId: StoreId, cache: StoreCache) {
+    this.#storeId = storeId
+    this.#cache = cache
+  }
+
+  #scheduleGC = (): void => {
+    this.#cancelGC()
+
+    const effectiveGcTime = this.#gcTime === undefined ? DEFAULT_GC_TIME : this.#gcTime
+
+    if (effectiveGcTime === Number.POSITIVE_INFINITY) return // Infinity disables GC
+
+    this.#gcTimeout = setTimeout(() => {
+      this.#gcTimeout = null
+
+      // Re-check to avoid racing with a new subscription
+      if (this.#subscribers.size > 0) return
+
+      void this.#shutdown().finally(() => {
+        // Double-check again just in case shutdown was slow
+        if (this.#subscribers.size === 0) this.#cache.delete(this.#storeId)
+      })
+    }, effectiveGcTime)
+  }
+
+  #cancelGC = (): void => {
+    if (!this.#gcTimeout) return
+    clearTimeout(this.#gcTimeout)
+    this.#gcTimeout = null
   }
 
   /**
@@ -54,11 +92,6 @@ class StoreEntry<TSchema extends LiveStoreSchema = LiveStoreSchema> {
     this.#notify()
   }
 
-  #reset = (): void => {
-    this.#state = { status: 'idle' }
-    this.#notify()
-  }
-
   /**
    * Notifies all subscribers of state changes.
    *
@@ -82,9 +115,12 @@ class StoreEntry<TSchema extends LiveStoreSchema = LiveStoreSchema> {
    * @returns Unsubscribe function
    */
   subscribe = (listener: () => void): Unsubscribe => {
+    this.#cancelGC()
     this.#subscribers.add(listener)
     return () => {
       this.#subscribers.delete(listener)
+      // If no more subscribers remain, schedule GC
+      if (this.#subscribers.size === 0) this.#scheduleGC()
     }
   }
 
@@ -101,6 +137,8 @@ class StoreEntry<TSchema extends LiveStoreSchema = LiveStoreSchema> {
    * - Invokes onSettle callback for GC scheduling when needed
    */
   getOrLoad = (options: CachedStoreOptions<TSchema>): Store<TSchema> | Promise<Store<TSchema>> => {
+    if (options.gcTime !== undefined) this.#gcTime = Math.max(this.#gcTime ?? 0, options.gcTime)
+
     if (this.#state.status === 'success') return this.#state.store
     if (this.#state.status === 'loading') return this.#state.promise
     if (this.#state.status === 'error') throw this.#state.error
@@ -114,17 +152,21 @@ class StoreEntry<TSchema extends LiveStoreSchema = LiveStoreSchema> {
         this.#setError(error)
         throw error
       })
+      .finally(() => {
+        // The store entry may have become inactive (no subscribers) while loading the store
+        if (this.#subscribers.size === 0) this.#scheduleGC()
+      })
 
     this.#setPromise(promise)
 
     return promise
   }
 
-  shutdown = async (): Promise<void> => {
+  #shutdown = async (): Promise<void> => {
     if (this.#state.status !== 'success') return
-    await this.#state.store.shutdownPromise()
-
-    this.#reset()
+    await this.#state.store.shutdownPromise().catch((reason) => {
+      console.warn(`Store ${this.#storeId} failed to shutdown cleanly during GC:`, reason)
+    })
   }
 }
 
@@ -147,7 +189,7 @@ class StoreCache {
     let entry = this.#entries.get(storeId) as StoreEntry<TSchema> | undefined
 
     if (!entry) {
-      entry = new StoreEntry<TSchema>()
+      entry = new StoreEntry<TSchema>(storeId, this)
       this.#entries.set(storeId, entry as unknown as StoreEntry)
     }
 
@@ -158,20 +200,12 @@ class StoreCache {
    * Removes an entry from the cache.
    *
    * @param storeId - The ID of the store to remove
-   *
-   * @remarks
-   * - Invokes shutdown on the store before removal.
    */
-  remove = (storeId: StoreId): void => {
-    const entry = this.#entries.get(storeId)
-    if (!entry) return
-    void entry.shutdown()
+  delete = (storeId: StoreId): void => {
     this.#entries.delete(storeId)
   }
 }
 
-const DEFAULT_GC_TIME = typeof window === 'undefined' ? Number.POSITIVE_INFINITY : 60_000
-
 type DefaultStoreOptions = Partial<
   Pick<
     CachedStoreOptions<any>,
@@ -208,7 +242,6 @@ type StoreRegistryConfig = {
  */
 export class StoreRegistry {
   readonly #cache = new StoreCache()
-  readonly #gcTimeouts = new Map<StoreId, ReturnType<typeof setTimeout>>()
   readonly #defaultOptions: DefaultStoreOptions
 
   constructor({ defaultOptions = {} }: StoreRegistryConfig = {}) {
@@ -222,23 +255,6 @@ export class StoreRegistry {
     ...options,
   })
 
-  #scheduleGC = (id: StoreId): void => {
-    this.#cancelGC(id)
-    const timer = setTimeout(() => {
-      this.#gcTimeouts.delete(id)
-      this.#cache.remove(id)
-    }, DEFAULT_GC_TIME)
-    this.#gcTimeouts.set(id, timer)
-  }
-
-  #cancelGC = (id: StoreId): void => {
-    const t = this.#gcTimeouts.get(id)
-    if (t) {
-      clearTimeout(t)
-      this.#gcTimeouts.delete(id)
-    }
-  }
-
   /**
    * Get or load a store, returning it directly if loaded or a promise if loading.
    *
@@ -256,18 +272,9 @@ export class StoreRegistry {
     options: CachedStoreOptions<TSchema>,
   ): Store<TSchema> | Promise<Store<TSchema>> => {
     const optionsWithDefaults = this.#applyDefaultOptions(options)
-    const entry = this.#cache.ensure<TSchema>(optionsWithDefaults.storeId)
-
-    const storeOrPromise = entry.getOrLoad(optionsWithDefaults)
-
-    if (storeOrPromise instanceof Promise) {
-      return storeOrPromise.finally(() => {
-        // If no subscribers remain after load settles, schedule GC
-        if (entry.subscriberCount === 0) this.#scheduleGC(optionsWithDefaults.storeId)
-      })
-    }
+    const storeEntry = this.#cache.ensure<TSchema>(optionsWithDefaults.storeId)
 
-    return storeOrPromise
+    return storeEntry.getOrLoad(optionsWithDefaults)
   }
 
   /**
@@ -290,15 +297,7 @@ export class StoreRegistry {
 
   subscribe = <TSchema extends LiveStoreSchema>(storeId: StoreId, listener: () => void): Unsubscribe => {
     const entry = this.#cache.ensure<TSchema>(storeId)
-    // Active subscriber: cancel any scheduled GC
-    this.#cancelGC(storeId)
-
-    const unsubscribe = entry.subscribe(listener)
 
-    return () => {
-      unsubscribe()
-      // If no more subscribers remain, schedule GC
-      if (entry.subscriberCount === 0) this.#scheduleGC(storeId)
-    }
+    return entry.subscribe(listener)
   }
 }

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

@@ -0,0 +1,197 @@
+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 * as React from 'react'
+import { afterEach, describe, expect, it, vi } 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', () => {
+  afterEach(() => {
+    vi.clearAllTimers()
+    vi.useRealTimers()
+  })
+
+  it('suspends when the store is loading', 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()
+
+    // Wait for store to load and component to render
+    await waitForSuspenseResolved(view)
+    expect(view.getByTestId('ready')).toBeDefined()
+
+    cleanupWithPendingTimers(() => view.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>
+    )
+
+    const view = render(<Wrapper opts={options} />)
+
+    // Wait for initial load
+    await waitForSuspenseResolved(view)
+    expect(view.getByTestId('ready')).toBeDefined()
+
+    // Rerender with new options object (but same storeId)
+    view.rerender(<Wrapper opts={{ ...options }} />)
+
+    // Should not show fallback
+    expect(view.queryByTestId('fallback')).toBeNull()
+    expect(view.getByTestId('ready')).toBeDefined()
+
+    cleanupWithPendingTimers(() => view.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
+    await expect(registry.getOrLoad(badOptions)).rejects.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()
+
+    const { result, unmount } = renderHook(() => useStore(options), {
+      wrapper: makeProvider(registry, { suspense: true }),
+      reactStrictMode: strictMode,
+    })
+
+    // Wait for store to be ready
+    await waitForStoreReady(result)
+    expect(result.current[StoreInternalsSymbol].clientSession).toBeDefined()
+
+    cleanupWithPendingTimers(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' })
+
+    const { result, rerender, unmount } = renderHook((opts) => useStore(opts), {
+      initialProps: optionsA,
+      wrapper: makeProvider(registry, { suspense: true }),
+    })
+
+    // Wait for first store to load
+    await waitForStoreReady(result)
+    const storeA = result.current
+    expect(storeA[StoreInternalsSymbol].clientSession).toBeDefined()
+
+    // Switch to different storeId
+    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)
+
+    cleanupWithPendingTimers(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
+  }
+
+const testStoreOptions = (overrides: Partial<CachedStoreOptions<typeof schema>> = {}) =>
+  storeOptions({
+    storeId: 'test-store',
+    schema,
+    adapter: makeInMemoryAdapter(),
+    ...overrides,
+  })
+
+/**
+ * Cleans up after component unmount by synchronously executing any pending GC timers.
+ *
+ * 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.
+ */
+const cleanupWithPendingTimers = (cleanup: () => void): void => {
+  vi.useFakeTimers()
+  cleanup()
+  vi.runOnlyPendingTimers()
+}
+
+/**
+ * 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

@@ -20,11 +20,15 @@ export const useStore = <TSchema extends LiveStoreSchema>(
     (onChange: () => void) => storeRegistry.subscribe(options.storeId, onChange),
     [storeRegistry, options.storeId],
   )
-  const getSnapshot = React.useCallback(() => storeRegistry.getOrLoad(options), [storeRegistry, options])
+  const getSnapshot = React.useCallback(() => {
+    const storeOrPromise = storeRegistry.getOrLoad(options)
 
-  const storeOrPromise = React.useSyncExternalStore(subscribe, getSnapshot)
+    if (storeOrPromise instanceof Promise) throw storeOrPromise
 
-  const loadedStore = storeOrPromise instanceof Promise ? React.use(storeOrPromise) : storeOrPromise
+    return storeOrPromise
+  }, [storeRegistry, options])
+
+  const loadedStore = React.useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
 
   return withReactApi(loadedStore)
 }

package/src/useClientDocument.test.tsx

@@ -1,6 +1,7 @@
 /** biome-ignore-all lint/a11y/useValidAriaRole: not needed for testing */
 /** biome-ignore-all lint/a11y/noStaticElementInteractions: not needed for testing */
 import * as LiveStore from '@livestore/livestore'
+import { StoreInternalsSymbol } from '@livestore/livestore'
 import { getAllSimplifiedRootSpans, getSimplifiedRootSpan } from '@livestore/livestore/internal/testing-utils'
 import { Effect, ReadonlyRecord, Schema } from '@livestore/utils/effect'
 import { Vitest } from '@livestore/utils-dev/node-vitest'
@@ -39,12 +40,12 @@ Vitest.describe('useClientDocument', () => {
       expect(result.current.id).toBe('u1')
       expect(result.current.state.username).toBe('')
       expect(renderCount.val).toBe(1)
-      expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+      expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
       store.commit(tables.userInfo.set({ username: 'username_u2' }, 'u2'))
 
       rerender('u2')
 
-      expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+      expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
       expect(result.current.id).toBe('u2')
       expect(result.current.state.username).toBe('username_u2')
       expect(renderCount.val).toBe(2)

package/src/useClientDocument.ts

@@ -111,7 +111,7 @@ export const useClientDocument: {
 
   // console.debug('useClientDocument', tableName, id)
 
-  const idStr: string = id === SessionIdSymbol ? store.clientSession.sessionId : id
+  const idStr: string = id === SessionIdSymbol ? store.sessionId : id
 
   type QueryDef = LiveQueryDef<TTableDef['Value']>
   const queryDef: QueryDef = React.useMemo(

package/src/useQuery.test.tsx

@@ -1,6 +1,6 @@
 /** biome-ignore-all lint/a11y: test */
 import * as LiveStore from '@livestore/livestore'
-import { queryDb, signal } from '@livestore/livestore'
+import { queryDb, StoreInternalsSymbol, signal } from '@livestore/livestore'
 import { RG } from '@livestore/livestore/internal/testing-utils'
 import { Effect, Schema } from '@livestore/utils/effect'
 import { Vitest } from '@livestore/utils-dev/node-vitest'
@@ -38,14 +38,14 @@ Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
 
         expect(result.current.length).toBe(0)
         expect(renderCount.val).toBe(1)
-        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+        expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
 
         ReactTesting.act(() => store.commit(events.todoCreated({ id: 't1', text: 'buy milk', completed: false })))
 
         expect(result.current.length).toBe(1)
         expect(result.current[0]!.text).toBe('buy milk')
         expect(renderCount.val).toBe(2)
-        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+        expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
       }),
     )
 
@@ -80,19 +80,25 @@ Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
 
         expect(result.current).toBe('buy milk')
         expect(renderCount.val).toBe(1)
-        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot('1: after first render')
+        expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot(
+          '1: after first render',
+        )
 
         ReactTesting.act(() => store.commit(events.todoUpdated({ id: 't1', text: 'buy soy milk' })))
 
         expect(result.current).toBe('buy soy milk')
         expect(renderCount.val).toBe(2)
-        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot('2: after first commit')
+        expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot(
+          '2: after first commit',
+        )
 
         rerender('t2')
 
         expect(result.current).toBe('buy eggs')
         expect(renderCount.val).toBe(3)
-        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot('3: after forced rerender')
+        expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot(
+          '3: after forced rerender',
+        )
       }),
     )
 
@@ -120,19 +126,19 @@ Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
 
         expect(result.current).toBe('buy milk')
         expect(renderCount.val).toBe(1)
-        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+        expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
 
         ReactTesting.act(() => store.commit(events.todoUpdated({ id: 't1', text: 'buy soy milk' })))
 
         expect(result.current).toBe('buy soy milk')
         expect(renderCount.val).toBe(2)
-        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+        expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
 
         ReactTesting.act(() => store.setSignal(filter$, 't2'))
 
         expect(result.current).toBe('buy eggs')
         expect(renderCount.val).toBe(3)
-        expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+        expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
       }),
     )
 

package/src/useQuery.ts

@@ -6,6 +6,7 @@ import {
   type Queryable,
   queryDb,
   type SignalDef,
+  StoreInternalsSymbol,
   stackInfoToString,
 } from '@livestore/livestore'
 import type { LiveQueries } from '@livestore/livestore/internal'
@@ -122,17 +123,17 @@ export const useQueryRef = <TQueryable extends Queryable<any>>(
   const { queryRcRef, span, otelContext } = useRcResource(
     rcRefKey,
     () => {
-      const span = store.otel.tracer.startSpan(
+      const span = store[StoreInternalsSymbol].otel.tracer.startSpan(
         options?.otelSpanName ?? `LiveStore:useQuery:${resourceLabel}`,
         { attributes: { label: resourceLabel, firstStackInfo: JSON.stringify(stackInfo) } },
-        options?.otelContext ?? store.otel.queriesSpanContext,
+        options?.otelContext ?? store[StoreInternalsSymbol].otel.queriesSpanContext,
       )
 
       const otelContext = otel.trace.setSpan(otel.context.active(), span)
 
       const queryRcRef =
         normalized._tag === 'definition'
-          ? normalized.def.make(store.reactivityGraph.context!, otelContext)
+          ? normalized.def.make(store[StoreInternalsSymbol].reactivityGraph.context!, otelContext)
           : ({
               value: normalized.query$,
               deref: () => {},