react-shared-states 1.0.11 → 1.0.13

package/README.md

@@ -23,7 +23,7 @@ Tiny, ergonomic, convention‑over‑configuration state, async function, and re
 * Predictable: key + scope ⇒ value. That’s it.
 
 
-## 🚀 Install
+## Install
 
 ```sh
 npm install react-shared-states
@@ -33,7 +33,7 @@ or
 pnpm add react-shared-states
 ```
 
-## ☕ 60‑Second TL;DR
+## 60‑Second TL;DR
 ```tsx
 import { useSharedState } from 'react-shared-states';
 
@@ -196,7 +196,7 @@ export default function App(){
 ```
 
 
-## 🧠 Core Concepts
+## Core Concepts
 | Concept                | Summary                                                                                                                                                            |
 |------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | Global by default      | No provider necessary. Same key => shared state.                                                                                                                   |
@@ -209,433 +209,92 @@ export default function App(){
 | 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?)`
-- `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 (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.).
-* Functions created with `createSharedFunction` are **static** and persist across `clearAll()` calls.
+## Selecting State Slices (`useSharedStateSelector`)
 
-### Pattern: lazy load on first render
-```tsx
-// profileFunction.ts
-export const profileFunction = createSharedFunction((id: string) => fetch(`/api/p/${id}`).then(r=>r.json()));
+When a shared state holds an object, you might only need a small piece of it.
+Using `useSharedState` will cause your component to re-render whenever *any* part of the object changes.
+To optimize performance and avoid unnecessary re-renders, you can use the `useSharedStateSelector` hook.
 
-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.
+This hook allows you to subscribe to a specific, memoized slice of a shared state.
+Your component will only re-render if the selected value changes.
+It uses `react-fast-compare` for efficient deep equality checks.
 
 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)
+- `const selectedValue = useSharedStateSelector(key, selector, scopeName?)`
+- `const selectedValue = useSharedStateSelector(sharedStateCreated, selector)`
 
-### 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';
+The `selector` is a function that receives the full state and returns the desired slice.
 
-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;
-  }
-);
+### Example: Subscribing to a slice of a user object
 
-function UserProfile({ userId }: { userId: string }) {
-  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>
-  );
-}
-```
+Imagine a shared state for user settings:
 
-### 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>
-  );
-}
+// settingsState.ts
+import { createSharedState } from 'react-shared-states';
+
+export const settingsState = createSharedState({
+  theme: 'dark',
+  notifications: {
+    email: true,
+    push: false,
+  },
+  language: 'en',
+});
 ```
 
-### Pattern: Server-Sent Events
-```tsx
-import { useEffect } from 'react';
-import { useSharedSubscription } from 'react-shared-states';
+A component that only cares about the theme can use `useSharedStateSelector` to avoid re-rendering when, for example, the notification settings change.
 
-function LiveUpdates() {
-  const { state, trigger } = useSharedSubscription(
-    'live-updates',
-    (set, error, complete) => {
-      const eventSource = new EventSource('/api/live-updates');
-      
-      eventSource.onopen = () => complete();
-      eventSource.onmessage = (event) => {
-        set(JSON.parse(event.data));
-      };
-      eventSource.onerror = error;
-      
-      return () => eventSource.close();
-    }
-  );
+```tsx
+import { useSharedState, useSharedStateSelector } from 'react-shared-states';
+import { settingsState } from './settingsState';
 
-  useEffect(() => {
-    trigger();
-  }, []);
+function ThemeDisplay() {
+  const theme = useSharedStateSelector(settingsState, (settings) => settings.theme);
+  
+  console.log('ThemeDisplay renders'); // This will only log when the theme changes
 
-  return <div>Latest: {JSON.stringify(state.data)}</div>;
+  return <div>Current theme: {theme}</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.
 
+function NotificationToggle() {
+  const [settings, setSettings] = useSharedState(settingsState);
 
-## 🛰️ Static APIs (outside React)
-## 🏛️ Static/Global Shared Resource Creation
+  const togglePush = () => {
+    setSettings(s => ({
+      ...s,
+      notifications: { ...s.notifications, push: !s.notifications.push }
+    }));
+  };
 
-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);
+  return <button onClick={togglePush}>Toggle Push Notifications</button>;
+}
 ```
-Useful for SSR hydration, event listeners, debugging, imperative workflows.
 
-```ts
-import { sharedStatesApi, sharedFunctionsApi, sharedSubscriptionsApi } from 'react-shared-states';
+In this example, clicking the `NotificationToggle` button will **not** cause `ThemeDisplay` to re-render.
 
-// Preload state (global scope by default)
-sharedStatesApi.set('bootstrap-data', { user: {...} });
-
-// Preload state in a named scope
-sharedStatesApi.set('bootstrap-data', { user: {...} }, 'myScope');
+### A Note on Type Safety
 
-// Read later
-const user = sharedStatesApi.get('bootstrap-data'); // global
-const userScoped = sharedStatesApi.get('bootstrap-data', 'myScope');
+For the best developer experience and full type safety,
+it is **highly recommended** to use `useSharedStateSelector` with a statically created shared state object from `createSharedState`.
 
-// Inspect all (returns nested object: { [scope]: { [key]: value } })
-console.log(sharedStatesApi.getAll());
+When you use a string key directly, the hook cannot infer the type of the state object.
+You would have to provide the types explicitly as generic arguments, or they will default to `any`.
 
-// 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');
+```tsx
+// Less safe: using a string key
+// You have to specify the types manually.
+const theme = useSharedStateSelector<{ theme: string; /*...other props*/ }, 'settings', string>(
+  'settings', 
+  (settings) => settings.theme
+);
 
-// For shared subscriptions
-const subState = sharedSubscriptionsApi.get('live-chat');
-const subStateScoped = sharedSubscriptionsApi.get('live-chat', 'myScope');
+// Recommended: using a created state object
+// Types are inferred automatically!
+const theme = useSharedStateSelector(settingsState, (settings) => settings.theme);
 ```
 
-## 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`)
+## Shared Async Functions (`useSharedFunction`)
 Signature:
 - `const { state, trigger, forceTrigger, clear } = useSharedFunction(key, asyncFn, scopeName?)`
 - `const { state, trigger, forceTrigger, clear } = useSharedFunction(sharedFunctionCreated)`
@@ -646,6 +305,7 @@ 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
@@ -665,7 +325,7 @@ const refresh = () => forceTrigger();
 ```
 
 
-## 📡 Real-time Subscriptions (`useSharedSubscription`)
+## Real-time Subscriptions (`useSharedSubscription`)
 Perfect for Firebase listeners, WebSocket connections,
 Server-Sent Events, or any streaming data source that needs cleanup.
 
@@ -807,10 +467,12 @@ Subscription semantics:
 * Components mounting later instantly get the latest `data` without re-subscribing.
 
 
-## 🛰️ Static APIs (outside React)
-## 🏛️ Static/Global Shared Resource Creation
+## 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:
+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';
@@ -866,7 +528,7 @@ const subStateScoped = sharedSubscriptionsApi.get('live-chat', 'myScope');
 `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
+## Scoping Rules Deep Dive
 Resolution order used inside hooks:
 1. Explicit 3rd parameter (`scopeName`)
 2. Nearest `SharedStatesProvider` above the component
@@ -877,7 +539,7 @@ Unnamed providers auto‑generate a random scope name: each mount = isolated isl
 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
+## Comparison Snapshot
 | Criterion      | react-shared-states                      | Redux Toolkit        | Zustand                          |
 |----------------|------------------------------------------|----------------------|----------------------------------|
 | Setup          | Install & call hook                      | Slice + store config | Create store function            |
@@ -889,7 +551,7 @@ Two providers sharing the same `scopeName` act as a single logical scope even if
 | Learning curve | Minutes                                  | Higher               | Low                              |
 
 
-## 🧪 Testing Tips
+## 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.
@@ -898,8 +560,7 @@ Two providers sharing the same `scopeName` act as a single logical scope even if
 
 ## ❓ 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.
+`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.
@@ -917,13 +578,19 @@ Subscriptions auto-cleanup when no components are listening. You can also manual
 Currently no built-in Suspense wrappers; wrap `useSharedFunction` yourself if desired.
 
 
-## 📚 Full API Reference
+## Full API Reference
 ### `useSharedState(key, initialValue, scopeName?)`
 Returns `[value, setValue]`.
 
 ### `useSharedState(sharedStateCreated)`
 Returns `[value, setValue]`.
 
+### `useSharedStateSelector(key, selector, scopeName?)`
+Returns the selected value.
+
+### `useSharedStateSelector(sharedStateCreated, selector)`
+Returns the selected value.
+
 ### `useSharedFunction(key, fn, scopeName?)`
 Returns `{ state, trigger, forceTrigger, clear }`.
 
@@ -944,7 +611,7 @@ Wrap children; optional `scopeName` (string). If omitted a random unique one is
 
 
 
-## 🤝 Contributions
+## Contributions
 
 We welcome contributions!
 If you'd like to improve `react-shared-states`,
@@ -962,4 +629,6 @@ feel free to [open an issue](https://github.com/HichemTab-tech/react-shared-stat
 ## 🌟 Acknowledgements
 
 Inspired by React's built-in primitives and the ergonomics of modern lightweight state libraries.
-Thanks to early adopters for feedback.
+Thanks to early adopters for feedback.
+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).

package/dist/hooks/index.d.ts

@@ -1,5 +1,5 @@
-export { useSharedState, sharedStatesApi, createSharedState, SharedStatesApi } from './use-shared-state';
-export type { SharedStateCreated } from './use-shared-state';
+export { useSharedState, sharedStatesApi, createSharedState, SharedStatesApi, useSharedStateSelector } from './use-shared-state';
+export type { SharedStateCreated, SharedStateSelector } from './use-shared-state';
 export { useSharedFunction, sharedFunctionsApi, createSharedFunction, SharedFunctionsApi } from './use-shared-function';
 export type { SharedFunctionStateReturn } from './use-shared-function';
 export { useSharedSubscription, sharedSubscriptionsApi, createSharedSubscription, SharedSubscriptionsApi } from './use-shared-subscription';

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

@@ -28,4 +28,7 @@ export interface SharedStateCreated<T> extends SharedCreated {
 export declare const createSharedState: <T>(initialValue: T, scopeName?: Prefix) => SharedStateCreated<T>;
 export declare function useSharedState<T, S extends string>(key: S, initialValue: T, scopeName?: Prefix): readonly [T, (v: T | ((prev: T) => T)) => void];
 export declare function useSharedState<T>(sharedStateCreated: SharedStateCreated<T>): readonly [T, (v: T | ((prev: T) => T)) => void];
+export type SharedStateSelector<S, T = S> = (original: S) => T;
+export declare function useSharedStateSelector<T, S extends string, R>(key: S, selector: SharedStateSelector<T, R>, scopeName?: Prefix): Readonly<R>;
+export declare function useSharedStateSelector<T, R>(sharedStateCreated: SharedStateCreated<T>, selector: SharedStateSelector<T, R>): Readonly<R>;
 export {};