Introduce createSharedState, createSharedFunction, and createSharedSubscription.

- Added factory functions (`createSharedState`, `createSharedFunction`, `createSharedSubscription`) for initializing shared resources with `key` generation and scoped prefixes.
- Updated `useSharedState`, `useSharedFunction`, and `useSharedSubscription` to accept created objects as arguments, providing streamlined usage.
- Introduced generic `SharedCreated` type for unified handling of shared resources.
- Refactored utility functions to include a `random` key generator for consistent key creation.
- Updated SharedData methods (`clear` and `resolve`) to accept the new shared objects.
- Adjusted documentation exports to include the new types and functions.
- Improved demo examples to showcase the new features.

Author: HichemTab-tech

demo/app.tsx

@@ -10,6 +10,7 @@ import {
 import './FakeSharedEmitter';
 import {FakeSharedEmitter} from "./FakeSharedEmitter";
 import {useEffect, useState} from "react";
+import {createSharedState} from "../src/hooks/use-shared-state";
 
 FakeSharedEmitter.intervalDuration = 3000;
 window.sharedSubscriptionsApi = sharedSubscriptionsApi;
@@ -18,8 +19,12 @@ window.sharedStatesApi = sharedStatesApi;
 
 sharedStatesApi.set("x", 55);
 
+const counterGlobal = createSharedState(0);
+
 const Comp1 = () => {
-    const [x, setX] = useSharedState('x', 0);
+    //const [x, setX] = useSharedState('x', 0);
+    //const [x, setX] = useSharedState(counterGlobal);
+    const [x, setX] = useSharedState("counterGlobal", "");
     const handle = (by = 1) => {
         setX(x+by)
     }
@@ -77,7 +82,8 @@ const Comp2 = () => {
 const App = () => {
 
     const [hide, setHide] = useState(false);
-    const [x, setX] = useSharedState('x', 0);
+    const [x, setX] = useSharedState(counterGlobal);
+    //const [x, setX] = useSharedState('x', 0);
     //const [x, setX] = useState(0);
     const handle = () => {
         setX(x+1)

src/SharedData.ts

@@ -1,4 +1,4 @@
-import type {AFunction, DataMapValue, Prefix} from "./types";
+import type {AFunction, DataMapValue, Prefix, SharedCreated} from "./types";
 import {useEffect} from "react";
 import {ensureNonEmptyString, log} from "./lib/utils";
 
@@ -149,14 +149,34 @@ export class SharedApi<T>{
         });
     }
 
+    /**
+     * resolve a shared created object to a value
+     * @param sharedCreated
+     */
+    resolve(sharedCreated: SharedCreated) {
+        const {key, prefix} = sharedCreated;
+        return this.get(key, prefix);
+    }
+
+    clear(key: string, scopeName: Prefix): void;
+    clear(sharedCreated: SharedCreated): void;
     /**
      * clear a value from the shared data
      * @param key
      * @param scopeName
      */
-    clear(key: string, scopeName: Prefix) {
-        const prefix: Prefix = scopeName || "_global";
-        this.sharedData.clear(key, prefix);
+    clear(key: string|SharedCreated, scopeName?: Prefix) {
+        let keyStr!: string;
+        let prefixStr!: string;
+        if (typeof key === "string") {
+            keyStr = key;
+            prefixStr = scopeName || "_global";
+        }
+        else{
+            keyStr = key.key;
+            prefixStr = key.prefix;
+        }
+        this.sharedData.clear(keyStr, prefixStr);
     }
 
     /**

src/context/SharedStatesContext.tsx

@@ -1,20 +1,21 @@
 import {createContext, type PropsWithChildren, useContext, useMemo} from 'react';
-import type {NonEmptyString} from "../types";
+import type {Prefix} from "../types";
+import {random} from "../lib/utils";
 
 export interface SharedStatesType {
     scopeName: string
 }
 
-const SharedStatesContext = createContext<SharedStatesType | undefined>(undefined);
+export const SharedStatesContext = createContext<SharedStatesType | undefined>(undefined);
 
-interface SharedStatesProviderProps<T extends string = string> extends PropsWithChildren {
-    scopeName?: '__global' extends NonEmptyString<T> ? never : NonEmptyString<T>;
+interface SharedStatesProviderProps extends PropsWithChildren {
+    scopeName?: Prefix;
 }
 
-export const SharedStatesProvider = <T extends string = string>({ children, scopeName }: SharedStatesProviderProps<T>) => {
+export const SharedStatesProvider = ({ children, scopeName }: SharedStatesProviderProps) => {
     if (scopeName && scopeName.includes("//")) throw new Error("scopeName cannot contain '//'");
 
-    if (!scopeName) scopeName = useMemo(() => Math.random().toString(36).substring(2, 15) as NonNullable<SharedStatesProviderProps<T>['scopeName']>, []);
+    if (!scopeName) scopeName = useMemo(() => random() as NonNullable<SharedStatesProviderProps['scopeName']>, []);
 
     return (
         <SharedStatesContext.Provider value={{scopeName}}>

src/hooks/index.ts

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

src/hooks/use-shared-function.ts

@@ -1,8 +1,8 @@
-import type {AFunction, Prefix} from "../types";
+import type {AFunction, Prefix, SharedCreated} from "../types";
 import {useMemo, useSyncExternalStore} from "react";
 import {SharedApi, SharedData} from "../SharedData";
 import useShared from "./use-shared";
-import {ensureNonEmptyString} from "../lib/utils";
+import {ensureNonEmptyString, random} from "../lib/utils";
 
 type SharedFunctionsState<T> = {
     fnState: {
@@ -49,21 +49,60 @@ const sharedFunctionsData = new SharedFunctionsData();
 
 export const sharedFunctionsApi = new SharedFunctionsApi(sharedFunctionsData);
 
-export const useSharedFunction = <T, Args extends unknown[], S extends string = string>(key: S, fn: AFunction<T, Args>, scopeName?: Prefix) => {
+interface SharedFunctionCreated<T, Args extends unknown[]> extends SharedCreated{
+    fn: AFunction<T, Args>
+}
+
+export const createSharedFunction = <T, Args extends unknown[]>(fn: AFunction<T, Args>, scopeName?: Prefix): SharedFunctionCreated<T, Args> => {
+    const prefix: Prefix = scopeName ?? scopeName ?? "_global";
 
-    key = ensureNonEmptyString(key);
-    const {prefix} = useShared(scopeName);
+    return {
+        key: random(),
+        prefix,
+        fn,
+    }
+}
+
+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 function useSharedFunction <T, Args extends unknown[], S extends string = string>(key: S, fn: AFunction<T, Args>, scopeName?: Prefix): SharedFunctionStateReturn<T, Args>;
+export function useSharedFunction <T, Args extends unknown[]>(sharedFunctionCreated: SharedFunctionCreated<T, Args>): SharedFunctionStateReturn<T, Args>;
+export function useSharedFunction <T, Args extends unknown[], S extends string = string>(
+    key: S | SharedFunctionCreated<T, Args>,
+    fn?: AFunction<T, Args>,
+    scopeName?: Prefix
+): SharedFunctionStateReturn<T, Args> {
+
+    let keyStr: string;
+    let fnVal!: AFunction<T, Args>;
+    let scope: Prefix | undefined = scopeName;
+
+    if (typeof key !== "string") {
+        const { key: key2, fn: fn2, prefix: prefix2 } = key;
+        keyStr = key2;
+        fnVal = fn2;
+        scope = prefix2;
+    } else {
+        keyStr = ensureNonEmptyString(key);
+        fnVal = fn as AFunction<T, Args>;
+    }
+    const {prefix} = useShared(scope);
 
-    sharedFunctionsData.init(key, prefix);
+    sharedFunctionsData.init(keyStr, prefix);
 
     const externalStoreSubscriber = useMemo<Parameters<typeof useSyncExternalStore<NonNullable<SharedFunctionsState<T>['fnState']>>>[0]>(
         () =>
             (listener) => {
-                sharedFunctionsData.init(key, prefix);
-                sharedFunctionsData.addListener(key, prefix, listener);
+                sharedFunctionsData.init(keyStr, prefix);
+                sharedFunctionsData.addListener(keyStr, prefix, listener);
 
                 return () => {
-                    sharedFunctionsData.removeListener(key, prefix, listener);
+                    sharedFunctionsData.removeListener(keyStr, prefix, listener);
                 }
             },
         []
@@ -72,27 +111,27 @@ export const useSharedFunction = <T, Args extends unknown[], S extends string =
     const externalStoreSnapshotGetter = useMemo<Parameters<typeof useSyncExternalStore<NonNullable<SharedFunctionsState<T>['fnState']>>>[1]>(
         () =>
             () =>
-                sharedFunctionsData.get(key, prefix)!.fnState as NonNullable<SharedFunctionsState<T>['fnState']>,
+                sharedFunctionsData.get(keyStr, prefix)!.fnState as NonNullable<SharedFunctionsState<T>['fnState']>,
         []
     );
 
     const state = useSyncExternalStore<NonNullable<SharedFunctionsState<T>['fnState']>>(externalStoreSubscriber, externalStoreSnapshotGetter);
 
     const trigger = async (force: boolean, ...args: Args) => {
-        const entry = sharedFunctionsData.get(key, prefix)!;
+        const entry = sharedFunctionsData.get(keyStr, prefix)!;
         if (!force && (entry.fnState.isLoading || entry.fnState.results !== undefined)) return entry.fnState;
         entry.fnState = { ...entry.fnState, isLoading: true, error: undefined };
         entry.listeners.forEach(l => l());
         try {
-            const results: Awaited<T> = await fn(...args);
+            const results: Awaited<T> = await fnVal(...args);
             entry.fnState = { results, isLoading: false, error: undefined };
         } catch (error) {
             entry.fnState = { ...entry.fnState, isLoading: false, error };
         }
         entry.listeners.forEach(l => l());
     };
 
-    sharedFunctionsData.useEffect(key, prefix);
+    sharedFunctionsData.useEffect(keyStr, prefix);
 
     // noinspection JSUnusedGlobalSymbols
     return {
@@ -104,8 +143,8 @@ export const useSharedFunction = <T, Args extends unknown[], S extends string =
             void trigger(true, ...args);
         },
         clear: () => {
-            sharedFunctionsData.clear(key, prefix);
-            sharedFunctionsData.init(key, prefix);
+            sharedFunctionsData.clear(keyStr, prefix);
+            sharedFunctionsData.init(keyStr, prefix);
         }
     } as const;
-};
+}

src/hooks/use-shared-state.ts

@@ -1,8 +1,8 @@
 import {useMemo, useSyncExternalStore} from "react";
-import type {AFunction, Prefix} from "../types";
+import type {AFunction, Prefix, SharedCreated} from "../types";
 import {SharedApi, SharedData} from "../SharedData";
 import useShared from "./use-shared";
-import {ensureNonEmptyString} from "../lib/utils";
+import {ensureNonEmptyString, random} from "../lib/utils";
 
 class SharedStatesData extends SharedData<{
     value: unknown
@@ -24,7 +24,7 @@ class SharedStatesData extends SharedData<{
     }
 }
 
-class SharedStatesApi extends SharedApi<{
+export class SharedStatesApi extends SharedApi<{
     value: unknown
 }>{
     get<T, S extends string = string>(key: S, scopeName: Prefix = "_global") {
@@ -43,37 +43,67 @@ const sharedStatesData = new SharedStatesData();
 
 export const sharedStatesApi = new SharedStatesApi(sharedStatesData);
 
+export interface SharedStateCreated<T> extends SharedCreated{
+    initialValue: T
+}
 
+export const createSharedState = <T>(initialValue: T, scopeName?: Prefix): SharedStateCreated<T> => {
+    const prefix: Prefix = scopeName ?? scopeName ?? "_global";
 
-export const useSharedState = <T, S extends string = string>(key: S, value: T, scopeName?: Prefix) => {
+    return {
+        key: random(),
+        prefix,
+        initialValue,
+    }
+}
+
+export function useSharedState<T, S extends string>(key: S, initialValue: T, scopeName?: Prefix): readonly [T, (v: T | ((prev: T) => T)) => void];
+export function useSharedState<T>(sharedStateCreated: SharedStateCreated<T>): readonly [T, (v: T | ((prev: T) => T)) => void];
+export function useSharedState<T, S extends string>(
+    key: S | SharedStateCreated<T>,
+    initialValue?: T,
+    scopeName?: Prefix
+): readonly [T, (v: T | ((prev: T) => T)) => void] {
+    let keyStr: string;
+    let initVal!: T;
+    let scope: Prefix | undefined = scopeName;
+
+    if (typeof key !== "string") {
+        const { key: key2, initialValue: value2, prefix: prefix2 } = key;
+        keyStr = key2;
+        initVal = value2;
+        scope = prefix2;
+    } else {
+        keyStr = ensureNonEmptyString(key);
+        initVal = initialValue as T;
+    }
 
-    key = ensureNonEmptyString(key);
-    const {prefix} = useShared(scopeName);
+    const {prefix} = useShared(scope);
 
-    sharedStatesData.init(key, prefix, value);
+    sharedStatesData.init(keyStr, prefix, initVal);
 
     const externalStoreSubscriber = useMemo<Parameters<typeof useSyncExternalStore>[0]>(() => (listener) => {
-        sharedStatesData.init(key, prefix, value);
-        sharedStatesData.addListener(key, prefix, listener);
+        sharedStatesData.init(keyStr, prefix, initialValue);
+        sharedStatesData.addListener(keyStr, prefix, listener);
 
         return () => {
-            sharedStatesData.removeListener(key, prefix, listener);
+            sharedStatesData.removeListener(keyStr, prefix, listener);
         }
     }, []);
 
-    const externalStoreSnapshotGetter = useMemo(() => () => sharedStatesData.get(key, prefix)?.value as T, []);
+    const externalStoreSnapshotGetter = useMemo(() => () => sharedStatesData.get(keyStr, prefix)?.value as T, []);
 
     const dataValue = useSyncExternalStore(externalStoreSubscriber, externalStoreSnapshotGetter);
 
     const setData = (newValueOrCallbackToNewValue: T|((prev: T) => T)) => {
-        const newValue = (typeof newValueOrCallbackToNewValue === "function") ? (newValueOrCallbackToNewValue as (prev: T) => T)(sharedStatesData.get(key, prefix)?.value as T) : newValueOrCallbackToNewValue
+        const newValue = (typeof newValueOrCallbackToNewValue === "function") ? (newValueOrCallbackToNewValue as (prev: T) => T)(sharedStatesData.get(keyStr, prefix)?.value as T) : newValueOrCallbackToNewValue
         if (newValue !== dataValue) {
-            sharedStatesData.setValue(key, prefix, newValue);
-            sharedStatesData.callListeners(key, prefix);
+            sharedStatesData.setValue(keyStr, prefix, newValue);
+            sharedStatesData.callListeners(keyStr, prefix);
         }
     }
 
-    sharedStatesData.useEffect(key, prefix);
+    sharedStatesData.useEffect(keyStr, prefix);
 
     return [
         dataValue,