react-shared-states 1.0.3 → 1.0.5

package/README.md

@@ -12,7 +12,7 @@
 [![license](https://img.shields.io/github/license/HichemTab-tech/react-shared-states)](LICENSE)
 
 
-Tiny, ergonomic, convention‑over‑configuration state & async function sharing for React. Global by default, trivially scoped when you need isolation, and opt‑in static APIs when you must touch state outside components. As simple as `useState`, as flexible as Zustand, without boilerplate like Redux.
+Tiny, ergonomic, convention‑over‑configuration state, async function, and real-time subscription sharing for React. Global by default, trivially scoped when you need isolation, and opt‑in static APIs when you must touch state outside components. As simple as `useState`, as flexible as Zustand, without boilerplate like Redux.
 
 ## 🔥 Why this instead of Redux / Zustand / Context soup?
 * 0 config. Just pick a key: `useSharedState('cart', [])`.
@@ -173,14 +173,15 @@ export default function App(){
 
 
 ## 🧠 Core Concepts
-| Concept           | Summary                                                                                                                         |
-|-------------------|---------------------------------------------------------------------------------------------------------------------------------|
-| Global by default | No provider necessary. Same key => shared state.                                                                                |
-| Scoping           | Wrap with `SharedStatesProvider` to isolate. Nearest provider wins.                                                             |
-| Named scopes      | `scopeName` prop lets distant providers sync (same name ⇒ same bucket). Unnamed providers auto‑generate a random isolated name. |
-| Manual override   | Third param in `useSharedState` / `useSharedFunction` enforces a specific scope ignoring tree search.                           |
-| Shared functions  | Encapsulate async logic: single flight + cached result + `error` + `isLoading` + opt‑in refresh.                                |
-| Static APIs       | Access state/functions outside components (`sharedStatesApi`, `sharedFunctionsApi`).                                            |
+| Concept              | Summary                                                                                                                         |
+|----------------------|---------------------------------------------------------------------------------------------------------------------------------|
+| Global by default    | No provider necessary. Same key => shared state.                                                                                |
+| Scoping              | Wrap with `SharedStatesProvider` to isolate. Nearest provider wins.                                                             |
+| Named scopes         | `scopeName` prop lets distant providers sync (same name ⇒ same bucket). Unnamed providers auto‑generate a random isolated name. |
+| Manual override      | Third param in `useSharedState` / `useSharedFunction` / `useSharedSubscription` enforces a specific scope ignoring tree search. |
+| Shared functions     | Encapsulate async logic: single flight + cached result + `error` + `isLoading` + opt‑in refresh.                                |
+| Shared subscriptions | Real-time data streams: automatic cleanup + shared connections + `error` + `isLoading` + subscription state.                    |
+| Static APIs          | Access state/functions/subscriptions outside components (`sharedStatesApi`, `sharedFunctionsApi`, `sharedSubscriptionsApi`).    |
 
 
 ## 🏗️ Sharing State (`useSharedState`)
@@ -248,13 +249,158 @@ const refresh = () => forceTrigger();
 ```
 
 
+## 📡 Real-time Subscriptions (`useSharedSubscription`)
+Perfect for Firebase listeners, WebSocket connections,
+Server-Sent Events, or any streaming data source that needs cleanup.
+
+Signature:
+```ts
+const { state, trigger, unsubscribe } = useSharedSubscription(key, subscriber, scopeName?);
+```
+
+`state` shape: `{ data?: T; isLoading: boolean; error?: unknown; subscribed: boolean }`
+
+The `subscriber` function receives three callbacks:
+- `set(data)`: Update the shared data
+- `onError(error)`: Handle errors 
+- `onCompletion()`: Mark loading as complete
+- Returns: Optional cleanup function (called on unsubscribe/unmount)
+
+### Pattern: Firebase Firestore real-time listener
+```tsx
+import { useEffect } from 'react';
+import { onSnapshot, doc } from 'firebase/firestore';
+import { useSharedSubscription } from 'react-shared-states';
+import { db } from './firebase-config'; // your Firebase config
+
+function UserProfile({ userId }: { userId: string }) {
+  const { state, trigger, unsubscribe } = useSharedSubscription(
+    `user-${userId}`,
+    async (set, onError, onCompletion) => {
+      const userRef = doc(db, 'users', userId);
+      
+      // Set up the real-time listener
+      const unsubscribe = onSnapshot(
+        userRef,
+        (snapshot) => {
+          if (snapshot.exists()) {
+            set({ id: snapshot.id, ...snapshot.data() });
+          } else {
+            set(null);
+          }
+        },
+        onError,
+        onCompletion
+      );
+      
+      // Return cleanup function
+      return unsubscribe;
+    }
+  );
+
+  // Start listening when component mounts
+  useEffect(() => {
+    trigger();
+  }, []);
+
+  if (state.isLoading) return <div>Connecting...</div>;
+  if (state.error) return <div>Error: {state.error.message}</div>;
+  if (!state.data) return <div>User not found</div>;
+
+  return (
+    <div>
+      <h1>{state.data.name}</h1>
+      <p>{state.data.email}</p>
+      <button onClick={unsubscribe}>Stop listening</button>
+    </div>
+  );
+}
+```
+
+### Pattern: WebSocket connection
+```tsx
+import { useEffect } from 'react';
+import { useSharedSubscription } from 'react-shared-states';
+
+function ChatRoom({ roomId }: { roomId: string }) {
+  const { state, trigger } = useSharedSubscription(
+    `chat-${roomId}`,
+    (set, onError, onCompletion) => {
+      const ws = new WebSocket(`ws://chat-server/${roomId}`);
+      
+      ws.onopen = () => onCompletion();
+      ws.onmessage = (event) => {
+        const message = JSON.parse(event.data);
+        set(prev => [...(prev || []), message]);
+      };
+      ws.onerror = onError;
+      
+      return () => ws.close();
+    }
+  );
+
+  useEffect(() => {
+    trigger();
+  }, []);
+
+  return (
+    <div>
+      {state.isLoading && <p>Connecting to chat...</p>}
+      {state.error && <p>Connection failed</p>}
+      <div>
+        {state.data?.map(msg => (
+          <div key={msg.id}>{msg.text}</div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+### Pattern: Server-Sent Events
+```tsx
+import { useEffect } from 'react';
+import { useSharedSubscription } from 'react-shared-states';
+
+function LiveUpdates() {
+  const { state, trigger } = useSharedSubscription(
+    'live-updates',
+    (set, onError, onCompletion) => {
+      const eventSource = new EventSource('/api/live-updates');
+      
+      eventSource.onopen = () => onCompletion();
+      eventSource.onmessage = (event) => {
+        set(JSON.parse(event.data));
+      };
+      eventSource.onerror = onError;
+      
+      return () => eventSource.close();
+    }
+  );
+
+  useEffect(() => {
+    trigger();
+  }, []);
+
+  return <div>Latest: {JSON.stringify(state.data)}</div>;
+}
+```
+
+Subscription semantics:
+* First `trigger()` establishes the subscription; subsequent calls do nothing if already subscribed.
+* Multiple components with the same key+scope share one subscription + data stream.
+* `unsubscribe()` closes the connection and clears the subscribed state.
+* Automatic cleanup on component unmount when no other components are listening.
+* Components mounting later instantly get the latest `data` without re-subscribing.
+
+
 ## 🛰️ Static APIs (outside React)
 Useful for SSR hydration, event listeners, debugging, imperative workflows.
 
 ```ts
-import { sharedStatesApi, sharedFunctionsApi } from 'react-shared-states';
+import { sharedStatesApi, sharedFunctionsApi, sharedSubscriptionsApi } from 'react-shared-states';
 
-// Preload
+// Preload state
 sharedStatesApi.set('bootstrap-data', { user: {...} });
 
 // Read later
@@ -265,14 +411,18 @@ console.log(sharedStatesApi.getAll()); // Map with prefixed keys
 
 // For shared functions
 const fnState = sharedFunctionsApi.get('profile-123');
+
+// For shared subscriptions
+const subState = sharedSubscriptionsApi.get('live-chat');
 ```
 
 ## API summary:
 
-| API                  | Methods                                                                              |
-|----------------------|--------------------------------------------------------------------------------------|
-| `sharedStatesApi`    | `get(key, scope?)`, `set(key,val,scope?)`, `has`, `clear`, `clearAll`, `getAll()`    |
-| `sharedFunctionsApi` | `get(key, scope?)` (returns fn state), `set`, `has`, `clear`, `clearAll`, `getAll()` |
+| API                      | Methods                                                                               |
+|--------------------------|---------------------------------------------------------------------------------------|
+| `sharedStatesApi`        | `get(key, scope?)`, `set(key,val,scope?)`, `has`, `clear`, `clearAll`, `getAll()`     |
+| `sharedFunctionsApi`     | `get(key, scope?)` (returns fn state), `set`, `has`, `clear`, `clearAll`, `getAll()`  |
+| `sharedSubscriptionsApi` | `get(key, scope?)` (returns sub state), `set`, `has`, `clear`, `clearAll`, `getAll()` |
 
 `scope` defaults to `"_global"`. Internally keys are stored as `${scope}_${key}`.
 
@@ -302,8 +452,9 @@ Two providers sharing the same `scopeName` act as a single logical scope even if
 
 ## 🧪 Testing Tips
 * Use static APIs to assert state after component interactions.
-* `sharedStatesApi.clearAll()` in `afterEach` to isolate tests.
+* `sharedStatesApi.clearAll()`, `sharedFunctionsApi.clearAll()`, `sharedSubscriptionsApi.clearAll()` in `afterEach` to isolate tests.
 * For async functions: trigger once, await UI stabilization, assert `results` present.
+* For subscriptions: mock the subscription source (Firebase, WebSocket, etc.) and verify data flow.
 
 
 ## ❓ FAQ
@@ -319,6 +470,9 @@ Prefix keys by domain (e.g. `user:profile`, `cart:items`) or rely on provider sc
 **Q: Why is my async function not re-running?**  
 It's cached. Use `forceTrigger()` or `clear()`.
 
+**Q: How do I handle subscription cleanup?**  
+Subscriptions auto-cleanup when no components are listening. You can also manually call `unsubscribe()`.
+
 **Q: Can I use it with Suspense?**  
 Currently no built-in Suspense wrappers; wrap `useSharedFunction` yourself if desired.
 
@@ -330,11 +484,14 @@ Returns `[value, setValue]`.
 ### `useSharedFunction(key, fn, scopeName?)`
 Returns `{ state, trigger, forceTrigger, clear }`.
 
+### `useSharedSubscription(key, subscriber, scopeName?)`
+Returns `{ state, trigger, unsubscribe }`.
+
 ### `<SharedStatesProvider scopeName?>`
 Wrap children; optional `scopeName` (string). If omitted a random unique one is generated.
 
 ### Static
-`sharedStatesApi`, `sharedFunctionsApi` (see earlier table).
+`sharedStatesApi`, `sharedFunctionsApi`, `sharedSubscriptionsApi` (see earlier table).
 
 
 

package/dist/SharedData.d.ts

@@ -1,4 +1,4 @@
-import { AFunction, DataMapValue, NonEmptyString, Prefix } from './types';
+import { AFunction, DataMapValue, Prefix } from './types';
 type SharedDataType<T> = DataMapValue & T;
 export declare abstract class SharedData<T> {
     data: Map<string, SharedDataType<T>>;
@@ -13,10 +13,11 @@ export declare abstract class SharedData<T> {
     setValue(key: string, prefix: Prefix, data: T): void;
     has(key: string, prefix: Prefix): string | undefined;
     static prefix(key: string, prefix: Prefix): string;
+    useEffect(key: string, prefix: Prefix, unsub?: (() => void) | null): void;
 }
 export interface SharedApi<T> {
-    get: <S extends string = string>(key: NonEmptyString<S>, scopeName: Prefix) => T;
-    set: <S extends string = string>(key: NonEmptyString<S>, value: T, scopeName: Prefix) => void;
+    get: <S extends string = string>(key: S, scopeName: Prefix) => T;
+    set: <S extends string = string>(key: S, value: T, scopeName: Prefix) => void;
     clearAll: () => void;
     clear: (key: string, scopeName: Prefix) => void;
     has: (key: string, scopeName: Prefix) => boolean;

package/dist/hooks/index.d.ts

@@ -1,2 +1,3 @@
 export { useSharedState, sharedStatesApi } from './use-shared-state';
 export { useSharedFunction, sharedFunctionsApi } from './use-shared-function';
+export { useSharedSubscription, sharedSubscriptionsApi } from './use-shared-subscription';

package/dist/hooks/use-shared-function.d.ts

@@ -1,4 +1,4 @@
-import { AFunction, NonEmptyString, Prefix } from '../types';
+import { AFunction, Prefix } from '../types';
 import { SharedApi } from '../SharedData';
 type SharedFunctionsState<T> = {
     fnState: {
@@ -8,15 +8,15 @@ type SharedFunctionsState<T> = {
     };
 };
 export declare class SharedFunctionsApi implements SharedApi<SharedFunctionsState<unknown>> {
-    get<T, S extends string = string>(key: NonEmptyString<S>, scopeName?: Prefix): T;
-    set<T, S extends string = string>(key: NonEmptyString<S>, fnState: SharedFunctionsState<T>, scopeName?: Prefix): void;
+    get<T, S extends string = string>(key: S, scopeName?: Prefix): T;
+    set<T, S extends string = string>(key: S, fnState: SharedFunctionsState<T>, scopeName?: Prefix): void;
     clearAll(): void;
     clear(key: string, scopeName?: Prefix): void;
     has(key: string, scopeName?: Prefix): boolean;
     getAll(): Map<string, import('..').DataMapValue & SharedFunctionsState<unknown>>;
 }
 export declare const sharedFunctionsApi: SharedFunctionsApi;
-export declare const useSharedFunction: <T, Args extends unknown[], S extends string = string>(key: NonEmptyString<S>, fn: AFunction<T, Args>, scopeName?: Prefix) => {
+export declare const useSharedFunction: <T, Args extends unknown[], S extends string = string>(key: S, fn: AFunction<T, Args>, scopeName?: Prefix) => {
     readonly state: {
         results?: T | undefined;
         isLoading: boolean;

package/dist/hooks/use-shared-state.d.ts

@@ -1,10 +1,10 @@
-import { NonEmptyString, Prefix } from '../types';
+import { Prefix } from '../types';
 import { SharedApi } from '../SharedData';
 declare class SharedStatesApi implements SharedApi<{
     value: unknown;
 }> {
-    get<T, S extends string = string>(key: NonEmptyString<S>, scopeName?: Prefix): T;
-    set<T, S extends string = string>(key: NonEmptyString<S>, value: T, scopeName?: Prefix): void;
+    get<T, S extends string = string>(key: S, scopeName?: Prefix): T;
+    set<T, S extends string = string>(key: S, value: T, scopeName?: Prefix): void;
     clearAll(): void;
     clear(key: string, scopeName?: Prefix): void;
     has(key: string, scopeName?: Prefix): boolean;
@@ -13,5 +13,5 @@ declare class SharedStatesApi implements SharedApi<{
     }>;
 }
 export declare const sharedStatesApi: SharedStatesApi;
-export declare const useSharedState: <T, S extends string = string>(key: NonEmptyString<S>, value: T, scopeName?: Prefix) => readonly [T, (newValueOrCallbackToNewValue: T | ((prev: T) => T)) => void];
+export declare const useSharedState: <T, S extends string = string>(key: S, value: T, scopeName?: Prefix) => readonly [T, (newValueOrCallbackToNewValue: T | ((prev: T) => T)) => void];
 export {};

package/dist/hooks/use-shared-subscription.d.ts

@@ -0,0 +1,39 @@
+import { PotentialPromise, Prefix } from '../types';
+import { SharedApi } from '../SharedData';
+type Unsubscribe = () => void;
+export declare namespace SubscriberEvents {
+    type OnError = (error: unknown) => void;
+    type OnCompletion = () => void;
+    type Set<T> = (value: T) => void;
+}
+type Subscriber<T> = (set: SubscriberEvents.Set<T>, onError: SubscriberEvents.OnError, onCompletion: SubscriberEvents.OnCompletion) => PotentialPromise<Unsubscribe | void | undefined>;
+type SharedSubscriptionsState<T> = {
+    fnState: {
+        data?: T;
+        isLoading: boolean;
+        error?: unknown;
+        subscribed: boolean;
+    };
+    unsubscribe?: Unsubscribe | void;
+};
+export declare class SharedSubscriptionsApi implements SharedApi<SharedSubscriptionsState<unknown>> {
+    get<T, S extends string = string>(key: S, scopeName?: Prefix): T;
+    set<T, S extends string = string>(key: S, fnState: SharedSubscriptionsState<T>, scopeName?: Prefix): void;
+    clearAll(): void;
+    clear(key: string, scopeName?: Prefix): void;
+    has(key: string, scopeName?: Prefix): boolean;
+    getAll(): Map<string, import('..').DataMapValue & SharedSubscriptionsState<unknown>>;
+}
+export declare const sharedSubscriptionsApi: SharedSubscriptionsApi;
+export declare const useSharedSubscription: <T, S extends string = string>(key: S, subscriber: Subscriber<T>, scopeName?: Prefix) => {
+    readonly state: {
+        data?: T | undefined;
+        isLoading: boolean;
+        error?: unknown;
+        subscribed: boolean;
+    };
+    readonly trigger: () => void;
+    readonly forceTrigger: () => void;
+    readonly unsubscribe: () => void;
+};
+export {};

package/dist/lib/utils.d.ts

@@ -0,0 +1,3 @@
+import { NonEmptyString } from '../types';
+export declare const log: (...args: any[]) => void;
+export declare const ensureNonEmptyString: <T extends string>(value: T) => NonEmptyString<T>;