@ossy/sdk-react 1.40.3 → 3.0.1

package/README.md

@@ -45,16 +45,17 @@ function MyComponent() {
 }
 ```
 
-`WorkspaceProvider` subscribes to SSE push invalidation automatically (ADR 0008 §9) and drops stale read-cache keys when the server emits `invalidate`.
+`WorkspaceProvider` provides the SDK and shared read cache. **SSE push invalidation is off by default** — enable it only where you need live cross-tab cache updates.
 
 ## API
 
 | Export | Purpose |
 |---|---|
-| `WorkspaceProvider` | Provides SDK + shared read cache + SSE invalidation |
+| `WorkspaceProvider` | Provides SDK + shared read cache (optional app-wide push via `enablePushInvalidation`) |
+| `PushInvalidationSubscriber` | Opt-in SSE invalidation for a page or subtree |
 | `useSdk()` | Returns `{ invoke, invokeOptimistic, read, invalidate, cacheKey, sdk }` |
 | `useRead()` | Same as `sdk.read` — hook for reactive reads |
-| `usePushInvalidation()` | Wire SSE push to a read-cache store (used by `WorkspaceProvider`) |
+| `usePushInvalidation()` | Low-level hook; prefer `PushInvalidationSubscriber` |
 | `cacheKey(action, payload)` | Stable cache key for an action + payload |
 | `projectionKey(projectionId, scopeId)` | Cache key for projection reads |
 | `applyOptimisticResource()` | Fold a pending event into cached resource state |
@@ -95,11 +96,50 @@ sdk.invalidate(sdk.cacheKey(ListResources, { location }))
 
 ## Push invalidation
 
-`WorkspaceProvider` calls `usePushInvalidation` internally. When the server sends SSE frames with `invalidate: string[]`, matching read-cache keys are cleared and active `useRead` hooks refetch.
+Push invalidation (ADR 0008 §9) opens a long-lived SSE connection to `GET /events` per subscriber. **It is disabled by default** because most pages only need fresh data after their own writes (`sdk.invalidate()` / refetch).
 
-For custom setups, subscribe manually:
+### When to enable
 
-```ts
+Use push only on pages or components that benefit from **background or cross-tab** updates, for example:
+
+- Collaborative resource lists that should refresh when another user edits
+- Long-lived dashboards or inbox views
+- Dev tooling that watches task runs or automation
+
+Avoid enabling it on static marketing pages, auth flows, or one-shot forms.
+
+### Page-level (recommended)
+
+```jsx
+import { PushInvalidationSubscriber } from '@ossy/sdk-react'
+
+export default function ResourcesPage() {
+  return (
+    <>
+      <PushInvalidationSubscriber />
+      {/* … */}
+    </>
+  )
+}
+```
+
+Requires `workspaceId` on the SDK (or same-origin workspace cookie). Must render inside `WorkspaceProvider`.
+
+### App-wide (optional)
+
+In `src/config.js`:
+
+```js
+export default {
+  enablePushInvalidation: true,
+}
+```
+
+Or pass `enablePushInvalidation` to `WorkspaceProvider` in custom setups.
+
+### Manual wiring
+
+```tsx
 import { usePushInvalidation, useReadCacheStore } from '@ossy/sdk-react'
 
 function MyBridge({ sdk }) {
@@ -109,7 +149,7 @@ function MyBridge({ sdk }) {
 }
 ```
 
-Requires `workspaceId` on the SDK config (or same-origin workspace cookie). See [@ossy/sdk README](../sdk/README.md#push-invalidation-adr-0008).
+See [@ossy/sdk README](../sdk/README.md#push-invalidation-adr-0008) for server-side details.
 
 ## Cache key conventions
 

package/build/packages/sdk-react/src/PushInvalidationSubscriber.js

@@ -0,0 +1 @@
+import{useContext as r}from"react";import{Context as o}from"./WorkspaceProvider.js";import{usePushInvalidation as t}from"./usePushInvalidation.js";import{useReadCacheStore as i}from"./Cache.js";function m(){var m=r(o).sdk,e=i();return t(m,e),null}export{m as PushInvalidationSubscriber};

package/build/packages/sdk-react/src/WorkspaceProvider.js

@@ -1 +1 @@
-import r,{createContext as e,useMemo as t}from"react";import{createCache as n,useReadCacheStore as o}from"./Cache.js";import{createMapCache as a}from"./cacheUtils.js";import{ReactSdk as m}from"./react-sdk.js";import{usePushInvalidation as i}from"./usePushInvalidation.js";var c=e({}),s=n(a());function l(r){var e=r.sdk,t=o();return i(e,t),null}var u=function(e){var n=e.sdk,o=e.children,a=t(function(){return m.from(n)},[n]);return r.createElement(s,null,r.createElement(c.Provider,{value:{sdk:a}},r.createElement(l,{sdk:a}),o))};export{c as Context,u as WorkspaceProvider};
+import r,{createContext as e,useMemo as t}from"react";import{createCache as n,useReadCacheStore as o}from"./Cache.js";import{createMapCache as a}from"./cacheUtils.js";import{ReactSdk as i}from"./react-sdk.js";import{usePushInvalidation as m}from"./usePushInvalidation.js";var l=e({}),s=n(a());function c(r){var e=r.sdk,t=o();return m(e,t),null}var u=function(e){var n=e.sdk,o=e.enablePushInvalidation,a=void 0!==o&&o,m=e.children,u=t(function(){return i.from(n)},[n]);return r.createElement(s,null,r.createElement(l.Provider,{value:{sdk:u}},a&&r.createElement(c,{sdk:u}),m))};export{l as Context,u as WorkspaceProvider};

package/build/packages/sdk-react/src/public.index.js

@@ -1 +1 @@
-export{AsyncStatus}from"./asyncStatus.js";export{normalizeLocation}from"./normalizeLocation.js";export{ReactSdk}from"./react-sdk.js";export{resolveActionId,toActionRef}from"./action.js";export{Context,WorkspaceProvider}from"./WorkspaceProvider.js";export{useSdk}from"./useSdk.js";export{useRead}from"./useRead.js";export{usePushInvalidation}from"./usePushInvalidation.js";export{applyOptimisticResource,rollbackOptimisticResource}from"./optimisticResource.js";export{cacheKey,projectionKey}from"./cacheKey.js";export{stableSerialize}from"./stableSerialize.js";export{useReadCacheStore}from"./Cache.js";
+export{AsyncStatus}from"./asyncStatus.js";export{normalizeLocation}from"./normalizeLocation.js";export{ReactSdk}from"./react-sdk.js";export{resolveActionId,toActionRef}from"./action.js";export{Context,WorkspaceProvider}from"./WorkspaceProvider.js";export{PushInvalidationSubscriber}from"./PushInvalidationSubscriber.js";export{useSdk}from"./useSdk.js";export{useRead}from"./useRead.js";export{usePushInvalidation}from"./usePushInvalidation.js";export{applyOptimisticResource,rollbackOptimisticResource}from"./optimisticResource.js";export{cacheKey,projectionKey}from"./cacheKey.js";export{stableSerialize}from"./stableSerialize.js";export{useReadCacheStore}from"./Cache.js";

package/build/public.index.d.ts

@@ -65,9 +65,24 @@ declare const Context: React.Context<Config>;
 interface Config {
     sdk: ReactSdk;
 }
-declare const WorkspaceProvider: ({ sdk, children, }: PropsWithChildren<{
+interface WorkspaceProviderProps {
     sdk: SDK | ReactSdk;
-}>) => React.JSX.Element;
+    /**
+     * When true, subscribe to SSE push for the whole app tree.
+     * Default false — prefer {@link PushInvalidationSubscriber} on specific pages.
+     */
+    enablePushInvalidation?: boolean;
+}
+declare const WorkspaceProvider: ({ sdk, enablePushInvalidation, children, }: PropsWithChildren<WorkspaceProviderProps>) => React.JSX.Element;
+
+/**
+ * Opt-in SSE push invalidation for a page or subtree.
+ *
+ * Mount only where live cache invalidation matters (e.g. collaborative lists,
+ * long-lived dashboards). Most pages should rely on `sdk.invalidate()` after
+ * writes instead — see sdk-react README § Push invalidation.
+ */
+declare function PushInvalidationSubscriber(): null;
 
 declare function projectionKey(projectionId: string, scopeId: string): string;
 declare function cacheKey(action: ActionRef | string, payload?: Record<string, unknown>): string;
@@ -139,5 +154,5 @@ declare function usePushInvalidation(sdk: {
 /** Deterministic JSON for cache keys — sorted object keys, no Ramda. */
 declare function stableSerialize(value: unknown): string;
 
-export { AsyncStatus, Context, ReactSdk, WorkspaceProvider, applyOptimisticResource, cacheKey, normalizeLocation, projectionKey, resolveActionId, rollbackOptimisticResource, stableSerialize, toActionRef, usePushInvalidation, useRead, useReadCacheStore, useSdk };
-export type { ActionRef, AsyncStatusType, Config, OptimisticResourceEvent, ReadOptions, ReadResult, SdkApi };
+export { AsyncStatus, Context, PushInvalidationSubscriber, ReactSdk, WorkspaceProvider, applyOptimisticResource, cacheKey, normalizeLocation, projectionKey, resolveActionId, rollbackOptimisticResource, stableSerialize, toActionRef, usePushInvalidation, useRead, useReadCacheStore, useSdk };
+export type { ActionRef, AsyncStatusType, Config, OptimisticResourceEvent, ReadOptions, ReadResult, SdkApi, WorkspaceProviderProps };

package/build/types/PushInvalidationSubscriber.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Opt-in SSE push invalidation for a page or subtree.
+ *
+ * Mount only where live cache invalidation matters (e.g. collaborative lists,
+ * long-lived dashboards). Most pages should rely on `sdk.invalidate()` after
+ * writes instead — see sdk-react README § Push invalidation.
+ */
+export function PushInvalidationSubscriber(): null;

package/build/types/WorkspaceProvider.d.ts

@@ -5,6 +5,12 @@ export declare const Context: React.Context<Config>;
 export interface Config {
     sdk: ReactSdk;
 }
-export declare const WorkspaceProvider: ({ sdk, children, }: PropsWithChildren<{
+export interface WorkspaceProviderProps {
     sdk: SDK | ReactSdk;
-}>) => React.JSX.Element;
+    /**
+     * When true, subscribe to SSE push for the whole app tree.
+     * Default false — prefer {@link PushInvalidationSubscriber} on specific pages.
+     */
+    enablePushInvalidation?: boolean;
+}
+export declare const WorkspaceProvider: ({ sdk, enablePushInvalidation, children, }: PropsWithChildren<WorkspaceProviderProps>) => React.JSX.Element;

package/build/types/public.index.d.ts

@@ -3,6 +3,7 @@ export * from './normalizeLocation';
 export * from './react-sdk';
 export * from './action';
 export * from './WorkspaceProvider';
+export { PushInvalidationSubscriber } from './PushInvalidationSubscriber.jsx';
 export * from './useSdk';
 export * from './useRead';
 export * from './usePushInvalidation';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ossy/sdk-react",
   "description": "Software Development Kit React",
-  "version": "1.40.3",
+  "version": "3.0.1",
   "url": "git://github.com/ossy-se/packages/sdk-react",
   "source": "src/public.index.ts",
   "main": "./build/packages/sdk-react/src/public.index.js",
@@ -40,8 +40,8 @@
     "@babel/preset-typescript": "^7.26.0"
   },
   "peerDependencies": {
-    "@ossy/fold": ">=1.0.0 <2.0.0",
-    "@ossy/sdk": ">=1.0.0 <2.0.0",
+    "@ossy/fold": ">=1.0.0 <4.0.0",
+    "@ossy/sdk": ">=1.0.0 <4.0.0",
     "react": ">=19.0.0 <20.0.0",
     "react-dom": ">=19.0.0 <20.0.0"
   },
@@ -53,5 +53,5 @@
     "/build",
     "README.md"
   ],
-  "gitHead": "a0d89185a17f8de8ce328c3a648c108ff1d61d8f"
+  "gitHead": "4a70ec216448680d2fddc57b2a8a0077489720ae"
 }