react-shared-states 1.0.7 → 1.0.11

package/README.md

@@ -1,4 +1,3 @@
-
 # React Shared States
 
 **_Global state made as simple as useState, with zero config, built-in async caching, and automatic scoping._**
@@ -48,7 +47,6 @@ function B(){
 }
 
 function App() {
-  
   return (
     <>
       <A/>
@@ -69,7 +67,6 @@ function Scoped(){
 }
 
 function App() {
-
   return (
     <>
       <A/>
@@ -82,6 +79,33 @@ function App() {
 }
 ```
 
+---
+
+> **Tip:** For large apps, you can also use `createSharedState(initialValue, scopeName?)` to create and export reusable shared states. If you specify a `scopeName`, the state will always be found in that scope; otherwise, it defaults to global. This helps avoid key collisions and ensures type safety.
+
+```tsx
+import { useSharedState } from 'react-shared-states';
+export const sharedCounter = createSharedState(0);
+
+function A(){
+  const [count, setCount] = useSharedState(sharedCounter);
+  return <button onClick={()=>setCount(c=>c+1)}>A {count}</button>;
+}
+function B(){
+  const [count] = useSharedState(sharedCounter);
+  return <span>B sees {count}</span>;
+}
+
+function App() {
+  return (
+    <>
+      <A/>
+      <B/>
+    </>
+  )
+}
+```
+
 Override / jump to a named scope explicitly:
 ```tsx
 useSharedState('counter', 0, 'modal'); // 3rd arg is scopeName override
@@ -173,56 +197,69 @@ 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` / `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`).    |
+| 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`).                                       |
+| Static/shared creation | Use `createSharedState`, `createSharedFunction`, `createSharedSubscription` to export reusable, type-safe shared resources that persist across `clearAll()` calls. |
 
 
 ## 🏗️ Sharing State (`useSharedState`)
-Signature: `const [value, setValue] = useSharedState(key, initialValue, scopeName?);`
+Signature: 
+- `const [value, setValue] = useSharedState(key, initialValue, scopeName?)`
+- `const [value, setValue] = useSharedState(sharedStateCreated)`
 
 Behavior:
 * First hook call (per key + scope) seeds with `initialValue`.
 * Subsequent mounts with same key+scope ignore their `initialValue` (consistent source of truth).
 * Setter accepts either value or updater `(prev)=>next`.
 * React batching + equality check: listeners fire only when the value reference actually changes.
+* States created with `createSharedState` are **static** by default and are not removed by `clear()` or `clearAll()`, ensuring they persist.
 
 ### Examples
-1. Global theme
+1. Global theme (recommended for large apps)
     ```tsx
-    const [theme, setTheme] = useSharedState('theme', 'light');
+    // themeState.ts
+    export const themeState = createSharedState('light');
+    // In components
+    const [theme, setTheme] = useSharedState(themeState);
     ```
 2. Isolated wizard progress
     ```tsx
+    const wizardProgress = createSharedState(0);
     <SharedStatesProvider>
       <Wizard/>
     </SharedStatesProvider>
+    // In Wizard
+    const [step, setStep] = useSharedState(wizardProgress);
     ```
 3. Forcing cross‑portal sync
     ```tsx
+    const navState = createSharedState('closed', 'nav');
     <SharedStatesProvider scopeName="nav" children={<PrimaryNav/>} />
     <Portal>
       <SharedStatesProvider scopeName="nav" children={<MobileNav/>} />
     </Portal>
+    // In both navs
+    const [navOpen, setNavOpen] = useSharedState(navState);
     ```
 4. Overriding nearest provider
     ```tsx
     // Even if inside a provider, this explicitly binds to global
-    const [flag, setFlag] = useSharedState('feature-x-enabled', false, '_global');
+    const globalFlag = createSharedState(false, '_global');
+    const [flag, setFlag] = useSharedState(globalFlag);
     ```
 
 
 ## ⚡ Shared Async Functions (`useSharedFunction`)
 Signature:
-```ts
-const { state, trigger, forceTrigger, clear } = useSharedFunction(key, asyncFn, scopeName?);
-```
+- `const { state, trigger, forceTrigger, clear } = useSharedFunction(key, asyncFn, scopeName?)`
+- `const { state, trigger, forceTrigger, clear } = useSharedFunction(sharedFunctionCreated)`
 `state` shape: `{ results?: T; isLoading: boolean; error?: unknown }`
 
 Semantics:
@@ -230,15 +267,16 @@ Semantics:
 * Multiple components with the same key+scope share one execution + result.
 * `clear()` deletes the cache (next trigger re-runs).
 * You decide when to invoke `trigger` (e.g. on mount, on button click, when dependencies change, etc.).
+* Functions created with `createSharedFunction` are **static** and persist across `clearAll()` calls.
 
 ### Pattern: lazy load on first render
 ```tsx
+// profileFunction.ts
+export const profileFunction = createSharedFunction((id: string) => fetch(`/api/p/${id}`).then(r=>r.json()));
+
 function Profile({id}:{id:string}){
-  const { state, trigger } = useSharedFunction(`profile-${id}`, () => fetch(`/api/p/${id}`).then(r=>r.json()));
-  
-  if(!state.results && !state.isLoading) trigger();
-  if(state.isLoading) return <p>Loading...</p>;
-  return <pre>{JSON.stringify(state.results,null,2)}</pre>
+  const { state, trigger } = useSharedFunction(profileFunction);
+  // ...same as before
 }
 ```
 
@@ -254,50 +292,425 @@ 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?);
-```
+- `const { state, trigger, unsubscribe } = useSharedSubscription(key, subscriber, scopeName?)`
+- `const { state, trigger, unsubscribe } = useSharedSubscription(sharedSubscriptionCreated)`
 
 `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
+- `error(error)`: Handle errors 
+- `complete()`: Mark loading as complete
 - Returns: Optional cleanup function (called on unsubscribe/unmount)
 
 ### Pattern: Firebase Firestore real-time listener
 ```tsx
-import { useEffect } from 'react';
+// userSubscription.ts
 import { onSnapshot, doc } from 'firebase/firestore';
-import { useSharedSubscription } from 'react-shared-states';
-import { db } from './firebase-config'; // your Firebase config
+import { createSharedSubscription } from 'react-shared-states';
+import { db } from './firebase-config';
+
+export const userSubscription = createSharedSubscription(
+  (set, error, complete) => {
+    const userDocRef = doc(db, 'users', 'some-user-id');
+    const unsubscribe = onSnapshot(userDocRef, 
+      (doc) => {
+        if (doc.exists()) {
+          set(doc.data());
+        } else {
+          error(new Error('User not found'));
+        }
+        complete();
+      }, 
+      (err) => {
+        error(err);
+        complete();
+      }
+    );
+    return unsubscribe;
+  }
+);
 
 function UserProfile({ userId }: { userId: string }) {
-  const { state, trigger, unsubscribe } = useSharedSubscription(
-    `user-${userId}`,
-    async (set, onError, onCompletion) => {
-      const userRef = doc(db, 'users', userId);
+  const { state, trigger, unsubscribe } = useSharedSubscription(userSubscription);
+  // 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, error, complete) => {
+      const ws = new WebSocket(`ws://chat-server/${roomId}`);
+      
+      ws.onopen = () => complete();
+      ws.onmessage = (event) => {
+        const message = JSON.parse(event.data);
+        set(prev => [...(prev || []), message]);
+      };
+      ws.onerror = error;
+      
+      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, error, complete) => {
+      const eventSource = new EventSource('/api/live-updates');
       
-      // 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
-      );
+      eventSource.onopen = () => complete();
+      eventSource.onmessage = (event) => {
+        set(JSON.parse(event.data));
+      };
+      eventSource.onerror = error;
       
-      // Return cleanup function
-      return unsubscribe;
+      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)
+## 🏛️ Static/Global Shared Resource Creation
+
+For large apps, you can create and export shared state, function,
+or subscription objects for type safety and to avoid key collisions.
+This pattern is similar to Zustand or Jotai stores:
+
+```ts
+import { createSharedState, createSharedFunction, createSharedSubscription, useSharedState, useSharedFunction, useSharedSubscription } from 'react-shared-states';
+
+// Create and export shared resources
+export const counterState = createSharedState(0);
+export const fetchUserFunction = createSharedFunction(() => fetch('/api/me').then(r => r.json()));
+export const chatSubscription = createSharedSubscription((set, error, complete) => {/* ... */});
+
+// Use anywhere in your app
+const [count, setCount] = useSharedState(counterState);
+const { state, trigger } = useSharedFunction(fetchUserFunction);
+const { state, trigger, unsubscribe } = useSharedSubscription(chatSubscription);
+```
+Useful for SSR hydration, event listeners, debugging, imperative workflows.
+
+```ts
+import { sharedStatesApi, sharedFunctionsApi, sharedSubscriptionsApi } from 'react-shared-states';
+
+// Preload state (global scope by default)
+sharedStatesApi.set('bootstrap-data', { user: {...} });
+
+// Preload state in a named scope
+sharedStatesApi.set('bootstrap-data', { user: {...} }, 'myScope');
+
+// Read later
+const user = sharedStatesApi.get('bootstrap-data'); // global
+const userScoped = sharedStatesApi.get('bootstrap-data', 'myScope');
+
+// Inspect all (returns nested object: { [scope]: { [key]: value } })
+console.log(sharedStatesApi.getAll());
+
+// Clear all keys in a scope
+sharedStatesApi.clearScope('myScope');
+
+// For shared functions
+const fnState = sharedFunctionsApi.get('profile-123');
+const fnStateScoped = sharedFunctionsApi.get('profile-123', 'myScope');
+
+// For shared subscriptions
+const subState = sharedSubscriptionsApi.get('live-chat');
+const subStateScoped = sharedSubscriptionsApi.get('live-chat', 'myScope');
+```
+
+## API summary:
+
+| API                      | Methods                                                                                                                                                                                 |
+|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `sharedStatesApi`        | `get(key, scopeName?)`, `set(key, val, scopeName?)`, `has(key, scopeName?)`, `clear(key, scopeName?)`, `clearAll(withoutListeners?, withStatic?)`, `clearScope(scopeName?)`, `getAll()` |
+| `sharedFunctionsApi`     | `get(key, scopeName?)`, `set(key, val, scopeName?)`, `has(key, scopeName?)`, `clear(key, scopeName?)`, `clearAll(withoutListeners?, withStatic?)`, `clearScope(scopeName?)`, `getAll()` |
+| `sharedSubscriptionsApi` | `get(key, scopeName?)`, `set(key, val, scopeName?)`, `has(key, scopeName?)`, `clear(key, scopeName?)`, `clearAll(withoutListeners?, withStatic?)`, `clearScope(scopeName?)`, `getAll()` |
+
+`scopeName` defaults to `"_global"`. Internally, keys are stored as `${scope}//${key}`. The `.getAll()` method returns a nested object: `{ [scope]: { [key]: value } }`.
+
+
+## 🧩 Scoping Rules Deep Dive
+Resolution order used inside hooks:
+1. Explicit 3rd parameter (`scopeName`)
+2. Nearest `SharedStatesProvider` above the component
+3. The implicit global scope (`_global`)
+
+Unnamed providers auto‑generate a random scope name: each mount = isolated island.
+
+Two providers sharing the same `scopeName` act as a single logical scope even if they are disjoint in the tree (great for portals / microfrontends).
+
+
+## 🆚 Comparison Snapshot
+| Criterion      | react-shared-states                      | Redux Toolkit        | Zustand                          |
+|----------------|------------------------------------------|----------------------|----------------------------------|
+| Setup          | Install & call hook                      | Slice + store config | Create store function            |
+| Global state   | Yes (by key)                             | Yes                  | Yes                              |
+| Scoped state   | Built-in (providers + names + overrides) | Needs custom logic   | Needs multiple stores / contexts |
+| Async helper   | `useSharedFunction` (cache + status)     | Thunks / RTK Query   | Manual or middleware             |
+| Boilerplate    | Near zero                                | Moderate             | Low                              |
+| Static access  | Yes (APIs)                               | Yes (store)          | Yes (store)                      |
+| Learning curve | Minutes                                  | Higher               | Low                              |
+
+
+## 🧪 Testing Tips
+* Use static APIs to assert state after component interactions.
+* `sharedStatesApi.clearAll(false, true)`, `sharedFunctionsApi.clearAll(false, true)`, `sharedSubscriptionsApi.clearAll(false, true)` in `afterEach` to isolate tests and clear static states.
+* 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
+**Q: How do I reset a single shared state?**  
+`sharedStatesApi.clear('key')`. If the state was created with `createSharedState`, it will reset to its initial value. Otherwise, it will be removed.
+
+**Q: Can I pre-hydrate data on the server?**  
+Yes. Call `sharedStatesApi.set(...)` during bootstrap, then first client hook usage will pick it up.
+
+**Q: How do I avoid accidental key collisions?**  
+Prefix keys by domain (e.g. `user:profile`, `cart:items`) or rely on provider scoping.
+
+**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.
+
+
+## 📚 Full API Reference
+### `useSharedState(key, initialValue, scopeName?)`
+Returns `[value, setValue]`.
+
+### `useSharedState(sharedStateCreated)`
+Returns `[value, setValue]`.
+
+### `useSharedFunction(key, fn, scopeName?)`
+Returns `{ state, trigger, forceTrigger, clear }`.
+
+### `useSharedFunction(sharedFunctionCreated)`
+Returns `{ state, trigger, forceTrigger, clear }`.
+
+### `useSharedSubscription(key, subscriber, scopeName?)`
+Returns `{ state, trigger, unsubscribe }`.
+
+### `useSharedSubscription(sharedSubscriptionCreated)`
+Returns `{ state, trigger, unsubscribe }`.
+
+### `<SharedStatesProvider scopeName?>`
+Wrap children; optional `scopeName` (string). If omitted a random unique one is generated.
+
+### Static APIs
+`sharedStatesApi`, `sharedFunctionsApi`, `sharedSubscriptionsApi` (see earlier table).
+
+
+
+## 🤝 Contributions
+
+We welcome contributions!
+If you'd like to improve `react-shared-states`,
+feel free to [open an issue](https://github.com/HichemTab-tech/react-shared-states/issues) or [submit a pull request](https://github.com/HichemTab-tech/react-shared-states/pulls).
+
+
+## Author
+
+- [@HichemTab-tech](https://www.github.com/HichemTab-tech)
+
+## License
+
+[MIT](https://github.com/HichemTab-tech/react-shared-states/blob/master/LICENSE)
+
+## 🌟 Acknowledgements
+
+Inspired by React's built-in primitives and the ergonomics of modern lightweight state libraries.
+Thanks to early adopters for feedback.
+
+
+
+## 🏗️ Sharing State (`useSharedState`)
+Signature: 
+- `const [value, setValue] = useSharedState(key, initialValue, scopeName?)`
+- `const [value, setValue] = useSharedState(sharedStateCreated)`
+
+Behavior:
+* First hook call (per key + scope) seeds with `initialValue`.
+* Subsequent mounts with same key+scope ignore their `initialValue` (consistent source of truth).
+* Setter accepts either value or updater `(prev)=>next`.
+* React batching + equality check: listeners fire only when the value reference actually changes.
+
+### Examples
+1. Global theme (recommended for large apps)
+    ```tsx
+    // themeState.ts
+    export const themeState = createSharedState('light');
+    // In components
+    const [theme, setTheme] = useSharedState(themeState);
+    ```
+2. Isolated wizard progress
+    ```tsx
+    const wizardProgress = createSharedState(0);
+    <SharedStatesProvider>
+      <Wizard/>
+    </SharedStatesProvider>
+    // In Wizard
+    const [step, setStep] = useSharedState(wizardProgress);
+    ```
+3. Forcing cross‑portal sync
+    ```tsx
+    const navState = createSharedState('closed', 'nav');
+    <SharedStatesProvider scopeName="nav" children={<PrimaryNav/>} />
+    <Portal>
+      <SharedStatesProvider scopeName="nav" children={<MobileNav/>} />
+    </Portal>
+    // In both navs
+    const [navOpen, setNavOpen] = useSharedState(navState);
+    ```
+4. Overriding nearest provider
+    ```tsx
+    // Even if inside a provider, this explicitly binds to global
+    const globalFlag = createSharedState(false, '_global');
+    const [flag, setFlag] = useSharedState(globalFlag);
+    ```
+
+
+## ⚡ Shared Async Functions (`useSharedFunction`)
+Signature:
+- `const { state, trigger, forceTrigger, clear } = useSharedFunction(key, asyncFn, scopeName?)`
+- `const { state, trigger, forceTrigger, clear } = useSharedFunction(sharedFunctionCreated)`
+`state` shape: `{ results?: T; isLoading: boolean; error?: unknown }`
+
+Semantics:
+* First `trigger()` (implicit or manual) runs the function; subsequent calls do nothing while loading or after success (cached) unless you `forceTrigger()`.
+* Multiple components with the same key+scope share one execution + result.
+* `clear()` deletes the cache (next trigger re-runs).
+* You decide when to invoke `trigger` (e.g. on mount, on button click, when dependencies change, etc.).
+
+### Pattern: lazy load on first render
+```tsx
+// profileFunction.ts
+export const profileFunction = createSharedFunction((id: string) => fetch(`/api/p/${id}`).then(r=>r.json()));
+
+function Profile({id}:{id:string}){
+  const { state, trigger } = useSharedFunction(profileFunction);
+  // ...same as before
+}
+```
+
+### Pattern: always fetch fresh
+```tsx
+const { state, forceTrigger } = useSharedFunction('server-time', () => fetch('/time').then(r=>r.text()));
+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:
+- `const { state, trigger, unsubscribe } = useSharedSubscription(key, subscriber, scopeName?)`
+- `const { state, trigger, unsubscribe } = useSharedSubscription(sharedSubscriptionCreated)`
+
+`state` shape: `{ data?: T; isLoading: boolean; error?: unknown; subscribed: boolean }`
+
+The `subscriber` function receives three callbacks:
+- `set(data)`: Update the shared data
+- `error(error)`: Handle errors 
+- `complete()`: Mark loading as complete
+- Returns: Optional cleanup function (called on unsubscribe/unmount)
+
+### Pattern: Firebase Firestore real-time listener
+```tsx
+// userSubscription.ts
+import { onSnapshot, doc } from 'firebase/firestore';
+import { createSharedSubscription } from 'react-shared-states';
+import { db } from './firebase-config';
+
+export const userSubscription = createSharedSubscription(
+  (set, error, complete) => {
+    const userDocRef = doc(db, 'users', 'some-user-id');
+    const unsubscribe = onSnapshot(userDocRef, 
+      (doc) => {
+        if (doc.exists()) {
+          set(doc.data());
+        } else {
+          error(new Error('User not found'));
+        }
+        complete();
+      }, 
+      (err) => {
+        error(err);
+        complete();
+      }
+    );
+    return unsubscribe;
+  }
+);
+
+function UserProfile({ userId }: { userId: string }) {
+  const { state, trigger, unsubscribe } = useSharedSubscription(userSubscription);
   // Start listening when component mounts
   useEffect(() => {
     trigger();
@@ -325,15 +738,15 @@ import { useSharedSubscription } from 'react-shared-states';
 function ChatRoom({ roomId }: { roomId: string }) {
   const { state, trigger } = useSharedSubscription(
     `chat-${roomId}`,
-    (set, onError, onCompletion) => {
+    (set, error, complete) => {
       const ws = new WebSocket(`ws://chat-server/${roomId}`);
       
-      ws.onopen = () => onCompletion();
+      ws.onopen = () => complete();
       ws.onmessage = (event) => {
         const message = JSON.parse(event.data);
         set(prev => [...(prev || []), message]);
       };
-      ws.onerror = onError;
+      ws.onerror = error;
       
       return () => ws.close();
     }
@@ -365,14 +778,14 @@ import { useSharedSubscription } from 'react-shared-states';
 function LiveUpdates() {
   const { state, trigger } = useSharedSubscription(
     'live-updates',
-    (set, onError, onCompletion) => {
+    (set, error, complete) => {
       const eventSource = new EventSource('/api/live-updates');
       
-      eventSource.onopen = () => onCompletion();
+      eventSource.onopen = () => complete();
       eventSource.onmessage = (event) => {
         set(JSON.parse(event.data));
       };
-      eventSource.onerror = onError;
+      eventSource.onerror = error;
       
       return () => eventSource.close();
     }
@@ -395,36 +808,62 @@ Subscription semantics:
 
 
 ## 🛰️ Static APIs (outside React)
+## 🏛️ Static/Global Shared Resource Creation
+
+For large apps, you can create and export shared state, function, or subscription objects for type safety and to avoid key collisions. This pattern is similar to Zustand or Jotai stores:
+
+```ts
+import { createSharedState, createSharedFunction, createSharedSubscription, useSharedState, useSharedFunction, useSharedSubscription } from 'react-shared-states';
+
+// Create and export shared resources
+export const counterState = createSharedState(0);
+export const fetchUserFunction = createSharedFunction(() => fetch('/api/me').then(r => r.json()));
+export const chatSubscription = createSharedSubscription((set, error, complete) => {/* ... */});
+
+// Use anywhere in your app
+const [count, setCount] = useSharedState(counterState);
+const { state, trigger } = useSharedFunction(fetchUserFunction);
+const { state, trigger, unsubscribe } = useSharedSubscription(chatSubscription);
+```
 Useful for SSR hydration, event listeners, debugging, imperative workflows.
 
 ```ts
 import { sharedStatesApi, sharedFunctionsApi, sharedSubscriptionsApi } from 'react-shared-states';
 
-// Preload state
+// Preload state (global scope by default)
 sharedStatesApi.set('bootstrap-data', { user: {...} });
 
+// Preload state in a named scope
+sharedStatesApi.set('bootstrap-data', { user: {...} }, 'myScope');
+
 // Read later
-const user = sharedStatesApi.get('bootstrap-data');
+const user = sharedStatesApi.get('bootstrap-data'); // global
+const userScoped = sharedStatesApi.get('bootstrap-data', 'myScope');
 
-// Inspect all
-console.log(sharedStatesApi.getAll()); // Map with prefixed keys
+// Inspect all (returns nested object: { [scope]: { [key]: value } })
+console.log(sharedStatesApi.getAll());
+
+// Clear all keys in a scope
+sharedStatesApi.clearScope('myScope');
 
 // For shared functions
 const fnState = sharedFunctionsApi.get('profile-123');
+const fnStateScoped = sharedFunctionsApi.get('profile-123', 'myScope');
 
 // For shared subscriptions
 const subState = sharedSubscriptionsApi.get('live-chat');
+const subStateScoped = sharedSubscriptionsApi.get('live-chat', 'myScope');
 ```
 
 ## 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()`  |
-| `sharedSubscriptionsApi` | `get(key, scope?)` (returns sub state), `set`, `has`, `clear`, `clearAll`, `getAll()` |
+| API                      | Methods                                                                                                                                                                                 |
+|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `sharedStatesApi`        | `get(key, scopeName?)`, `set(key, val, scopeName?)`, `has(key, scopeName?)`, `clear(key, scopeName?)`, `clearAll(withoutListeners?, withStatic?)`, `clearScope(scopeName?)`, `getAll()` |
+| `sharedFunctionsApi`     | `get(key, scopeName?)`, `set(key, val, scopeName?)`, `has(key, scopeName?)`, `clear(key, scopeName?)`, `clearAll(withoutListeners?, withStatic?)`, `clearScope(scopeName?)`, `getAll()` |
+| `sharedSubscriptionsApi` | `get(key, scopeName?)`, `set(key, val, scopeName?)`, `has(key, scopeName?)`, `clear(key, scopeName?)`, `clearAll(withoutListeners?, withStatic?)`, `clearScope(scopeName?)`, `getAll()` |
 
-`scope` defaults to `"_global"`. Internally keys are stored as `${scope}_${key}`.
+`scopeName` defaults to `"_global"`. Internally, keys are stored as `${scope}//${key}`. The `.getAll()` method returns a nested object: `{ [scope]: { [key]: value } }`.
 
 
 ## 🧩 Scoping Rules Deep Dive
@@ -452,14 +891,15 @@ 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()`, `sharedFunctionsApi.clearAll()`, `sharedSubscriptionsApi.clearAll()` in `afterEach` to isolate tests.
+* `sharedStatesApi.clearAll(false, true)`, `sharedFunctionsApi.clearAll(false, true)`, `sharedSubscriptionsApi.clearAll(false, true)` in `afterEach` to isolate tests and clear static states.
 * 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
 **Q: How do I reset a single shared state?**  
-`sharedStatesApi.clear('key')` or inside component: call a setter with the initial value.
+`sharedStatesApi.clear('key')`. If the state was created with `createSharedState`, it will reset to its initial value.
+Otherwise, it will be removed.
 
 **Q: Can I pre-hydrate data on the server?**  
 Yes. Call `sharedStatesApi.set(...)` during bootstrap, then first client hook usage will pick it up.
@@ -481,16 +921,25 @@ Currently no built-in Suspense wrappers; wrap `useSharedFunction` yourself if de
 ### `useSharedState(key, initialValue, scopeName?)`
 Returns `[value, setValue]`.
 
+### `useSharedState(sharedStateCreated)`
+Returns `[value, setValue]`.
+
 ### `useSharedFunction(key, fn, scopeName?)`
 Returns `{ state, trigger, forceTrigger, clear }`.
 
+### `useSharedFunction(sharedFunctionCreated)`
+Returns `{ state, trigger, forceTrigger, clear }`.
+
 ### `useSharedSubscription(key, subscriber, scopeName?)`
 Returns `{ state, trigger, unsubscribe }`.
 
+### `useSharedSubscription(sharedSubscriptionCreated)`
+Returns `{ state, trigger, unsubscribe }`.
+
 ### `<SharedStatesProvider scopeName?>`
 Wrap children; optional `scopeName` (string). If omitted a random unique one is generated.
 
-### Static
+### Static APIs
 `sharedStatesApi`, `sharedFunctionsApi`, `sharedSubscriptionsApi` (see earlier table).