@livequery/react 2.0.133 → 2.0.135

package/README.md

@@ -2,18 +2,7 @@
 
 Thin React bindings for `@livequery/client`.
 
-This repository is the React bindings library package, not an application. Changes here should preserve reusable hook behavior unless a task explicitly targets a breaking change.
-
-This package provides a small set of hooks and helpers for wiring a `LivequeryClient` instance into a React app, subscribing to RxJS streams, and reading collection or document state from `@livequery/client`.
-
-## AI Agent Guidance
-
-Repository-specific agent guidance lives in `AGENTS.md` and `copilot-instructions.md`.
-
-- `AGENTS.md` is the implementation-focused guide for coding agents modifying this package.
-- `copilot-instructions.md` provides repo-level instructions for Copilot when generating or reviewing code in this workspace.
-- Both documents assume this repo is a React bindings library package, so agent changes should avoid app-specific scaffolding and should preserve public API compatibility by default.
-- Agents generating consumer code should create one shared `LivequeryClient`, provide it through `LivequeryClientProvider`, and subscribe to collection state with `useObservable()`.
+This package is a small integration layer. It does not implement transport, storage, caching, or query behavior itself. Those responsibilities stay in `@livequery/client`; this package gives React components a clean way to access a shared `LivequeryClient`, create `LivequeryCollection` instances, and mirror RxJS streams into render state.
 
 ## Install
 
@@ -34,12 +23,12 @@ npm install @livequery/react @livequery/client react rxjs
 - `useCollection`
 - `useDocument`
 - `useObservable`
-- `useGlobalValue`
+- `useAction`
 - `createContextFromHook`
 
-## Core setup
+## Recommended App Shape
 
-`useCollection` and `useDocument` read the active `LivequeryClient` instance from `LivequeryClientProvider`.
+Create one `LivequeryClient` for your app or data boundary, provide it once, then use hooks inside descendant components.
 
 ```tsx
 import { LivequeryClient } from '@livequery/client'
@@ -51,18 +40,58 @@ const client = new LivequeryClient({
 
 export function AppProviders({ children }: { children: React.ReactNode }) {
   return (
-    <LivequeryClientProvider client={client}>
+    <LivequeryClientProvider core={client}>
       {children}
     </LivequeryClientProvider>
   )
 }
 ```
 
-## useCollection
+Use collection methods from effects or event handlers, not during render. Use `useObservable()` to subscribe to reactive fields before rendering their values.
+
+## `LivequeryClientProvider`
+
+`LivequeryClientProvider` makes a shared `LivequeryClient` available to `useCollection()` and any component that calls `useLivequeryClient()`.
+
+Use it when:
+
+- an app has one shared Livequery connection
+- a route, workspace, tenant, or feature boundary needs its own client
+- hooks below the boundary should avoid receiving the client as a prop
+
+```tsx
+<LivequeryClientProvider core={client}>
+  <TodoList />
+</LivequeryClientProvider>
+```
+
+The provider currently expects a `core` prop. Passing `client` will not work unless the implementation is changed.
+
+## `useLivequeryClient`
+
+`useLivequeryClient()` reads the nearest `LivequeryClient` from `LivequeryClientProvider`.
+
+Use it when you need direct access to the shared client, usually for setup code or integration with APIs that are not covered by `useCollection()`.
+
+```tsx
+import { useLivequeryClient } from '@livequery/react'
+
+export function ClientStatus() {
+  const client = useLivequeryClient()
+  return <span>{client ? 'Connected' : 'Missing client'}</span>
+}
+```
+
+The hook must be used under a matching provider. If it is called outside the provider tree, the generated context hook throws `Context provider is missing`.
 
-`useCollection` creates a `LivequeryCollection`, initializes it when `ref` is available, and returns the collection instance.
+## `useCollection`
+
+`useCollection<T>(ref, options)` creates one `LivequeryCollection<T>` for the component, initializes it when `ref` is truthy, and returns the collection instance.
+
+Use it when a component needs the full collection API: reactive state plus methods such as querying or mutations.
 
 ```tsx
+import { useEffect } from 'react'
 import { useCollection, useObservable } from '@livequery/react'
 
 type Todo = {
@@ -75,8 +104,14 @@ export function TodoList() {
   const collection = useCollection<Todo>('todos', { lazy: false })
   const items = useObservable(collection.items, [])
   const loading = useObservable(collection.loading, false)
+  const error = useObservable(collection.error)
+
+  useEffect(() => {
+    collection.query()
+  }, [collection])
 
   if (loading) return <p>Loading...</p>
+  if (error) return <p>Could not load todos.</p>
 
   return (
     <ul>
@@ -88,15 +123,21 @@ export function TodoList() {
 }
 ```
 
-Notes:
+Behavior notes:
 
-- `ref` can be falsy. In that case initialization is skipped.
+- `ref` may be `undefined`, `null`, `false`, or an empty string. Falsy refs skip initialization.
 - The same hook call keeps one collection instance for the lifetime of the component.
-- To render stream values, subscribe with `useObservable`.
+- `options` are used when that collection instance is first created. Pass stable options, or remount the hook if options need to change.
+- Subscribe to fields such as `collection.items`, `collection.loading`, and `collection.error` with `useObservable()`.
+- Do not call `query()`, `add()`, `update()`, or `delete()` directly during render.
+
+## `useDocument`
 
-## useDocument
+`useDocument<T>(ref, options)` is a document-focused convenience wrapper over `useCollection()`.
 
-`useDocument` is a small convenience wrapper built on top of `LivequeryCollection`. It initializes a collection for a single document path and returns `[document, loading]`.
+It initializes a collection for a document ref, subscribes to collection items and loading state, then returns `[items[0], loading]`.
+
+Use it when a component only needs one document and a loading flag.
 
 ```tsx
 import { useDocument } from '@livequery/react'
@@ -117,9 +158,13 @@ export function TodoDetail({ id }: { id: string }) {
 }
 ```
 
-## useObservable
+Use `useCollection()` instead when you need collection methods, error state, multiple documents, or more control over subscriptions.
+
+## `useObservable`
+
+`useObservable()` bridges an RxJS `Observable` or `BehaviorSubject` into React state.
 
-`useObservable` bridges an RxJS `Observable` or `BehaviorSubject` into React state.
+Use it for any reactive value that should cause a component rerender when it emits.
 
 ```tsx
 import { BehaviorSubject } from 'rxjs'
@@ -133,65 +178,58 @@ export function Counter() {
 }
 ```
 
-You can also pass a function when the observable should be resolved lazily.
-
-## useGlobalValue
-
-`useGlobalValue` stores a lazily created singleton on `globalThis`. This is useful when an app should reuse one object across renders or across multiple React roots in the same runtime.
+Supported shapes:
 
 ```tsx
-import { LivequeryClient } from '@livequery/client'
-import { useGlobalValue } from '@livequery/react'
-
-export function useAppClient() {
-  return useGlobalValue('livequery-client', () => {
-    return new LivequeryClient({
-      endpoint: 'https://your-livequery-server'
-    })
-  })
-}
+const value = useObservable(source$)
+const valueWithDefault = useObservable(source$, defaultValue)
+const lazyValue = useObservable(() => source$)
 ```
 
-## createContextFromHook
-
-`createContextFromHook` is the most distinctive helper in this package. It lets you define shared state once at the provider boundary, but consume it later with an API that still feels like a normal hook.
+Behavior notes:
 
-In practice, it turns this idea:
+- `BehaviorSubject` is treated specially. Its initial value is read with `getValue()` so the first render can use the current value.
+- Lazy sources are resolved once for the hook lifetime.
+- If the source is `undefined`, the hook returns the default value, or `undefined` if no default was provided.
+- Reading `.value` or `.getValue()` manually in render is not a replacement for `useObservable()` because it will not subscribe the component to future emissions.
 
-- "I have some setup logic that depends on provider props"
-- "I want descendants to read the computed result through a hook"
+## `useAction`
 
-into a reusable pattern.
+`useAction(fn, options)` wraps an async function and attaches action state to the returned callable.
 
-The helper takes one function `fn(props) => value` and returns a tuple:
+Use it for button clicks, form submissions, and other event-driven async work where the UI needs `loading`, `data`, or `error`.
 
-- `useValue`: reads the current context value
-- `Provider`: receives props, calls `fn(props)`, and stores the result in context
-
-That means consumers do not need to know about `React.createContext`, context objects, or provider value wiring. They only call a hook.
-
-### Why this helper is useful
-
-Compared to creating context by hand, `createContextFromHook` removes the repetitive parts:
+```tsx
+import { useAction } from '@livequery/react'
 
-- creating the context object
-- writing a custom consumer hook
-- writing a provider that computes and passes `value`
+export function SaveButton({ save }: { save: () => Promise<{ id: string }> }) {
+  const saveAction = useAction(save, {
+    onError(error) {
+      console.error(error)
+    }
+  })
 
-It is especially useful when you want an API that reads like a hook-based service locator, but stays explicit through React providers.
+  return (
+    <button disabled={saveAction.loading} onClick={() => void saveAction()}>
+      {saveAction.loading ? 'Saving...' : 'Save'}
+    </button>
+  )
+}
+```
 
-The `LivequeryClientProvider` and `useLivequeryClient` pair in this package is built from this helper.
+The returned function has these state fields:
 
-### Mental model
+- `loading`: `true` while the latest call is pending
+- `data`: resolved data from the latest successful call
+- `error`: normalized `{ code, message }` from the latest failed call
 
-You can think of it as turning a factory into two coordinated pieces:
+If multiple calls overlap, only the latest call is allowed to update state. Earlier calls still resolve or reject normally, but they will not overwrite the visible action state after a newer call has started.
 
-1. A provider-side adapter: `Provider(props)` computes a value from props.
-2. A consumer-side hook: `useValue()` reads that computed value from the nearest provider.
+## `createContextFromHook`
 
-So instead of manually writing both pieces every time, you derive them from one source function.
+`createContextFromHook(fn)` derives a provider and a consumer hook from one factory function.
 
-### Example
+Use it when a value should be computed at a provider boundary and consumed through a hook.
 
 ```tsx
 import { createContextFromHook } from '@livequery/react'
@@ -214,42 +252,58 @@ function App() {
 }
 ```
 
-### What happens internally
+The helper returns:
 
-The generated provider receives props plus `children`, calls your factory with those props, and pushes the returned value into a private React context.
+- `useValue`: reads the current context value
+- `Provider`: receives props, calls `fn(props)`, and stores the returned value in context
 
-The generated hook simply reads that context and returns the value as type `R`.
+Behavior notes:
 
-This is why the consumer side feels like a plain hook even though the data flow is still standard React context under the hood.
+- The provider calls `fn(props)` on every provider render.
+- `createContextFromHook()` does not memoize the returned value. Memoize inside `fn` or stabilize provider props if recomputation matters.
+- The generated hook throws `Context provider is missing` when consumed outside its provider.
 
-### Good use cases
+`LivequeryClientProvider` and `useLivequeryClient` are built with this helper.
 
-- exposing a configured client instance such as `LivequeryClient`
-- deriving session or auth state from provider props
-- wrapping feature-specific state that should be consumed through a single custom hook
-- hiding context implementation details from package consumers
+## Choosing The Right API
 
-### Important behavior notes
+- Use `LivequeryClientProvider` once near the app or data boundary.
+- Use `useLivequeryClient()` only when you need direct client access.
+- Use `useCollection()` when you need collection methods or multiple reactive collection fields.
+- Use `useDocument()` when you only need the first document and loading state.
+- Use `useObservable()` whenever an RxJS source should drive rendering.
+- Use `useAction()` for async event handlers that need loading, data, and error state.
+- Use `createContextFromHook()` for package or app utilities that should expose provider plus hook pairs.
 
-- The provider recomputes the value on every render because it directly calls `fn(props)`.
-- The consumer hook assumes a provider exists. In the current implementation it casts the context value to `R`, so using the hook outside its provider can result in `undefined` flowing through at runtime.
-- `createContextFromHook` does not add memoization by itself. If `fn(props)` is expensive, memoize inside `fn` or stabilize the incoming props.
+## Common Mistakes
 
-### Relationship to plain context
+- Creating a new `LivequeryClient` inside a component render.
+- Calling collection mutations directly during render.
+- Reading `BehaviorSubject` values manually and expecting rerenders.
+- Passing changing `useCollection()` options and expecting the existing collection instance to rebuild.
+- Using `useDocument()` when you need error state or collection methods.
+- Importing APIs not listed in the `Exports` section.
 
-If you wrote this manually, the shape would be:
+## Build
 
-1. create a context
-2. write `useX()` that calls `useContext`
-3. write `XProvider` that computes a value from props
-4. pass that value to the provider
+```bash
+bun run build
+```
 
-`createContextFromHook` compresses those four steps into one helper and keeps the consuming API ergonomic.
+Build output is published from `dist/` and exposed through the package `exports` field.
 
-## Build
+## Test
 
 ```bash
-bun run build
+bun test
 ```
 
-Build output is published from `dist/` and exposed through the package `exports` field.
+The current test suite covers the React hook behavior that is most sensitive to regressions: observable subscriptions, lazy observable sources, generated context hooks, and async action race handling.
+
+## Agent Guidance
+
+Repository-specific coding-agent guidance lives in `AGENTS.md`, `AGENT_API_GUIDE.md`, and `copilot-instructions.md`.
+
+- `README.md` is end-user documentation.
+- `AGENTS.md` is the implementation-focused entry point for coding agents.
+- `AGENT_API_GUIDE.md` explains how agents should choose and use each public API when generating code or modifying this package.

package/dist/createContextFromHook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createContextFromHook.d.ts","sourceRoot":"","sources":["../src/createContextFromHook.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,GAAG,EAAE,KAAK,iBAAiB,EAAE,MAAM,OAAO,CAAA;AAGnF,eAAO,MAAM,qBAAqB,GAAI,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,KAczC,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,OAAO,CACzF,CAAA"}
+{"version":3,"file":"createContextFromHook.d.ts","sourceRoot":"","sources":["../src/createContextFromHook.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,GAAG,EAAE,KAAK,iBAAiB,EAAE,MAAM,OAAO,CAAA;AAGnF,eAAO,MAAM,qBAAqB,GAAI,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,KAkBzC,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,OAAO,CACzF,CAAA"}

package/dist/createContextFromHook.js

@@ -3,7 +3,11 @@ import { createContext, useContext } from "react";
 export const createContextFromHook = (fn) => {
     const ctx = createContext(undefined);
     const useState = () => {
-        return useContext(ctx);
+        const value = useContext(ctx);
+        if (value === undefined) {
+            throw new Error('Context provider is missing');
+        }
+        return value;
     };
     const Provider = ({ children, ...props }) => {
         const value = fn(props);

package/dist/createContextFromHook.js.map

@@ -1 +1 @@
-{"version":3,"file":"createContextFromHook.js","sourceRoot":"","sources":["../src/createContextFromHook.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAoC,MAAM,OAAO,CAAA;AAGnF,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAO,EAAiC,EAAE,EAAE;IAC7E,MAAM,GAAG,GAAG,aAAa,CAAgB,SAAS,CAAC,CAAA;IAEnD,MAAM,QAAQ,GAAG,GAAG,EAAE;QAClB,OAAO,UAAU,CAAC,GAAG,CAAM,CAAA;IAC/B,CAAC,CAAA;IACD,MAAM,QAAQ,GAAG,CAAC,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAwB,EAAE,EAAE;QAC9D,MAAM,KAAK,GAAG,EAAE,CAAC,KAAU,CAAC,CAAA;QAC5B,OAAO,CACH,KAAC,GAAG,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YACrB,QAAQ,GACE,CAClB,CAAA;IACL,CAAC,CAAA;IACD,OAAO,CAAC,QAAQ,EAAE,QAAQ,EAA6D,CAAA;AAC3F,CAAC,CAAA"}
+{"version":3,"file":"createContextFromHook.js","sourceRoot":"","sources":["../src/createContextFromHook.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAoC,MAAM,OAAO,CAAA;AAGnF,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAO,EAAiC,EAAE,EAAE;IAC7E,MAAM,GAAG,GAAG,aAAa,CAAgB,SAAS,CAAC,CAAA;IAEnD,MAAM,QAAQ,GAAG,GAAG,EAAE;QAClB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAA;QAC7B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAA;QAClD,CAAC;QACD,OAAO,KAAK,CAAA;IAChB,CAAC,CAAA;IACD,MAAM,QAAQ,GAAG,CAAC,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAwB,EAAE,EAAE;QAC9D,MAAM,KAAK,GAAG,EAAE,CAAC,KAAU,CAAC,CAAA;QAC5B,OAAO,CACH,KAAC,GAAG,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YACrB,QAAQ,GACE,CAClB,CAAA;IACL,CAAC,CAAA;IACD,OAAO,CAAC,QAAQ,EAAE,QAAQ,EAA6D,CAAA;AAC3F,CAAC,CAAA"}

package/dist/useAction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useAction.d.ts","sourceRoot":"","sources":["../src/useAction.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,EAAE,UAAS,OAAO,CAAC;IAAE,OAAO,EAAE,QAAQ,CAAA;CAAE,CAAM;aAExG,OAAO;WACT,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YACrB;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;CAehD,CAAA"}
+{"version":3,"file":"useAction.d.ts","sourceRoot":"","sources":["../src/useAction.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,EAAE,UAAS,OAAO,CAAC;IAAE,OAAO,EAAE,QAAQ,CAAA;CAAE,CAAM;aAGxG,OAAO;WACT,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YACrB;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;CAoBhD,CAAA"}

package/dist/useAction.js

@@ -1,16 +1,22 @@
-import { useState } from "react";
+import { useRef, useState } from "react";
 export const useAction = (fn, options = {}) => {
+    const requestId = useRef(0);
     const [state, set_state] = useState({ loading: false });
     const f = async (...args) => {
+        const currentRequestId = ++requestId.current;
         set_state({ loading: true });
         try {
             const data = await fn(...args);
-            set_state({ loading: false, data });
+            if (currentRequestId === requestId.current) {
+                set_state({ loading: false, data });
+            }
             return data;
         }
         catch (error) {
             options.onError?.(error);
-            set_state({ loading: false, error: error instanceof Error ? { code: 'error', message: error.message } : { code: 'error', message: String(error) } });
+            if (currentRequestId === requestId.current) {
+                set_state({ loading: false, error: error instanceof Error ? { code: 'error', message: error.message } : { code: 'error', message: String(error) } });
+            }
         }
     };
     return Object.assign(f, state);

package/dist/useAction.js.map

@@ -1 +1 @@
-{"version":3,"file":"useAction.js","sourceRoot":"","sources":["../src/useAction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAEhC,MAAM,CAAC,MAAM,SAAS,GAAG,CAA6C,EAAK,EAAE,UAA0C,EAAE,EAAE,EAAE;IACzH,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG,QAAQ,CAIhC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAA;IAEtB,MAAM,CAAC,GAAG,KAAK,EAAE,GAAG,IAAS,EAAE,EAAE;QAC7B,SAAS,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAA;QAC5B,IAAI,CAAC;YACD,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,CAAA;YAC9B,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;YACnC,OAAO,IAAI,CAAA;QACf,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAA;YACxB,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAA;QACxJ,CAAC;IACL,CAAC,CAAA;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,CAAM,EAAE,KAAK,CAAC,CAAA;AACvC,CAAC,CAAA"}
+{"version":3,"file":"useAction.js","sourceRoot":"","sources":["../src/useAction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAExC,MAAM,CAAC,MAAM,SAAS,GAAG,CAA6C,EAAK,EAAE,UAA0C,EAAE,EAAE,EAAE;IACzH,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC,CAAA;IAC3B,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG,QAAQ,CAIhC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAA;IAEtB,MAAM,CAAC,GAAG,KAAK,EAAE,GAAG,IAAS,EAAE,EAAE;QAC7B,MAAM,gBAAgB,GAAG,EAAE,SAAS,CAAC,OAAO,CAAA;QAC5C,SAAS,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAA;QAC5B,IAAI,CAAC;YACD,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,CAAA;YAC9B,IAAI,gBAAgB,KAAK,SAAS,CAAC,OAAO,EAAE,CAAC;gBACzC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;YACvC,CAAC;YACD,OAAO,IAAI,CAAA;QACf,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAA;YACxB,IAAI,gBAAgB,KAAK,SAAS,CAAC,OAAO,EAAE,CAAC;gBACzC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAA;YACxJ,CAAC;QACL,CAAC;IACL,CAAC,CAAA;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,CAAM,EAAE,KAAK,CAAC,CAAA;AACvC,CAAC,CAAA"}

package/dist/useObservable.d.ts

@@ -1,6 +1,7 @@
 import { Observable, BehaviorSubject } from "rxjs";
 export type MaybeFunction<T> = T | (() => T);
-type ObservableSource<T> = MaybeFunction<BehaviorSubject<T> | Observable<T>> | undefined;
+type Source<T> = BehaviorSubject<T> | Observable<T>;
+type ObservableSource<T> = MaybeFunction<Source<T>> | undefined;
 export declare function useObservable<T>(o: BehaviorSubject<T>): T;
 export declare function useObservable<T>(o: ObservableSource<T>): T | undefined;
 export declare function useObservable<T>(o: ObservableSource<T>, default_value: T): T;

package/dist/useObservable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useObservable.d.ts","sourceRoot":"","sources":["../src/useObservable.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAc,MAAM,MAAM,CAAC;AAG/D,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAA;AAE5C,KAAK,gBAAgB,CAAC,CAAC,IAAI,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAA;AAExF,wBAAgB,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;AAC1D,wBAAgB,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAAA;AACvE,wBAAgB,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,GAAG,CAAC,CAAA"}
+{"version":3,"file":"useObservable.d.ts","sourceRoot":"","sources":["../src/useObservable.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAO,MAAM,MAAM,CAAC;AAGxD,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAA;AAE5C,KAAK,MAAM,CAAC,CAAC,IAAI,eAAe,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAA;AACnD,KAAK,gBAAgB,CAAC,CAAC,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAA;AAU/D,wBAAgB,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;AAC1D,wBAAgB,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAAA;AACvE,wBAAgB,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,GAAG,CAAC,CAAA"}

package/dist/useObservable.js

@@ -1,22 +1,28 @@
 import { useEffect, useRef, useState } from "react";
-import { Observable, BehaviorSubject, tap, EMPTY } from "rxjs";
+import { Observable, BehaviorSubject, tap } from "rxjs";
 import { skip } from "rxjs/operators";
+const isBehaviorSubject = (source) => {
+    return typeof source?.getValue === 'function';
+};
+const hasPipe = (source) => {
+    return typeof source?.pipe === 'function';
+};
 export function useObservable(o, default_value) {
-    const prev = useRef(o);
-    const source = o || EMPTY;
-    const isBehaviorSubject = typeof o == 'object' && typeof source.getValue === 'function';
-    const dfv = isBehaviorSubject ? source.getValue() : default_value;
-    const [v, s] = useState(dfv);
+    const lazySource = useRef(undefined);
+    const source = typeof o === 'function'
+        ? lazySource.current ?? (lazySource.current = o())
+        : o;
+    const prev = useRef(source);
+    const [v, s] = useState(() => isBehaviorSubject(source) ? source.getValue() : default_value);
     useEffect(() => {
-        const diff = prev.current !== o;
-        prev.current = o;
-        try {
-            const subscription = source.pipe(skip(isBehaviorSubject && !diff ? 1 : 0), tap(s)).subscribe();
-            return () => {
-                subscription.unsubscribe();
-            };
-        }
-        catch (e) { }
+        const diff = prev.current !== source;
+        prev.current = source;
+        if (!hasPipe(source))
+            return;
+        const subscription = source.pipe(skip(isBehaviorSubject(source) && !diff ? 1 : 0), tap(s)).subscribe();
+        return () => {
+            subscription.unsubscribe();
+        };
     }, typeof o === 'function' ? [] : [o]);
     return v;
 }

package/dist/useObservable.js.map

@@ -1 +1 @@
-{"version":3,"file":"useObservable.js","sourceRoot":"","sources":["../src/useObservable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAUtC,MAAM,UAAU,aAAa,CAAI,CAAmB,EAAE,aAAiB;IACnE,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAA;IACtB,MAAM,MAAM,GAAG,CAA8B,IAAI,KAAK,CAAA;IACtD,MAAM,iBAAiB,GAAE,OAAO,CAAC,IAAI,QAAQ,IAAK,OAAO,MAAM,CAAC,QAAQ,KAAK,UAAU,CAAA;IACvF,MAAM,GAAG,GAAG,iBAAiB,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,aAAa,CAAA;IACjE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,QAAQ,CAAgB,GAAG,CAAC,CAAA;IAC3C,SAAS,CAAC,GAAG,EAAE;QACX,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,KAAK,CAAC,CAAA;QAC/B,IAAI,CAAC,OAAO,GAAG,CAAC,CAAA;QAChB,IAAI,CAAC;YACD,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAC5B,IAAI,CAAC,iBAAiB,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EACxC,GAAG,CAAC,CAAC,CAAC,CACT,CAAC,SAAS,EAAE,CAAA;YACb,OAAO,GAAG,EAAE;gBACR,YAAY,CAAC,WAAW,EAAE,CAAA;YAC9B,CAAC,CAAA;QACL,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;IACnB,CAAC,EAAE,OAAO,CAAC,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAEtC,OAAO,CAAC,CAAA;AACZ,CAAC"}
+{"version":3,"file":"useObservable.js","sourceRoot":"","sources":["../src/useObservable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AACxD,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAOtC,MAAM,iBAAiB,GAAG,CAAI,MAA6B,EAAgC,EAAE;IACzF,OAAO,OAAQ,MAAkD,EAAE,QAAQ,KAAK,UAAU,CAAA;AAC9F,CAAC,CAAA;AAED,MAAM,OAAO,GAAG,CAAI,MAA6B,EAAuB,EAAE;IACtE,OAAO,OAAQ,MAA6C,EAAE,IAAI,KAAK,UAAU,CAAA;AACrF,CAAC,CAAA;AAMD,MAAM,UAAU,aAAa,CAAI,CAAsB,EAAE,aAAiB;IACtE,MAAM,UAAU,GAAG,MAAM,CAAwB,SAAS,CAAC,CAAA;IAC3D,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,UAAU;QAClC,CAAC,CAAC,UAAU,CAAC,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;QAClD,CAAC,CAAC,CAAC,CAAA;IACP,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAA;IAC3B,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,QAAQ,CAAgB,GAAG,EAAE,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAA;IAE3G,SAAS,CAAC,GAAG,EAAE;QACX,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,KAAK,MAAM,CAAA;QACpC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;QAErB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,OAAM;QAE5B,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAC5B,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAChD,GAAG,CAAC,CAAC,CAAC,CACT,CAAC,SAAS,EAAE,CAAA;QACb,OAAO,GAAG,EAAE;YACR,YAAY,CAAC,WAAW,EAAE,CAAA;QAC9B,CAAC,CAAA;IACL,CAAC,EAAE,OAAO,CAAC,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAEtC,OAAO,CAAC,CAAA;AACZ,CAAC"}

package/package.json

@@ -1,68 +1,73 @@
 {
-    "name": "@livequery/react",
-    "repository": {
-        "url": "https://github.com/livequery/react"
+  "name": "@livequery/react",
+  "repository": {
+    "url": "https://github.com/livequery/react"
+  },
+  "type": "module",
+  "version": "2.0.135",
+  "description": "",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
-    "type": "module",
-    "version": "2.0.133",
-    "description": "",
-    "main": "./dist/index.js",
-    "types": "./dist/index.d.ts",
-    "exports": {
-        ".": {
-            "types": "./dist/index.d.ts",
-            "import": "./dist/index.js",
-            "default": "./dist/index.js"
-        },
-        "./createContextFromHook": {
-            "types": "./dist/createContextFromHook.d.ts",
-            "import": "./dist/createContextFromHook.js",
-            "default": "./dist/createContextFromHook.js"
-        },
-        "./LivequeryClientContext": {
-            "types": "./dist/LivequeryClientContext.d.ts",
-            "import": "./dist/LivequeryClientContext.js",
-            "default": "./dist/LivequeryClientContext.js"
-        },
-        "./useAction": {
-            "types": "./dist/useAction.d.ts",
-            "import": "./dist/useAction.js",
-            "default": "./dist/useAction.js"
-        },
-        "./useCollection": {
-            "types": "./dist/useCollection.d.ts",
-            "import": "./dist/useCollection.js",
-            "default": "./dist/useCollection.js"
-        },
-        "./useDocument": {
-            "types": "./dist/useDocument.d.ts",
-            "import": "./dist/useDocument.js",
-            "default": "./dist/useDocument.js"
-        },
-        "./useObservable": {
-            "types": "./dist/useObservable.d.ts",
-            "import": "./dist/useObservable.js",
-            "default": "./dist/useObservable.js"
-        }
+    "./createContextFromHook": {
+      "types": "./dist/createContextFromHook.d.ts",
+      "import": "./dist/createContextFromHook.js",
+      "default": "./dist/createContextFromHook.js"
     },
-    "files": [
-        "dist/**/*"
-    ],
-    "devDependencies": {
-        "@types/react": "^19.2.14"
+    "./LivequeryClientContext": {
+      "types": "./dist/LivequeryClientContext.d.ts",
+      "import": "./dist/LivequeryClientContext.js",
+      "default": "./dist/LivequeryClientContext.js"
     },
-    "peerDependencies": {
-        "@livequery/client": "^2.0.133",
-        "rxjs": "^7.8.2",
-        "react": "^19.2.5"
+    "./useAction": {
+      "types": "./dist/useAction.d.ts",
+      "import": "./dist/useAction.js",
+      "default": "./dist/useAction.js"
     },
-    "scripts": {
-        "clean": "rm -rf dist",
-        "build:types": "bunx tsc -p tsconfig.build.json",
-        "build": "bun run clean && bun run build:types",
-        "build:prod": "bun run build",
-        "build:watch": "bunx tsc -p tsconfig.build.json --watch"
+    "./useCollection": {
+      "types": "./dist/useCollection.d.ts",
+      "import": "./dist/useCollection.js",
+      "default": "./dist/useCollection.js"
     },
-    "author": "",
-    "license": "ISC"
+    "./useDocument": {
+      "types": "./dist/useDocument.d.ts",
+      "import": "./dist/useDocument.js",
+      "default": "./dist/useDocument.js"
+    },
+    "./useObservable": {
+      "types": "./dist/useObservable.d.ts",
+      "import": "./dist/useObservable.js",
+      "default": "./dist/useObservable.js"
+    }
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "devDependencies": {
+    "@livequery/client": "^2.0.135",
+    "@types/bun": "^1.3.14",
+    "@types/react": "^19.2.14",
+    "@types/react-test-renderer": "^19.1.0",
+    "react-test-renderer": "^19.2.6"
+  },
+  "peerDependencies": {
+    "@livequery/client": "^2.0.135",
+    "react": "^19.2.5",
+    "rxjs": "^7.8.2"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build:types": "bunx tsc -p tsconfig.build.json",
+    "build": "bun run clean && bun run build:types",
+    "build:prod": "bun run build",
+    "test": "bun test",
+    "build:watch": "bunx tsc -p tsconfig.build.json --watch"
+  },
+  "author": "",
+  "license": "ISC"
 }