react-shared-states 1.0.0

package/.editorconfig

@@ -0,0 +1,9 @@
+# EditorConfig is awesome: https://editorconfig.org
+
+root = true
+
+[*]
+indent_size = 4
+
+[*.md]
+indent_size = 2

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+hichem.taboukouyout@hichemtab-tech.me.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

package/CONTRIBUTING.md

@@ -0,0 +1,112 @@
+# 👥 Contributing to React shared states
+
+Thank you for your interest in contributing to this project! Open source contributions help improve projects, introduce new ideas, and build a better community.
+
+---
+
+## 🚨 Before You Start
+
+Before contributing, please:
+
+- Browse [existing issues](https://github.com/HichemTab-tech/react-shared-states/issues) to see if your issue or feature idea has already been raised.
+- If your idea or issue hasn't been addressed, feel free to [create a new issue](https://github.com/HichemTab-tech/react-shared-states/issues/new).
+
+---
+
+## 📄 Code of Conduct
+
+Please ensure your contributions follow these general guidelines:
+
+- Be respectful and professional at all times.
+- Treat everyone in the community with kindness.
+- Discuss constructively and respectfully.
+
+Any harassment or inappropriate behavior is strictly prohibited.
+
+---
+
+## ⚙️ Setting Up Your Environment
+
+To start contributing to the project, follow these steps:
+
+1. Fork this repository on GitHub.
+2. Clone your forked repository:
+
+    ```sh
+    git clone https://github.com/YOUR_GITHUB_USERNAME/react-shared-states
+    cd react-shared-states
+    ```
+
+3. Install dependencies with your preferred package manager:
+
+- npm:
+```sh
+npm install
+```
+
+- pnpm:
+```sh
+pnpm install
+```
+
+---
+
+## 🔨 Making Changes
+
+To submit a feature or bug fix, please:
+
+1. Create a branch from the `main` branch. Name the branch according to your feature or bug fix:
+
+    ```sh
+    git checkout -b feature/CoolNewFeature
+    ```
+
+    or for bug fixes:
+
+    ```sh
+    git checkout -b fix/bug-description
+    ```
+
+2. After making your necessary changes, run relevant checks and tests to ensure everything works correctly:
+
+    ```sh
+    npm test
+    ```
+
+    or with pnpm:
+
+    ```sh
+    pnpm test
+    ```
+
+3. Stage and commit your changes clearly describing what has been changed:
+
+    ```sh
+    git add .
+    git commit -m 'feat: Add CoolNewFeature to improve performance'
+    ```
+
+4. Push your branch to your forked repo:
+
+    ```sh
+    git push origin feature/CoolNewFeature
+    ```
+
+---
+
+## 📝 Submitting a Pull Request
+
+When your changes are ready:
+
+1. Open GitHub and navigate to your forked repository.
+2. Click `Compare & pull request`.
+3. Clearly explain the following in your pull request description:
+   - **What changes you made and why they are needed.**
+   - **Any linked relevant issues (e.g., "**Closes #number**").**
+4. Wait for project maintainers review to suggest changes or to merge your PR.
+
+---
+
+## 📌 Commit Message Guidelines
+
+Write clear commit messages, formatted this way:

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hichem Taboukouyout
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,359 @@
+
+# React Shared States
+
+**_Global state made as simple as useState, with zero config, built-in async caching, and automatic scoping._**
+
+![react-shared-states banner](assets/banner.png)
+
+---
+
+[![npm version](https://img.shields.io/npm/v/react-shared-states)](https://www.npmjs.com/package/react-shared-states)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/react-shared-states)](https://bundlephobia.com/package/react-shared-states)
+[![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.
+
+## 🔥 Why this instead of Redux / Zustand / Context soup?
+* 0 config. Just pick a key: `useSharedState('cart', [])`.
+* Automatic scoping: nearest `SharedStatesProvider` wins; omit it for global.
+* Cross‑tree sharing via named scopes (two providers with same `scopeName` share data) – powerful for portals/modals/micro‑frontends.
+* Async functions become cached shared resources via `useSharedFunction` (built‑in loading, error, results, reentrancy guard, manual or forced refresh).
+* Static APIs (`sharedStatesApi`, `sharedFunctionsApi`) let you prime / read / mutate outside React (SSR, event buses, dev tools, tests).
+* No custom store objects, reducers, actions, selectors, immer, proxies, or serialization hoops.
+* Predictable: key + scope ⇒ value. That’s it.
+
+
+## 🚀 Install
+
+```sh
+npm install react-shared-states
+```
+or
+```sh
+pnpm add react-shared-states
+```
+
+## ☕ 60‑Second TL;DR
+```tsx
+import { useSharedState } from 'react-shared-states';
+
+function A(){
+  const [count, setCount] = useSharedState('counter', 0);
+  return <button onClick={()=>setCount(c=>c+1)}>A {count}</button>;
+}
+function B(){
+  const [count] = useSharedState('counter', 0);
+  return <span>B sees {count}</span>;
+}
+
+function App() {
+  
+  return (
+    <>
+      <A/>
+      <B/>
+    </>
+  )
+}
+```
+Same key ⇒ same state (global scope by default).
+
+Add a scope:
+```tsx
+import { SharedStatesProvider, useSharedState } from 'react-shared-states';
+
+function Scoped(){
+  const [count, set] = useSharedState('counter', 0); // isolated inside provider
+  return <button onClick={()=>set(c=>c+1)}>Scoped {count}</button>;
+}
+
+function App() {
+
+  return (
+    <>
+      <A/>
+      <B/>
+      <SharedStatesProvider>
+        <Scoped/>
+      </SharedStatesProvider>
+    </>
+  )
+}
+```
+
+Override / jump to a named scope explicitly:
+```tsx
+useSharedState('counter', 0, 'modal'); // 3rd arg is scopeName override
+```
+
+Two separate trees with the same `SharedStatesProvider scopeName` share their data:
+```tsx
+<SharedStatesProvider scopeName="modal">
+  <ModalContent/>
+</SharedStatesProvider>
+<Portal target={...}>
+  <SharedStatesProvider scopeName="modal">
+    <FloatingToolbar/>
+  </SharedStatesProvider>
+</Portal>
+function App() {
+
+  return (
+    <>
+      <SharedStatesProvider scopeName="modal">
+        <ModalContent/>
+      </SharedStatesProvider>
+      <Portal target={...}>
+        <SharedStatesProvider scopeName="modal">
+          <FloatingToolbar/>
+        </SharedStatesProvider>
+      </Portal>
+    </>
+  )
+}
+```
+
+Async shared function (one fetch, instant reuse when new component mounts):
+```tsx
+import { useEffect, useState } from 'react';
+import { useSharedFunction } from 'react-shared-states';
+
+// Any async callback you want to share
+const fetchCurrentUser = () => fetch('/api/me').then(r => r.json());
+
+function UserHeader(){
+  const { state, trigger } = useSharedFunction('current-user', fetchCurrentUser);
+  
+  useEffect(() => {
+    
+    trigger();
+    
+  }, []);
+  
+  if(state.isLoading && !state.results) return <p>Loading user...</p>;
+  
+  if(state.error) return <p style={{color:'red'}}>Failed.</p>;
+  
+  return <h1>{state.results.name}</h1>;
+}
+
+function UserDetails(){
+  const { state, trigger } = useSharedFunction('current-user', fetchCurrentUser);
+  // This effect will run when the component appears later, but fetch is already cached so trigger does nothing.
+  useEffect(() => {
+
+    trigger();
+
+  }, []);
+
+  if(state.isLoading && !state.results) return <p>Loading user...</p>; // this will not happen, cuz we already have the shared result
+  if(state.error) return <p style={{color:'red'}}>Failed.</p>; // this will not happen, cuz we already have the shared result
+  
+  return <pre>{JSON.stringify(state.results, null, 2)}</pre>;
+}
+
+export default function App(){
+  const [showDetails, setShowDetails] = useState(false);
+  return (
+    <div>
+      <UserHeader/>
+      <button onClick={()=>setShowDetails(s=>!s)}>
+        {showDetails ? 'Hide details' : 'Show details'}
+      </button>
+      {showDetails && <UserDetails/>}
+    </div>
+  );
+}
+
+// If you need to force a refetch somewhere:
+// const { forceTrigger } = useSharedFunction('current-user', fetchCurrentUser);
+// forceTrigger(); // bypass cache & re-run
+```
+
+
+## 🧠 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`).                                            |
+
+
+## 🏗️ Sharing State (`useSharedState`)
+Signature: `const [value, setValue] = useSharedState(key, initialValue, scopeName?);`
+
+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
+    ```tsx
+    const [theme, setTheme] = useSharedState('theme', 'light');
+    ```
+2. Isolated wizard progress
+    ```tsx
+    <SharedStatesProvider>
+      <Wizard/>
+    </SharedStatesProvider>
+    ```
+3. Forcing cross‑portal sync
+    ```tsx
+    <SharedStatesProvider scopeName="nav" children={<PrimaryNav/>} />
+    <Portal>
+      <SharedStatesProvider scopeName="nav" children={<MobileNav/>} />
+    </Portal>
+    ```
+4. Overriding nearest provider
+    ```tsx
+    // Even if inside a provider, this explicitly binds to global
+    const [flag, setFlag] = useSharedState('feature-x-enabled', false, '_global');
+    ```
+
+
+## ⚡ Shared Async Functions (`useSharedFunction`)
+Signature:
+```ts
+const { state, trigger, forceTrigger, clear } = useSharedFunction(key, asyncFn, scopeName?);
+```
+`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
+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>
+}
+```
+
+### Pattern: always fetch fresh
+```tsx
+const { state, forceTrigger } = useSharedFunction('server-time', () => fetch('/time').then(r=>r.text()));
+const refresh = () => forceTrigger();
+```
+
+
+## 🛰️ Static APIs (outside React)
+Useful for SSR hydration, event listeners, debugging, imperative workflows.
+
+```ts
+import { sharedStatesApi, sharedFunctionsApi } from 'react-shared-states';
+
+// Preload
+sharedStatesApi.set('bootstrap-data', { user: {...} });
+
+// Read later
+const user = sharedStatesApi.get('bootstrap-data');
+
+// Inspect all
+console.log(sharedStatesApi.getAll()); // Map with prefixed keys
+
+// For shared functions
+const fnState = sharedFunctionsApi.get('profile-123');
+```
+
+## 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()` |
+
+`scope` defaults to `"_global"`. Internally keys are stored as `${scope}_${key}`.
+
+
+## 🧩 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()` in `afterEach` to isolate tests.
+* For async functions: trigger once, await UI stabilization, assert `results` present.
+
+
+## ❓ FAQ
+**Q: How do I reset a single shared state?**  
+`sharedStatesApi.clear('key')` or inside component: call a setter with the initial value.
+
+**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: 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]`.
+
+### `useSharedFunction(key, fn, scopeName?)`
+Returns `{ state, trigger, forceTrigger, clear }`.
+
+### `<SharedStatesProvider scopeName?>`
+Wrap children; optional `scopeName` (string). If omitted a random unique one is generated.
+
+### Static
+`sharedStatesApi`, `sharedFunctionsApi` (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.

package/dist/SharedData.d.ts

@@ -0,0 +1,25 @@
+import { AFunction, DataMapValue, NonEmptyString, Prefix } from './types';
+type SharedDataType<T> = DataMapValue & T;
+export declare abstract class SharedData<T> {
+    data: Map<string, SharedDataType<T>>;
+    defaultValue(): T;
+    addListener(key: string, prefix: Prefix, listener: AFunction): void;
+    removeListener(key: string, prefix: Prefix, listener: AFunction): void;
+    callListeners(key: string, prefix: Prefix): void;
+    init(key: string, prefix: Prefix, data: T): void;
+    clearAll(withoutListeners?: boolean): void;
+    clear(key: string, prefix: Prefix, withoutListeners?: boolean): void;
+    get(key: string, prefix: Prefix): SharedDataType<T> | undefined;
+    setValue(key: string, prefix: Prefix, data: T): void;
+    has(key: string, prefix: Prefix): string | undefined;
+    static prefix(key: string, prefix: Prefix): string;
+}
+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;
+    clearAll: () => void;
+    clear: (key: string, scopeName: Prefix) => void;
+    has: (key: string, scopeName: Prefix) => boolean;
+    getAll: () => Map<string, DataMapValue>;
+}
+export {};

package/dist/context/SharedStatesContext.d.ts

@@ -0,0 +1,11 @@
+import { PropsWithChildren } from 'react';
+import { NonEmptyString } from '../types';
+export interface SharedStatesType {
+    scopeName: string;
+}
+interface SharedStatesProviderProps<T extends string = string> extends PropsWithChildren {
+    scopeName?: '__global' extends NonEmptyString<T> ? never : NonEmptyString<T>;
+}
+export declare const SharedStatesProvider: <T extends string = string>({ children, scopeName }: SharedStatesProviderProps<T>) => import("react/jsx-runtime").JSX.Element;
+export declare const useSharedStatesContext: () => SharedStatesType | undefined;
+export {};

package/dist/context/index.d.ts

@@ -0,0 +1 @@
+export { SharedStatesProvider, } from './SharedStatesContext';

package/dist/hooks/index.d.ts

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