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

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

@@ -1,347 +0,0 @@
-import type { LiveStoreSchema } from '@livestore/common/schema'
-import { createStorePromise, type Store, type Unsubscribe } from '@livestore/livestore'
-import type { CachedStoreOptions, StoreId } from './types.ts'
-
-type StoreEntryState<TSchema extends LiveStoreSchema> =
-  | { status: 'idle' }
-  | { status: 'loading'; promise: Promise<Store<TSchema>>; abortController: AbortController }
-  | { status: 'success'; store: Store<TSchema> }
-  | { status: 'error'; error: unknown }
-  | { status: 'shutting_down'; shutdownPromise: Promise<void> }
-
-/**
- * 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
-
-/**
- * @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' }
-
-  #unusedCacheTime?: number
-  #disposalTimeout?: ReturnType<typeof setTimeout> | null
-
-  /**
-   * Set of subscriber callbacks to notify on state changes.
-   */
-  readonly #subscribers = new Set<() => void>()
-
-  constructor(storeId: StoreId, cache: StoreCache) {
-    this.#storeId = storeId
-    this.#cache = cache
-  }
-
-  #scheduleDisposal = (): void => {
-    this.#cancelDisposal()
-
-    const effectiveTime = this.#unusedCacheTime === undefined ? DEFAULT_UNUSED_CACHE_TIME : this.#unusedCacheTime
-
-    if (effectiveTime === Number.POSITIVE_INFINITY) return // Infinity disables disposal
-
-    this.#disposalTimeout = setTimeout(() => {
-      this.#disposalTimeout = null
-
-      // Re-check to avoid racing with a new subscription
-      if (this.#subscribers.size > 0) return
-
-      // Abort any in-progress loading to release resources early
-      this.#abortLoading()
-
-      // Transition to shutting_down state BEFORE starting async shutdown.
-      // This prevents new subscribers from receiving a store that's about to be disposed.
-      const shutdownPromise = this.#shutdown().finally(() => {
-        // Reset to idle so fresh loads can proceed, then remove from cache if still inactive
-        this.#setIdle()
-        if (this.#subscribers.size === 0) this.#cache.delete(this.#storeId)
-      })
-
-      this.#setShuttingDown(shutdownPromise)
-    }, effectiveTime)
-  }
-
-  #cancelDisposal = (): void => {
-    if (!this.#disposalTimeout) return
-    clearTimeout(this.#disposalTimeout)
-    this.#disposalTimeout = null
-  }
-
-  /**
-   * Transitions to the loading state.
-   */
-  #setLoading(promise: Promise<Store<TSchema>>, abortController: AbortController): void {
-    if (this.#state.status === 'success' || this.#state.status === 'loading') return
-    this.#state = { status: 'loading', promise, abortController }
-    this.#notify()
-  }
-
-  /**
-   * Transitions to the success state.
-   */
-  #setStore = (store: Store<TSchema>): void => {
-    this.#state = { status: 'success', store }
-    this.#notify()
-  }
-
-  /**
-   * Transitions to the error state.
-   */
-  #setError = (error: unknown): void => {
-    this.#state = { status: 'error', error }
-    this.#notify()
-  }
-
-  /**
-   * Transitions to the shutting_down state.
-   */
-  #setShuttingDown = (shutdownPromise: Promise<void>): void => {
-    this.#state = { status: 'shutting_down', shutdownPromise }
-    this.#notify()
-  }
-
-  /**
-   * Transitions to the idle state.
-   */
-  #setIdle = (): void => {
-    this.#state = { status: 'idle' }
-    // No notify needed - getOrLoad will handle the fresh load
-  }
-
-  /**
-   * Notifies all subscribers of state changes.
-   *
-   * @remarks
-   * This should be called after any meaningful state change.
-   */
-  #notify = (): void => {
-    for (const sub of this.#subscribers) {
-      try {
-        sub()
-      } catch {
-        // Swallow to protect other listeners
-      }
-    }
-  }
-
-  /**
-   * Subscribes to this entry's updates.
-   *
-   * @param listener - Callback invoked when the entry changes
-   * @returns Unsubscribe function
-   */
-  subscribe = (listener: () => void): Unsubscribe => {
-    this.#cancelDisposal()
-    this.#subscribers.add(listener)
-    return () => {
-      this.#subscribers.delete(listener)
-      // If no more subscribers remain, schedule disposal
-      if (this.#subscribers.size === 0) this.#scheduleDisposal()
-    }
-  }
-
-  /**
-   * Gets the loaded store or initiates loading if not already in progress.
-   *
-   * @param options - Store creation options
-   * @returns The loaded store if available, or a Promise that resolves to the loaded store
-   *
-   * @remarks
-   * This method handles the complete lifecycle of loading a store:
-   * - Returns the store directly if already loaded (synchronous)
-   * - Returns a Promise if loading is in progress or needs to be initiated
-   * - Transitions through loading → success/error states
-   * - Schedules disposal when loading completes without active subscribers
-   */
-  getOrLoad = (options: CachedStoreOptions<TSchema>): Store<TSchema> | Promise<Store<TSchema>> => {
-    if (options.unusedCacheTime !== undefined)
-      this.#unusedCacheTime = Math.max(this.#unusedCacheTime ?? 0, options.unusedCacheTime)
-
-    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
-
-    // Wait for shutdown to complete, then recursively call to load a fresh store
-    if (this.#state.status === 'shutting_down') {
-      return this.#state.shutdownPromise.then(() => this.getOrLoad(options))
-    }
-
-    const abortController = new AbortController()
-
-    const promise = createStorePromise({ ...options, signal: abortController.signal })
-      .then((store) => {
-        this.#setStore(store)
-        return store
-      })
-      .catch((error) => {
-        this.#setError(error)
-        throw error
-      })
-      .finally(() => {
-        // The store entry may have become unused (no subscribers) while loading the store
-        if (this.#subscribers.size === 0) this.#scheduleDisposal()
-      })
-
-    this.#setLoading(promise, abortController)
-
-    return promise
-  }
-
-  /**
-   * Aborts an in-progress store load.
-   *
-   * This signals the createStorePromise to cancel, releasing resources like
-   * worker threads, SQLite connections, and network requests.
-   */
-  #abortLoading = (): void => {
-    if (this.#state.status !== 'loading') return
-    this.#state.abortController.abort()
-  }
-
-  #shutdown = async (): Promise<void> => {
-    if (this.#state.status !== 'success') return
-    await this.#state.store.shutdownPromise().catch((reason) => {
-      console.warn(`Store ${this.#storeId} failed to shutdown cleanly during disposal:`, reason)
-    })
-  }
-}
-
-/**
- * In-memory map of {@link StoreEntry} instances keyed by {@link StoreId}.
- *
- * @privateRemarks
- * The cache is intentionally small; eviction and disposal timers are coordinated by the client.
- *
- * @internal
- */
-class StoreCache {
-  readonly #entries = new Map<StoreId, StoreEntry>()
-
-  get = <TSchema extends LiveStoreSchema>(storeId: StoreId): StoreEntry<TSchema> | undefined => {
-    return this.#entries.get(storeId) as StoreEntry<TSchema> | undefined
-  }
-
-  ensure = <TSchema extends LiveStoreSchema>(storeId: StoreId): StoreEntry<TSchema> => {
-    let entry = this.#entries.get(storeId) as StoreEntry<TSchema> | undefined
-
-    if (!entry) {
-      entry = new StoreEntry<TSchema>(storeId, this)
-      this.#entries.set(storeId, entry as unknown as StoreEntry)
-    }
-
-    return entry
-  }
-
-  /**
-   * Removes an entry from the cache.
-   *
-   * @param storeId - The ID of the store to remove
-   */
-  delete = (storeId: StoreId): void => {
-    this.#entries.delete(storeId)
-  }
-}
-
-type DefaultStoreOptions = Partial<
-  Pick<
-    CachedStoreOptions<any>,
-    'batchUpdates' | 'disableDevtools' | 'confirmUnsavedChanges' | 'syncPayload' | 'debug' | 'otelOptions'
-  >
-> & {
-  /**
-   * The time in milliseconds that unused stores remain in memory.
-   * When a store becomes unused (no subscribers), it will be disposed
-   * after this duration.
-   *
-   * Stores transition to the unused state as soon as they have no
-   * subscriptions registered, 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
-}
-
-type StoreRegistryConfig = {
-  defaultOptions?: DefaultStoreOptions
-}
-
-/**
- * Store Registry coordinating store loading, caching, and subscription
- *
- * @public
- */
-export class StoreRegistry {
-  readonly #cache = new StoreCache()
-  readonly #defaultOptions: DefaultStoreOptions
-
-  constructor({ defaultOptions = {} }: StoreRegistryConfig = {}) {
-    this.#defaultOptions = defaultOptions
-  }
-
-  #applyDefaultOptions = <TSchema extends LiveStoreSchema>(
-    options: CachedStoreOptions<TSchema>,
-  ): CachedStoreOptions<TSchema> => ({
-    ...this.#defaultOptions,
-    ...options,
-  })
-
-  /**
-   * Get or load a store, returning it directly if loaded or a promise if loading.
-   *
-   * @typeParam TSchema - The schema of the store to load
-   * @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
-   * - Applies default options from registry config, with call-site options taking precedence
-   */
-  getOrLoad = <TSchema extends LiveStoreSchema>(
-    options: CachedStoreOptions<TSchema>,
-  ): Store<TSchema> | Promise<Store<TSchema>> => {
-    const optionsWithDefaults = this.#applyDefaultOptions(options)
-    const storeEntry = this.#cache.ensure<TSchema>(optionsWithDefaults.storeId)
-
-    return storeEntry.getOrLoad(optionsWithDefaults)
-  }
-
-  /**
-   * Warms the cache for a store without mounting a subscriber.
-   *
-   * @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.getOrLoad(options)
-    } catch {
-      // Do nothing; preload is best-effort
-    }
-  }
-
-  subscribe = <TSchema extends LiveStoreSchema>(storeId: StoreId, listener: () => void): Unsubscribe => {
-    const entry = this.#cache.ensure<TSchema>(storeId)
-
-    return entry.subscribe(listener)
-  }
-}

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

@@ -1,23 +0,0 @@
-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

@@ -1,5 +0,0 @@
-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

@@ -1,8 +0,0 @@
-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

@@ -1,55 +0,0 @@
-import type { Adapter } from '@livestore/common'
-import type { LiveStoreSchema } from '@livestore/common/schema'
-import type { CreateStoreOptions, OtelOptions } from '@livestore/livestore'
-
-export type StoreId = string
-
-/**
- * Minimum information required to create a store
- */
-export type StoreDescriptor<TSchema extends LiveStoreSchema> = {
-  /**
-   * Schema describing the data structure.
-   */
-  readonly schema: TSchema
-
-  /**
-   * Adapter for persistence and synchronization.
-   */
-  readonly adapter: Adapter
-
-  /**
-   * The ID of the store.
-   */
-  readonly storeId: StoreId
-}
-
-export type CachedStoreOptions<
-  TSchema extends LiveStoreSchema = LiveStoreSchema.Any,
-  TContext = {},
-> = StoreDescriptor<TSchema> &
-  Pick<
-    CreateStoreOptions<TSchema, TContext>,
-    'boot' | 'batchUpdates' | 'disableDevtools' | 'confirmUnsavedChanges' | 'syncPayload' | 'debug'
-  > & {
-    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 subscribers), it will be disposed after this duration.
-     *
-     * Stores transition to the unused state as soon as they have no
-     * subscriptions registered, 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

@@ -1,197 +0,0 @@
-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

@@ -1,34 +0,0 @@
-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 + 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()
-
-  const subscribe = React.useCallback(
-    (onChange: () => void) => storeRegistry.subscribe(options.storeId, onChange),
-    [storeRegistry, options.storeId],
-  )
-  const getSnapshot = React.useCallback(() => {
-    const storeOrPromise = storeRegistry.getOrLoad(options)
-
-    if (storeOrPromise instanceof Promise) throw storeOrPromise
-
-    return storeOrPromise
-  }, [storeRegistry, options])
-
-  const loadedStore = React.useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
-
-  return withReactApi(loadedStore)
-}