react-native-global-state-hooks 7.0.2 → 8.0.0

package/README.md

@@ -23,7 +23,7 @@ The best part? [react-hooks-global-states](https://www.npmjs.com/package/react-h
 We are gonna create a global state hook **useCount** with one line of code.
 
 ```ts
-import { createGlobalState } from "react-native-global-state-hooks";
+import { createGlobalState } from "react-native-global-state-hooks/createGlobalState";
 
 export const useCount = createGlobalState(0);
 ```
@@ -68,76 +68,154 @@ The metadata and components will be updated and re-rendered even if there's no d
 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**
 
 ```ts
-import { createGlobalState } from "react-native-global-state-hooks";
+import { createGlobalState } from 'react-hooks-global-states';
 
 export const useContacts = createGlobalState({
   isLoading: true,
-  filter: "",
-  items: [] as Contact[],
+  entities: Contact[],
+  selected: Set<number>,
 });
 ```
 
-Now, let's say we want to have a filter bar for the contacts that will only have access to the filter.
-
-**FilterBar.tsx**
+Now, let's say we have a situation where we want to access only the list of contacts. We don't care about the rest of the state.
 
 ```tsx
-const [contacts] = useContacts((state) =>
-  state.contacts.filter((contact) => contact.status === "active")
-);
+// That's it. With that simple selector, we now get the list of contacts,
+// and the component will only re-render if the property **entities** changes on the global state
+const [contacts] = useContacts((state) => state.entities]);
 
 return (
-  <View>
+  <ul>
     {contacts.map((contact) => (
-      <Text key={contact.id}>{contact.name}</Text>
+      <li key={contact.id}>{contact.name}</li>
     ))}
-  </View>
+  </ul>
 );
 ```
 
-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.
+What about special cases, like when you have a map instead of an array and want to extract a list of contacts? It's common to use selectors that return a new array, but this can cause React to re-render because the new array has a different reference than the previous one.
+
+```tsx
+export const useContacts = createGlobalState({
+  isLoading: true,
+  entities: Map<number, Contact>,
+  selected: Set<number>,
+});
+
+// The selector is simply a standard selector used to extract the values from the map.
+
+const [contacts] = useContacts((state) => [...state.entities.values()], {
+  // The isEqualRoots function allows you to create your own validation logic for determining when to recompute the selector.
+  isEqualRoot: (a, b) => a.entities === b.entities,
+});
+```
+
+Okay, everything works when the changes come from the state, but what happens if I want to recompute the selector based on the internal state of the component?
 
-If you want to have more control over when the hook should recompute the selector result, there are a couple of options:
+**component.ts**
 
 ```tsx
 const [filter, setFilter] = useState("");
 
 const [contacts] = useContacts(
-  (state) => state.contacts.filter((contact) => contact.name.includes(filter)),
+  (state) => [...state.entities.values()].filter((item) => item.name.includes(filter)),
   {
+    isEqualRoot: (a, b) => a.entities === b.entities,
     /**
-     * You can use the `isEqualRoot` to validate if the values before the selector are equal.
-     * This validation will run before `isEqual` and if the result is true the selector will not be recomputed.
-     * If the result is true the re-render of the component will be prevented.
-     */
-    isEqualRoot: (r1, r2) => r1.filter === r2.filter,
-
-    /**
-     * You can use the `isEqual` to validate if the values after the selector are equal.
-     * This validation will run after the selector computed a new value...
-     * and if the result is true it will prevent the re-render of the component.
-     */
-    isEqual: (filter1, filter2) => filter1 === filter2,
-
-    /**
-     * You can use the `dependencies` array as with regular hooks to to force the recomputation of the selector.
-     * Is important ot mention that changes in the dependencies will not trigger a re-render of the component...
-     * Instead the recomputation of the selector will returned immediately.
-     */
+     * Easy to understand, right? With the dependencies prop, you can,
+     * just like with any other hook, provide a collection of values that will be compared during each render cycle
+     * to determine if the selector should be recomputed.*/
     dependencies: [filter],
   }
 );
+```
+
+And finally, what if you need to reuse this selector throughout your application and don't want to duplicate code?
+
+```tsx
+export const useContacts = createGlobalState({
+  isLoading: true,
+  entities: Map<number, Contact>,
+  selected: Set<number>,
+});
+
+const useContactsArray = useContacts.createSelectorHook((state) => [...state.entities.values()], {
+  isEqualRoot: (a, b) => a.entities === b.entities,
+});
+```
+
+Now inside your component just call the new hook
+
+**component.ts**
+
+```tsx
+const [filter, setFilter] = useState("");
+
+const [contacts] = useContactsArray((entities) => entities.name.includes(filter), {
+  dependencies: [filter],
+});
+```
+
+Or you can create another selectorHook from your **useContactsArray**
+
+```ts
+const useContactsArray = useContacts.createSelectorHook((state) => [...state.entities.values()], {
+  isEqualRoot: (a, b) => a.entities === b.entities,
+});
+
+const useContactsLength = useContactsArray.createSelectorHook((entities) => entities.length);
+```
+
+Or you can create a custom hook
+
+```tsx
+const useFilteredContacts = (filter: string) => {
+  const [contacts] = useContactsArray((entities) => entities.name.includes(filter), {
+    dependencies: [filter],
+  });
+
+  return contacts;
+};
+```
+
+To summarize
+
+```tsx
+const [filter, setFilter] = useState("");
+
+const [contacts] = useContacts((state) => state.contacts.filter((contact) => contact.name.includes(filter)), {
+  /**
+   * You can use the `isEqualRoot` to validate if the values before the selector are equal.
+   * This validation will run before `isEqual` and if the result is true the selector will not be recomputed.
+   * If the result is true the re-render of the component will be prevented.
+   */
+  isEqualRoot: (r1, r2) => r1.filter === r2.filter,
+
+  /**
+   * You can use the `isEqual` to validate if the values after the selector are equal.
+   * This validation will run after the selector computed a new value...
+   * and if the result is true it will prevent the re-render of the component.
+   */
+  isEqual: (filter1, filter2) => filter1 === filter2,
+
+  /**
+   * You can use the `dependencies` array as with regular hooks to to force the recomputation of the selector.
+   * Is important ot mention that changes in the dependencies will not trigger a re-render of the component...
+   * Instead the recomputation of the selector will returned immediately.
+   */
+  dependencies: [filter],
+});
 
 return (
-  <View>
+  <ul>
     {contacts.map((contact) => (
-      <Text key={contact.id}>{contact.name}</Text>
+      <li key={contact.id}>{contact.name}</li>
     ))}
-  </View>
+  </ul>
 );
 ```
 
-If you want to perform a shallow comparison between the previous and new values, you can use the **shallowCompare** function from the library.
+Btw, If you want to perform a shallow comparison between the previous and new values, you can use the **shallowCompare** function from the library.
 
 ```TSX
 ({
@@ -148,29 +226,23 @@ If you want to perform a shallow comparison between the previous and new values,
 })
 ```
 
-## What if you want to reuse the selector?
-
-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?
+Just remember, you can select or derive different values from the global state endlessly, but the state mutator will remain the same throughout the hooks.
 
-No problem, you can create a reusable **derivative-state** and use it across your components. Let's create one for our filter.
+More examples:
 
 ```ts
-const useFilter = createDerivate(useContacts, ({ filter }) => ({ filter }));
-```
+const useFilter = useContacts.createSelectorHook(({ filter }) => filter);
 
-Well, that's it! Now you can simply call **useFilter** inside your component, and everything will continue to work the same.
+const useContactsArray = useContacts.createSelectorHook(({ items }) => items);
 
-**FilterBar.tsx**
-
-```ts
-const [{ filter }, setState] = useFilter();
+const useContactsLength = useContactsArray.createSelectorHook((items) => items.length);
 
-return (
-  <TextInput onChangeText={() => setState((state) => ({ ...state, filter }))} />
-);
+const useIsContactsEmpty = useContactsLength.createSelectorHook((length) => !length);
 ```
 
-Notice that the **state** changes, but the **stateMutator** 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.
+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.
+
+Each selector hook is reactive only to the fragment/derived of the state returned by the selector. And again you can optimize it by using the **isEqualRoot** and **isEqual** functions, which help avoid recomputing the selector if the root state or the fragment hasn't changed.
 
 # State actions
 
@@ -181,30 +253,29 @@ By defining a custom API for the **useContacts**, we can encapsulate and expose
 ```ts
 import { createGlobalState } from "react-native-global-state-hooks";
 
-const initialState = {
-  isLoading: true,
-  filter: "",
-  items: [] as Contact[],
-};
-
-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
+export const useContacts = createGlobalState(
+  {
+    isLoading: true,
+    filter: "",
+    items: [] as Contact[],
   },
-});
+  {
+    // this are the actions available for this state
+    actions: {
+      setFilter(filter: string) {
+        return ({ setState }) => {
+          setState((state) => ({
+            ...state,
+            filter,
+          }));
+        };
+      },
+    } as const,
+    onInit: ({ setState }) => {
+      // fetch contacts
+    },
+  }
+);
 ```
 
 That's it! In this updated version, the **useContacts** hook will no longer return [**state**, **stateMutator**] 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.
@@ -237,33 +308,22 @@ It can't get any simpler, right? Everything is connected, everything is reactive
 
 # State Controls
 
-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.
+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:
 
-Using the state controls 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:
+```tsx
+useContacts.stateControls: () => [stateRetriever: StateGetter<State>, stateMutator: Setter<State>|ActionCollectionResult<State>, metadataRetriever: Metadata];
 
-```ts
-import { createGlobalState } from "react-native-global-state-hooks";
+// example:
+const [getContacts, setContacts] = useContacts.stateControls();
 
-export const useContacts = createGlobalState({
-  isLoading: true,
-  filter: "",
-  items: [] as Contact[],
-});
-
-export const [contactsRetriever, contactsRetriever] =
-  useContacts.stateControls();
+console.log(getContacts()); // prints the list of contacts
 ```
 
-That's great! With the addition of the **contactsRetriever** and **contactsRetriever** methods, you now have the ability to access and modify the state without the need for subscription to the hook.
-
-While **useContacts** will allow your components to subscribe to the custom hook, using the **contactsRetriever** 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:
+**stateMutator** 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.
 
-```ts
-// To synchronously get the value of the state
-const value = contactsRetriever();
+Using the **stateRetriever** and the **stateMutator** 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.
 
-// the type of value will be { isLoading: boolean; filter: string; items: Contact[] }
-```
+So, While **useContacts** will allow your components to subscribe to the custom hook, using the **contactsRetriever** 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 and with the **contactsMutator** you now have the ability to modify the state without the need for subscription to the hook.
 
 Additionally, to subscribe to state changes, you can pass a callback function as a parameter to the **stateRetriever**. 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 **stateRetriever**, 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.
 
@@ -288,19 +348,162 @@ const removeSubscriptionGroup = contactsRetriever<Subscribe>((subscribe) => {
 
 That's great, isn't it? everything stays synchronized with the original state!!
 
-# Emitters
+## stateMutator
 
-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:
+Let's add more actions to the state and explore how to use one action from inside another.
+
+Here's an example of adding multiple actions to the state and utilizing one action within another:
 
 ```ts
-const subscribeToFilter = createDerivateEmitter(
-  contactsRetriever,
-  ({ filter }) => ({
-    filter,
-  })
+import { createGlobalState } from "react-hooks-global-states";
+
+export const useCount = createGlobalState(0, {
+  actions: {
+    log: (currentValue: string) => {
+      return ({ getState }: StoreTools<number>): void => {
+        console.log(`Current Value: ${getState()}`);
+      };
+    },
+
+    increase(value: number = 1) {
+      return ({ getState, setState, actions }: StoreTools<number>) => {
+        setState((count) => count + value);
+
+        actions.log(message);
+      };
+    },
+
+    decrease(value: number = 1) {
+      return ({ getState, setState, actions }: StoreTools<number>) => {
+        setState((count) => count - value);
+
+        actions.log(message);
+      };
+    },
+  } as const,
+});
+```
+
+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.
+
+# Stateful Context with Actions
+
+**The ultimate blend of flexibility and control in React state management!** You can now create an isolated global state within a React context, giving each consumer of the context provider a unique state instance. But that’s not all...
+
+**Stateful Context with Actions** extends the powerful features of global hooks into the realm of React Context. By integrating global hooks within a context, you bring all the benefits of global state management—such as modularity, selectors, derived states, and actions—into a context-specific environment. This means each consumer of the context not only gets a unique state instance but also inherits all the advanced capabilities of global hooks.
+
+## Creating a Stateful Context
+
+Forget about the boilerplate of creating a context... with **createStatefulContext** it's straightforward and powerful. You can create a context and provider with one line of code.
+
+```tsx
+export const [useCounterContext, CounterProvider] = createStatefulContext(2);
+```
+
+Then just wrap the components you need with the provider:
+
+```tsx
+<CounterProvider>
+  <MyComponent />
+</CounterProvider>
+```
+
+And finally, access the context value with the generated custom hook:
+
+```tsx
+const MyComponent = () => {
+  const [useCounter] = useCounterContext();
+
+  // If the component needs to react to state changes, simply use the hook
+  const [count, setCount] = useCounter();
+
+  return <>{count}</>;
+};
+```
+
+What’s the advantage of this, you might ask? Well, now you have all the capabilities of the global hooks within the isolated scope of the context. For example, you can choose whether or not to listen to changes in the state:
+
+```tsx
+const MyComponent = () => {
+  const [, , setCount] = useCounterContext();
+
+  // This component can access only the stateMutator of the state,
+  // and won't re-render if the counter changes
+  return <button onClick={() => setCount((count) => count + 1)}>Increase</button>;
+};
+```
+
+Now you have selectors—if the state changes, the component will only re-render if the selected portion of the state changes.
+
+```tsx
+const MyComponent = () => {
+  const [useCounter] = useCounterContext();
+
+  // Notice that we can select and derive values from the state
+  const [isEven, setCount] = useCounter((count) => count % 2 === 0);
+
+  useEffect(() => {
+    // Since the counter initially was 2 and now is 4, it’s still an even number.
+    // Because of this, the component will not re-render.
+    setCount(4);
+  }, []);
+
+  return <>{isEven ? "is even" : "is odd"}</>;
+};
+```
+
+**createStatefulContext** also allows you to add custom actions to control the manipulation of the state.
+
+```tsx
+import { createStatefulContext, StoreTools } from "react-global-state-hooks";
+
+export const [useCounterContext, CounterProvider] = createStatefulContext(
+  {
+    count: 0,
+  },
+  {
+    actions: {
+      increase: (value: number = 1) => {
+        return ({ setState }) => {
+          setState((state) => ({
+            ...state,
+            count: state.count + value,
+          }));
+        };
+      },
+      decrease: (value: number = 1) => {
+        return ({ setState }) => {
+          setState((state) => ({
+            ...state,
+            count: state.count - value,
+          }));
+        };
+      },
+    } as const,
+  }
 );
 ```
 
+And just like with regular global hooks, now instead of a setState function, the hook will return the collection of actions:
+
+```tsx
+const MyComponent = () => {
+  const [, , actions] = useCounterContext();
+
+  return <button onClick={() => actions.increase(1)}>Increase</button>;
+};
+```
+
+# Emitters
+
+So, we have seen that we can subscribe a callback to state changes, create **selector hooks** from our global states. Guess what? We can also create derived **emitters** and subscribe callbacks to specific portions of the state. Let's review it:
+
+```ts
+const subscribeToFilter = createDerivateEmitter(contactsRetriever, ({ filter }) => ({
+  filter,
+}));
+```
+
 Cool, it's basically the same, but instead of using the **hook** as a parameter, we just have to use the **stateRetriever** as a parameter, and that will make the magic.
 
 Now we are able to add a callback that will be executed every time the state of the **filter** changes.
@@ -324,7 +527,7 @@ const removeFilterSubscription = subscribeToFilter<Subscribe>(
 );
 ```
 
-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
+Also, of course, if you have an exceptional case where you want to derived/selected 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>(
@@ -350,26 +553,20 @@ const removeFilterSubscription = subscribeToFilter<Subscribe>(
 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(
-  contactsRetriever,
-  ({ items }) => items
-);
+const subscribeToItems = createDerivateEmitter(contactsRetriever, ({ items }) => items);
 
-const subscribeToItemsLength = createDerivateEmitter(
-  subscribeToItems,
-  (items) => items.length
-);
+const subscribeToItemsLength = createDerivateEmitter(subscribeToItems, (items) => items.length);
 ```
 
-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!
+The examples may seem a little silly, but they allow you to see the incredible things you can accomplish with these **derived states** and **emitters**. They open up a world of possibilities!
 
-# Combining stateRetrievers
+# Combining stateRetriever
 
-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 **stateRetrievers**.
+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 **stateRetriever**.
 
 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:
 
-Fist we are gonna create a couple of **global states**:
+First we are gonna create a couple of **global states**, and extract the **stateRetriever**.
 
 ```ts
 const useHook1 = createGlobalState({
@@ -384,13 +581,13 @@ const useHook2 = createGlobalState({
   propD: 4,
 });
 
-const [stateRetriever2] = useHook2.stateControls();
+const [, stateRetriever2] = useHook2.stateControls();
 ```
 
 Okay, cool, the first state as **propA, propB** while the second one has **propC, propD**, let's combine them:
 
 ```ts
-const [useCombinedHook, stateRetriever, dispose] = combineAsyncGetters(
+const [useCombinedHook, combinedStateRetriever] = combineAsyncGetters(
   {
     selector: ([state1, state2]) => ({
       ...state1,
@@ -402,7 +599,7 @@ const [useCombinedHook, stateRetriever, dispose] = combineAsyncGetters(
 );
 ```
 
-Well, that's it! Now you have access to a **stateRetriever** that will return the combined value of the two states. From this new **stateRetriever**, you can retrieve the value or subscribe to its changes. Let'see:
+Well, that's it! Now you have access to a **combinedStateRetriever** that will return the combined value of the two states. From this new **combinedStateRetriever**, you can retrieve the value or subscribe to its changes. Let'see:
 
 ```ts
 const value = stateRetriever(); // { propA, propB, propC, propD }
@@ -417,8 +614,8 @@ const unsubscribeGroup = stateRetriever<Subscribe>((subscribe) => {
   // the callback will only trigger if the result of the selector changes.
   subscribe(
     ({ propA, propD }) => ({ propA, propD }),
-    (derivate) => {
-      console.log(derivate); // { propA, propD }
+    (derived) => {
+      console.log(derived); // { propA, propD }
     }
   );
 });
@@ -440,22 +637,21 @@ Similar to your other **global state hooks**, **combined hooks** allow you to us
 const [fragment] = useCombinedHook(({ propA, propD }) => ({ propA, propD }));
 ```
 
-Lastly, you have the flexibility to continue combining stateRetriever if desired. This means you can extend the functionality of combined hooks by adding more stateRetriever to merge additional states. By combining stateRetriever 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.
+Lastly, you have the flexibility to continue combining stateRetrievers if desired. This means you can extend the functionality of combined hooks by adding more stateRetrievers to merge additional states. By combining stateRetrievers 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 see an example:
 
 ```ts
-const [useCombinedHook, combinedStateRetriever1, dispose1] =
-  combineAsyncGetters(
-    {
-      selector: ([state1, state2]) => ({
-        ...state1,
-        ...state2,
-      }),
-    },
-    stateRetriever1,
-    stateRetriever2
-  );
+const [useCombinedHook, combinedStateRetriever1] = combineAsyncGetters(
+  {
+    selector: ([state1, state2]) => ({
+      ...state1,
+      ...state2,
+    }),
+  },
+  stateRetriever1,
+  stateRetriever2
+);
 
 const useHook3 = createGlobalState({
   propE: 1,
@@ -466,13 +662,13 @@ const [stateRetriever3, stateMutator3] = useHook3.stateControls();
 
 const useIsLoading = createGlobalState(false);
 
-const [isLoadingGetter, isLoadingSetter] = useIsLoading.stateControls();
+const [isLoadingStateRetriever, isLoadingMutator] = useIsLoading.stateControls();
 ```
 
 Once we created another peace of state, we can combine it with our other **global hooks** and **emitters**
 
 ```ts
-const [useCombinedHook2, combinedGetter2, dispose2] = combineAsyncGetters(
+const [useCombinedHook2, combinedStateRetriever2] = combineAsyncGetters(
   {
     selector: ([state1, state2, isLoading]) => ({
       ...state1,
@@ -482,7 +678,7 @@ const [useCombinedHook2, combinedGetter2, dispose2] = combineAsyncGetters(
   },
   combinedStateRetriever1,
   stateRetriever3,
-  isLoadingGetter
+  isLoadingStateRetriever
 );
 ```
 
@@ -492,190 +688,6 @@ You have the freedom to combine as many global hooks as you wish. This means you
 
 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.
 
-## Setter
-
-Similarly, the **contactsRetriever** 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**.
-
-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.
-
-Here's an example of adding multiple actions to the state and utilizing one action within another:
-
-```ts
-import { createGlobalState } from "react-native-global-state-hooks";
-
-export const useCount = createGlobalState(0, {
-  actions: {
-    log: (currentValue: string) => {
-      return ({ getState }: StoreTools<number>): void => {
-        console.log(`Current Value: ${getState()}`);
-      };
-    },
-
-    increase(value: number = 1) {
-      return ({ getState, setState, actions }: StoreTools<number>) => {
-        setState((count) => count + value);
-
-        actions.log(message);
-      };
-    },
-
-    decrease(value: number = 1) {
-      return ({ getState, setState, actions }: StoreTools<number>) => {
-        setState((count) => count - value);
-
-        actions.log(message);
-      };
-    },
-  } as const,
-});
-```
-
-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.
-
-```ts
-import { createGlobalState } from "react-native-global-state-hooks";
-
-export const useCount = createGlobalState(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,
-});
-
-export const [getCount, $actions] = useCount.stateControls();
-```
-
-In the example the hook will work the same and you'll have access to the correct typing.
-
-# Stateful Context with Actions
-
-**The ultimate blend of flexibility and control in React state management!** You can now create an isolated global state within a React context, giving each consumer of the context provider a unique state instance. But that’s not all...
-
-**Stateful Context with Actions** extends the powerful features of global hooks into the realm of React Context. By integrating global hooks within a context, you bring all the benefits of global state management—such as modularity, selectors, derived states, and actions—into a context-specific environment. This means each consumer of the context not only gets a unique state instance but also inherits all the advanced capabilities of global hooks.
-
-## Creating a Stateful Context
-
-Forget about the boilerplate of creating a context... with **createStatefulContext** it's straightforward and powerful. You can create a context and provider with one line of code.
-
-```tsx
-export const [useCounterContext, CounterProvider] = createStatefulContext(2);
-```
-
-Then just wrap the components you need with the provider:
-
-```tsx
-<CounterProvider>
-  <MyComponent />
-</CounterProvider>
-```
-
-And finally, access the context value with the generated custom hook:
-
-```tsx
-const MyComponent = () => {
-  const [useCounter] = useCounterContext();
-
-  // If the component needs to react to state changes, simply use the hook
-  const [count, setCount] = useCounter();
-
-  return <>{count}</>;
-};
-```
-
-What’s the advantage of this, you might ask? Well, now you have all the capabilities of the global hooks within the isolated scope of the context. For example, you can choose whether or not to listen to changes in the state:
-
-```tsx
-const MyComponent = () => {
-  const [, , setCount] = useCounterContext();
-
-  // This component can access only the stateMutator of the state,
-  // and won't re-render if the counter changes
-  return (
-    <button onClick={() => setCount((count) => count + 1)}>Increase</button>
-  );
-};
-```
-
-Now you have selectors—if the state changes, the component will only re-render if the selected portion of the state changes.
-
-```tsx
-const MyComponent = () => {
-  const [useCounter] = useCounterContext();
-
-  // Notice that we can select and derive values from the state
-  const [isEven, setCount] = useCounter((count) => count % 2 === 0);
-
-  useEffect(() => {
-    // Since the counter initially was 2 and now is 4, it’s still an even number.
-    // Because of this, the component will not re-render.
-    setCount(4);
-  }, []);
-
-  return <>{isEven ? "is even" : "is odd"}</>;
-};
-```
-
-**createStatefulContext** also allows you to add custom actions to control the manipulation of the state.
-
-```tsx
-import { createStatefulContext, StoreTools } from "react-global-state-hooks";
-
-type CounterState = {
-  count: number;
-};
-
-const initialState: CounterState = {
-  count: 0,
-};
-
-export const [useCounterContext, CounterProvider] = createStatefulContext(
-  initialState,
-  {
-    actions: {
-      increase: (value: number = 1) => {
-        return ({ setState }: StoreTools<CounterState>) => {
-          setState((state) => ({
-            ...state,
-            count: state.count + value,
-          }));
-        };
-      },
-      decrease: (value: number = 1) => {
-        return ({ setState }: StoreTools<CounterState>) => {
-          setState((state) => ({
-            ...state,
-            count: state.count - value,
-          }));
-        };
-      },
-    } as const,
-  }
-);
-```
-
-And just like with regular global hooks, now instead of a setState function, the hook will return the collection of actions:
-
-```tsx
-const MyComponent = () => {
-  const [, , actions] = useCounterContext();
-
-  return <button onClick={() => actions.increase(1)}>Increase</button>;
-};
-```
-
 # Extending Global Hooks
 
 ## `[IMPORTANT!]`: From version 6.0.0, you can continue creating your custom implementations or using your previous ones. However, now AsyncStorage is already integrated into the global hooks with @react-native-async-storage/async-storage. You simply need to add a key for the persistent storage, and that will do the trick.
@@ -700,7 +712,7 @@ const useCountPersisted = createGlobalState(1, {
 const [count, setCount, { isAsyncStorageReady }] = useCountPersisted();
 ```
 
-##### Now lets continue analizing how to create a custom GlobalStore!
+##### Now lets continue analyzing how to create a custom GlobalStore!
 
 Creating a global hook that connects to an asyncStorage is made incredibly easy with the **createCustomGlobalState** function.
 
@@ -842,17 +854,17 @@ onInit?: ({
 /**
 * @description - callback function called every time the state is changed
 */
-onStateChanged?: (parameters: StateChangesParam<TState, TMetadata, TActions>) => void;
+onStateChanged?: (parameters: StoreTools<any, any> & StateChanges<unknown>) => void;
 
 /**
 * callback function called every time a component is subscribed to the store
 */
-onSubscribed?: (parameters: StateConfigCallbackParam<TState, TMetadata, TActions>) => void;
+onSubscribed?: (parameters: StoreTools<any, any>) => 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;
+computePreventStateChange?: (parameters: StoreTools<any, any> & StateChanges<unknown>) => boolean;
 ```
 
 You can pass this callbacks between on the second parameter of the builders like **createGlobalState**
@@ -886,9 +898,7 @@ export class GlobalStore<
     asyncStorageKey?: string;
     isAsyncStorageReady?: boolean;
   } | null = null,
-  TStateSetter extends
-    | ActionCollectionConfig<TState, TMetadata>
-    | StateSetter<TState> = StateSetter<TState>
+  TStateSetter extends ActionCollectionConfig<TState, TMetadata> | StateSetter<TState> = StateSetter<TState>
 > extends GlobalStoreAbstract<TState, TMetadata, TStateSetter> {
   constructor(
     state: TState,
@@ -936,10 +946,7 @@ export class GlobalStore<
     setState(items, { forceUpdate: true });
   };
 
-  protected onChange = ({
-    getMetadata,
-    getState,
-  }: StateChangesParam<TState, TMetadata, NonNullable<TStateSetter>>) => {
+  protected onChange = ({ getMetadata, getState }: StoreTools<any, any> & StateChanges<unknown>) => {
     const asyncStorageKey = getMetadata()?.asyncStorageKey;
 
     if (!asyncStorageKey) return;
@@ -959,9 +966,8 @@ Then, from an instance of the global store, you will be able to access the hooks
 
 ```ts
 const storage = new GlobalStore(0, {
-  metadata: {
-    asyncStorageKey: "counter",
-    isAsyncStorageReady: false,
+  asyncStorage: {
+    key: "counter",
   },
 });