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

package/types.d.ts

@@ -1,68 +1,75 @@
-export type StateSetter<State> = (setter: State | ((state: State) => State), meta?: {
+export type AnyFunction = (...args: any[]) => any;
+/**
+ * @description Represents the complete non-reactive API of a global state instance.
+ * This API provides full control over the state, including reading, writing, subscribing,
+ * and creating derived hooks or observable fragments.
+ */
+export type StateApi<State, StateDispatch, StateMutator, Metadata extends BaseMetadata> = {
     /**
-     * @description you can add an identifier to the state call
-     * this will show up in the devtools to help you identify from where the state change was called
+     * Returns the metadata
+     * Metadata is additional non reactive information associated with the global state
      */
-    identifier?: string | undefined;
+    getMetadata: MetadataGetter<Metadata>;
     /**
-     * @deprecated forceUpdate normally should not be used inside components
-     * Use this flag just in custom implementations of the global store
+     * Sets the metadata value
+     * The metadata value is not reactive and wont trigger re-renders
      */
-    forceUpdate?: boolean | undefined;
-}) => void;
-export type HookExtensions<State, StateMutator, Metadata extends BaseMetadata | unknown> = {
+    setMetadata: MetadataSetter<Metadata>;
+    /**
+     * @description Contains the generated action functions if custom actions are defined.
+     * When actions exist, direct state mutation via `setState` is disabled and setState will be `null`.
+     * If no actions are provided, this property is `null`.
+     */
+    actions: StateMutator extends AnyFunction ? null : StateMutator;
+    /**
+     * @description Provides direct access to the state updater when no custom actions are defined.
+     * When actions exist, direct state mutation via `setState` is disabled and this property will be `null`.
+     * If no actions are provided, this property exposes the `setState` function.
+     */
+    setState: StateMutator extends AnyFunction ? StateDispatch : null;
     /**
-     * @description Return the state controls of the hook
-     * This selectors includes:
-     * - stateRetriever: a function to get the current state or subscribe a callback to the state changes
-     * - stateMutator: a function to set the state or a collection of actions if you pass an storeActionsConfig configuration
-     * - metadataRetriever: a function to get the metadata of the global state
+     * @description Get the current state value
      */
-    stateControls: () => Readonly<[
-        retriever: StateGetter<State>,
-        mutator: StateMutator,
-        metadata: MetadataGetter<Metadata>
-    ]>;
+    getState: () => State;
+    /**
+     * @description Subscribe to the state changes
+     * You can subscribe to the whole state or to a fragment of the state by passing a selector as first parameter,
+     * this can be used in non react environments to listen to the state changes
+     */
+    subscribe: SubscribeToState<State>;
     /***
      * @description Creates a new hooks that returns the result of the selector passed as a parameter
      * Your can create selector hooks of other selectors hooks and extract as many derived states as or fragments of the state as you want
      * The selector hook will be evaluated only if the result of the selector changes and the equality function returns false
      * you can customize the equality function by passing the isEqualRoot and isEqual parameters
      */
-    createSelectorHook: <Derivate>(this: StateHook<State, StateMutator, Metadata>, selector: (state: State) => Derivate, args?: Omit<UseHookConfig<Derivate, State>, 'dependencies'> & {
-        name?: string;
-    }) => StateHook<Derivate, StateMutator, Metadata>;
-    createObservable: <Fragment>(this: StateHook<State, StateMutator, Metadata>, mainSelector: (state: State) => Fragment, args?: {
-        isEqual?: (current: Fragment, next: Fragment) => boolean;
-        isEqualRoot?: (current: State, next: State) => boolean;
+    createSelectorHook: <Selection>(selector: (state: State) => Selection, args?: Omit<UseHookConfig<Selection, State>, 'dependencies'> & {
         name?: string;
-    }) => ObservableFragment<Fragment>;
-    removeSubscriptions: () => void;
-    dispose: () => void;
-};
-export type ObservableFragment<State> = StateGetter<State> & {
-    createObservable: <Fragment>(this: ObservableFragment<State>, mainSelector: (state: State) => Fragment, args?: {
-        isEqual?: (current: Fragment, next: Fragment) => boolean;
+    }) => StateHook<Selection, StateDispatch, StateMutator, Metadata>;
+    /**
+     * @description Creates a function 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
+     */
+    createObservable: <Selection>(this: StateApi<State, StateDispatch, StateMutator, Metadata>, 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<Fragment>;
-    removeSubscriptions: () => void;
-    _name: string | undefined;
+    }) => ObservableFragment<Selection, StateDispatch, StateMutator, Metadata>;
 };
-export interface StateHook<State, StateMutator, Metadata extends BaseMetadata | unknown> extends HookExtensions<State, StateMutator, Metadata> {
+/**
+ * @description Function that allows you to subscribe to a fragment of the state
+ */
+export type ObservableFragment<State, StateDispatch, StateMutator, Metadata extends BaseMetadata> = SubscribeToState<State> & StateApi<State, StateDispatch, StateMutator, Metadata>;
+export interface StateHook<State, StateDispatch, StateMutator, Metadata extends BaseMetadata> extends StateApi<State, StateDispatch, StateMutator, 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
-    ]>;
+    <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]>;
 }
-export type MetadataSetter<Metadata extends BaseMetadata | unknown> = (setter: Metadata | ((metadata: Metadata) => Metadata)) => void;
+export type MetadataSetter<Metadata extends BaseMetadata> = (setter: Metadata | ((metadata: Metadata) => Metadata)) => void;
 export type StateChanges<State> = {
     state: State;
     previousState: State | undefined;
@@ -71,31 +78,51 @@ export type StateChanges<State> = {
 /**
  * API for the actions of the global states
  **/
-export type StoreTools<State, Metadata extends BaseMetadata | unknown = BaseMetadata, Actions extends undefined | unknown | Record<string, (...args: any[]) => any> = unknown> = {
+export type StoreTools<State, Metadata extends BaseMetadata = BaseMetadata, Actions extends undefined | unknown | Record<string, AnyFunction> = unknown> = {
     setMetadata: MetadataSetter<Metadata>;
-    setState: StateSetter<State>;
-    getState: StateGetter<State>;
+    setState: React.Dispatch<React.SetStateAction<State>>;
+    getState: () => State;
+    subscribe: SubscribeToState<State>;
     getMetadata: () => Metadata;
     actions: Actions;
 };
 /**
  * contract for the storeActionsConfig configuration
  */
-export interface ActionCollectionConfig<State, Metadata extends BaseMetadata | unknown, ThisAPI = Record<string, (...parameters: any[]) => unknown>> {
+export interface ActionCollectionConfig<State, Metadata extends BaseMetadata, ThisAPI = Record<string, (...parameters: any[]) => unknown>> {
     readonly [key: string]: {
         (this: ThisAPI, ...parameters: any[]): (this: ThisAPI, storeTools: StoreTools<State, Metadata, Record<string, (...parameters: any[]) => unknown | void>>) => unknown | void;
     };
 }
-export type ActionCollectionResult<State, Metadata extends BaseMetadata | unknown, ActionsConfig extends ActionCollectionConfig<State, Metadata>> = {
+export type ActionCollectionResult<State, Metadata extends BaseMetadata, ActionsConfig extends ActionCollectionConfig<State, Metadata>> = {
     [key in keyof ActionsConfig]: {
         (...params: Parameters<ActionsConfig[key]>): ReturnType<ReturnType<ActionsConfig[key]>>;
     };
 };
-export type GlobalStoreCallbacks<State, Metadata extends BaseMetadata | unknown> = {
+/**
+ * Callbacks for the global store lifecycle events
+ */
+export type GlobalStoreCallbacks<State, Metadata extends BaseMetadata> = {
+    /**
+     * @description Called when the store is initialized
+     */
     onInit?: (args: StoreTools<State, Metadata>) => void;
+    /**
+     * @description Called when the state has changed
+     */
     onStateChanged?: (args: StoreTools<State, Metadata> & StateChanges<State>) => void;
+    /**
+     * @description Called when a new subscription is created
+     */
     onSubscribed?: (args: StoreTools<State, Metadata>, subscription: SubscriberParameters) => void;
+    /**
+     * @description Called to determine whether to prevent a state change
+     */
     computePreventStateChange?: (args: StoreTools<State, Metadata> & StateChanges<State>) => boolean;
+    /**
+     * @description Called when the store is unmounted, only applicable in context stores
+     */
+    onUnMount?: (store: StateApi<State, any, any, Metadata>) => void;
 };
 export type UseHookConfig<State, TRoot = any> = {
     isEqual?: (current: State, next: State) => boolean;
@@ -114,24 +141,24 @@ export type SubscribeCallbackConfig<State> = UseHookConfig<State> & {
  */
 export type SubscribeCallback<State> = (state: State) => void;
 /**
- * get the current state or subscribe to the state changes
+ * @description Subscribe to the state changes
+ * You can subscribe to the whole state or to a fragment of the state by passing a selector as first parameter
+ * This can be used in non react environments to listen to the state changes
  */
-export type StateGetter<State> = {
-    (): State;
+export type SubscribeToState<State> = {
     (subscription: SubscribeCallback<State>, config?: SubscribeCallbackConfig<State>): UnsubscribeCallback;
     <TDerivate>(selector: SelectorCallback<State, TDerivate>, subscription: SubscribeCallback<TDerivate>, config?: SubscribeCallbackConfig<TDerivate>): UnsubscribeCallback;
 };
 export type BaseMetadata = Record<string, unknown>;
-export type MetadataGetter<Metadata extends BaseMetadata | unknown> = () => Metadata;
-export type CustomGlobalHookBuilderParams<TCustomConfig extends BaseMetadata | unknown, Metadata extends BaseMetadata | unknown> = {
+export type MetadataGetter<Metadata extends BaseMetadata> = () => Metadata;
+export type CustomGlobalHookBuilderParams<TCustomConfig extends BaseMetadata | unknown, Metadata extends BaseMetadata> = {
     onInitialize?: (args: StoreTools<unknown, Metadata, unknown>, config: TCustomConfig | undefined) => void;
     onChange?: (args: StoreTools<unknown, Metadata, unknown> & StateChanges<unknown>, config: TCustomConfig | undefined) => void;
 };
 export type SelectorCallback<State, TDerivate> = (state: State) => TDerivate;
 export type SubscriberParameters = {
-    subscriptionId: string;
-    selector: SelectorCallback<unknown, unknown> | undefined;
-    getConfig: () => UseHookConfig<unknown> | SubscribeCallbackConfig<unknown> | undefined;
+    selector: SelectorCallback<any, any> | undefined;
+    getConfig: () => UseHookConfig<any> | SubscribeCallbackConfig<any> | undefined;
     currentState: unknown;
     callback: SubscriptionCallback | (() => void);
 };

package/webpack.config.js

@@ -5,15 +5,12 @@ const individualEntries = {
   createContext: './src/createContext.ts',
   GlobalStore: './src/GlobalStore.ts',
   GlobalStoreAbstract: './src/GlobalStoreAbstract.ts',
-  createCustomGlobalState: './src/createCustomGlobalState.ts',
   createGlobalState: './src/createGlobalState.ts',
   types: './src/types.ts',
   isRecord: './src/isRecord.ts',
   shallowCompare: './src/shallowCompare.ts',
   throwWrongKeyOnActionCollectionConfig: './src/throwWrongKeyOnActionCollectionConfig.ts',
   uniqueId: './src/uniqueId.ts',
-  useStableState: './src/useStableState.ts',
-  generateStackHash: './src/generateStackHash.ts',
 };
 
 const getExternalsForEntries = () => {

package/createCustomGlobalState.d.ts

@@ -1,23 +0,0 @@
-import type { ActionCollectionConfig, StateSetter, ActionCollectionResult, StateHook, CustomGlobalHookBuilderParams, BaseMetadata, GlobalStoreCallbacks } from './types';
-export interface CustomCreateGlobalState<TCustomConfig extends BaseMetadata | unknown, InheritMetadata extends BaseMetadata | unknown = BaseMetadata> {
-    <State>(state: State): StateHook<State, StateSetter<State>, BaseMetadata>;
-    <State, Metadata extends BaseMetadata | unknown, ActionsConfig extends ActionCollectionConfig<State, InheritMetadata & Metadata> | null | {}, PublicStateMutator = keyof ActionsConfig extends never | undefined ? StateSetter<State> : ActionCollectionResult<State, InheritMetadata & Metadata, NonNullable<ActionsConfig>>>(state: State, args: {
-        name?: string;
-        metadata?: Metadata;
-        callbacks?: GlobalStoreCallbacks<State, InheritMetadata & Metadata>;
-        actions?: ActionsConfig;
-        config?: TCustomConfig;
-    }): StateHook<State, PublicStateMutator, InheritMetadata & Metadata>;
-    <State, Metadata extends BaseMetadata | unknown, ActionsConfig extends Readonly<ActionCollectionConfig<State, InheritMetadata & Metadata>>>(state: State, args: {
-        name?: string;
-        metadata?: Metadata;
-        callbacks?: GlobalStoreCallbacks<State, InheritMetadata & Metadata>;
-        actions: ActionsConfig;
-        config?: TCustomConfig;
-    }): StateHook<State, ActionCollectionResult<State, InheritMetadata & Metadata, ActionsConfig>, InheritMetadata & Metadata>;
-}
-/**
- * @description Simple custom global state hook builder
- */
-export declare const createCustomGlobalState: <TCustomConfig extends BaseMetadata | unknown, InheritMetadata extends BaseMetadata | unknown = BaseMetadata>({ onInitialize, onChange, }: CustomGlobalHookBuilderParams<TCustomConfig, InheritMetadata>) => CustomCreateGlobalState<TCustomConfig, InheritMetadata>;
-export default createCustomGlobalState;

package/createCustomGlobalState.js

@@ -1 +0,0 @@
-var e;e=e=>(()=>{"use strict";var t={154:(e,t,o)=>{Object.defineProperty(t,"__esModule",{value:!0}),t.createCustomGlobalState=void 0;var a=o(670);t.createCustomGlobalState=function(e){var t=e.onInitialize,o=e.onChange;return function(e){var l=arguments.length>1&&void 0!==arguments[1]?arguments[1]:{},n=l.callbacks,r=function(e,t){var o={};for(var a in e)Object.prototype.hasOwnProperty.call(e,a)&&t.indexOf(a)<0&&(o[a]=e[a]);if(null!=e&&"function"==typeof Object.getOwnPropertySymbols){var l=0;for(a=Object.getOwnPropertySymbols(e);l<a.length;l++)t.indexOf(a[l])<0&&Object.prototype.propertyIsEnumerable.call(e,a[l])&&(o[a[l]]=e[a[l]])}return o}(l,["callbacks"]);return(0,a.createGlobalState)(e,Object.assign(Object.assign({},r),{callbacks:Object.assign(Object.assign({},null!=n?n:{}),{onInit:function(e){var o;null==t||t(e,null==r?void 0:r.config),null===(o=null==n?void 0:n.onInit)||void 0===o||o.call(n,e)},onStateChanged:function(e){var t;null==o||o(e,null==r?void 0:r.config),null===(t=null==n?void 0:n.onStateChanged)||void 0===t||t.call(n,e)}})}))}},t.default=t.createCustomGlobalState},670:t=>{t.exports=e}},o={};return function e(a){var l=o[a];if(void 0!==l)return l.exports;var n=o[a]={exports:{}};return t[a](n,n.exports,e),n.exports}(154)})(),"object"==typeof exports&&"object"==typeof module?module.exports=e(require("./createGlobalState.js")):"function"==typeof define&&define.amd?define(["./createGlobalState.js"],e):"object"==typeof exports?exports["react-hooks-global-states"]=e(require("./createGlobalState.js")):this["react-hooks-global-states"]=e(this["./createGlobalState.js"]);

package/generateStackHash.d.ts

@@ -1,2 +0,0 @@
-export declare const generateStackHash: (stack: string) => string;
-export default generateStackHash;

package/generateStackHash.js

@@ -1 +0,0 @@
-var e;e=()=>(()=>{"use strict";var e={};return((e,t)=>{Object.defineProperty(t,"__esModule",{value:!0}),t.generateStackHash=void 0,t.generateStackHash=function(e){if(!e.trim())return"unknown";e=e.replace(/\s/g,"");for(var t=2166136261,o=0;o<e.length;o++)t^=e.charCodeAt(o),t*=16777619,t&=4294967295;return function(e){for(var t="";e>0;)t="0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"[e%62]+t,e=Math.floor(e/62);return t||"0"}(t>>>0)},t.default=t.generateStackHash})(0,e),e})(),"object"==typeof exports&&"object"==typeof module?module.exports=e():"function"==typeof define&&define.amd?define([],e):"object"==typeof exports?exports["react-hooks-global-states"]=e():this["react-hooks-global-states"]=e();

package/useStableState.d.ts

@@ -1,14 +0,0 @@
-type Cleanup = () => void;
-type StateBuilder<T> = () => [state: T, cleanup?: Cleanup];
-type RefObject<T> = {
-    current: T;
-};
-/**
- * @deprecated
- * - Only one stable initial render
- * - Only one stable cleanup every time dependencies change
- * - Initial render doesn't trigger cleanup
- * - Starts cold, returns null until the first render or fallback if provided
- */
-export declare const useStableState: <T, F extends T | never>(builder: StateBuilder<T>, dependencies: unknown[], fallbackArg?: F) => F extends T ? RefObject<T> : RefObject<T> | null;
-export default useStableState;

package/useStableState.js

@@ -1 +0,0 @@
-var t;t=t=>(()=>{"use strict";var e={155:e=>{e.exports=t},163:(t,e,r)=>{function n(t,e){return function(t){if(Array.isArray(t))return t}(t)||function(t,e){var r=null==t?null:"undefined"!=typeof Symbol&&t[Symbol.iterator]||t["@@iterator"];if(null!=r){var n,o,a,u,l=[],i=!0,c=!1;try{if(a=(r=r.call(t)).next,0===e){if(Object(r)!==r)return;i=!1}else for(;!(i=(n=a.call(r)).done)&&(l.push(n.value),l.length!==e);i=!0);}catch(t){c=!0,o=t}finally{try{if(!i&&null!=r.return&&(u=r.return(),Object(u)!==u))return}finally{if(c)throw o}}return l}}(t,e)||o(t,e)||function(){throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.")}()}function o(t,e){if(t){if("string"==typeof t)return a(t,e);var r={}.toString.call(t).slice(8,-1);return"Object"===r&&t.constructor&&(r=t.constructor.name),"Map"===r||"Set"===r?Array.from(t):"Arguments"===r||/^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(r)?a(t,e):void 0}}function a(t,e){(null==e||e>t.length)&&(e=t.length);for(var r=0,n=Array(e);r<e;r++)n[r]=t[r];return n}Object.defineProperty(e,"__esModule",{value:!0}),e.useStableState=void 0;var u=r(155);e.useStableState=function(t,e,r){var l,i,c=n((0,u.useState)({}),2)[1],f=(0,u.useCallback)((function(){c({})}),[]),s=(0,u.useRef)({builder:t,stateRef:null,fallback:r?{current:r}:void 0,isMounted:!1});s.current.builder=t,(0,u.useEffect)((function(){var t=n((0,s.current.builder)(),2),e=t[0],r=t[1];if(s.current.stateRef={current:e},f(),s.current.isMounted)return function(){null==r||r()};s.current.isMounted=!0}),[f].concat(function(t){if(Array.isArray(t))return a(t)}(i=e)||function(t){if("undefined"!=typeof Symbol&&null!=t[Symbol.iterator]||null!=t["@@iterator"])return Array.from(t)}(i)||o(i)||function(){throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.")}()));var d=s.current,b=d.stateRef,y=d.fallback;return null!==(l=null!=b?b:y)&&void 0!==l?l:null},e.default=e.useStableState}},r={};return function t(n){var o=r[n];if(void 0!==o)return o.exports;var a=r[n]={exports:{}};return e[n](a,a.exports,t),a.exports}(163)})(),"object"==typeof exports&&"object"==typeof module?module.exports=t(require("react")):"function"==typeof define&&define.amd?define(["react"],t):"object"==typeof exports?exports["react-hooks-global-states"]=t(require("react")):this["react-hooks-global-states"]=t(this.react);