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

package/dist/useStore.js

@@ -2,6 +2,19 @@ import React from 'react';
 import { LiveStoreContext } from "./LiveStoreContext.js";
 import { useClientDocument } from "./useClientDocument.js";
 import { useQuery } from "./useQuery.js";
+/**
+ * Augments a Store instance with React-specific methods (`useQuery`, `useClientDocument`).
+ *
+ * This is called automatically by `useStore()` and `LiveStoreProvider`. You typically
+ * don't need to call it directly unless you're building custom integrations.
+ *
+ * @example
+ * ```ts
+ * // Usually not needed—useStore() does this automatically
+ * const store = withReactApi(myStore)
+ * const todos = store.useQuery(tables.todos.all())
+ * ```
+ */
 export const withReactApi = (store) => {
     // @ts-expect-error TODO properly implement this
     store.useQuery = (queryable) => useQuery(queryable, { store });
@@ -9,6 +22,44 @@ export const withReactApi = (store) => {
     store.useClientDocument = (table, idOrOptions, options) => useClientDocument(table, idOrOptions, options, { store });
     return store;
 };
+/**
+ * Returns the current Store instance from React context, augmented with React-specific methods.
+ *
+ * Use this hook when you need direct access to the Store for operations like
+ * `store.commit()`, `store.subscribe()`, or accessing `store.sessionId`.
+ *
+ * For reactive queries, prefer `useQuery()` or `useClientDocument()` which handle
+ * subscriptions and re-renders automatically.
+ *
+ * @example
+ * ```ts
+ * const MyComponent = () => {
+ *   const { store } = useStore()
+ *
+ *   const handleClick = () => {
+ *     store.commit(events.todoCreated({ id: nanoid(), text: 'New todo' }))
+ *   }
+ *
+ *   return <button onClick={handleClick}>Add Todo</button>
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Access store metadata
+ * const { store } = useStore()
+ * console.log('Session ID:', store.sessionId)
+ * console.log('Client ID:', store.clientId)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Use with an explicit store instance (bypasses context)
+ * const { store } = useStore({ store: myExternalStore })
+ * ```
+ *
+ * @throws Error if called outside of `<LiveStoreProvider>` or before the store is running
+ */
 export const useStore = (options) => {
     if (options?.store !== undefined) {
         return { store: withReactApi(options.store) };

package/dist/useStore.js.map

@@ -1 +1 @@
-{"version":3,"file":"useStore.js","sourceRoot":"","sources":["../src/useStore.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,OAAO,CAAA;AAGzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC,MAAM,CAAC,MAAM,YAAY,GAAG,CAAkC,KAAqB,EAA6B,EAAE;IAChH,gDAAgD;IAEhD,KAAK,CAAC,QAAQ,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;IAC9D,gDAAgD;IAEhD,KAAK,CAAC,iBAAiB,GAAG,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;IACpH,OAAO,KAAkC,CAAA;AAC3C,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,OAA2B,EAA+B,EAAE;IACnF,IAAI,OAAO,EAAE,KAAK,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAA;IAC/C,CAAC;IAED,mEAAmE;IACnE,MAAM,YAAY,GAAG,KAAK,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAA;IAEvD,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAA;IAC3E,CAAC;IAED,IAAI,YAAY,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAA;IACzE,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAA;AACpD,CAAC,CAAA"}
+{"version":3,"file":"useStore.js","sourceRoot":"","sources":["../src/useStore.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,OAAO,CAAA;AAGzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAkC,KAAqB,EAA6B,EAAE;IAChH,gDAAgD;IAEhD,KAAK,CAAC,QAAQ,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,QAAQ,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;IAC9D,gDAAgD;IAEhD,KAAK,CAAC,iBAAiB,GAAG,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;IACpH,OAAO,KAAkC,CAAA;AAC3C,CAAC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,OAA2B,EAA+B,EAAE;IACnF,IAAI,OAAO,EAAE,KAAK,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAA;IAC/C,CAAC;IAED,mEAAmE;IACnE,MAAM,YAAY,GAAG,KAAK,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAA;IAEvD,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAA;IAC3E,CAAC;IAED,IAAI,YAAY,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAA;IACzE,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAA;AACpD,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livestore/react",
-  "version": "0.4.0-dev.20",
+  "version": "0.4.0-dev.21",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -9,9 +9,9 @@
   },
   "dependencies": {
     "@opentelemetry/api": "1.9.0",
-    "@livestore/common": "0.4.0-dev.20",
-    "@livestore/livestore": "0.4.0-dev.20",
-    "@livestore/utils": "0.4.0-dev.20"
+    "@livestore/common": "0.4.0-dev.21",
+    "@livestore/utils": "0.4.0-dev.21",
+    "@livestore/livestore": "0.4.0-dev.21"
   },
   "devDependencies": {
     "@opentelemetry/sdk-trace-base": "2.0.1",
@@ -26,8 +26,8 @@
     "typescript": "5.9.2",
     "vite": "7.2.4",
     "vitest": "3.2.4",
-    "@livestore/utils-dev": "0.4.0-dev.20",
-    "@livestore/adapter-web": "0.4.0-dev.20"
+    "@livestore/adapter-web": "0.4.0-dev.21",
+    "@livestore/utils-dev": "0.4.0-dev.21"
   },
   "files": [
     "package.json",

package/src/LiveStoreContext.ts

@@ -4,11 +4,38 @@ import React from 'react'
 import type { useClientDocument } from './useClientDocument.ts'
 import type { useQuery } from './useQuery.ts'
 
+/**
+ * React-specific methods added to the Store when used via React hooks.
+ *
+ * These methods are attached by `withReactApi()` and `useStore()`, allowing you
+ * to call `store.useQuery()` and `store.useClientDocument()` directly on the
+ * Store instance.
+ */
 export type ReactApi = {
+  /** Hook version of query subscription—re-renders component when query result changes */
   useQuery: typeof useQuery
+  /** Hook for reading and writing client-document tables with React state semantics */
   useClientDocument: typeof useClientDocument
 }
 
+/**
+ * React context for accessing the LiveStore instance.
+ *
+ * This context is provided by `<LiveStoreProvider>` and consumed by hooks like
+ * `useStore()`, `useQuery()`, and `useClientDocument()`.
+ *
+ * The context value is `undefined` until the Store has finished booting,
+ * then transitions to `{ stage: 'running', store: ... }`.
+ *
+ * @example
+ * ```tsx
+ * // Typically you don't use this directly—use useStore() instead
+ * const context = React.useContext(LiveStoreContext)
+ * if (context?.stage === 'running') {
+ *   console.log('Store ready:', context.store.storeId)
+ * }
+ * ```
+ */
 export const LiveStoreContext = React.createContext<
   { stage: 'running'; store: LiveStoreContextRunning['store'] & ReactApi } | undefined
 >(undefined)

package/src/LiveStoreProvider.tsx

@@ -62,6 +62,13 @@ export interface LiveStoreProviderProps<TSyncPayloadSchema extends Schema.Schema
    * @default true
    */
   confirmUnsavedChanges?: boolean
+  /**
+   * Advanced store parameters forwarded to `createStore`.
+   * Currently supports:
+   * - `leaderPushBatchSize`: max events pushed to the leader per write batch.
+   * - `eventQueryBatchSize`: chunk size used when the stream replays confirmed events.
+   */
+  params?: CreateStoreOptions<LiveStoreSchema>['params']
   /**
    * Payload that will be passed to the sync backend when connecting
    *
@@ -113,6 +120,7 @@ export const LiveStoreProvider = <TSyncPayloadSchema extends Schema.Schema<any>
   disableDevtools,
   signal,
   confirmUnsavedChanges = true,
+  params,
   syncPayload,
   syncPayloadSchema,
   debug,
@@ -129,6 +137,7 @@ export const LiveStoreProvider = <TSyncPayloadSchema extends Schema.Schema<any>
       otelOptions,
       boot,
       disableDevtools,
+      params,
       signal,
       syncPayload,
       syncPayloadSchema,