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

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

@@ -0,0 +1,304 @@
+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>> }
+  | { status: 'success'; store: Store<TSchema> }
+  | { status: 'error'; error: unknown }
+
+/**
+ * Minimal cache entry that tracks store state and subscribers.
+ *
+ * @typeParam TSchema - The schema for this entry's store.
+ * @internal
+ */
+class StoreEntry<TSchema extends LiveStoreSchema = LiveStoreSchema> {
+  #state: StoreEntryState<TSchema> = { status: 'idle' }
+
+  /**
+   * Set of subscriber callbacks to notify on state changes.
+   */
+  #subscribers = new Set<() => void>()
+
+  /**
+   * The number of active subscribers for this entry.
+   */
+  get subscriberCount() {
+    return this.#subscribers.size
+  }
+
+  /**
+   * Transitions to the loading state.
+   */
+  #setPromise(promise: Promise<Store<TSchema>>): void {
+    if (this.#state.status === 'success' || this.#state.status === 'loading') return
+    this.#state = { status: 'loading', promise }
+    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()
+  }
+
+  #reset = (): void => {
+    this.#state = { status: 'idle' }
+    this.#notify()
+  }
+
+  /**
+   * 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.#subscribers.add(listener)
+    return () => {
+      this.#subscribers.delete(listener)
+    }
+  }
+
+  /**
+   * Initiates loading of the store if not already in progress.
+   *
+   * @param options - Store creation options
+   * @returns Promise that resolves to the loaded store or rejects with an error
+   *
+   * @remarks
+   * This method handles the complete lifecycle of loading a store:
+   * - Creates the store promise via createStorePromise
+   * - Transitions through loading → success/error states
+   * - Invokes onSettle callback for GC scheduling when needed
+   */
+  getOrLoad = (options: CachedStoreOptions<TSchema>): Store<TSchema> | Promise<Store<TSchema>> => {
+    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
+
+    const promise = createStorePromise(options)
+      .then((store) => {
+        this.#setStore(store)
+        return store
+      })
+      .catch((error) => {
+        this.#setError(error)
+        throw error
+      })
+
+    this.#setPromise(promise)
+
+    return promise
+  }
+
+  shutdown = async (): Promise<void> => {
+    if (this.#state.status !== 'success') return
+    await this.#state.store.shutdownPromise()
+
+    this.#reset()
+  }
+}
+
+/**
+ * In-memory map of {@link StoreEntry} instances keyed by {@link StoreId}.
+ *
+ * @privateRemarks
+ * The cache is intentionally small; eviction and GC 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>()
+      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
+   *
+   * @remarks
+   * - Invokes shutdown on the store before removal.
+   */
+  remove = (storeId: StoreId): void => {
+    const entry = this.#entries.get(storeId)
+    if (!entry) return
+    void entry.shutdown()
+    this.#entries.delete(storeId)
+  }
+}
+
+const DEFAULT_GC_TIME = typeof window === 'undefined' ? Number.POSITIVE_INFINITY : 60_000
+
+type DefaultStoreOptions = Partial<
+  Pick<
+    CachedStoreOptions<any>,
+    'batchUpdates' | 'disableDevtools' | 'confirmUnsavedChanges' | 'syncPayload' | 'debug' | 'otelOptions'
+  >
+> & {
+  /**
+   * The time in milliseconds that inactive stores remain in memory.
+   * When a store becomes inactive, it will be garbage collected
+   * after this duration.
+   *
+   * Stores transition to the inactive 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 garbage collection
+   * - 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.
+   */
+  gcTime?: number
+}
+
+type StoreRegistryConfig = {
+  defaultOptions?: DefaultStoreOptions
+}
+
+/**
+ * Store Registry coordinating cache, GC, and Suspense reads.
+ *
+ * @public
+ */
+export class StoreRegistry {
+  readonly #cache = new StoreCache()
+  readonly #gcTimeouts = new Map<StoreId, ReturnType<typeof setTimeout>>()
+  readonly #defaultOptions: DefaultStoreOptions
+
+  constructor({ defaultOptions = {} }: StoreRegistryConfig = {}) {
+    this.#defaultOptions = defaultOptions
+  }
+
+  #applyDefaultOptions = <TSchema extends LiveStoreSchema>(
+    options: CachedStoreOptions<TSchema>,
+  ): CachedStoreOptions<TSchema> => ({
+    ...this.#defaultOptions,
+    ...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.
+   *
+   * @typeParam TSchema - The schema of the store to load
+   * @returns The loaded store if available, or a Promise that resolves to the store if loading
+   * @throws unknown loading error
+   *
+   * @remarks
+   * - Designed to work with React.use() for Suspense integration.
+   * - When the store is already loaded, returns the store instance directly (not wrapped in a Promise)
+   * - When loading, returns a stable Promise reference that can be used with React.use()
+   * - This prevents re-suspension on subsequent renders when the store is already loaded
+   */
+  getOrLoad = <TSchema extends LiveStoreSchema>(
+    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)
+      })
+    }
+
+    return storeOrPromise
+  }
+
+  /**
+   * 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 GC.
+   */
+  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)
+    // 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)
+    }
+  }
+}

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 <MultiStoreProvider>')
+
+  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,55 @@
+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 inactive. When this store becomes
+     * inactive, it will be garbage collected after this duration.
+     *
+     * Stores transition to the inactive state as soon as they have no
+     * subscriptions registered, so when all components which use that
+     * store have unmounted.
+     *
+     * @remarks
+     * - When different `gcTime` config are used for the same store, the longest one will be used.
+     * - If set to `Infinity`, will disable garbage collection
+     * - 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.
+     */
+    gcTime?: number
+  }

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

@@ -0,0 +1,30 @@
+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(() => storeRegistry.getOrLoad(options), [storeRegistry, options])
+
+  const storeOrPromise = React.useSyncExternalStore(subscribe, getSnapshot)
+
+  const loadedStore = storeOrPromise instanceof Promise ? React.use(storeOrPromise) : storeOrPromise
+
+  return withReactApi(loadedStore)
+}

package/src/useClientDocument.test.tsx

@@ -10,9 +10,9 @@ import * as ReactTesting from '@testing-library/react'
 import type React from 'react'
 import { beforeEach, expect, it } from 'vitest'
 
-import { events, makeTodoMvcReact, tables } from './__tests__/fixture.js'
-import type * as LiveStoreReact from './mod.js'
-import { __resetUseRcResourceCache } from './useRcResource.js'
+import { events, makeTodoMvcReact, tables } from './__tests__/fixture.tsx'
+import type * as LiveStoreReact from './mod.ts'
+import { __resetUseRcResourceCache } from './useRcResource.ts'
 
 // const strictMode = process.env.REACT_STRICT_MODE !== undefined
 

package/src/useQuery.test.tsx

@@ -10,8 +10,8 @@ import React from 'react'
 import * as ReactWindow from 'react-window'
 import { expect } from 'vitest'
 
-import { events, makeTodoMvcReact, tables } from './__tests__/fixture.js'
-import { __resetUseRcResourceCache } from './useRcResource.js'
+import { events, makeTodoMvcReact, tables } from './__tests__/fixture.tsx'
+import { __resetUseRcResourceCache } from './useRcResource.ts'
 
 Vitest.describe.each([{ strictMode: true }, { strictMode: false }] as const)(
   'useQuery (strictMode=%s)',

package/src/useRcResource.test.tsx

@@ -2,7 +2,7 @@ import * as ReactTesting from '@testing-library/react'
 import * as React from 'react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
-import { __resetUseRcResourceCache, useRcResource } from './useRcResource.js'
+import { __resetUseRcResourceCache, useRcResource } from './useRcResource.ts'
 
 describe.each([{ strictMode: true }, { strictMode: false }])('useRcResource (strictMode=%s)', ({ strictMode }) => {
   beforeEach(() => {

package/src/useStore.ts

@@ -1,3 +1,4 @@
+import type { LiveStoreSchema } from '@livestore/common/schema'
 import type { Store } from '@livestore/livestore'
 import React from 'react'
 
@@ -6,14 +7,14 @@ import { LiveStoreContext } from './LiveStoreContext.ts'
 import { useClientDocument } from './useClientDocument.ts'
 import { useQuery } from './useQuery.ts'
 
-export const withReactApi = (store: Store): Store & ReactApi => {
+export const withReactApi = <TSchema extends LiveStoreSchema>(store: Store<TSchema>): Store<TSchema> & ReactApi => {
   // @ts-expect-error TODO properly implement this
 
   store.useQuery = (queryable) => useQuery(queryable, { store })
   // @ts-expect-error TODO properly implement this
 
   store.useClientDocument = (table, idOrOptions, options) => useClientDocument(table, idOrOptions, options, { store })
-  return store as Store & ReactApi
+  return store as Store<TSchema> & ReactApi
 }
 
 export const useStore = (options?: { store?: Store }): { store: Store & ReactApi } => {