Athena

A Vuex-like state management system for React, providing a simple and flexible way to manage global state, actions, mutations, and getters. This package allows you to define modular state management in React using a structure similar to Vuex, which makes it easy to scale and maintain complex React applications.

Features

• Modular state management: Easily define modules for different parts of your application.
• Actions: Perform async operations and commit mutations to update state.
• Mutations: Directly modify the state in a predictable and organized way.
• Getters: Extract computed values based on the state.
• Commit function: Allows actions to modify the state via mutations.

Installation

You can install athena via npm or yarn:

1npm install @opensource-dev/athena
2# or
3yarn add @opensource-dev/athena

Package Contents

This package provides the following components:

• createGlobalStore: A function to create a global store that includes multiple modules.
• useModule: A custom hook to access state, mutations, actions, and getters from the store.
• Module Structure: A pattern to define your state modules with states, mutations, actions, and getters.

Getting Started

Here’s a guide on how to integrate athena into your React or React Native application.

Step 1: Define Your Modules

Each module will have a structure containing states, mutations, actions, and getters.

1import { Module } from '@opensource-dev/athena';
2
3const authModule: Module = () => ({
4  name: 'auth',
5
6  states: { 
7    username: null,
8    loggedIn: false 
9  },
10
11  mutations: {
12    SET_USERNAME(state, { payload }) {
13      state.username = payload
14    },
15
16    SET_LOGGED_IN(state, { payload }) {
17      state.loggedIn = payload
18    }
19  },
20
21  actions: {
22    async login({ commit }, params) {
23      try {
24        const response = await apiLogin(params)
25        commit('SET_USERNAME', { payload: response.username })
26        commit('SET_LOGGED_IN', { payload: true })
27        return response
28      } catch (error) {
29        return { error: { message: error.message } }
30      }
31    },
32
33    async logout({ commit }) {
34      commit('SET_USERNAME', { payload: null })
35      commit('SET_LOGGED_IN', { payload: false })
36    }
37  },
38
39  getters: {
40    isLoggedIn(state) {
41      return state.loggedIn
42    }
43  }
44})

• name: The name of the module (e.g., auth, cart).
• states: The initial state of the module.
• mutations: The mutations to modify the state.
• actions: The asynchronous actions that dispatch mutations.
• getters: The computed values based on the state.

Step 2: Create a Global Store

Once you have your modules, you can combine them into a global store using createGlobalStore. You can then wrap your app in the Provider component that this function returns.

1import { createGlobalStore } from '@opensource-dev/athena'
2import authModule from './modules/authModule'
3import cartModule from './modules/cartModule'  // Example of another module
4
5const { Provider } = createGlobalStore([authModule, cartModule])
6
7const App = () => {
8  return (
9    <Provider>
10      <YourAppComponents />
11    </Provider>
12  )
13}

• Provider: The context provider that makes the global store available to your React components.

Step 3: Using the Store in Your Components

Once the global store is set up, you can access state, mutations, actions, and getters using the useModule hook.

1import { useModule } from '@opensource-dev/athena'
2
3const LoginComponent = () => {
4  const { states, actions } = useModule()
5  
6  const auth = {
7    ...states('auth', ['username', 'loggedIn']),
8    ...actions('auth', ['login', 'logout'])
9  }
10
11  const handleLogin = async (username: string, password: string) => {
12    const response = await auth.login({ username, password })
13    if (response.error) {
14      console.error(response.error.message);
15    }
16  }
17
18  return (
19    <div>
20      {auth.loggedIn ? (
21        <p>Welcome, {auth.username}!</p>
22      ) : (
23        <button onClick={() => handleLogin('user', 'password')}>Login</button>
24      )}
25    </div>
26  )
27}

In the component:

• states('moduleName', ['stateName1', 'stateName2']): Access the state values from the specified module.
• actions('moduleName', ['actionName1', 'actionName2']): Access the actions from the specified module.
• mutations('moduleName', ['mutationName1', 'mutationName2']): Access the mutations from the specified module.
• getters('moduleName', ['getterName1', 'getterName2']): Access the getters from the specified module.

Step 4: Commiting Mutations

Actions will use the commit function to update the state through mutations. This is done automatically within the actions and does not require explicit interaction by the user.

Example of how mutations work within actions:

1actions: {
2  async login({ commit }, { username, password }) {
3    try {
4      const response = await apiLogin({ username, password })
5      commit('SET_USERNAME', { payload: response.username })
6      commit('SET_LOGGED_IN', { payload: true })
7      return response
8    } catch (error) {
9      return { error: { message: error.message } }
10    }
11  }
12}

Example of a Complete App.tsx with Multiple Modules:

1import React from 'react'
2import { useModule } from '@opensource-dev/athena'
3
4const App = () => {
5  const { states, actions } = useModule()
6
7  const auth = {
8    ...states('auth', ['username', 'loggedIn']),
9    ...actions('auth', ['login', 'logout'])
10  }
11
12  const handleLogin = async () => {
13    await auth.login({ username: 'test', password: 'password' });
14  };
15
16  return (
17    <div>
18      {auth.loggedIn ? (
19        <p>Welcome, {auth.username}!</p>
20      ) : (
21        <button onClick={handleLogin}>Login</button>
22      )}
23    </div>
24  );
25};
26
27export default App

---

API

createGlobalStore(modules: Module[])

• Description: Creates a global store by combining multiple modules.
• Parameters:
  • modules: An array of module functions that define the state, actions, mutations, and getters for the store.
• Returns: An object containing the Provider component to wrap your app.

useModule()

• Description: A custom hook to access the global store.
• Returns: An object with states, actions, mutations, and getters.
  • states(moduleName, stateNames): Get the specified states from the module.
  • actions(moduleName, actionNames): Get the specified actions from the module.
  • mutations(moduleName, mutationNames): Get the specified mutations from the module.
  • getters(moduleName, getterNames): Get the specified getters from the module.

---

License

This project is licensed under the MIT License