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

package/src/LiveStoreProvider.test.tsx

@@ -7,9 +7,9 @@ import React from 'react'
 import { unstable_batchedUpdates as batchUpdates } from 'react-dom'
 import { describe, expect, it } from 'vitest'
 
-import { events, schema, tables } from './__tests__/fixture.js'
-import { LiveStoreProvider } from './LiveStoreProvider.js'
-import * as LiveStoreReact from './mod.js'
+import { events, schema, tables } from './__tests__/fixture.tsx'
+import { LiveStoreProvider } from './LiveStoreProvider.tsx'
+import * as LiveStoreReact from './mod.ts'
 
 describe.each([true, false])('LiveStoreProvider (strictMode: %s)', (strictMode) => {
   const WithStrictMode = strictMode ? React.StrictMode : React.Fragment

package/src/LiveStoreProvider.tsx

@@ -28,7 +28,7 @@ import React from 'react'
 
 import { LiveStoreContext } from './LiveStoreContext.ts'
 
-export interface LiveStoreProviderProps {
+export interface LiveStoreProviderProps<TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue> {
   schema: LiveStoreSchema
   /**
    * The `storeId` can be used to isolate multiple stores from each other.
@@ -77,7 +77,8 @@ export interface LiveStoreProviderProps {
    *
    * @default undefined
    */
-  syncPayload?: Schema.JsonValue
+  syncPayloadSchema?: TSyncPayloadSchema
+  syncPayload?: Schema.Schema.Type<TSyncPayloadSchema>
   debug?: {
     instanceId?: string
   }
@@ -108,7 +109,7 @@ const defaultRenderShutdown = (cause: IntentionalShutdownCause | StoreInterrupte
 const defaultRenderLoading = (status: BootStatus) =>
   IS_REACT_NATIVE ? null : <>LiveStore is loading ({status.stage})...</>
 
-export const LiveStoreProvider = ({
+export const LiveStoreProvider = <TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue>({
   renderLoading = defaultRenderLoading,
   renderError = defaultRenderError,
   renderShutdown = defaultRenderShutdown,
@@ -123,8 +124,9 @@ export const LiveStoreProvider = ({
   signal,
   confirmUnsavedChanges = true,
   syncPayload,
+  syncPayloadSchema,
   debug,
-}: LiveStoreProviderProps & React.PropsWithChildren): React.ReactNode => {
+}: LiveStoreProviderProps<TSyncPayloadSchema> & React.PropsWithChildren): React.ReactNode => {
   const storeCtx = useCreateStore({
     storeId,
     schema,
@@ -137,6 +139,7 @@ export const LiveStoreProvider = ({
       disableDevtools,
       signal,
       syncPayload,
+      syncPayloadSchema,
       debug,
     }),
   })
@@ -175,6 +178,7 @@ const useCreateStore = ({
   params,
   confirmUnsavedChanges,
   syncPayload,
+  syncPayloadSchema,
   debug,
 }: CreateStoreOptions<LiveStoreSchema> & {
   signal?: AbortSignal
@@ -211,6 +215,7 @@ const useCreateStore = ({
     params,
     confirmUnsavedChanges,
     syncPayload,
+    syncPayloadSchema,
     debugInstanceId,
   })
 
@@ -239,6 +244,7 @@ const useCreateStore = ({
     params: inputPropsCacheRef.current.params !== params,
     confirmUnsavedChanges: inputPropsCacheRef.current.confirmUnsavedChanges !== confirmUnsavedChanges,
     syncPayload: inputPropsCacheRef.current.syncPayload !== syncPayload,
+    syncPayloadSchema: inputPropsCacheRef.current.syncPayloadSchema !== syncPayloadSchema,
     debugInstanceId: inputPropsCacheRef.current.debugInstanceId !== debugInstanceId,
   }
 
@@ -253,7 +259,8 @@ const useCreateStore = ({
     inputPropChanges.context ||
     inputPropChanges.params ||
     inputPropChanges.confirmUnsavedChanges ||
-    inputPropChanges.syncPayload
+    inputPropChanges.syncPayload ||
+    inputPropChanges.syncPayloadSchema
   ) {
     inputPropsCacheRef.current = {
       schema,
@@ -267,6 +274,7 @@ const useCreateStore = ({
       params,
       confirmUnsavedChanges,
       syncPayload,
+      syncPayloadSchema,
       debugInstanceId,
     }
     if (ctxValueRef.current.componentScope !== undefined && ctxValueRef.current.shutdownDeferred !== undefined) {
@@ -342,6 +350,7 @@ const useCreateStore = ({
             params,
             confirmUnsavedChanges,
             syncPayload,
+            syncPayloadSchema,
           }),
           onBootStatus: (status) => {
             if (ctxValueRef.current.value.stage === 'running' || ctxValueRef.current.value.stage === 'error') return
@@ -405,6 +414,7 @@ const useCreateStore = ({
     params,
     confirmUnsavedChanges,
     syncPayload,
+    syncPayloadSchema,
     debugInstanceId,
     interrupt,
   ])

package/src/__tests__/fixture.tsx

@@ -8,7 +8,7 @@ import { Effect, Schema, type Scope } from '@livestore/utils/effect'
 import type * as otel from '@opentelemetry/api'
 import React from 'react'
 
-import * as LiveStoreReact from '../mod.js'
+import * as LiveStoreReact from '../mod.ts'
 
 export type Todo = {
   id: string

package/src/experimental/components/LiveList.tsx

@@ -2,7 +2,7 @@ import type { LiveQueryDef } from '@livestore/livestore'
 import { computed } from '@livestore/livestore'
 import React from 'react'
 
-import { useQuery } from '../../useQuery.js'
+import { useQuery } from '../../useQuery.ts'
 
 /*
 TODO:

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

@@ -1,48 +1,78 @@
 import type { LiveStoreSchema } from '@livestore/common/schema'
 import { createStorePromise, type Store, type Unsubscribe } from '@livestore/livestore'
-import { noop } from '@livestore/utils'
 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, error, and in-flight promise along with subscribers.
+ * 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' }
+
   /**
-   * The resolved store.
-   *
-   * @remarks
-   * A value of `undefined` indicates "not loaded yet".
+   * Set of subscriber callbacks to notify on state changes.
    */
-  store: Store<TSchema> | undefined = undefined
+  #subscribers = new Set<() => void>()
 
   /**
-   * The most recent error encountered for this entry, if any.
+   * The number of active subscribers for this entry.
    */
-  error: unknown = undefined
+  get subscriberCount() {
+    return this.#subscribers.size
+  }
 
   /**
-   * The in-flight promise for loading the store, or `undefined` if not yet loading or already resolved.
+   * Transitions to the loading state.
    */
-  promise: Promise<Store<TSchema>> | undefined = undefined
+  #setPromise(promise: Promise<Store<TSchema>>): void {
+    if (this.#state.status === 'success' || this.#state.status === 'loading') return
+    this.#state = { status: 'loading', promise }
+    this.#notify()
+  }
 
   /**
-   * Set of subscriber callbacks to notify on state changes.
+   * Transitions to the success state.
    */
-  #subscribers = new Set<() => void>()
+  #setStore = (store: Store<TSchema>): void => {
+    this.#state = { status: 'success', store }
+    this.#notify()
+  }
 
   /**
-   * Monotonic counter that increments on every notify.
+   * Transitions to the error state.
    */
-  version = 0
+  #setError = (error: unknown): void => {
+    this.#state = { status: 'error', error }
+    this.#notify()
+  }
+
+  #reset = (): void => {
+    this.#state = { status: 'idle' }
+    this.#notify()
+  }
 
   /**
-   * The number of active subscribers for this entry.
+   * Notifies all subscribers of state changes.
+   *
+   * @remarks
+   * This should be called after any meaningful state change.
    */
-  get subscriberCount() {
-    return this.#subscribers.size
+  #notify = (): void => {
+    for (const sub of this.#subscribers) {
+      try {
+        sub()
+      } catch {
+        // Swallow to protect other listeners
+      }
+    }
   }
 
   /**
@@ -59,33 +89,42 @@ class StoreEntry<TSchema extends LiveStoreSchema = LiveStoreSchema> {
   }
 
   /**
-   * Notifies all subscribers and increments the version counter.
+   * 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 should be called after any meaningful state change.
+   * 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
    */
-  notify = (): void => {
-    this.version++
-    for (const sub of this.#subscribers) {
-      try {
-        sub()
-      } catch {
-        // Swallow to protect other listeners
-      }
-    }
-  }
+  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)
 
-  setStore = (store: Store<TSchema>): void => {
-    this.store = store
-    this.error = undefined
-    this.promise = undefined
-    this.notify()
+    return promise
   }
 
-  setError = (error: unknown): void => {
-    this.error = error
-    this.promise = undefined
-    this.notify()
+  shutdown = async (): Promise<void> => {
+    if (this.#state.status !== 'success') return
+    await this.#state.store.shutdownPromise()
+
+    this.#reset()
   }
 }
 
@@ -104,7 +143,7 @@ class StoreCache {
     return this.#entries.get(storeId) as StoreEntry<TSchema> | undefined
   }
 
-  getOrCreate = <TSchema extends LiveStoreSchema>(storeId: StoreId): StoreEntry<TSchema> => {
+  ensure = <TSchema extends LiveStoreSchema>(storeId: StoreId): StoreEntry<TSchema> => {
     let entry = this.#entries.get(storeId) as StoreEntry<TSchema> | undefined
 
     if (!entry) {
@@ -116,29 +155,18 @@ class StoreCache {
   }
 
   /**
-   * Removes an entry from the cache and notifies its subscribers.
+   * Removes an entry from the cache.
    *
    * @param storeId - The ID of the store to remove
+   *
    * @remarks
-   * Notifying subscribers prompts consumers to re-render and re-read as needed.
+   * - 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)
-    // Notify any subscribers of the removal to force re-render;
-    // components will resubscribe to a new entry and re-read.
-    try {
-      entry.notify()
-    } catch {
-      // Best-effort notify; swallowing to avoid crashing removal flows.
-    }
-  }
-
-  clear = (): void => {
-    for (const storeId of Array.from(this.#entries.keys())) {
-      this.remove(storeId)
-    }
   }
 }
 
@@ -187,112 +215,59 @@ export class StoreRegistry {
     this.#defaultOptions = defaultOptions
   }
 
-  /**
-   * Ensures a store entry exists in the cache.
-   *
-   * @param storeId - The ID of the store
-   * @returns The existing or newly created store entry
-   *
-   * @internal
-   */
-  ensureStoreEntry = <TSchema extends LiveStoreSchema>(storeId: StoreId): StoreEntry<TSchema> => {
-    return this.#cache.getOrCreate<TSchema>(storeId)
-  }
-
-  /**
-   * Resolves a store instance for imperative code paths.
-   *
-   * @typeParam TSchema - Schema associated with the requested store.
-   * @returns A promise that resolves with the ready store or rejects with the loading error.
-   *
-   * @remarks
-   * - If the store is already cached, the returned promise resolves immediately with that instance.
-   * - Concurrent callers share the same in-flight request to avoid duplicate store creation.
-   */
-  load = async <TSchema extends LiveStoreSchema>(options: CachedStoreOptions<TSchema>): Promise<Store<TSchema>> => {
-    const optionsWithDefaults = this.#applyDefaultOptions(options)
-    const entry = this.ensureStoreEntry<TSchema>(optionsWithDefaults.storeId)
-
-    // If already loaded, return it
-    if (entry.store) return entry.store
-
-    // If a load is already in flight, return its promise
-    if (entry.promise) return entry.promise
-
-    // If a previous error exists, throw it
-    if (entry.error !== undefined) throw entry.error
-
-    // Load store if none is in flight
-    entry.promise = createStorePromise(optionsWithDefaults)
-      .then((store) => {
-        entry.setStore(store)
-
-        // If no one subscribed (e.g., initial render aborted), schedule GC.
-        if (entry.subscriberCount === 0) this.#scheduleGC(optionsWithDefaults.storeId)
-
-        return store
-      })
-      .catch((error) => {
-        entry.setError(error)
-
-        // Likewise, ensure unused entries are eventually collected.
-        if (entry.subscriberCount === 0) this.#scheduleGC(optionsWithDefaults.storeId)
+  #applyDefaultOptions = <TSchema extends LiveStoreSchema>(
+    options: CachedStoreOptions<TSchema>,
+  ): CachedStoreOptions<TSchema> => ({
+    ...this.#defaultOptions,
+    ...options,
+  })
 
-        throw error
-      })
+  #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)
+  }
 
-    return entry.promise
+  #cancelGC = (id: StoreId): void => {
+    const t = this.#gcTimeouts.get(id)
+    if (t) {
+      clearTimeout(t)
+      this.#gcTimeouts.delete(id)
+    }
   }
 
   /**
-   * Reads a store, returning it directly if loaded or a promise if loading.
-   * Designed to work with React.use() for Suspense integration.
+   * 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 to integrate with React Error Boundaries
+   * @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
-   * - If the initial render that triggered the fetch never commits, we still schedule GC on settle.
    */
-  read = <TSchema extends LiveStoreSchema>(
+  getOrLoad = <TSchema extends LiveStoreSchema>(
     options: CachedStoreOptions<TSchema>,
   ): Store<TSchema> | Promise<Store<TSchema>> => {
     const optionsWithDefaults = this.#applyDefaultOptions(options)
-    const entry = this.ensureStoreEntry<TSchema>(optionsWithDefaults.storeId)
-
-    // If already loaded, return it directly (not wrapped in Promise)
-    if (entry.store) return entry.store
+    const entry = this.#cache.ensure<TSchema>(optionsWithDefaults.storeId)
 
-    // If a previous error exists, throw it
-    if (entry.error !== undefined) throw entry.error
+    const storeOrPromise = entry.getOrLoad(optionsWithDefaults)
 
-    // If a load is already in flight, return the existing promise
-    if (entry.promise) return entry.promise
-
-    // Load store if none is in flight
-    entry.promise = createStorePromise(optionsWithDefaults)
-      .then((store) => {
-        entry.setStore(store)
-
-        // If no one subscribed (e.g., initial render aborted), schedule GC.
+    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 store
-      })
-      .catch((error) => {
-        entry.setError(error)
-
-        // Likewise, ensure unused entries are eventually collected.
-        if (entry.subscriberCount === 0) this.#scheduleGC(optionsWithDefaults.storeId)
-
-        throw error
       })
+    }
 
-    return entry.promise
+    return storeOrPromise
   }
 
   /**
@@ -306,11 +281,15 @@ export class StoreRegistry {
    * - If the entry remains unused after preload resolves/rejects, it is scheduled for GC.
    */
   preload = async <TSchema extends LiveStoreSchema>(options: CachedStoreOptions<TSchema>): Promise<void> => {
-    return this.load(options).then(noop).catch(noop)
+    try {
+      await this.getOrLoad(options)
+    } catch {
+      // Do nothing; preload is best-effort
+    }
   }
 
   subscribe = <TSchema extends LiveStoreSchema>(storeId: StoreId, listener: () => void): Unsubscribe => {
-    const entry = this.ensureStoreEntry<TSchema>(storeId)
+    const entry = this.#cache.ensure<TSchema>(storeId)
     // Active subscriber: cancel any scheduled GC
     this.#cancelGC(storeId)
 
@@ -319,38 +298,7 @@ export class StoreRegistry {
     return () => {
       unsubscribe()
       // If no more subscribers remain, schedule GC
-      if (entry.subscriberCount === 0) {
-        this.#scheduleGC(storeId)
-      }
-    }
-  }
-
-  getVersion = <TSchema extends LiveStoreSchema>(storeId: StoreId): number => {
-    const entry = this.ensureStoreEntry<TSchema>(storeId)
-    return entry.version
-  }
-
-  #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)
+      if (entry.subscriberCount === 0) this.#scheduleGC(storeId)
     }
   }
 }

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

@@ -1,5 +1,5 @@
 import * as React from 'react'
-import type { StoreRegistry } from './StoreRegistry.js'
+import type { StoreRegistry } from './StoreRegistry.ts'
 
 export const StoreRegistryContext = React.createContext<StoreRegistry | undefined>(undefined)
 

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

@@ -16,23 +16,14 @@ export const useStore = <TSchema extends LiveStoreSchema>(
 ): Store<TSchema> & ReactApi => {
   const storeRegistry = useStoreRegistry()
 
-  storeRegistry.ensureStoreEntry(options.storeId)
-
   const subscribe = React.useCallback(
     (onChange: () => void) => storeRegistry.subscribe(options.storeId, onChange),
     [storeRegistry, options.storeId],
   )
-  const getSnapshot = React.useCallback(
-    () => storeRegistry.getVersion(options.storeId),
-    [storeRegistry, options.storeId],
-  )
-
-  React.useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+  const getSnapshot = React.useCallback(() => storeRegistry.getOrLoad(options), [storeRegistry, options])
 
-  const storeOrPromise = storeRegistry.read(options)
+  const storeOrPromise = React.useSyncExternalStore(subscribe, getSnapshot)
 
-  // If read() returns a Promise, use React.use() to suspend
-  // If it returns a Store directly, use it immediately
   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(() => {