@livequery/react 2.0.151 → 2.0.153

package/README.md

@@ -20,6 +20,7 @@ npm install @livequery/react @livequery/client react rxjs
 
 - `LivequeryClientProvider`
 - `useLivequeryClient`
+- `useLivequeryContext`
 - `useCollection`
 - `useDocument`
 - `useObservable`
@@ -74,6 +75,18 @@ Use it when:
 
 The provider currently expects a `core` prop. Passing `client` will not work unless the implementation is changed.
 
+### Provider-level `context`
+
+The provider also accepts an optional `context` prop — an arbitrary bag forwarded with every collection operation down to the transporter's `onRequest` hook (see [`@livequery/client` → context](../client/README.md#context)). The canonical use is per-tab multi-account routing: set `{ account_id }` once at the provider and every `useCollection()` below it inherits it.
+
+```tsx
+<LivequeryClientProvider core={client} context={{ account_id: currentAccountId }}>
+  <TodoList />
+</LivequeryClientProvider>
+```
+
+Changing the provider `context` (e.g. switching account) re-creates every descendant collection under the new context — old subscriptions tear down and re-subscribe. A per-call `options.context` on `useCollection` overrides the provider one (shallow merge, per-call wins).
+
 ### SharedWorker
 
 If your app uses a SharedWorker via `@livequery/rpc`, the setup inside the worker is different — but from React's perspective nothing changes. You still construct a `LivequeryClient` and pass it to `LivequeryClientProvider` exactly as shown above. Read the `@livequery/rpc` documentation for how to expose the client from a SharedWorker; the React layer stays the same.
@@ -95,10 +108,35 @@ export function ClientStatus() {
 
 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`.
 
+## `useLivequeryContext`
+
+`useLivequeryContext()` reads the optional `context` bag passed to `LivequeryClientProvider`. Returns `undefined` when no `context` prop was provided.
+
+```tsx
+import { useLivequeryContext } from '@livequery/react'
+
+export function CurrentAccount() {
+  const context = useLivequeryContext()
+  return <span>account: {context?.account_id ?? 'none'}</span>
+}
+```
+
+Most code never calls this directly — `useCollection()` already merges this provider context into the collections it creates. Use it only when you need to read the active context for display or branching.
+
 ## `useCollection`
 
 `useCollection<T>(ref, options)` creates a `LivequeryCollection<T>` for the current `ref`, initializes it when `ref` is truthy, and returns the collection instance. When `ref` changes, a fresh collection is created — its state is reset and reloaded for the new ref.
 
+The collection's `context` is the provider `context` shallow-merged with `options.context` (per-call wins). `useCollection` keys the collection on both `ref` **and** the resolved context, so changing either creates a fresh instance — switching account therefore tears down the old subscription and re-subscribes under the new context.
+
+```tsx
+// inherits provider context (e.g. { account_id })
+const todos = useCollection<Todo>('todos', { lazy: false })
+
+// override / extend context for this collection only
+const orders = useCollection<Order>('orders', { lazy: false, context: { account_id: otherId } })
+```
+
 Use it when a component needs the full collection API: reactive state plus methods such as querying or mutations.
 
 ```tsx

package/dist/LivequeryClientContext.d.ts

@@ -1,5 +1,9 @@
 import type { LivequeryClient } from "@livequery/client";
-export declare const useLivequeryClient: () => LivequeryClient, LivequeryClientProvider: (props: import("react").PropsWithChildren<{
+declare const LivequeryClientProvider: (props: import("react").PropsWithChildren<{
     core: any;
+    context?: Record<string, any>;
 }>) => import("react").JSX.Element;
+export { LivequeryClientProvider };
+export declare const useLivequeryClient: () => LivequeryClient;
+export declare const useLivequeryContext: () => Record<string, any> | undefined;
 //# sourceMappingURL=LivequeryClientContext.d.ts.map

package/dist/LivequeryClientContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LivequeryClientContext.d.ts","sourceRoot":"","sources":["../src/LivequeryClientContext.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGzD,eAAO,MAAO,kBAAkB,yBAAE,uBAAuB;UACrC,GAAG;kCACtB,CAAA"}
+{"version":3,"file":"LivequeryClientContext.d.ts","sourceRoot":"","sources":["../src/LivequeryClientContext.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAMzD,QAAA,MAAyB,uBAAuB;UAC5B,GAAG;cAAY,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;kCAIrD,CAAA;AAED,OAAO,EAAE,uBAAuB,EAAE,CAAA;AAClC,eAAO,MAAM,kBAAkB,uBAAgC,CAAA;AAC/D,eAAO,MAAM,mBAAmB,uCAAmC,CAAA"}

package/dist/LivequeryClientContext.js

@@ -1,3 +1,12 @@
 import { createContextFromHook } from "./createContextFromHook.js";
-export const [useLivequeryClient, LivequeryClientProvider] = createContextFromHook((props) => props.core);
+// The provider now carries both the client (`core`) and an optional `context` —
+// an arbitrary bag forwarded with every collection operation down to the
+// transporter's onRequest hook (e.g. { account_id } for per-tab multi-account).
+const [useLivequeryRoot, LivequeryClientProvider] = createContextFromHook((props) => ({
+    core: props.core,
+    context: props.context
+}));
+export { LivequeryClientProvider };
+export const useLivequeryClient = () => useLivequeryRoot().core;
+export const useLivequeryContext = () => useLivequeryRoot().context;
 //# sourceMappingURL=LivequeryClientContext.js.map

package/dist/LivequeryClientContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"LivequeryClientContext.js","sourceRoot":"","sources":["../src/LivequeryClientContext.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,MAAM,CAAC,MAAM,CAAC,kBAAkB,EAAE,uBAAuB,CAAC,GAAG,qBAAqB,CAC9E,CAAC,KAAoB,EAAE,EAAE,CAAC,KAAK,CAAC,IAAuB,CAC1D,CAAA"}
+{"version":3,"file":"LivequeryClientContext.js","sourceRoot":"","sources":["../src/LivequeryClientContext.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,gFAAgF;AAChF,yEAAyE;AACzE,gFAAgF;AAChF,MAAM,CAAC,gBAAgB,EAAE,uBAAuB,CAAC,GAAG,qBAAqB,CACrE,CAAC,KAAmD,EAAE,EAAE,CAAC,CAAC;IACtD,IAAI,EAAE,KAAK,CAAC,IAAuB;IACnC,OAAO,EAAE,KAAK,CAAC,OAA0C;CAC5D,CAAC,CACL,CAAA;AAED,OAAO,EAAE,uBAAuB,EAAE,CAAA;AAClC,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,EAAE,CAAC,gBAAgB,EAAE,CAAC,IAAI,CAAA;AAC/D,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,EAAE,CAAC,gBAAgB,EAAE,CAAC,OAAO,CAAA"}

package/dist/useCollection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useCollection.d.ts","sourceRoot":"","sources":["../src/useCollection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,KAAK,GAAG,EAAE,KAAK,0BAA0B,EAAE,MAAM,mBAAmB,CAAA;AAMlG,eAAO,MAAM,aAAa,GAAI,CAAC,SAAS,GAAG,EAAE,KAAK,MAAM,GAAG,SAAS,GAAG,EAAE,GAAG,IAAI,GAAG,KAAK,EAAE,UAAS,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAM,2BAe7I,CAAA"}
+{"version":3,"file":"useCollection.d.ts","sourceRoot":"","sources":["../src/useCollection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,KAAK,GAAG,EAAE,KAAK,0BAA0B,EAAE,MAAM,mBAAmB,CAAA;AAMlG,eAAO,MAAM,aAAa,GAAI,CAAC,SAAS,GAAG,EAAE,KAAK,MAAM,GAAG,SAAS,GAAG,EAAE,GAAG,IAAI,GAAG,KAAK,EAAE,UAAS,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAM,2BAoB7I,CAAA"}

package/dist/useCollection.js

@@ -1,13 +1,18 @@
 import { LivequeryCollection } from "@livequery/client";
 import { useMemo, useEffect } from "react";
-import { useLivequeryClient } from "./LivequeryClientContext.js";
+import { useLivequeryClient, useLivequeryContext } from "./LivequeryClientContext.js";
 export const useCollection = (ref, options = {}) => {
     const client = useLivequeryClient();
-    // Recreate the collection whenever the ref changes so each ref gets a fresh, fully-reset
-    // instance. The client is stable (provided once via context), so it is intentionally NOT a
+    // Provider-level context (e.g. { account_id }); a per-call options.context overrides it.
+    const providerContext = useLivequeryContext();
+    const context = { ...providerContext, ...options.context };
+    const contextKey = JSON.stringify(context);
+    // Recreate the collection whenever the ref OR the context changes so each (ref, context)
+    // pair gets a fresh, fully-reset instance — switching account re-subscribes under the new
+    // context. The client is stable (provided once via context), so it is intentionally NOT a
     // dependency — keying on it would rebuild the collection on every render if a caller ever
     // passed an unstable client.
-    const collection = useMemo(() => new LivequeryCollection(client, options), [ref]);
+    const collection = useMemo(() => new LivequeryCollection(client, { ...options, context }), [ref, contextKey]);
     useEffect(() => {
         if (!client || !ref)
             return;

package/dist/useCollection.js.map

@@ -1 +1 @@
-{"version":3,"file":"useCollection.js","sourceRoot":"","sources":["../src/useCollection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAA6C,MAAM,mBAAmB,CAAA;AAClG,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAIhE,MAAM,CAAC,MAAM,aAAa,GAAG,CAAgB,GAA2C,EAAE,UAAkD,EAAE,EAAE,EAAE;IAC9I,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAA;IACnC,yFAAyF;IACzF,2FAA2F;IAC3F,0FAA0F;IAC1F,6BAA6B;IAC7B,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,mBAAmB,CAAI,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAA;IACpF,SAAS,CAAC,GAAG,EAAE;QACX,IAAI,CAAC,MAAM,IAAI,CAAC,GAAG;YAAE,OAAM;QAC3B,MAAM,MAAM,GAAG,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,CAAA;QACzC,OAAO,GAAG,EAAE;YACR,MAAM,EAAE,WAAW,EAAE,CAAA;QACzB,CAAC,CAAA;IACL,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAA;IAChB,OAAO,UAAU,CAAA;AACrB,CAAC,CAAA"}
+{"version":3,"file":"useCollection.js","sourceRoot":"","sources":["../src/useCollection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAA6C,MAAM,mBAAmB,CAAA;AAClG,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAC1C,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AAIrF,MAAM,CAAC,MAAM,aAAa,GAAG,CAAgB,GAA2C,EAAE,UAAkD,EAAE,EAAE,EAAE;IAC9I,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAA;IACnC,yFAAyF;IACzF,MAAM,eAAe,GAAG,mBAAmB,EAAE,CAAA;IAC7C,MAAM,OAAO,GAAG,EAAE,GAAG,eAAe,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAA;IAC1D,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;IAC1C,yFAAyF;IACzF,0FAA0F;IAC1F,0FAA0F;IAC1F,0FAA0F;IAC1F,6BAA6B;IAC7B,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,mBAAmB,CAAI,MAAM,EAAE,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAA;IAChH,SAAS,CAAC,GAAG,EAAE;QACX,IAAI,CAAC,MAAM,IAAI,CAAC,GAAG;YAAE,OAAM;QAC3B,MAAM,MAAM,GAAG,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,CAAA;QACzC,OAAO,GAAG,EAAE;YACR,MAAM,EAAE,WAAW,EAAE,CAAA;QACzB,CAAC,CAAA;IACL,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAA;IAChB,OAAO,UAAU,CAAA;AACrB,CAAC,CAAA"}

package/package.json

@@ -4,7 +4,7 @@
     "url": "https://github.com/livequery/react"
   },
   "type": "module",
-  "version": "2.0.151",
+  "version": "2.0.153",
   "description": "",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -49,14 +49,14 @@
     "dist/**/*"
   ],
   "devDependencies": {
-    "@livequery/client": "^2.0.151",
+    "@livequery/client": "^2.0.152",
     "@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.151",
+    "@livequery/client": "^2.0.152",
     "react": "^19.2.5",
     "rxjs": "^7.8.2"
   },