react-shared-states 1.0.7 → 1.0.8

package/.editorconfig

@@ -9,4 +9,7 @@ indent_size = 4
 indent_size = 2
 
 [*.yml]
+indent_size = 2
+
+[*.json]
 indent_size = 2

package/README.md

@@ -48,7 +48,6 @@ function B(){
 }
 
 function App() {
-  
   return (
     <>
       <A/>
@@ -69,7 +68,6 @@ function Scoped(){
 }
 
 function App() {
-
   return (
     <>
       <A/>
@@ -82,6 +80,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,19 +198,22 @@ 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.     |
 
 
 ## 🏗️ 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`.
@@ -194,35 +222,44 @@ Behavior:
 * React batching + equality check: listeners fire only when the value reference actually changes.
 
 ### 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:
@@ -233,12 +270,12 @@ Semantics:
 
 ### 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,9 +291,8 @@ 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 }`
 
@@ -268,36 +304,19 @@ The `subscriber` function receives three callbacks:
 
 ### 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';
 
-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;
-    }
-  );
+export const userSubscription = createSharedSubscription(
+  async (set, onError, onCompletion) => {
+    // ...same as before
+  }
+);
 
+function UserProfile({ userId }: { userId: string }) {
+  const { state, trigger, unsubscribe } = useSharedSubscription(userSubscription);
   // Start listening when component mounts
   useEffect(() => {
     trigger();
@@ -395,36 +414,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, onError, onCompletion) => {/* ... */});
+
+// 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 (returns nested object: { [scope]: { [key]: value } })
+console.log(sharedStatesApi.getAll());
 
-// Inspect all
-console.log(sharedStatesApi.getAll()); // Map with prefixed keys
+// 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()`, `clearScope(scopeName?)`, `getAll()` |
+| `sharedFunctionsApi`     | `get(key, scopeName?)`, `set(key, val, scopeName?)`, `has(key, scopeName?)`, `clear(key, scopeName?)`, `clearAll()`, `clearScope(scopeName?)`, `getAll()` |
+| `sharedSubscriptionsApi` | `get(key, scopeName?)`, `set(key, val, scopeName?)`, `has(key, scopeName?)`, `clear(key, scopeName?)`, `clearAll()`, `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
@@ -481,16 +526,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).
 
 

package/dist/SharedData.d.ts

@@ -1,4 +1,4 @@
-import { AFunction, DataMapValue, Prefix } from './types';
+import { AFunction, DataMapValue, Prefix, SharedCreated } from './types';
 type SharedDataType<T> = DataMapValue & T;
 export declare abstract class SharedData<T> {
     data: Map<string, SharedDataType<T>>;
@@ -42,11 +42,12 @@ export declare class SharedApi<T> {
      */
     clearScope(scopeName?: Prefix): void;
     /**
-     * clear a value from the shared data
-     * @param key
-     * @param scopeName
+     * resolve a shared created object to a value
+     * @param sharedCreated
      */
+    resolve(sharedCreated: SharedCreated): T;
     clear(key: string, scopeName: Prefix): void;
+    clear(sharedCreated: SharedCreated): void;
     /**
      * check if a value exists in the shared data
      * @param key

package/dist/context/SharedStatesContext.d.ts

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

package/dist/hooks/index.d.ts

@@ -1,3 +1,6 @@
-export { useSharedState, sharedStatesApi } from './use-shared-state';
-export { useSharedFunction, sharedFunctionsApi } from './use-shared-function';
-export { useSharedSubscription, sharedSubscriptionsApi } from './use-shared-subscription';
+export { useSharedState, sharedStatesApi, createSharedState, SharedStatesApi } from './use-shared-state';
+export type { SharedStateCreated } 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';
+export type { SharedSubscriptionStateReturn } from './use-shared-subscription';

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

@@ -1,4 +1,4 @@
-import { AFunction, Prefix } from '../types';
+import { AFunction, Prefix, SharedCreated } from '../types';
 import { SharedApi } from '../SharedData';
 type SharedFunctionsState<T> = {
     fnState: {
@@ -12,14 +12,16 @@ export declare class SharedFunctionsApi extends SharedApi<SharedFunctionsState<u
     set<T, S extends string = string>(key: S, fnState: SharedFunctionsState<T>, scopeName?: Prefix): void;
 }
 export declare const sharedFunctionsApi: SharedFunctionsApi;
-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;
-        error?: unknown;
-    };
+interface SharedFunctionCreated<T, Args extends unknown[]> extends SharedCreated {
+    fn: AFunction<T, Args>;
+}
+export declare const createSharedFunction: <T, Args extends unknown[]>(fn: AFunction<T, Args>, scopeName?: Prefix) => SharedFunctionCreated<T, Args>;
+export type SharedFunctionStateReturn<T, Args extends unknown[]> = {
+    readonly state: NonNullable<SharedFunctionsState<T>['fnState']>;
     readonly trigger: (...args: Args) => void;
     readonly forceTrigger: (...args: Args) => void;
     readonly clear: () => void;
 };
+export declare function useSharedFunction<T, Args extends unknown[], S extends string = string>(key: S, fn: AFunction<T, Args>, scopeName?: Prefix): SharedFunctionStateReturn<T, Args>;
+export declare function useSharedFunction<T, Args extends unknown[]>(sharedFunctionCreated: SharedFunctionCreated<T, Args>): SharedFunctionStateReturn<T, Args>;
 export {};

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

@@ -1,11 +1,15 @@
-import { Prefix } from '../types';
+import { Prefix, SharedCreated } from '../types';
 import { SharedApi } from '../SharedData';
-declare class SharedStatesApi extends SharedApi<{
+export declare class SharedStatesApi extends SharedApi<{
     value: unknown;
 }> {
     get<T, S extends string = string>(key: S, scopeName?: Prefix): T;
     set<T, S extends string = string>(key: S, value: T, scopeName?: Prefix): void;
 }
 export declare const sharedStatesApi: SharedStatesApi;
-export declare const useSharedState: <T, S extends string = string>(key: S, value: T, scopeName?: Prefix) => readonly [T, (newValueOrCallbackToNewValue: T | ((prev: T) => T)) => void];
-export {};
+export interface SharedStateCreated<T> extends SharedCreated {
+    initialValue: T;
+}
+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];

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

@@ -1,4 +1,4 @@
-import { PotentialPromise, Prefix } from '../types';
+import { PotentialPromise, Prefix, SharedCreated } from '../types';
 import { SharedApi } from '../SharedData';
 type Unsubscribe = () => void;
 export declare namespace SubscriberEvents {
@@ -21,15 +21,16 @@ export declare class SharedSubscriptionsApi extends SharedApi<SharedSubscription
     set<T, S extends string = string>(key: S, fnState: SharedSubscriptionsState<T>, scopeName?: Prefix): void;
 }
 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;
-    };
+interface SharedSubscriptionCreated<T> extends SharedCreated {
+    subscriber: Subscriber<T>;
+}
+export declare const createSharedSubscription: <T, Args extends unknown[]>(subscriber: Subscriber<T>, scopeName?: Prefix) => SharedSubscriptionCreated<T>;
+export type SharedSubscriptionStateReturn<T> = {
+    readonly state: NonNullable<SharedSubscriptionsState<T>['fnState']>;
     readonly trigger: () => void;
     readonly forceTrigger: () => void;
     readonly unsubscribe: () => void;
 };
+export declare function useSharedSubscription<T, S extends string = string>(key: S, subscriber: Subscriber<T>, scopeName?: Prefix): SharedSubscriptionStateReturn<T>;
+export declare function useSharedSubscription<T>(sharedSubscriptionCreated: SharedSubscriptionCreated<T>): SharedSubscriptionStateReturn<T>;
 export {};

package/dist/lib/utils.d.ts

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