react-global-state-hooks 1.1.1 → 2.0.0

package/README.md

@@ -1,694 +1,769 @@
 # react-global-state-hooks
 
-This is a package to easily handling global-state across your react components
-
-This utility uses the **useState** hook within a subscription pattern and **HOFs** to create a more intuitive, atomic and easy way of sharing state between components... You can see an introduction video [here!](https://www.youtube.com/watch?v=WfoMhO1zZ04)
+This is a package to easily handling **global state hooks** across your **react components**
 
 For seen a running example of the hooks, you can check the following link: [react-global-state-hooks-example](https://johnny-quesada-developer.github.io/react-global-state-hooks-example/)
 
-...
-
-...
+To see **TODO-LIST** with the hooks and **async storage** take a look here: [todo-list-with-global-hooks](https://github.com/johnny-quesada-developer/todo-list-with-global-hooks.git).
 
-# Creating a global store
+To see how to create a custom hook connected to your favorite async storage, please refer to the documentation section titled **Extending Global Hooks**
 
-We are gonna create a global count example **useCountGlobal.ts**:
-
-```ts
-import { GlobalStore } from 'react-global-state-hooks';
+You can also see an introduction video [here!](https://www.youtube.com/watch?v=WfoMhO1zZ04&t=8s)
 
-// initialize your store with the default value of the same.
-const countStore = new GlobalStore(0);
+# Creating a global state
 
-// get the hook
-export const useCountGlobal = countStore.getHook();
+We are gonna create a global state hook **useCount** with one line of code.
 
-// inside your component just call...
-const [count, setCount] = useCountGlobal(); // no paremeters are needed since this is a global store
-
-// That's it, that's a global store... Strongly typed, with a global-hook that we could reuse cross all our react-components.
+```ts
+import { createGlobalState } from 'react-global-state-hooks';
 
-// #### Optionally you are able to use a decoupled hook,
-// #### This function is linked to the store hooks but is not a hook himself.
+export const useCount = createGlobalState(0);
+```
 
-export const [getCount, sendCount] = countStore.getHookDecoupled();
+That's it! Welcome to global hooks. Now, you can use this state wherever you need it in your application.
 
-// @example
-console.log(getCount()); // 0;
+Let's see how to use it inside a simple **component**
 
-// components subscribed to the global hook if there are so
-sendCount(5);
+```ts
+const [count, setCount] = useCount();
 
-console.log(getCount()); // 5;
+return <button onclick={() => setCount((count) => count + 1)}>{count}</button>;
 ```
 
-...
+Isn't it cool? It works just like a regular **useState**. Notice the only difference is that now you don't need to provide the initial value since this is a global hook, and the initial value has already been provided.
+
+# Selectors
 
-...
+What if you already have a global state that you want to subscribe to, but you don't want your component to listen to all the changes of the state, only a small portion of it? Let's create a more complex **state**
 
-# Implementing your global hook into your components
+```ts
+import { createGlobalState } from 'react-global-state-hooks';
 
-Let's say we have two components **MyFirstComponent**, **MySecondComponent**, in order to use our global hook they will look just like:
+export const useContacts = createGlobalState({
+  isLoading: true,
+  filter: '',
+  items: [] as Contact[],
+});
+```
 
-```JSX
-import { useCountGlobal } from './useCountGlobal'
+Now, let's say we want to have a filter bar for the contacts that will only have access to the filter.
 
-const MyFirstComponent: React.FC = () => {
-  const [count, setter] = useCountGlobal();
-  const onClickAddOne = () => setter(count + 1);
+**FilterBar.tsx**
 
-  return (<button onClick={onClickAddOne}>{`count: ${count}`}</button>);
-}
+```ts
+const [{ filter }, setState] = useContacts(({ filter }) => ({ filter }));
+
+return (
+  <input
+    onChange={(event) =>
+      setState((state) => ({ ...state, filter: event.target.value }))
+    }
+  />
+);
+```
 
-const MySecondComponent: React.FC = () => {
-  const [count, setter] = useCountGlobal();
+There you have it again, super simple! By adding a **selector** function, you are able to create a derivative hook that will only trigger when the result of the **selector** changes.
 
-  // it can also be use as a normal setter into a callback or other hooks
-  const onClickAddTwo = useCallback(() => setter(state => state + 2), [])
+By the way, in the example, the **selector** returning a new object is not a problem at all. This is because, by default, there is a shallow comparison between the previous and current versions of the state, so the render won't trigger if it's not necessary.
 
-  return (<button onClick={onClickAddOne}>{`count: ${count}`}</button>);
-}
+## What if you want to reuse the selector?
 
-// It's so simple to share information between components
-```
+It will be super common to have the necessity of reusing a specific **selector**, and it can be a little annoying to have to do the same thing again and again. Right?
 
-Note that the only difference between this and the default **useState** hook is that you are not adding the initial value, cause you already did that when you created the store:
+No problem, you can create a reusable **derivative-state** and use it across your components. Let's create one for our filter.
 
 ```ts
-const countStore = new GlobalStore(0);
+const useFilter = createDerivate(useContacts, ({ filter }) => ({ filter }));
 ```
 
-...
-
-...
-
-# Persisting state into localhost
+Well, that's it! Now you can simply call **useFilter** inside your component, and everything will continue to work the same.
 
-if you want to persist the value of the store into the. **localstorage**, you only have to add the property **localStorageKey** into the configuration parameter.
+**FilterBar.tsx**
 
 ```ts
-const countStore = new GlobalStore(0, {
-  localStorageKey: 'my_persisted_state',
-
-  // by default, the state is encrypted to base64, but you can disable it, or use a custom encryptor
-  encrypt: false,
-
-  // by default, the state is encrypted to base64, but you can disable it, or use a custom decrypt
-  decrypt: false,
-});
+const [{ filter }, setState] = useFilter();
+
+return (
+  <input
+    onChange={(event) =>
+      setState((state) => ({ ...state, filter: event.target.value }))
+    }
+  />
+);
 ```
 
-...
-
-...
+Notice that the **state** changes, but the **setter** does not. This is because this is a **DERIVATE state**, and it cannot be directly changed. It will always be derived from the main hook.
 
-# Decoupled hook
+# State actions
 
-If you want to access the global state outside a component or outside a hook, or without subscribing the component to the state changes...
+Is common and often necessary to restrict the manipulation of state to a specific set of actions or operations. To achieve this, we can simplify the process by adding a custom API to the configuration of our **useContacts**.
 
-This is especially useful when you want to create components that have edition access to a certain store, but they actually don't need to be reactive to the state changes, like a search component that just need to get the current state every time that is going to search the data; but actually don't need to be subscribed to the changes over the collection he is going to be filtering.
+By defining a custom API for the **useContacts**, we can encapsulate and expose only the necessary actions or operations that are allowed to modify the state. This provides a controlled interface for interacting with the state, ensuring that modifications stick to the desired restrictions.
 
 ```ts
-import { GlobalStore } from 'react-global-state-hooks';
-
-const countStore = new GlobalStore(0);
+import { createGlobalState } from 'react-global-state-hooks';
 
-// remember this should be used as the **useState** hook.
-export const useCountGlobal = countStore.getHook();
+const initialState = {
+  isLoading: true,
+  filter: '',
+  items: [] as Contact[],
+};
 
-// this functions are not hooks, and they can be used in whatever place into your code, ClassComponents, OtherHooks, Services etc.
-export const [getCount, sendCount] = countStore.getHookDecoupled();
+type State = typeof initialState;
+
+export const useContacts = createGlobalState(initialState, {
+  // this are the actions available for this state
+  actions: {
+    setFilter(filter: string) {
+      return ({ setState }: StoreTools<State>) => {
+        setState((state) => ({
+          ...state,
+          filter,
+        }));
+      };
+    },
+  } as const,
+  onInit: async ({ setState }: StoreTools<State>) => {
+    // fetch contacts
+  },
+});
 ```
 
-Let's see a trivial example:
-
-...
-
-```JSX
-import { useCountGlobal, sendCount } from './useCountGlobal'
+That's it! In this updated version, the **useContacts** hook will no longer return [**state**, **stateSetter**] but instead will return [**state**, **actions**]. This change will provide a more intuitive and convenient way to access and interact with the state and its associated actions.
 
-const CountDisplayerComponent: React.FC = () => {
-  const [count] = useCountGlobal();
+Let's see how that will look now into our **FilterBar.tsx**
 
-  return (<label>{count}<label/>);
-}
+```tsx
+const [{ filter }, { setFilter }] = useFilter();
 
-// here we have a separate component that is gonna handle the state of the previous component we created,
-// this new component is not gonna be affected by the changes applied on <CountDisplayerComponent/>
-// Stage2 does not need to be updated once the global count changes
-const CountManagerComponent: React.FC = () => {
-  const increaseClick = useCallback(() => sendCount(count => count + 1), []);
-  const decreaseClick = useCallback(() => sendCount(count => count - 1), []);
-
-  return (<>
-      <button onClick={increaseClick} >increase</button>
-      <button onClick={decreaseClick} >decrease</button>
-    </>);
-}
+return <input onChange={(event) => setFilter(event.target.value)} />;
 ```
 
-...
-
-...
-
-# Restricting the manipulation of the global **state**
-
-## Who hate reducers?
+Yeah, that's it! All the **derived states** and **emitters** (we will talk about this later) will inherit the new actions interface.
 
-It's super common to have the wish or the necessity of restricting the manipulation of the **state** through a specific set of actions or manipulations...**Dispatches**? **Actions**? Let's make it simple BY adding a custom **API** to the configuration of our **GlobalStore**
-...
+You can even **derive** from another **derived state**! Let's explore a few silly examples:
 
 ```ts
-const initialValue = 0;
+const useFilter = createDerivate(useContacts, ({ filter }) => ({ filter }));
 
-const config = {
-  // this is not reactive information that you could also store in the async storage
-  // upating the metadata will not trigger the onStateChanged method or any update on the components
-  metadata: null,
+const useFilterString = createDerivate(useFilter, { filter } => filter);
 
-  // The lifecycle callbacks are: onInit, onStateChanged, onSubscribed and computePreventStateChange
-};
+const useContacts = createDerivate(useContacts, ({ items }) => items);
 
-const countStore = new GlobalStore(
-  initialValue,
-  config,
-  {
-    log: (message: string) => (): void => {
-      console.log(message);
-    },
+const useContactsLength = createDerivate(useContacts, (items) => items.length);
 
-    increase(message: string) {
-      return (storeTools: StoreTools<number>) => {
-        this.log(message);
+const useIsContactsEmpty = createDerivate(useContactsLength, (length) => !length);
+```
 
-        return storeTools.getState();
-      };
-    },
+It can't get any simpler, right? Everything is connected, everything is reactive. Plus, these hooks are strongly typed, so if you're working with **TypeScript**, you'll absolutely love it.
 
-    decrease(message: string) {
-      return (storeTools: StoreTools<number>) => {
-        this.log(message);
+# Decoupled state access
 
-        return storeTools.getState();
-      };
-    },
-  } as const // the -as const- is necessary to avoid typescript errors
-);
+If you need to access the global state outside of a component or a hook without subscribing to state changes, or even inside a **ClassComponent**, you can use the **createGlobalStateWithDecoupledFuncs**.
 
-// the way to get the hook is the same as for simple setters
-const useCountStore = countStore.getHook();
+Decoupled state access is particularly useful when you want to create components that have editing access to a specific store but don't necessarily need to reactively respond to state changes.
 
-// now instead of a setState method, you'll get an actions object
-// that contains all the actions that you defined in the setterConfig
-const [count, countActions] = useCountStore();
+Using decoupled state access allows you to retrieve the state when needed without establishing a reactive relationship with the state changes. This approach provides more flexibility and control over when and how components interact with the global state. Let's see and example:
 
-// count is the current state - 0 (number)
-// countActions is an object that contains all the actions that you defined in the setterConfig
-// countActions.increase(); // this will increase the count by 1, returns the new count (number)
-// countActions.decrease(); // this will decrease the count by 1, returns the new count (number)
+```ts
+import { createGlobalStateWithDecoupledFuncs } from 'react-global-state-hooks';
+
+export const [useContacts, contactsGetter, contactsSetter] =
+  createGlobalStateWithDecoupledFuncs({
+    isLoading: true,
+    filter: '',
+    items: [] as Contact[],
+  });
 ```
 
-...
-
-# Configuration callbacks
-
-## config.onInit
-
-This method will be called once the store is created after the constructor,
+That's great! With the addition of the **contactsGetter** and **contactsSetter** methods, you now have the ability to access and modify the state without the need for subscription to the hook.
 
-@examples
+While **useContacts** will allow your components to subscribe to the custom hook, using the **contactsGetter** method you will be able retrieve the current value of the state. This allows you to access the state whenever necessary, without being reactive to its changes. Let' see how:
 
 ```ts
-import { GlobalStore } from 'react-global-state-hooks';
+// To synchronously get the value of the state
+const value = contactsGetter();
 
-const initialValue = 0;
+// the type of value will be { isLoading: boolean; filter: string; items: Contact[] }
+```
 
-const store = new GlobalStore(0, {
-  onInit: async ({ setMetadata, setState }) => {
-    const data = await someApiCall();
+Additionally, to subscribe to state changes, you can pass a callback function as a parameter to the **getter**. This approach enables you to create a subscription group, allowing you to subscribe to either the entire state or a specific portion of it. When a callback function is provided to the **getter**, it will return a cleanup function instead of the state. This cleanup function can be used to unsubscribe or clean up the subscription when it is no longer needed.
 
-    setState(data);
-    setMetadata({ isDataUpdated: true });
-  },
+```ts
+/**
+ * This not only allows you to retrieve the current value of the state...
+ * but also enables you to subscribe to any changes in the state or a portion of it
+ */
+const removeSubscriptionGroup = contactsGetter<Subscribe>((subscribe) => {
+  subscribe((state) => {
+    console.log('state changed: ', state);
+  });
+
+  subscribe(
+    (state) => state.isLoading,
+    (isLoading) => {
+      console.log('is loading changed', isLoading);
+    }
+  );
 });
 ```
 
-...
+That's great, isn't it? everything stays synchronized with the original state!!
 
-## config.onStateChanged
+# Emitters
 
-This method will be called every time the state is changed
-
-@examples
+So, we have seen that we can subscribe a callback to state changes, create **derivative states** from our global hooks, **and derive hooks from those derivative states**. Guess what? We can also create derivative **emitters** and subscribe callbacks to specific portions of the state. Let's review it:
 
 ```ts
-import { GlobalStore } from 'react-global-state-hooks';
-
-const store = new GlobalStore(0, {
-  onStateChanged: ({ getState }) => {
-    const state = getState();
-
-    console.log(state);
-  },
-});
+const subscribeToFilter = createDerivateEmitter(
+  contactsGetter,
+  ({ filter }) => ({
+    filter,
+  })
+);
 ```
 
-...
-
-## config.onSubscribed
-
-This method will be called every time a component is subscribed to the store
+Cool, it's basically the same, but instead of using the **hook** as a parameter, we just have to use the **getter** as a parameter, and that will make the magic.
 
-@examples
+Now we are able to add a callback that will be executed every time the state of the **filter** changes.
 
 ```ts
-import { GlobalStore } from 'react-global-state-hooks';
-
-const store = new GlobalStore(0, {
-  onSubscribed: ({ getState }) => {
-    console.log('A component was subscribed to the store');
-  },
+const removeFilterSubscription = subscribeToFilter<Subscribe>(({ filter }) => {
+  console.log(`The filter value changed: ${filter}`);
 });
 ```
 
-...
-
-## config.computePreventStateChange
-
-This method will be called every time the state is going to be changed, if it returns true the state won't be changed
-
-@examples
+By default, the callback will be executed once subscribed, using the current value of the state. If you want to avoid this initial call, you can pass an extra parameter to the **subscribe** function.
 
 ```ts
-import { GlobalStore } from 'react-global-state-hooks';
-
-const store = new GlobalStore(0, {
-  computePreventStateChange: ({ getState }) => {
-    const state = getState();
-    const shouldPrevent = state < 0;
-
-    if (shouldPrevent) return true;
-
-    return false;
+const removeFilterSubscription = subscribeToFilter<Subscribe>(
+  ({ filter }) => {
+    console.log(`The filter value changed: ${filter}`);
   },
-});
+  {
+    skipFirst: true,
+  }
+);
 ```
 
-...
+Also, of course, if you have an exceptional case where you want to derivate directly from the current **emitter**, you can add a **selector**. This allows you to fine-tune the emitted values based on your requirements
 
-...
+```ts
+const removeFilterSubscription = subscribeToFilter<Subscribe>(
+  ({ filter }) => filter,
+  /**
+   *  Cause of the selector the filter now is an string
+   */
+  (filter) => {
+    console.log(`The filter value changed: ${filter}`);
+  },
+  {
+    skipFirst: true,
+    /**
+     * You can also override the default shallow comparison...
+     * or disable it completely by setting the isEqual callback to null.
+     */
+    isEqual: (a, b) => a === b,
+    // isEqual: null // this will avoid doing a shallow comparison
+  }
+);
+```
 
-...
+And guess what again? You can also derive emitters from derived emitters without any trouble at all! It works basically the same. Let's see an example:
 
-...
+```ts
+const subscribeToItems = createDerivateEmitter(
+  contactsGetter,
+  ({ items }) => items
+);
 
-...
+const subscribeToItemsLength = createDerivateEmitter(
+  subscribeToItems,
+  (items) => items.length
+);
+```
 
-# Examples and Comparison:
+The examples may seem a little silly, but they allow you to see the incredible things you can accomplish with these **derivative states** and **emitters**. They open up a world of possibilities!
 
-## 1. Lets try to share some state between components
+# Combining getters
 
-### **With the GlobalStore approach, it will look like this:**
+What if you have two states and you want to combine them? You may have already guessed it right? ... you can create combined **emitters** and **hooks** from the hook **getters**.
 
-```tsx
-type TUser = {
-  name: string;
-  email: string;
-};
+By utilizing the approach of combining **emitters** and **hooks**, you can effectively merge multiple states and make them shareable. This allows for better organization and simplifies the management of the combined states. You don't need to refactor everything; you just need to combine the **global state hooks** you already have. Let's see a simple example:
 
-const useUserStore = new GlobalStore<TUser>({
-  name: null,
-  email: null,
-}).getHook();
+Fist we are gonna create a couple of **global state**, is important to create them with the **createGlobalStateWithDecoupledFuncs** since we need the decoupled **getter**. (In case you are using an instance of **GlobalStore** or **GlobalStoreAbstract** you can just pick up the getters from the **getHookDecoupled** method)
 
-const Component = () => {
-  const [currentUser] = useUserStore();
+```ts
+const [useHook1, getter1, setter1] = createGlobalStateWithDecoupledFuncs({
+  propA: 1,
+  propB: 2,
+});
 
-  return <Text>{currentUser.name}</Text>;
-};
+const [, getter2] = createGlobalStateWithDecoupledFuncs({
+  propC: 3,
+  propD: 4,
+});
 ```
 
-## Simple, right?
+Okay, cool, the first state as **propA, propB** while the second one has **propC, propD**, let's combine them:
 
-### Let's now see how this same thing would look like by using context:
+```ts
+const [useCombinedHook, getter, dispose] = combineAsyncGetters(
+  {
+    selector: ([state1, state2]) => ({
+      ...state1,
+      ...state2,
+    }),
+  },
+  getter1,
+  getter2
+);
+```
 
-```tsx
-type TUser = {
-  name: string;
-  email: string;
-};
+Well, that's it! Now you have access to a **getter** that will return the combined value of the two states. From this new **getter**, you can retrieve the value or subscribe to its changes. Let'see:
 
-const UserContext = createContext<{
-  currentUser: TUser;
-}>({
-  currentUser: null,
+```ts
+const value = getter(); // { propA, propB, propC, propD }
+
+// subscribe to the new emitter
+const unsubscribeGroup = getter<Subscribe>((subscribe) => {
+  subscribe((state) => {
+    console.log(subscribe); // full state
+  });
+
+  // Please note that if you add a selector,
+  // the callback will only trigger if the result of the selector changes.
+  subscribe(
+    ({ propA, propD }) => ({ propA, propD }),
+    (derivate) => {
+      console.log(derivate); // { propA, propD }
+    }
+  );
 });
+```
 
-const UserProvider: React.FC<PropsWithChildren> = ({ children }) => {
-  const [currentUser, setCurrentUser] = useState<TUser>(null);
+Regarding the newly created hook, **useCombinedHook**, you can seamlessly utilize it across all your components, just like your other **global state hooks**. This enables a consistent and familiar approach for accessing and managing the combined state within your application.
 
-  // ...get current user information
+```ts
+const [combinedState] = useCombinedHook();
+```
 
-  return (
-    <UserContext.Provider value={{ currentUser }}>
-      {children}
-    </UserContext.Provider>
-  );
-};
+The main difference with **combined hooks** compared to individual **global state hooks** is the absence of **metadata** and **actions**. Instead, combined hooks provide a condensed representation of the underlying global states using simple React functionality. This streamlined approach ensures lightweight usage, making it easy to access and manage the combined state within your components.
 
-const Component = () => {
-  const { currentUser } = useContext(UserContext);
+### Let's explore some additional examples.
 
-  return <Text>{currentUser.name}</Text>;
-};
+Similar to your other **global state hooks**, **combined hooks** allow you to use **selectors** directly from consumer components. This capability eliminates the need to create an excessive number of reusable hooks if they are not truly necessary. By utilizing selectors, you can efficiently extract specific data from the **combined state** and utilize it within your components. This approach offers a more concise and focused way of accessing the required state values without the need for creating additional hooks unnecessarily.
 
-const App = () => {
-  return (
-    <UserProvider>
-      <Component />
-    </UserProvider>
-  );
-};
+```ts
+const [fragment] = useCombinedHook(({ propA, propD }) => ({ propA, propD }));
 ```
 
-### We already are able to notice a couple of extra lines right?
+Lastly, you have the flexibility to continue combining getters if desired. This means you can extend the functionality of combined hooks by adding more getters to merge additional states. By combining getters in this way, you can create a comprehensive and unified representation of the combined states within your application. This approach allows for modular and scalable state management, enabling you to efficiently handle complex state compositions.
 
-Let's now add another simple store to the equation
+Let's see an example:
 
-### **With the GlobalStore approach, it will look like this:**
-
-```tsx
-type TUser = {
-  name: string;
-  email: string;
-};
-
-const useUserStore = new GlobalStore<TUser>({
-  name: null,
-  email: null,
-}).getHook();
+```ts
+const [useCombinedHook, combinedGetter1, dispose1] = combineAsyncGetters(
+  {
+    selector: ([state1, state2]) => ({
+      ...state1,
+      ...state2,
+    }),
+  },
+  getter1,
+  getter2
+);
 
-// we create the store
-const useCountStore = new GlobalStore(0).getHook();
+const [useHook3, getter3, setter3] = createGlobalStateWithDecoupledFuncs({
+  propE: 1,
+  propF: 2,
+});
 
-const Component = () => {
-  const [currentUser] = useUserStore();
+const [useIsLoading, isLoadingGetter, isLoadingSetter] =
+  createGlobalStateWithDecoupledFuncs(false);
+```
 
-  // from the component we consume the new store
-  const [count, setCount] = useCountStore();
+Once we created another peace of state, we can combine it with our other **global hooks** and **emitters**
 
-  return <label>{currentUser.name}</label>;
-};
+```ts
+const [useCombinedHook2, combinedGetter2, dispose2] = combineAsyncGetters(
+  {
+    selector: ([state1, state2, isLoading]) => ({
+      ...state1,
+      ...state2,
+      isLoading,
+    }),
+  },
+  combinedGetter1,
+  getter3,
+  isLoadingGetter
+);
 ```
 
-With context, we'll have again to create all the boilerplate, and wrap the component into the new provider...
+You have the freedom to combine as many global hooks as you wish. This means you can merge multiple states into a single cohesive unit by combining their respective hooks. This approach offers flexibility and scalability, allowing you to handle complex state compositions in a modular and efficient manner.
 
-### **Lets see that**
+### **Quick note**:
 
-```tsx
-type TUser = {
-  name: string;
-  email: string;
-};
+Please be aware that the third parameter is a **dispose callback**, which can be particularly useful in **high-order** functions when you want to release any resources associated with the hook. By invoking the dispose callback, the hook will no longer report any changes, ensuring that resources are properly cleaned up. This allows for efficient resource management and can be beneficial in scenarios where you need to handle resource cleanup or termination in a controlled manner.
 
-const UserContext = createContext<{
-  currentUser: TUser;
-}>({
-  currentUser: null,
-});
+## Setter
 
-// let's create the context
-const CountContext = createContext({
-  count: 0,
-  setCount: (() => {
-    throw new Error('not implemented');
-  }) as Dispatch<SetStateAction<number>>,
-});
+Similarly, the **contactsSetter** method allows you to modify the state stored in **useContacts**. You can use this method to update the state with a new value or perform any necessary state mutations without the restrictions imposed by **hooks**.
 
-const UserProvider: React.FC<PropsWithChildren> = ({ children }) => {
-  const [currentUser, setCurrentUser] = useState<TUser>(null);
+These additional methods provide a more flexible and granular way to interact with the state managed by **useContacts**. You can retrieve and modify the state as needed, without establishing a subscription relationship or reactivity with the state changes.
 
-  // ...
+Let's add more actions to the state and explore how to use one action from inside another.
 
-  return (
-    <UserContext.Provider value={{ currentUser }}>
-      {children}
-    </UserContext.Provider>
-  );
-};
+Here's an example of adding multiple actions to the state and utilizing one action within another:
 
-// we also need another provider
-const CountProvider: React.FC<PropsWithChildren> = ({ children }) => {
-  const [count, setCount] = useState(0);
+```ts
+import { createGlobalState } from 'react-global-state-hooks';
 
-  return (
-    <CountContext.Provider value={{ count, setCount }}>
-      {children}
-    </CountContext.Provider>
-  );
-};
+export const useCount = createGlobalState(0, {
+  actions: {
+    log: (currentValue: string) => {
+      return ({ getState }: StoreTools<number>): void => {
+        console.log(`Current Value: ${getState()}`);
+      };
+    },
 
-// we need to wrap the component into the new provider (this is for each future context)
-const App = () => {
-  return (
-    <UserProvider>
-      <CountProvider>
-        <Component />
-      </CountProvider>
-    </UserProvider>
-  );
-};
+    increase(value: number = 1) {
+      return ({ getState, setState, actions }: StoreTools<number>) => {
+        setState((count) => count + value);
 
-const Component = () => {
-  const { currentUser } = useContext(UserContext);
+        actions.log(message);
+      };
+    },
 
-  // finally we are able to get access to the new context...
-  const { count, setCount } = useContext(CountContext);
+    decrease(value: number = 1) {
+      return ({ getState, setState, actions }: StoreTools<number>) => {
+        setState((count) => count - value);
 
-  return <label>{currentUser.name}</label>;
-};
+        actions.log(message);
+      };
+    },
+  } as const,
+});
 ```
 
-In this example, we are able to see how every time along with creating a good amount of repetitive code, we also have to wrap the necessary components into the Provider... Also, notice how every time we need to modify the **App** component, even when the App component is not gonna use the new state.
-
-### Let's make this a little more complex, now I want to implement custom methods for manipulating the count state, I also want to have the ability to modify the count state **without** having to be subscribed to the changes of the state... have you ever done that?
+Notice that the **StoreTools** will contain a reference to the generated actions API. From there, you'll be able to access all actions from inside another one... the **StoreTools** is generic and allow your to set an interface for getting the typing on the actions.
 
-This is a common scenery, and guess what? in the **context** examples, we'll have to create another context, another provider, wrap and everything again...
+If you don't want to create an extra type please use **createGlobalStateWithDecoupledFuncs** in that way you'll be able to use the decoupled **actions** which will have the correct typing. Let's take a quick look into that:
 
-## Let's see this time first the **context** approach
+```ts
+import { createGlobalStateWithDecoupledFuncs } from 'react-global-state-hooks';
+
+export const [useCount, getCount, $actions] =
+  createGlobalStateWithDecoupledFuncs(0, {
+    actions: {
+      log: (currentValue: string) => {
+        return ({ getState }: StoreTools<number>): void => {
+          console.log(`Current Value: ${getState()}`);
+        };
+      },
+
+      increase(value: number = 1) {
+        return ({ getState, setState }: StoreTools<number>) => {
+          setState((count) => count + value);
+
+          $actions.log(message);
+        };
+      },
+    } as const,
+  });
+```
 
-```tsx
-type TUser = {
-  name: string;
-  email: string;
-};
+In the example the hook will work the same and you'll have access to the correct typing.
 
-const UserContext = createContext<{
-  currentUser: TUser;
-}>({
-  currentUser: null,
-});
+# Local Storage
 
-// let's remove the setter from this context
-const CountContext = createContext({
-  count: 0,
-});
+By default, our global hooks are capable of persisting information in local storage. To achieve this, you need to provide the key that will be used to persist the data. Additionally, you have the option to encrypt the stored data.
 
-// lets create another context to share the actions
-const CountContextSetter = createContext({
-  increase: (): void => {
-    throw new Error('increase is not implemented');
-  },
-  decrease: (): void => {
-    throw new Error('decrease is not implemented');
+```ts
+const useContacts = createGlobalState(
+  {
+    filter: '',
+    items: [] as Contact[],
   },
-});
+  {
+    localStorage: {
+      key: 'data',
+    },
+  }
+);
+```
 
-const UserProvider: React.FC<PropsWithChildren> = ({ children }) => {
-  const [currentUser, setCurrentUser] = useState<TUser>(null);
+That means your data will automatically be synchronized with the local storage, and you don't need to worry about losing the type of your Maps/Sets/Dates - the store takes care of it for you.
 
-  // ...
+# Extending Global Hooks
 
-  return (
-    <UserContext.Provider value={{ currentUser }}>
-      {children}
-    </UserContext.Provider>
-  );
-};
+Creating a custom builder for your **global hook** is made incredibly easy with the **createCustomGlobalState** function.
 
-// To don't overcomplicate the example let's just add but providers into this component, that will be enough
-const CountProvider: React.FC<PropsWithChildren> = ({ children }) => {
-  const [count, setCount] = useState(0);
-
-  const increase = () => setCount(count + 1);
-  const decrease = () => setCount(count - 1);
-
-  return (
-    //one context is gonna share the edition of the state
-    <CountContext.Provider value={{ count }}>
-      {/* this second component will share the mutations of the state */}
-      <CountContextSetter.Provider value={{ increase, decrease }}>
-        {children}
-      </CountContextSetter.Provider>
-    </CountContext.Provider>
-  );
-};
-
-// Since we used the same provider we don't need to modify the  **App** component, but we do are **Wrapping** everything into one more **Provider**
-const App = () => {
-  return (
-    <UserProvider>
-      <CountProvider>
-        {/* lets create two componets instead of one */}
-        <ComponentSetter />
-        <Component />
-      </CountProvider>
-    </UserProvider>
-  );
-};
+This function returns a new global state builder wrapped with the desired custom implementation, allowing you to get creative! Le'ts see and example:
 
-const ComponentSetter = () => {
-  const { increase, decrease } = useContext(CountContextSetter);
+```ts
+import { formatFromStore, formatToStore, createCustomGlobalState } = 'react-global-state-hooks'
 
-  return (
-    <>
-      <button onPress={increase}>Increase</button>
-      <button onPress={decrease}>Decrease</button>
-    </>
-  );
+// Optional configuration available for the consumers of the builder
+type HookConfig = {
+  asyncStorageKey?: string;
 };
 
-const Component = () => {
-  const { currentUser } = useContext(UserContext);
-
-  // finally we are able to get access to the new context...
-  const { count } = useContext(CountContext);
-
-  return (
-    <>
-      <label>{currentUser.name}</label>
-      <label>{count}</label>
-    </>
-  );
+// This is the base metadata that all the stores created from the builder will have.
+type BaseMetadata = {
+  isAsyncStorageReady?: boolean;
 };
-```
 
-Wow, a lot!!! just to be able to separate the mutations... and have mutations!!
+export const createGlobalState = createCustomGlobalState<
+  BaseMetadata,
+  HookConfig
+>({
+  /**
+   * This function executes immediately after the global state is created, before the invocations of the hook
+   */
+  onInitialize: async ({ setState, setMetadata }, config) => {
+    setMetadata((metadata) => ({
+      ...(metadata ?? {}),
+      isAsyncStorageReady: null,
+    }));
+
+    const asyncStorageKey = config?.asyncStorageKey;
+    if (!asyncStorageKey) return;
+
+    const storedItem = (await asyncStorage.getItem(asyncStorageKey)) as string;
+
+    // update the metadata, remember, metadata is not reactive
+    setMetadata((metadata) => ({
+      ...metadata,
+      isAsyncStorageReady: true,
+    }));
+
+    if (storedItem === null) {
+      return setState((state) => state, { forceUpdate: true });
+    }
+
+    const parsed = formatFromStore(storedItem, {
+      jsonParse: true,
+    });
+
+    setState(parsed, { forceUpdate: true });
+  },
 
-### it would be easier with the GlobalStore? Let's see.
+  onChange: ({ getState }, config) => {
+    if (!config?.asyncStorageKey) return;
 
-```tsx
-type TUser = {
-  name: string;
-  email: string;
-};
+    const state = getState();
 
-const useUser = new GlobalStore<TUser>({
-  name: null,
-  email: null,
-}).getHook();
-
-// let's modify the store to add custom actions, the second parameter is configuration let's just pass null for now
-const countStore = new GlobalStore(0, null, {
-  increase() {
-    return ({ setState }: StoreTools<number>) => {
-      setState((state) => state + 1);
-    };
-  },
+    const formattedObject = formatToStore(state, {
+      stringify: true,
+    });
 
-  decrease() {
-    return ({ setState }: StoreTools<number>) => {
-      setState((state) => state - 1);
-    };
+    asyncStorage.setItem(config.asyncStorageKey, formattedObject);
   },
-} as const);
+});
+```
 
-const useCount = countStore.getHook();
+It is important to use **forceUpdate** to force React to re-render our components and obtain the most recent state of the **metadata**. This is especially useful when working with primitive types, as it can be challenging to differentiate between a primitive value that originates from storage and one that does not.
 
-// this actions don't use hooks, but are connected to the store and all the subscribers will be notified
-const [, countActions] = countStore.getHookDecoupled();
+It is worth mentioning that the **onInitialize** function will be executed only once per global state.
 
-// this component is not subscribed to the store, so it will not be notified when the state changes
-const ComponentSetter = () => {
-  return (
-    <>
-      <button onPress={countActions.increase}>Increase</button>
-      <button onPress={countActions.decrease}>Decrease</button>
-    </>
-  );
-};
+You can use to **formatToStore**, and **formatFromStore** to sanitize your data, These methods will help you transform objects into JSON strings and retrieve them back without losing any of the original data types. You will no longer encounter problems when **stringifying** Dates, Maps, Sets, and other complex data types. You could take a look in the API here: [json-storage-formatter](https://www.npmjs.com/package/json-storage-formatter).
 
-// this component is subscribed to the store, so it will be notified when the state changes
-const Component = () => {
-  const [user] = useUser();
-  const [count, actions] = useCount();
+Let's see how to create a global state using our new builder:
 
-  return (
-    <>
-      <label>{count}</label>
-    </>
-  );
-};
+```ts
+const useTodos = createGlobalState(new Map<string, number>(), {
+  config: {
+    asyncStorageKey: 'todos',
+  },
+});
 ```
 
-### So let's analyze what happened
+That's correct! If you add an **asyncStorageKey** to the state configuration, the state will be synchronized with the **asyncStorage**
 
-To restrict the state manipulations with the custom actions, we just need to add a third parameter to the store.
+Let's see how to use this async storage hook into our components:
 
 ```ts
-const countStore = new GlobalStore(0, null, {
-  log: (action: string) => () => console.log(action),
+const [todos, setTodos, metadata] = useTodos();
 
-  // every action is a function that returns a function that receives the store tools
-  increase() {
-    return ({ setState, getState }: StoreTools<number>): number => {
-      setState((state) => state + 1);
+return (<>
+  {metadata.isAsyncStorageReady ? <TodoList todos={todos} /> : <Text>Loading...</Text>}
+<>);
+```
 
-      // actions are able to communicate between them
-      this.log('increase');
+The **metadata** is not reactive information and can only be modified from inside the global state lifecycle methods.
 
-      return getState();
-    };
-  },
-} as const);
+# Life cycle methods
+
+There are some lifecycle methods available for use with global hooks, let's review them:
 
-// the const is necessary to avoid typescript errors
+```ts
+/**
+* @description callback function called when the store is initialized
+* @returns {void} result - void
+* */
+onInit?: ({
+  /**
+   * Set the metadata
+   * @param {TMetadata} setter - The metadata or a function that will receive the metadata and return the new metadata
+   * */
+  setMetadata: MetadataSetter<TMetadata>;
+
+  /**
+   * Set the state
+   * @param {TState} setter - The state or a function that will receive the state and return the new state
+   * @param {{ forceUpdate?: boolean }} options - Options
+   * */
+  setState: StateSetter<TState>;
+
+  /**
+   * Get the state
+   * @returns {TState} result - The state
+   * */
+  getState: () => TState;
+
+  /**
+   * Get the metadata
+   * @returns {TMetadata} result - The metadata
+   * */
+  getMetadata: () => TMetadata;
+
+  /**
+   * Actions of the hook if configuration was provided
+   */
+  actions: TActions;
+}: StateConfigCallbackParam<TState, TMetadata, TActions>) => void;
+
+/**
+* @description - callback function called every time the state is changed
+*/
+onStateChanged?: (parameters: StateChangesParam<TState, TMetadata, TActions>) => void;
+
+/**
+* callback function called every time a component is subscribed to the store
+*/
+onSubscribed?: (parameters: StateConfigCallbackParam<TState, TMetadata, TActions>) => void;
+
+/**
+* callback function called every time the state is about to change and it allows you to prevent the state change
+*/
+computePreventStateChange?: (parameters: StateChangesParam<TState, TMetadata, TActions>) => boolean;
 ```
 
-All the library is strongly typed, we use generics to return the correct data type in each action.
+You can pass this callbacks between on the second parameter of the builders like **createGlobalState**
 
 ```ts
-const [, actions] = countStore.getHookDecoupled();
+const useData = createGlobalState(
+  { value: 1 },
+  {
+    metadata: {
+      someExtraInformation: 'someExtraInformation',
+    },
+    // onSubscribed: (StateConfigCallbackParam) => {},
+    // onInit // etc
+    computePreventStateChange: ({ state, previousState }) => {
+      const prevent = isEqual(state, previousState);
 
-// for example the type of actions.increase will be: () => number
-// just in case, even the parameters of the actions are gonna be exposed through TS
+      return prevent;
+    },
+  }
+);
 ```
 
-## getHookDecoupled
+Finally, if you have a very specific necessity but still want to use the global hooks, you can extend the **GlobalStoreAbstract** class. This will give you even more control over the state and the lifecycle of the global state.
 
-### **getHookDecoupled** returns a tuple with the state and the actions,
+Let's see an example again with the **asyncStorage** custom global hook but with the abstract class.
 
-This is so useful when you want to use the actions without having to be subscribed to changes of the state.
-There is also a third element in the tuple which is a function for getting the metadata of the store
+```ts
+export class GlobalStore<
+  TState,
+  TMetadata extends {
+    asyncStorageKey?: string;
+    isAsyncStorageReady?: boolean;
+  } | null = null,
+  TStateSetter extends
+    | ActionCollectionConfig<TState, TMetadata>
+    | StateSetter<TState> = StateSetter<TState>
+> extends GlobalStoreAbstract<TState, TMetadata, TStateSetter> {
+  constructor(
+    state: TState,
+    config: GlobalStoreConfig<TState, TMetadata, TStateSetter> = {},
+    actionsConfig: TStateSetter | null = null
+  ) {
+    super(state, config, actionsConfig);
+
+    this.initialize();
+  }
+
+  protected onInitialize = async ({
+    setState,
+    setMetadata,
+    getMetadata,
+    getState,
+  }: StateConfigCallbackParam<TState, TMetadata, TStateSetter>) => {
+    setMetadata({
+      ...(metadata ?? {}),
+      isAsyncStorageReady: null,
+    });
+
+    const metadata = getMetadata();
+    const asyncStorageKey = metadata?.asyncStorageKey;
+
+    if (!asyncStorageKey) return;
+
+    const storedItem = (await asyncStorage.getItem(asyncStorageKey)) as string;
+    setMetadata({
+      ...metadata,
+      isAsyncStorageReady: true,
+    });
+
+    if (storedItem === null) {
+      const state = getState();
+
+      // force the re-render of the subscribed components even if the state is the same
+      return setState(state, { forceUpdate: true });
+    }
+
+    const items = formatFromStore<TState>(storedItem, {
+      jsonParse: true,
+    });
+
+    setState(items, { forceUpdate: true });
+  };
+
+  protected onChange = ({
+    getMetadata,
+    getState,
+  }: StateChangesParam<TState, TMetadata, NonNullable<TStateSetter>>) => {
+    const asyncStorageKey = getMetadata()?.asyncStorageKey;
+
+    if (!asyncStorageKey) return;
 
-### the metadata of the store is not reactive information which could be shared through the store
+    const state = getState();
 
-## Adding metadata to the store
+    const formattedObject = formatToStore(state, {
+      stringify: true,
+    });
 
-```tsx
-const [, , getMetadata] = new GlobalStore(0, {
+    asyncStorage.setItem(asyncStorageKey, formattedObject);
+  };
+}
+```
+
+Then, from an instance of the global store, you will be able to access the hooks.
+
+```ts
+const storage = new GlobalStore(0, {
   metadata: {
-    isStoredSyncronized: false,
+    asyncStorageKey: 'counter',
+    isAsyncStorageReady: false,
   },
-}).getHookDecoupled();
+});
 
-console.log(getMetadata().isStoredSyncronized); // false
+const [getState, _, getMetadata] = storage.getHookDecoupled();
+const useState = storage.getHook();
 ```
 
-The setMetadata is part of the store tools, so it can be used in the actions, but againg the metadata is not reactive!! so it will not trigger a re-render on the subscribers
-
-...
-
-...
+### **Note**: The GlobalStore class is still available in the package in case you were already extending from it.
 
 # That's it for now!! hope you enjoy coding!!