react-hooks-global-states 11.0.0 → 12.0.0

package/createContext.d.ts

@@ -1,17 +1,9 @@
 import React, { type PropsWithChildren, Context as ReactContext } from 'react';
-import type { ActionCollectionConfig, ActionCollectionResult, BaseMetadata, MetadataSetter, GlobalStoreCallbacks, UseHookConfig, SubscribeToState, AnyFunction } from './types';
+import type { ActionCollectionConfig, ActionCollectionResult, BaseMetadata, GlobalStoreCallbacks, UseHookOptions, AnyFunction, StateApi, StoreTools, ReadonlyStateApi, SelectHook, ObservableFragment } from './types';
 /**
- * @description Context API
+ * @description Extensions methods for the ContextProvider component
  */
-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 ContextProviderExtensions<State, Actions, Metadata extends BaseMetadata> = {
+export type ContextProviderExtensions<State, StateMutator, Metadata extends BaseMetadata> = {
     /**
      * Creates a provider wrapper which allows to capture the context value,
      * useful for testing purposes.
@@ -21,20 +13,36 @@ export type ContextProviderExtensions<State, Actions, Metadata extends BaseMetad
      * @returns an object containing the wrapper component and a reference to the context value
      */
     makeProviderWrapper: (options?: {
+        /**
+         * @description Optional initial state or initializer function, useful for testing, storybooks, etc.
+         */
         value?: State | ((initialValue: State) => State);
-        onCreated?: (context: ContextApi<State, Actions, Metadata>) => void;
+        /**
+         * @description Optional callback invoked after the context is created,
+         */
+        onCreated?: (
+        /**
+         * @description Full context instance
+         */
+        context: StoreTools<State, StateMutator extends AnyFunction ? null : StateMutator, Metadata>) => void;
     }) => {
         /**
          * Provider for the context
          */
         wrapper: React.FC<PropsWithChildren<{
+            /**
+             * @description Optional initial state or initializer function, useful for testing, storybooks, etc.
+             */
             value?: State | ((initialValue: State) => State);
         }>>;
         /**
          * Reference to the current context value
          */
         context: {
-            current: ContextApi<State, Actions, Metadata>;
+            /**
+             * @description Current context value
+             */
+            current: StoreTools<State, StateMutator extends AnyFunction ? null : StateMutator, Metadata>;
         };
     };
 };
@@ -43,29 +51,45 @@ export type ContextProviderExtensions<State, Actions, Metadata extends BaseMetad
  * @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<{
+export type ContextProvider<State, StateMutator, Metadata extends BaseMetadata> = React.FC<PropsWithChildren<{
+    /**
+     * @description Optional initial state or initializer function, useful for testing, storybooks, etc.
+     */
     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.
+     * @description Optional callback invoked after the context is created,
      */
-    (): Readonly<[state: State, stateMutator: StateMutator, metadata: Metadata]>;
+    onCreated?: (
     /**
-     * @description Retrieves a derived value from the state using the provided selector function.
+     * @description Full context instance
+     */
+    context: StoreTools<State, StateMutator extends AnyFunction ? null : StateMutator, Metadata>) => void;
+}>> & ContextProviderExtensions<State, StateMutator, Metadata>;
+/**
+ * @description Represents a hook that returns a readonly state.
+ */
+interface ReadonlyContextHook<State, StateMutator, Metadata extends BaseMetadata> extends ReadonlyContextPublicApi<State, StateMutator, Metadata> {
+    /**
+     * @description Returns the full state.
+     */
+    (): State;
+    /**
+     * @description Returns 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.
+     * @returns The derived value from the state.
      */
-    <Derivate>(selector: (state: State) => Derivate, dependencies?: unknown[]): Readonly<[state: Derivate, stateMutator: StateMutator, metadata: Metadata]>;
+    <Derivate>(selector: (state: State) => Derivate, dependencies?: unknown[]): Derivate;
     /**
-     * @description Retrieves a derived value from the state using the provided selector function.
+     * @description Returns 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.
+     * @param options Optional configuration for the selector hook.
+     * @param options.isEqual Optional equality function to compare the selected fragment.
+     * @param options.isEqualRoot Optional equality function to compare the root state.
+     * @param options.dependencies Optional array of dependencies to control when the selector is re-evaluated.
+     * @returns The derived value from the state.
      */
-    <Derivate>(selector: (state: State) => Derivate, config?: UseHookConfig<Derivate, State>): Readonly<[state: Derivate, stateMutator: StateMutator, metadata: Metadata]>;
+    <Derivate>(selector: (state: State) => Derivate, options?: UseHookOptions<Derivate, State>): Derivate;
 }
 /**
  * @description Hook for accessing a context's state, mutator (setState or actions), and metadata.
@@ -85,11 +109,30 @@ export interface ContextBaseHook<State, StateMutator, Metadata extends BaseMetad
  * actions.setTodos(next);
  * ```
  */
-export interface ContextHook<State, StateMutator, Metadata extends BaseMetadata> extends HookExtensions<State, StateMutator, Metadata>, ContextBaseHook<State, StateMutator, Metadata> {
+export interface ContextHook<State, StateMutator, Metadata extends BaseMetadata> extends ContextPublicApi<State, StateMutator, Metadata> {
+    /**
+     * @description Retrieves the full state, state mutator (setState or actions), and metadata.
+     */
+    (): Readonly<[state: State, 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?: UseHookOptions<Derivate, State>): Readonly<[state: Derivate, stateMutator: StateMutator, metadata: Metadata]>;
 }
-export type HookExtensions<State, StateMutator, Metadata extends BaseMetadata> = {
+export type ContextPublicApi<State, StateMutator, Metadata extends BaseMetadata> = {
     /**
-     * @description Creates a derived hook that subscribes to a selected fragment of the context state.
+     * @description [NOT A HOOK, NON-REACTIVE]
+     * 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.
      *
@@ -130,16 +173,67 @@ export type HookExtensions<State, StateMutator, Metadata extends BaseMetadata> =
      * }
      * ```
      */
-    createSelectorHook: <Derivate>(this: ContextHook<State, StateMutator, Metadata>, selector: (state: State) => Derivate, args?: Omit<UseHookConfig<Derivate, State>, 'dependencies'> & {
+    createSelectorHook: <Derivate>(this: ReadonlyContextPublicApi<State, StateMutator, Metadata>, selector: (state: State) => Derivate, args?: Omit<UseHookOptions<Derivate, State>, 'dependencies'> & {
         name?: string;
-    }) => ContextBaseHook<Derivate, StateMutator, Metadata>;
+    }) => ReadonlyContextHook<Derivate, StateMutator, Metadata>;
+    /**
+     * @description [NON-REACTIVE]
+     * 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: () => StateApi<State, StateMutator, Metadata>;
+    /**
+     * @description [NON-REACTIVE]
+     *  Provides direct access to the context's actions, if available.
+     */
+    actions: () => StateMutator extends AnyFunction ? null : StateMutator;
+    /**
+     * @description Selects a fragment of the state using the provided selector function.
+     */
+    select: SelectHook<State>;
+    /**
+     * @description
+     * Creates a hook that allows you to subscribe to a fragment of the state
+     * The observable selection will notify the subscribers only if the fragment changes and the equality function returns false
+     * you can customize the equality function by passing the isEqualRoot and isEqual parameters
+     *
+     * @example
+     * ```tsx
+     * const observable = store.use.observable(state => state.count);
+     *
+     * useEffect(() => {
+     *   const unsubscribe = observable.subscribe(() => {
+     *     // do something when the selected fragment changes
+     *   });
+     *
+     *   return () => {
+     *     unsubscribe();
+     *   };
+     * }, [observable]);
+     * ```
+     */
+    observable: <Selection>(selector: (state: State) => Selection, args?: {
+        isEqual?: (current: Selection, next: Selection) => boolean;
+        isEqualRoot?: (current: State, next: State) => boolean;
+        /**
+         * @description Name of the observable fragment for debugging purposes
+         */
+        name?: string;
+    }) => ObservableFragment<Selection, StateMutator, Metadata>;
+};
+/**
+ * @description Readonly version of the ContextPublicApi, expose by selectors and observables
+ */
+export type ReadonlyContextPublicApi<State, StateMutator, Metadata extends BaseMetadata> = Pick<ContextPublicApi<State, StateMutator, Metadata>, 'createSelectorHook'> & {
     /**
      * @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>;
+    api: () => ReadonlyStateApi<State, StateMutator, Metadata>;
 };
 interface CreateContext {
     /**
@@ -153,10 +247,51 @@ interface CreateContext {
      * - **`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>;
+    <State, StateMutator = React.Dispatch<React.SetStateAction<State>>>(value: State | (() => State)): {
+        /**
+         * @description Hook and API for interacting with the context.
+         * This hook provides access to the context state, actions, and metadata.
+         *
+         * There are two ways to use the hook
+         * @example
+         * The more simple and familiar way is to use it as a regular hook
+         *
+         * ```tsx
+         * const { Context, Provider, user: useUser} = createContext({ name: 'John', age: 30 });
+         *
+         * function UserProfile() {
+         *  const [state, setState, metadata] = useUser();
+         *
+         *  ....
+         * }
+         * ```
+         *
+         * @example
+         * The recommended, more sematic and easier to read way:
+         *
+         * ```tsx
+         * const user = createContext({ name: 'John', age: 30 });
+         *
+         * <user.Provider>
+         *   <UserProfile />
+         * </user.Provider>
+         *
+         * function UserProfile() {
+         *   const [state, setState, metadata] = user.use();
+         *   const userContext = user.use.api();
+         *   const userName = user.use.select(s => s.name);
+         *   // ...
+         * }
+         */
+        use: ContextHook<State, StateMutator, BaseMetadata>;
+        /**
+         * @description Provider for the context
+         */
+        Provider: ContextProvider<State, StateMutator, BaseMetadata>;
+        /**
+         * @description The raw React Context object
+         */
+        Context: ReactContext<ContextHook<State, StateMutator, BaseMetadata> | null>;
     };
     /**
      * @description Creates a highly granular React context with its associated provider and state hook.
@@ -174,17 +309,70 @@ interface CreateContext {
      * - **`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: {
+    <State, Metadata extends BaseMetadata, ActionsConfig extends ActionCollectionConfig<State, Metadata> | null | {}, StateMutator = keyof ActionsConfig extends never | undefined ? React.Dispatch<React.SetStateAction<State>> : ActionCollectionResult<State, Metadata, NonNullable<ActionsConfig>>>(
+    /**
+     * @description Initial state value or initializer function.
+     */
+    value: State | (() => State), 
+    /**
+     * @description 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].
+     */
+    args: {
         name?: string;
         metadata?: Metadata | (() => Metadata);
-        callbacks?: GlobalStoreCallbacks<State, Metadata> & {
+        callbacks?: GlobalStoreCallbacks<State, StateMutator, Metadata> & {
             onUnMount?: () => void;
         };
         actions?: ActionsConfig;
     }): {
-        use: ContextHook<State, PublicStateMutator, Metadata>;
-        Provider: ContextProvider<State, PublicStateMutator, Metadata>;
-        Context: ReactContext<ContextHook<State, PublicStateMutator, Metadata> | null>;
+        /**
+         * @description Hook and API for interacting with the context.
+         * This hook provides access to the context state, actions, and metadata.
+         *
+         * There are two ways to use the hook
+         * @example
+         * The more simple and familiar way is to use it as a regular hook
+         *
+         * ```tsx
+         * const { Context, Provider, user: useUser} = createContext({ name: 'John', age: 30 });
+         *
+         * function UserProfile() {
+         *  const [state, setState, metadata] = useUser();
+         *
+         *  ....
+         * }
+         * ```
+         *
+         * @example
+         * The recommended, more sematic and easier to read way:
+         *
+         * ```tsx
+         * const user = createContext({ name: 'John', age: 30 });
+         *
+         * <user.Provider>
+         *   <UserProfile />
+         * </user.Provider>
+         *
+         * function UserProfile() {
+         *   const [state, setState, metadata] = user.use();
+         *   const userContext = user.use.api();
+         *   const userName = user.use.select(s => s.name);
+         *   // ...
+         * }
+         */
+        use: ContextHook<State, StateMutator, Metadata>;
+        /**
+         * @description Provider for the context
+         */
+        Provider: ContextProvider<State, StateMutator, Metadata>;
+        /**
+         * @description Raw React Context object
+         */
+        Context: ReactContext<ContextHook<State, StateMutator, Metadata> | null>;
     };
     /**
      * @description Creates a highly granular React context with its associated provider and state hook.
@@ -202,16 +390,69 @@ interface CreateContext {
      * - **`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: {
+    <State, Metadata extends BaseMetadata, ActionsConfig extends ActionCollectionConfig<State, Metadata>, StateMutator = React.Dispatch<React.SetStateAction<State>>>(
+    /**
+     * @description Initial state value or initializer function.
+     */
+    value: State | (() => State), 
+    /**
+     * @description 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].
+     */
+    args: {
         name?: string;
         metadata?: Metadata | (() => Metadata);
-        callbacks?: GlobalStoreCallbacks<State, Metadata> & {
+        callbacks?: GlobalStoreCallbacks<State, StateMutator, Metadata> & {
             onUnMount?: () => void;
         };
         actions: ActionsConfig;
     }): {
+        /**
+         * @description Hook and API for interacting with the context.
+         * This hook provides access to the context state, actions, and metadata.
+         *
+         * There are two ways to use the hook
+         * @example
+         * The more simple and familiar way is to use it as a regular hook
+         *
+         * ```tsx
+         * const { Context, Provider, user: useUser} = createContext({ name: 'John', age: 30 });
+         *
+         * function UserProfile() {
+         *  const [state, setState, metadata] = useUser();
+         *
+         *  ....
+         * }
+         * ```
+         *
+         * @example
+         * The recommended, more sematic and easier to read way:
+         *
+         * ```tsx
+         * const user = createContext({ name: 'John', age: 30 });
+         *
+         * <user.Provider>
+         *   <UserProfile />
+         * </user.Provider>
+         *
+         * function UserProfile() {
+         *   const [state, setState, metadata] = user.use();
+         *   const userContext = user.use.api();
+         *   const userName = user.use.select(s => s.name);
+         *   // ...
+         * }
+         */
         use: ContextHook<State, ActionCollectionResult<State, Metadata, ActionsConfig>, Metadata>;
+        /**
+         * @description Provider for the context
+         */
         Provider: ContextProvider<State, ActionCollectionResult<State, Metadata, ActionsConfig>, Metadata>;
+        /**
+         * @description Raw React Context object
+         */
         Context: ReactContext<ContextHook<State, ActionCollectionResult<State, Metadata, ActionsConfig>, Metadata> | null>;
     };
 }
@@ -237,5 +478,5 @@ export declare const createContext: CreateContext;
  * 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 type InferContextApi<Context extends ReactContext<ContextHook<any, any, BaseMetadata> | null>> = NonNullable<React.ContextType<Context>> extends ContextHook<infer State, infer StateMutator, infer Metadata> ? StateApi<State, StateMutator extends AnyFunction ? null : StateMutator, Metadata> : never;
 export default createContext;

package/createContext.js

@@ -1,70 +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);
-/**
- * @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.
- */
-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),
-/**
-         * Required by the global hooks developer tools
-         */
-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={
-/**
-     * Store selectors are not created until the first time they are used
-     */
-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"]);
+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);function u(e,t){var r=this,a=function(){var n=r.api();return(0,o.useMemo)((function(){return n.createSelectorHook(e,t)}),[n]).apply(void 0,arguments)},i={createSelectorHook:u.bind(a),api:function(){var a=r.api();return(0,o.useMemo)((function(){var r=a.createObservable(e,t);return Object.assign(Object.assign({},a),{getState:function(){return r.getState()},subscribe:r.subscribe.bind(r),createSelectorHook:n.createSelectorHook.bind(r),createObservable:n.createObservable.bind(r)})}),[a])}};return Object.assign(a,i),a}t.createContext=function(e){var t=arguments.length>1&&void 0!==arguments[1]?arguments[1]:{},r=(0,o.createContext)(null),s=function(u){var s=u.children,l=u.value,c=u.onCreated,v=(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=v.callbacks)||void 0===e?void 0:e.onUnMount)||void 0===t||t.call(e,v),null===(o=(r=v).__onUnMountContext)||void 0===o||o.call(r,v),v.dispose()}}),[v]),null==c||c(v.getConfigCallbackParam()),(0,o.createElement)(r.Provider,{value:v.use},s)},l={makeProviderWrapper:function(e){var t={current:void 0};return{wrapper:function(r){var n=r.children;return(0,o.createElement)(s,{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}}},c=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)},v=function(){var e=(0,o.useContext)(r);if(!e)throw new Error("api hook must be used within a ContextProvider");return e},d={createSelectorHook:u.bind(c),api:v,select:function(){return c.apply(void 0,arguments)[0]},observable:function(){for(var e=v(),t=arguments.length,r=new Array(t),n=0;n<t;n++)r[n]=arguments[n];var a=(0,o.useRef)(r);return a.current=r,(0,o.useMemo)((function(){var t,r,o;return e.createObservable((function(e){return(0,a.current[0])(e)}),{isEqualRoot:Boolean(null===(t=a.current[1])||void 0===t?void 0:t.isEqualRoot)?function(e,t){var r,o=null===(r=a.current[1])||void 0===r?void 0:r.isEqualRoot;return Boolean(o(e,t))}:void 0,isEqual:Boolean(null===(r=a.current[1])||void 0===r?void 0:r.isEqual)?function(e,t){var r,o=null===(r=a.current[1])||void 0===r?void 0:r.isEqual;return Boolean(o(e,t))}:void 0,name:null===(o=a.current[1])||void 0===o?void 0:o.name})}),[e])},actions:function(){return v().actions}};return Object.assign(s,l),Object.assign(c,d),{use:c,Provider:s,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

@@ -4,7 +4,9 @@ interface CreateGlobalState {
      * Creates a global state hook.
      * @param state initial state value
      * @returns a state hook for your components
+     *
      * @example
+     * ```tsx
      * const useCounter = createGlobalState(0);
      *
      * function Counter() {
@@ -18,8 +20,23 @@ interface CreateGlobalState {
      *     </div>
      *   );
      * }
+     * ```
+     *
+     * @example You can also use a more semantic and declarative approach
+     * ```tsx
+     * const counter = createGlobalState(0);
+     *
+     * function Counter() {
+     *   const [count, setCount] = counter.use();
+     *   const count = counter.use.select();
+     *
+     *   counter.setState(prev => prev + 1);
+     *
+     *   // if you have actions
+     *   counter.actions.someAction();
+     * ```
      */
-    <State, StateDispatch = React.Dispatch<React.SetStateAction<State>>>(state: State): StateHook<State, StateDispatch, StateDispatch, BaseMetadata>;
+    <State>(state: State): StateHook<State, React.Dispatch<React.SetStateAction<State>>, BaseMetadata>;
     /**
      * Creates a global state hook that you can use across your application
      * @param state initial state value
@@ -72,9 +89,9 @@ interface CreateGlobalState {
     <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>;
+        callbacks?: GlobalStoreCallbacks<State, PublicStateMutator, Metadata>;
         actions?: ActionsConfig;
-    }): StateHook<State, StateDispatch, PublicStateMutator, Metadata>;
+    }): StateHook<State, PublicStateMutator, Metadata>;
     /**
      * Creates a global state hook that you can use across your application
      * @param state initial state value
@@ -124,12 +141,12 @@ interface CreateGlobalState {
      * }
      * ```
      */
-    <State, Metadata extends BaseMetadata, ActionsConfig extends ActionCollectionConfig<State, Metadata>, StateDispatch = React.Dispatch<React.SetStateAction<State>>>(state: State, args: {
+    <State, Metadata extends BaseMetadata, ActionsConfig extends ActionCollectionConfig<State, Metadata>, PublicStateMutator = ActionCollectionResult<State, Metadata, NonNullable<ActionsConfig>>>(state: State, args: {
         name?: string;
         metadata?: Metadata;
-        callbacks?: GlobalStoreCallbacks<State, Metadata>;
+        callbacks?: GlobalStoreCallbacks<State, PublicStateMutator, Metadata>;
         actions: ActionsConfig;
-    }): StateHook<State, StateDispatch, ActionCollectionResult<State, Metadata, ActionsConfig>, Metadata>;
+    }): StateHook<State, PublicStateMutator, Metadata>;
 }
 /**
  * Creates a global state hook
@@ -142,5 +159,5 @@ export declare const createGlobalState: CreateGlobalState;
  * type CounterActions = InferActionsType<typeof useCounter>;
  * ```
  */
-export type InferActionsType<Hook extends StateHook<any, any, any, any>> = ReturnType<Hook['actions']>['1'];
+export type InferActionsType<Hook extends StateHook<any, any, any>> = ReturnType<Hook['actions']>['1'];
 export default createGlobalState;

package/createGlobalState.js

@@ -1,47 +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);
-/**
- * Creates a global state hook
- */t.createGlobalState=function(){for(var e=arguments.length,t=new Array(e),o=0;o<e;o++)t[o]=arguments[o];var a=t[0],l=t[1];return new r.GlobalStore(a,l).use},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},840:(e,t,o)=>{Object.defineProperty(t,"__esModule",{value:!0}),t.createGlobalState=void 0;var r=o(778);t.createGlobalState=function(){for(var e=arguments.length,t=new Array(e),o=0;o<e;o++)t[o]=arguments[o];var a=t[0],l=t[1];return new r.GlobalStore(a,l).use},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"]);

package/index.d.ts

@@ -1,4 +1,4 @@
-export { StateApi, ObservableFragment, MetadataSetter, StateChanges, StoreTools, ActionCollectionResult, GlobalStoreCallbacks, UseHookConfig, UnsubscribeCallback, SubscribeCallbackConfig, SubscribeCallback, BaseMetadata, MetadataGetter, CustomGlobalHookBuilderParams, SelectorCallback, SubscriberParameters, SubscriptionCallback, StateHook, ActionCollectionConfig, } from './types';
+export { StateApi, ObservableFragment, MetadataSetter, StateChanges, StoreTools, ActionCollectionResult, GlobalStoreCallbacks, UseHookOptions, UnsubscribeCallback, SubscribeCallbackConfig, SubscribeCallback, BaseMetadata, MetadataGetter, SelectorCallback, SubscriberParameters, SubscriptionCallback, StateHook, ActionCollectionConfig, } from './types';
 export { GlobalStore } from './GlobalStore';
 export { GlobalStoreAbstract } from './GlobalStoreAbstract';
 export { createGlobalState, type InferActionsType } from './createGlobalState';
@@ -6,4 +6,4 @@ export { shallowCompare } from './shallowCompare';
 export { uniqueId } from './uniqueId';
 export { throwWrongKeyOnActionCollectionConfig } from './throwWrongKeyOnActionCollectionConfig';
 export { isRecord } from './isRecord';
-export { type ContextApi, type ContextProvider, type ContextHook, type InferContextApi, createContext, } from './createContext';
+export { type ContextProvider, type ContextHook, type InferContextApi, createContext } from './createContext';