react-hooks-global-states 10.2.0 → 11.0.0-beta.0

package/createContext.d.ts

@@ -1,104 +1,241 @@
-import { type PropsWithChildren, Context as ReactContext } from 'react';
-import type { ActionCollectionConfig, StateHook, StateSetter, ActionCollectionResult, StateGetter, BaseMetadata, MetadataSetter, GlobalStoreCallbacks, UseHookConfig, ObservableFragment, MetadataGetter } from './types';
-export type Context<State, Actions, Metadata extends BaseMetadata | unknown> = {
-    setMetadata: MetadataSetter<Metadata>;
-    setState: StateSetter<State>;
-    getState: StateGetter<State>;
-    getMetadata: () => Metadata;
+import React, { type PropsWithChildren, Context as ReactContext } from 'react';
+import type { ActionCollectionConfig, ActionCollectionResult, BaseMetadata, MetadataSetter, GlobalStoreCallbacks, UseHookConfig, SubscribeToState, AnyFunction } from './types';
+/**
+ * @description Context API
+ */
+export type ContextApi<State, Actions, Metadata extends BaseMetadata> = {
     actions: Actions;
+    getMetadata: () => Metadata;
+    getState: () => State;
+    setMetadata: MetadataSetter<Metadata>;
+    setState: React.Dispatch<React.SetStateAction<State>>;
+    subscribe: SubscribeToState<State>;
 };
-export type ContextProvider<State, Actions, Metadata extends BaseMetadata | unknown> = React.FC<PropsWithChildren<{
-    value?: State | ((initialValue: State) => State);
+export type ContextProviderExtensions<State, Actions, Metadata extends BaseMetadata> = {
     /**
-     * Callback called when the context is created.
-     */
-    onCreated?: (context: Context<State, Actions, Metadata>) => void;
-}>> & {
-    /**F
      * Creates a provider wrapper which allows to capture the context value,
      * useful for testing purposes.
+     * @param options configuration options for the provider wrapper
+     * @param options.value optional initial state or initializer function
+     * @param options.onCreated optional callback invoked after the context is created
+     * @returns an object containing the wrapper component and a reference to the context value
      */
     makeProviderWrapper: (options?: {
         value?: State | ((initialValue: State) => State);
-        onCreated?: (context: Context<State, Actions, Metadata>) => void;
+        onCreated?: (context: ContextApi<State, Actions, Metadata>) => void;
     }) => {
+        /**
+         * Provider for the context
+         */
         wrapper: React.FC<PropsWithChildren<{
             value?: State | ((initialValue: State) => State);
         }>>;
         /**
-         * Returns access to the created context
-         * context.current will hold the context value
+         * Reference to the current context value
          */
         context: {
-            current: Context<State, Actions, Metadata>;
+            current: ContextApi<State, Actions, Metadata>;
         };
     };
 };
-export type StateControlsHook<State, StateMutator, Metadata extends BaseMetadata | unknown> = () => Readonly<[
-    retriever: StateGetter<State>,
-    mutator: StateMutator,
-    metadata: MetadataGetter<Metadata>
-]>;
-export type ObservableBuilderHook<State, StateMutator, Metadata extends BaseMetadata | unknown> = <Fragment>(this: ContextHook<State, StateMutator, Metadata>, mainSelector: (state: State) => Fragment, args?: {
-    isEqual?: (current: Fragment, next: Fragment) => boolean;
-    isEqualRoot?: (current: State, next: State) => boolean;
-    name?: string;
-}) => ObservableFragment<Fragment>;
-export interface ContextBaseHook<State, StateMutator, Metadata extends BaseMetadata | unknown> {
+/**
+ * @description Creates a React context provider component for the given global state.
+ * @param value Optional initial state or initializer function, useful for testing.
+ * @param onCreated Optional callback invoked after the context is created, receiving the full context instance.
+ */
+export type ContextProvider<State, Actions, Metadata extends BaseMetadata> = React.FC<PropsWithChildren<{
+    value?: State | ((initialValue: State) => State);
+    onCreated?: (context: ContextApi<State, Actions, Metadata>) => void;
+}>> & ContextProviderExtensions<State, Actions, Metadata>;
+export interface ContextBaseHook<State, StateMutator, Metadata extends BaseMetadata> {
+    /**
+     * @description Retrieves the full state, state mutator (setState or actions), and metadata.
+     */
     (): Readonly<[state: State, stateMutator: StateMutator, metadata: Metadata]>;
-    <Derivate>(selector: (state: State) => Derivate, dependencies?: unknown[]): Readonly<[
-        state: Derivate,
-        stateMutator: StateMutator,
-        metadata: Metadata
-    ]>;
-    <Derivate>(selector: (state: State) => Derivate, config?: UseHookConfig<Derivate, State>): Readonly<[
-        state: Derivate,
-        stateMutator: StateMutator,
-        metadata: Metadata
-    ]>;
+    /**
+     * @description Retrieves a derived value from the state using the provided selector function.
+     * @param selector A function that selects a part of the state.
+     * @param dependencies Optional array of dependencies to control when the selector is re-evaluated.
+     * @returns A read-only tuple containing the derived state, state mutator (setState or actions), and metadata.
+     */
+    <Derivate>(selector: (state: State) => Derivate, dependencies?: unknown[]): Readonly<[state: Derivate, stateMutator: StateMutator, metadata: Metadata]>;
+    /**
+     * @description Retrieves a derived value from the state using the provided selector function.
+     * @param selector A function that selects a part of the state.
+     * @param dependencies Optional array of dependencies to control when the selector is re-evaluated.
+     * @returns A read-only tuple containing the derived state, state mutator (setState or actions), and metadata.
+     */
+    <Derivate>(selector: (state: State) => Derivate, config?: UseHookConfig<Derivate, State>): Readonly<[state: Derivate, stateMutator: StateMutator, metadata: Metadata]>;
 }
-export interface ContextHook<State, StateMutator, Metadata extends BaseMetadata | unknown> extends HookExtensions<State, StateMutator, Metadata>, ContextBaseHook<State, StateMutator, Metadata> {
+/**
+ * @description Hook for accessing a context's state, mutator (setState or actions), and metadata.
+ * @returns A read-only tuple containing:
+ *  - state: the current state, or the derived value when a selector is used
+ *  - stateMutator: a function or actions collection to update the state
+ *  - metadata: the current context metadata
+ *
+ * @example
+ * ```tsx
+ * // Simple usage (full state)
+ * const [state, setState] = useTodosContext();
+ *
+ * // With a selector (preferred for render isolation)
+ * const [todos, actions] = useTodosContext(s => s.todos);
+ *
+ * actions.setTodos(next);
+ * ```
+ */
+export interface ContextHook<State, StateMutator, Metadata extends BaseMetadata> extends HookExtensions<State, StateMutator, Metadata>, ContextBaseHook<State, StateMutator, Metadata> {
 }
-export type HookExtensions<State, StateMutator, Metadata extends BaseMetadata | unknown> = {
-    stateControls: () => readonly [
-        useStateControls: StateControlsHook<State, StateMutator, Metadata>,
-        useObservableBuilder: ObservableBuilderHook<State, StateMutator, Metadata>
-    ];
+export type HookExtensions<State, StateMutator, Metadata extends BaseMetadata> = {
+    /**
+     * @description Creates a derived hook that subscribes to a selected fragment of the context state.
+     * The selector determines which portion of the state the new hook exposes.
+     * This hook must be used within the corresponding context provider.
+     *
+     * @param selector A function that selects a part of the state.
+     * @param args Optional configuration for the derived hook, including:
+     *  - isEqual: A function to compare the current and next selected fragment for equality.
+     *  - isEqualRoot: A function to compare the entire state for equality.
+     *  - name: An optional name for debugging purposes.
+     * @returns A new context hook that provides access to the selected fragment of the state,
+     * along with the state mutator and metadata.
+     *
+     * @example
+     * ```tsx
+     * const useTodos = createContext({
+     *   todos: [],
+     *   filter: '',
+     * }, {
+     * actions: {
+     *   setFilter(filter: string) {
+     *   ...
+     * });
+     *
+     * const useFilter = useTodos.createSelectorHook((state) => {
+     *   return state.filter;
+     * });
+     *
+     * function FilterComponent() {
+     *   // The selector only listen to the selected fragment (filter)
+     *   // But has access to the full actions collection
+     *   const [filter, { setFilter }] = useFilter();
+     *
+     *   return (
+     *     <input
+     *       value={filter}
+     *       onChange={(e) => setFilter(e.target.value)}
+     *     />
+     *   );
+     * }
+     * ```
+     */
     createSelectorHook: <Derivate>(this: ContextHook<State, StateMutator, Metadata>, selector: (state: State) => Derivate, args?: Omit<UseHookConfig<Derivate, State>, 'dependencies'> & {
         name?: string;
     }) => ContextBaseHook<Derivate, StateMutator, Metadata>;
+    /**
+     * @description Hook that provides non-reactive access to the context API.
+     * This allows direct interaction with the context’s state, metadata, and actions
+     * without triggering component re-renders.
+     * @returns An object containing the context API methods and properties.
+     */
+    api: () => ContextApi<State, StateMutator, Metadata>;
 };
 export interface CreateContext {
-    <State>(value: State | (() => State)): [
-        ContextHook<State, StateSetter<State>, BaseMetadata>,
-        ContextProvider<State, null, BaseMetadata>,
-        ReactContext<StateHook<State, StateSetter<State>, BaseMetadata> | null>
-    ];
-    <State, Metadata extends BaseMetadata | unknown, ActionsConfig extends ActionCollectionConfig<State, Metadata> | null | {}, PublicStateMutator = keyof ActionsConfig extends never | undefined ? StateSetter<State> : ActionCollectionResult<State, Metadata, NonNullable<ActionsConfig>>>(value: State | (() => State), args: {
+    /**
+     * @description Creates a highly granular React context with its associated provider and state hook.
+     * @param value Initial state value or initializer function.
+     * @returns An object containing:
+     * - **`use`** — A custom hook to read and mutate the context state.
+     *   Supports selectors for granular subscriptions and returns `[state, stateMutator, metadata]`.
+     * - **`Provider`** — A React component that provides the context to its descendants.
+     *   It accepts an optional initial value and `onCreated` callback.
+     * - **`Context`** — The raw React `Context` object for advanced usage, such as integration with
+     *   external tools or non-React consumers.
+     */
+    <State>(value: State | (() => State)): {
+        use: ContextHook<State, React.Dispatch<React.SetStateAction<State>>, BaseMetadata>;
+        Provider: ContextProvider<State, null, BaseMetadata>;
+        Context: ReactContext<ContextHook<State, React.Dispatch<React.SetStateAction<State>>, BaseMetadata> | null>;
+    };
+    /**
+     * @description Creates a highly granular React context with its associated provider and state hook.
+     * @param value Initial state value or initializer function.
+     * @param args Additional configuration for the context.
+     * @param args.name Optional name for debugging purposes.
+     * @param args.metadata Optional non-reactive metadata associated with the state.
+     * @param args.callbacks Optional lifecycle callbacks for the context.
+     * @param args.actions Optional actions to restrict state mutations [if provided `setState` will be nullified].
+     * @returns An object containing:
+     * - **`use`** — A custom hook to read and mutate the context state.
+     *   Supports selectors for granular subscriptions and returns `[state, stateMutator, metadata]`.
+     * - **`Provider`** — A React component that provides the context to its descendants.
+     *   It accepts an optional initial value and `onCreated` callback.
+     * - **`Context`** — The raw React `Context` object for advanced usage, such as integration with
+     *   external tools or non-React consumers.
+     */
+    <State, Metadata extends BaseMetadata, ActionsConfig extends ActionCollectionConfig<State, Metadata> | null | {}, PublicStateMutator = keyof ActionsConfig extends never | undefined ? React.Dispatch<React.SetStateAction<State>> : ActionCollectionResult<State, Metadata, NonNullable<ActionsConfig>>>(value: State | (() => State), args: {
         name?: string;
         metadata?: Metadata | (() => Metadata);
         callbacks?: GlobalStoreCallbacks<State, Metadata> & {
             onUnMount?: () => void;
         };
         actions?: ActionsConfig;
-    }): [
-        ContextHook<State, PublicStateMutator, Metadata>,
-        ContextProvider<State, PublicStateMutator, Metadata>,
-        ReactContext<StateHook<State, PublicStateMutator, Metadata> | null>
-    ];
-    <State, Metadata extends BaseMetadata | unknown, ActionsConfig extends ActionCollectionConfig<State, Metadata>>(value: State | (() => State), args: {
+    }): {
+        use: ContextHook<State, PublicStateMutator, Metadata>;
+        Provider: ContextProvider<State, PublicStateMutator, Metadata>;
+        Context: ReactContext<ContextHook<State, PublicStateMutator, Metadata> | null>;
+    };
+    /**
+     * @description Creates a highly granular React context with its associated provider and state hook.
+     * @param value Initial state value or initializer function.
+     * @param args Additional configuration for the context.
+     * @param args.name Optional name for debugging purposes.
+     * @param args.metadata Optional non-reactive metadata associated with the state.
+     * @param args.callbacks Optional lifecycle callbacks for the context.
+     * @param args.actions Optional actions to restrict state mutations [if provided `setState` will be nullified].
+     * @returns An object containing:
+     * - **`use`** — A custom hook to read and mutate the context state.
+     *   Supports selectors for granular subscriptions and returns `[state, stateMutator, metadata]`.
+     * - **`Provider`** — A React component that provides the context to its descendants.
+     *   It accepts an optional initial value and `onCreated` callback.
+     * - **`Context`** — The raw React `Context` object for advanced usage, such as integration with
+     *   external tools or non-React consumers.
+     */
+    <State, Metadata extends BaseMetadata, ActionsConfig extends ActionCollectionConfig<State, Metadata>>(value: State | (() => State), args: {
         name?: string;
         metadata?: Metadata | (() => Metadata);
         callbacks?: GlobalStoreCallbacks<State, Metadata> & {
             onUnMount?: () => void;
         };
         actions: ActionsConfig;
-    }): [
-        ContextHook<State, ActionCollectionResult<State, Metadata, ActionsConfig>, Metadata>,
-        ContextProvider<State, ActionCollectionResult<State, Metadata, ActionsConfig>, Metadata>,
-        ReactContext<StateHook<State, ActionCollectionResult<State, Metadata, ActionsConfig>, Metadata> | null>
-    ];
+    }): {
+        use: ContextHook<State, ActionCollectionResult<State, Metadata, ActionsConfig>, Metadata>;
+        Provider: ContextProvider<State, ActionCollectionResult<State, Metadata, ActionsConfig>, Metadata>;
+        Context: ReactContext<ContextHook<State, ActionCollectionResult<State, Metadata, ActionsConfig>, Metadata> | null>;
+    };
 }
+/**
+ * @description Creates a highly granular React context with its associated provider and state hook.
+ * Unlike the native `React.createContext`, this version provides fine-grained reactivity and supports
+ * state selection, metadata handling, and optional custom actions for controlled mutations.
+ *
+ * Components using the generated hook only re-render when the selected part of the state changes,
+ * making it efficient for large or deeply nested state trees.
+ */
 export declare const createContext: CreateContext;
-export type InferContextType<Provider extends ContextProvider<any, any, any>> = ReturnType<Provider['makeProviderWrapper']>['context']['current'];
+/**
+ * @description Infers the context API type
+ *
+ * @example
+ * ```ts
+ * const counter = createContext(0);
+ *
+ * type CounterContextApi = InferContextApi<typeof counter.Context>;
+ *
+ * // Equivalent to:
+ * ContextApi<number, React.Dispatch<React.SetStateAction<number>>, BaseMetadata>;
+ * ```
+ */
+export type InferContextApi<Context extends ReactContext<ContextHook<any, any, any> | null>> = NonNullable<React.ContextType<Context>> extends ContextHook<infer State, infer StateMutator, infer Metadata> ? ContextApi<State, StateMutator extends AnyFunction ? null : StateMutator, Metadata> : never;
 export default createContext;

package/createContext.js

@@ -1 +1 @@
-var e,t;e=this,t=(e,t,r,o)=>(()=>{"use strict";var n={155:t=>{t.exports=e},506:e=>{e.exports=t},639:(e,t,r)=>{Object.defineProperty(t,"__esModule",{value:!0}),t.createContext=void 0;var o=r(155),n=r(778),a=r(506),i=r(773);t.createContext=function(e){var t=arguments.length>1&&void 0!==arguments[1]?arguments[1]:{},r=(0,o.createContext)(null),u=function(u){var s=u.children,l=u.value,c=u.onCreated,f=(0,o.useMemo)((function(){var r,o=function(){return(0,a.isFunction)(e)?e():e},u=(0,i.isNil)(l)?o():(0,a.isFunction)(l)?l(o()):l,s=new n.GlobalStore(u,Object.assign(Object.assign({},t),{metadata:null!==(r=(0,a.isFunction)(t.metadata)?t.metadata():t.metadata)&&void 0!==r?r:{}})),c=s.getHook();return{store:s,parentHook:c}}),[]),v=f.store,d=f.parentHook;return(0,o.useEffect)((function(){return function(){var e,t,r,o;null===(t=null===(e=v.callbacks)||void 0===e?void 0:e.onUnMount)||void 0===t||t.call(e),null===(o=(r=v).__onUnMountContext)||void 0===o||o.call(r,v,d),v.dispose()}}),[v,d]),null==c||c(v.getConfigCallbackParam()),(0,o.createElement)(r.Provider,{value:d},s)},s=function(){var e=(0,o.useContext)(r);if(!e)throw new Error("ContextHook must be used within a ContextProvider");return e.apply(void 0,arguments)};s.createSelectorHook=function(e,t){return function(){var n=(0,o.useContext)(r);if((0,i.isNil)(n))throw new Error("SelectorHook must be used within a ContextProvider");var a=(0,o.useRef)(e);a.current=e;var u=(0,o.useMemo)((function(){return(0,i.isNil)(e)?n:n.createSelectorHook((function(){return a.current.apply(a,arguments)}),t)}),[n]);return(0,o.useEffect)((function(){return function(){null==u||u.dispose()}}),[u]),u.apply(void 0,arguments)}};var l=function(){var e=(0,o.useContext)(r);if((0,i.isNil)(e))throw new Error("useStateControls must be used within a ContextProvider");return e.stateControls()},c=function(e,t){var n=(0,o.useContext)(r);if((0,i.isNil)(n))throw new Error("useObservableBuilder must be used within a ContextProvider");return n.createObservable(e,t)};return s.stateControls=function(){return[l,c]},u.makeProviderWrapper=function(e){var t={current:void 0};return{wrapper:function(r){var n=r.children;return(0,o.createElement)(u,{value:null==e?void 0:e.value,onCreated:function(r){var o;t.current=r,null===(o=null==e?void 0:e.onCreated)||void 0===o||o.call(e,r)}},n)},context:t}},[s,u,r]},t.default=t.createContext},773:e=>{e.exports=r},778:e=>{e.exports=o}},a={};return function e(t){var r=a[t];if(void 0!==r)return r.exports;var o=a[t]={exports:{}};return n[t](o,o.exports,e),o.exports}(639)})(),"object"==typeof exports&&"object"==typeof module?module.exports=t(require("react"),require("json-storage-formatter/isFunction"),require("json-storage-formatter/isNil"),require("./GlobalStore.js")):"function"==typeof define&&define.amd?define(["react","json-storage-formatter/isFunction","json-storage-formatter/isNil","./GlobalStore.js"],t):"object"==typeof exports?exports["react-hooks-global-states"]=t(require("react"),require("json-storage-formatter/isFunction"),require("json-storage-formatter/isNil"),require("./GlobalStore.js")):e["react-hooks-global-states"]=t(e.react,e["json-storage-formatter/isFunction"],e["json-storage-formatter/isNil"],e["./GlobalStore.js"]);
+var e,t;e=this,t=(e,t,r,o)=>(()=>{"use strict";var n={155:t=>{t.exports=e},506:e=>{e.exports=t},639:(e,t,r)=>{Object.defineProperty(t,"__esModule",{value:!0}),t.createContext=void 0;var o=r(155),n=r(778),a=r(506),i=r(773);t.createContext=function(e){var t=arguments.length>1&&void 0!==arguments[1]?arguments[1]:{},r=(0,o.createContext)(null),u=function(u){var s=u.children,l=u.value,c=u.onCreated,f=(0,o.useMemo)((function(){var r,o=function(){return(0,a.isFunction)(e)?e():e},u=(0,i.isNil)(l)?o():(0,a.isFunction)(l)?l(o()):l;return new n.GlobalStore(u,Object.assign(Object.assign({},t),{metadata:null!==(r=(0,a.isFunction)(t.metadata)?t.metadata():t.metadata)&&void 0!==r?r:{}}))}),[]);return(0,o.useEffect)((function(){return function(){var e,t,r,o;null===(t=null===(e=f.callbacks)||void 0===e?void 0:e.onUnMount)||void 0===t||t.call(e,f),null===(o=(r=f).__onUnMountContext)||void 0===o||o.call(r,f),f.dispose()}}),[f]),null==c||c(f.getConfigCallbackParam()),(0,o.createElement)(r.Provider,{value:f.use},s)},s={makeProviderWrapper:function(e){var t={current:void 0};return{wrapper:function(r){var n=r.children;return(0,o.createElement)(u,{value:null==e?void 0:e.value,onCreated:function(r){var o;t.current=r,null===(o=null==e?void 0:e.onCreated)||void 0===o||o.call(e,r)}},n)},context:t}}},l=function(){var e=(0,o.useContext)(r);if(!e)throw new Error("use hook must be used within a ContextProvider");return e.apply(void 0,arguments)},c={createSelectorHook:function(e,t){return function(){var n=(0,o.useContext)(r);if((0,i.isNil)(n))throw new Error("SelectorHook must be used within a ContextProvider");var a=(0,o.useRef)(e);a.current=e;var u=(0,o.useMemo)((function(){return n.createSelectorHook((function(){return a.current.apply(a,arguments)}),t)}),[n]);return(0,o.useEffect)((function(){return function(){null==u||u.dispose()}}),[u]),u.apply(void 0,arguments)}},api:function(){var e=(0,o.useContext)(r);if(!e)throw new Error("api hook must be used within a ContextProvider");return e}};return Object.assign(u,s),Object.assign(l,c),{use:l,Provider:u,Context:r}},t.default=t.createContext},773:e=>{e.exports=r},778:e=>{e.exports=o}},a={};return function e(t){var r=a[t];if(void 0!==r)return r.exports;var o=a[t]={exports:{}};return n[t](o,o.exports,e),o.exports}(639)})(),"object"==typeof exports&&"object"==typeof module?module.exports=t(require("react"),require("json-storage-formatter/isFunction"),require("json-storage-formatter/isNil"),require("./GlobalStore.js")):"function"==typeof define&&define.amd?define(["react","json-storage-formatter/isFunction","json-storage-formatter/isNil","./GlobalStore.js"],t):"object"==typeof exports?exports["react-hooks-global-states"]=t(require("react"),require("json-storage-formatter/isFunction"),require("json-storage-formatter/isNil"),require("./GlobalStore.js")):e["react-hooks-global-states"]=t(e.react,e["json-storage-formatter/isFunction"],e["json-storage-formatter/isNil"],e["./GlobalStore.js"]);

package/createGlobalState.d.ts

@@ -1,19 +1,145 @@
-import type { ActionCollectionConfig, StateSetter, ActionCollectionResult, StateHook, BaseMetadata, GlobalStoreCallbacks } from './types';
+import type { ActionCollectionConfig, ActionCollectionResult, StateHook, BaseMetadata, GlobalStoreCallbacks } from './types';
 export interface CreateGlobalState {
-    <State>(state: State): StateHook<State, StateSetter<State>, BaseMetadata>;
-    <State, Metadata extends BaseMetadata | unknown, ActionsConfig extends ActionCollectionConfig<State, Metadata> | null | {}, PublicStateMutator = keyof ActionsConfig extends never | undefined ? StateSetter<State> : ActionCollectionResult<State, Metadata, NonNullable<ActionsConfig>>>(state: State, args: {
+    /**
+     * Creates a global state hook.
+     * @param state initial state value
+     * @returns a state hook for your components
+     * @example
+     * const useCounter = createGlobalState(0);
+     *
+     * function Counter() {
+     *   const [count, setCount] = useCounter();
+     *   return (
+     *     <div>
+     *       <p>Count: {count}</p>
+     *       <button onClick={() =>
+     *         setCount(prev => prev + 1)
+     *       }>Increment</button>
+     *     </div>
+     *   );
+     * }
+     */
+    <State, StateDispatch = React.Dispatch<React.SetStateAction<State>>>(state: State): StateHook<State, StateDispatch, StateDispatch, BaseMetadata>;
+    /**
+     * Creates a global state hook that you can use across your application
+     * @param state initial state value
+     * @param args additional configuration for the global state
+     * @param args.name optional name for debugging purposes
+     * @param args.metadata optional non-reactive metadata associated with the state
+     * @param args.callbacks optional lifecycle callbacks for the global state
+     * @param args.actions optional actions to restrict state mutations [if provided `setState` will be nullified]
+     * @returns a state hook that you can use in your components
+     *
+     * @example
+     * ```tsx
+     * const useCounter = createGlobalState(0, {
+     *   actions: {
+     *     increase() {
+     *       return ({ setState }) => {
+     *         setState((c) => c + 1);
+     *       };
+     *     },
+     *     decrease(amount: number) {
+     *       return ({ setState }) => {
+     *         setState((c) => c - amount);
+     *       };
+     *     },
+     *   },
+     * });
+     *
+     * function Counter() {
+     *  const [count, {
+     *    increase,
+     *    decrease
+     *  }] = useCounter();
+     *
+     *  return (
+     *   <div>
+     *    <p>Count: {count}</p>
+     *    <button onClick={increase}>
+     *      Increment
+     *    </button>
+     *    <button onClick={() => {
+     *      decrease(1);
+     *    }}>
+     *      Decrement
+     *    </button>
+     *   </div>
+     *  );
+     * }
+     * ```
+     */
+    <State, Metadata extends BaseMetadata, ActionsConfig extends ActionCollectionConfig<State, Metadata> | null | {}, PublicStateMutator = keyof ActionsConfig extends never | undefined ? React.Dispatch<React.SetStateAction<State>> : ActionCollectionResult<State, Metadata, NonNullable<ActionsConfig>>, StateDispatch = React.Dispatch<React.SetStateAction<State>>>(state: State, args: {
         name?: string;
         metadata?: Metadata;
         callbacks?: GlobalStoreCallbacks<State, Metadata>;
         actions?: ActionsConfig;
-    }): StateHook<State, PublicStateMutator, Metadata>;
-    <State, Metadata extends BaseMetadata | unknown, ActionsConfig extends ActionCollectionConfig<State, Metadata>>(state: State, args: {
+    }): StateHook<State, StateDispatch, PublicStateMutator, Metadata>;
+    /**
+     * Creates a global state hook that you can use across your application
+     * @param state initial state value
+     * @param args additional configuration for the global state
+     * @param args.name optional name for debugging purposes
+     * @param args.metadata optional non-reactive metadata associated with the state
+     * @param args.callbacks optional lifecycle callbacks for the global state
+     * @param args.actions optional actions to restrict state mutations [if provided `setState` will be nullified]
+     * @returns a state hook that you can use in your components
+     *
+     * @example
+     * ```tsx
+     * const useCounter = createGlobalState(0, {
+     *   actions: {
+     *     increase() {
+     *       return ({ setState }) => {
+     *         setState((c) => c + 1);
+     *       };
+     *     },
+     *     decrease(amount: number) {
+     *       return ({ setState }) => {
+     *         setState((c) => c - amount);
+     *       };
+     *     },
+     *   },
+     * });
+     *
+     * function Counter() {
+     *  const [count, {
+     *    increase,
+     *    decrease
+     *  }] = useCounter();
+     *
+     *  return (
+     *   <div>
+     *    <p>Count: {count}</p>
+     *    <button onClick={increase}>
+     *      Increment
+     *    </button>
+     *    <button onClick={() => {
+     *      decrease(1);
+     *    }}>
+     *      Decrement
+     *    </button>
+     *   </div>
+     *  );
+     * }
+     * ```
+     */
+    <State, Metadata extends BaseMetadata, ActionsConfig extends ActionCollectionConfig<State, Metadata>, StateDispatch = React.Dispatch<React.SetStateAction<State>>>(state: State, args: {
         name?: string;
         metadata?: Metadata;
         callbacks?: GlobalStoreCallbacks<State, Metadata>;
         actions: ActionsConfig;
-    }): StateHook<State, ActionCollectionResult<State, Metadata, ActionsConfig>, Metadata>;
+    }): StateHook<State, StateDispatch, ActionCollectionResult<State, Metadata, ActionsConfig>, Metadata>;
 }
+/**
+ * Creates a global state hook
+ */
 export declare const createGlobalState: CreateGlobalState;
-export type InferActionsType<Hook extends StateHook<any, any, any>> = ReturnType<Hook['stateControls']>['1'];
-export default createGlobalState;
+/**
+ * Infers the actions type from a StateHook
+ * @example
+ * ```ts
+ * type CounterActions = InferActionsType<typeof useCounter>;
+ * ```
+ */
+export type InferActionsType<Hook extends StateHook<any, any, any, any>> = ReturnType<Hook['actions']>['1'];

package/createGlobalState.js

@@ -1 +1 @@
-var e;e=e=>(()=>{"use strict";var t={778:t=>{t.exports=e},840:(e,t,o)=>{Object.defineProperty(t,"__esModule",{value:!0}),t.createGlobalState=void 0;var r=o(778);t.createGlobalState=function(e,t){return new r.GlobalStore(e,t).getHook()},t.default=t.createGlobalState}},o={};return function e(r){var a=o[r];if(void 0!==a)return a.exports;var l=o[r]={exports:{}};return t[r](l,l.exports,e),l.exports}(840)})(),"object"==typeof exports&&"object"==typeof module?module.exports=e(require("./GlobalStore.js")):"function"==typeof define&&define.amd?define(["./GlobalStore.js"],e):"object"==typeof exports?exports["react-hooks-global-states"]=e(require("./GlobalStore.js")):this["react-hooks-global-states"]=e(this["./GlobalStore.js"]);
+var e;e=e=>(()=>{"use strict";var t={778:t=>{t.exports=e}},r={};function o(e){var a=r[e];if(void 0!==a)return a.exports;var s=r[e]={exports:{}};return t[e](s,s.exports,o),s.exports}var a={};return(()=>{var e=a;Object.defineProperty(e,"__esModule",{value:!0}),e.createGlobalState=void 0;var t=o(778);e.createGlobalState=function(){for(var e=arguments.length,r=new Array(e),o=0;o<e;o++)r[o]=arguments[o];var a=r[0],s=r[1];return new t.GlobalStore(a,s).use}})(),a})(),"object"==typeof exports&&"object"==typeof module?module.exports=e(require("./GlobalStore.js")):"function"==typeof define&&define.amd?define(["./GlobalStore.js"],e):"object"==typeof exports?exports["react-hooks-global-states"]=e(require("./GlobalStore.js")):this["react-hooks-global-states"]=e(this["./GlobalStore.js"]);

package/index.d.ts

@@ -1,12 +1,9 @@
-export { StateSetter, HookExtensions, ObservableFragment, MetadataSetter, StateChanges, StoreTools, ActionCollectionResult, GlobalStoreCallbacks, UseHookConfig, UnsubscribeCallback, SubscribeCallbackConfig, SubscribeCallback, StateGetter, BaseMetadata, MetadataGetter, CustomGlobalHookBuilderParams, SelectorCallback, SubscriberParameters, SubscriptionCallback, StateHook, ActionCollectionConfig, } from './types';
+export { StateApi as HookExtensions, ObservableFragment, MetadataSetter, StateChanges, StoreTools, ActionCollectionResult, GlobalStoreCallbacks, UseHookConfig, UnsubscribeCallback, SubscribeCallbackConfig, SubscribeCallback, BaseMetadata, MetadataGetter, CustomGlobalHookBuilderParams, SelectorCallback, SubscriberParameters, SubscriptionCallback, StateHook, ActionCollectionConfig, } from './types';
 export { GlobalStore } from './GlobalStore';
 export { GlobalStoreAbstract } from './GlobalStoreAbstract';
 export { createGlobalState, type InferActionsType } from './createGlobalState';
-export { createCustomGlobalState } from './createCustomGlobalState';
 export { shallowCompare } from './shallowCompare';
 export { uniqueId } from './uniqueId';
 export { throwWrongKeyOnActionCollectionConfig } from './throwWrongKeyOnActionCollectionConfig';
 export { isRecord } from './isRecord';
-export { useStableState } from './useStableState';
-export { type Context, type ContextProvider, type ContextHook, type CreateContext, type InferContextType, createContext, } from './createContext';
-export { generateStackHash } from './generateStackHash';
+export { type ContextApi as Context, type ContextProvider, type ContextHook, type CreateContext, type InferContextApi as InferContextType, createContext, } from './createContext';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-hooks-global-states",
-  "version": "10.2.0",
+  "version": "11.0.0-beta.0",
   "description": "This is a package to easily handling global-state across your react-components using hooks.",
   "main": "./bundle.js",
   "types": "./index.d.ts",
@@ -26,11 +26,6 @@
       "require": "./GlobalStoreAbstract.js",
       "types": "./GlobalStoreAbstract.d.ts"
     },
-    "./createCustomGlobalState": {
-      "import": "./createCustomGlobalState.js",
-      "require": "./createCustomGlobalState.js",
-      "types": "./createCustomGlobalState.d.ts"
-    },
     "./createGlobalState": {
       "import": "./createGlobalState.js",
       "require": "./createGlobalState.js",
@@ -60,16 +55,6 @@
       "import": "./uniqueId.js",
       "require": "./uniqueId.js",
       "types": "./uniqueId.d.ts"
-    },
-    "./useStableState": {
-      "import": "./useStableState.js",
-      "require": "./useStableState.js",
-      "types": "./useStableState.d.ts"
-    },
-    "./generateStackHash": {
-      "import": "./generateStackHash.js",
-      "require": "./generateStackHash.js",
-      "types": "./generateStackHash.d.ts"
     }
   },
   "files": [
@@ -77,7 +62,8 @@
     "*.d.ts"
   ],
   "scripts": {
-    "test:debug": "node --inspect-brk node_modules/.bin/jest --watch --runInBand",
+    "format": "prettier --write .",
+    "test-debug": "node --inspect-brk node_modules/.bin/jest --runInBand --detectOpenHandles",
     "test:quick": "jest --maxWorkers=4 -c --no-watchman -u",
     "test:coverage": "jest --maxWorkers=4 -c --colors --no-watchman --verbose --coverage",
     "build": "yarn clean && webpack --config webpack.config.js",
@@ -137,6 +123,7 @@
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^30.0.4",
     "json-storage-formatter": "^2.0.9",
+    "prettier": "^3.6.2",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "ts-jest": "^29.1.1",

package/shallowCompare.d.ts

@@ -1,13 +1,52 @@
 /**
- * Returns true if the two values are equal.
+ * @description It performs a shallow comparison of the values.
+ * @param value1 - The first value to compare.
+ * @param value2 - The second value to compare.
+ * @returns True if the values are equal, false otherwise.
  */
 export declare const shallowCompare: <T>(value1: T, value2: T) => boolean;
 export declare const isArray: (value: unknown) => value is unknown[];
 export declare const isMap: (value: unknown) => value is Map<unknown, unknown>;
 export declare const isSet: (value: unknown) => value is Set<unknown>;
+/**
+ * @description Determines whether a simple equality check (using `===`) is sufficient
+ * to compare the provided values. This helps decide when a deep equality check
+ * is unnecessary or inefficient.
+ *
+ * Simple equality checks are considered valid when:
+ * - The values have different types (comparison will trivially return false)
+ * - Either value is null or undefined
+ * - Both values are primitive types (string, number, boolean, symbol, bigint)
+ * - Both values are Date objects
+ * - Both values are functions
+ *
+ * @param value1 - The first value to compare.
+ * @param value2 - The second value to compare.
+ * @returns `true` if a simple `===` check is sufficient, `false` if a deep comparison may be required.
+ *
+ * @example
+ * ```ts
+ * canCheckSimpleEquality(42, 42); // true (primitive numbers)
+ * canCheckSimpleEquality({ a: 1 }, { a: 1 }); // false (objects)
+ * canCheckSimpleEquality([1, 2], [1, 2]); // false (arrays)
+ * canCheckSimpleEquality('a', 1); // true (different types, shallow check enough)
+ * ```
+ */
 export declare const canCheckSimpleEquality: (value1: unknown, value2: unknown) => boolean;
-export declare const isEqualArray: <T>(array1: T[], array2: T[]) => boolean;
-export declare const isEqualMap: <K, V>(map1: Map<K, V>, map2: Map<K, V>) => boolean;
-export declare const isEqualSet: <T>(set1: Set<T>, set2: Set<T>) => boolean;
+/**
+ * @description Performs a shallow comparison between two arrays.
+ */
+export declare const isEqualArray: <T>(array1: T[], array2: T[]) => array1 is T[];
+/**
+ * @description Performs a shallow comparison between two maps.
+ */
+export declare const isEqualMap: <K, V>(map1: Map<K, V>, map2: Map<K, V>) => map1 is Map<K, V>;
+/**
+ * @description Performs a shallow comparison between two sets.
+ */
+export declare const isEqualSet: <T>(set1: Set<T>, set2: Set<T>) => set1 is Set<T>;
+/**
+ * @description Performs a shallow comparison between two objects.
+ */
 export declare const isEqualObject: <T extends Record<string, unknown>>(value1: T, value2: T) => boolean;
 export default shallowCompare;