GX - Global State Management for React Applications

React and React Native Library for managing global state.

This library aims to provide you an easy and fast way to set up and manage the global state of your react application.

Documentation

You can read the entire documentation and see how to use this library perfectly.

But, If you want to start directly with the library continue reading this small documentation here.

Installation

You can use npm or yarn to install this library into your react application.

Using npm

npm install @dilane3/gx

Using yarn

yarn add @dilane3/gx

Prerequisites

Since version `1.4.0` of `gx`, you can use it with `strict mode` enabled.

But, if you are using a version below 1.4.0, you have to disable strict mode in your react application.

Disabling strict mode on React

Before

import React, { StrictMode } from "react";

function App() {
  return (
    <StrictMode>
      {
        // Your application here
      }
    </StrictMode>
  );
}

export default App;

After

import React, { Fragment } from "react";

function App() {
  return (
    <Fragment>
      {
        // Your application here
      }
    </Fragment>
  );
}

export default App;

Disabling strict mode on Next.js

Open the next.config.js file and add the following code.

module.exports = {
  reactStrictMode: false,
};

Definition of concepts

GX comes with some new concepts like signal, action, and store.

1. Signal

Signal represent a specific state that your application has to manage. For example, for managing users and products inside your ecommerce application you will have to create two separate signals called usersSignal and productsSignal.

For handle it, there is a special createSignal function for this case.

2. Action

Actions represent functions that act to the state and make it changing over the time.

You have to specify these actions when you create yours signals.

Since version `1.4.0` of `gx`, you can use `async` actions.

You can read more about it on the documentation

3. Store

Store is a collection of signals. We know that in an application, we can manage many state separately, so gx gives you the possibility to centralize all your state into a special place. The state becomes easier to manage like that.

For handle it, there is a special createStore function for this case, which takes an array of signals.

Usage

First step: Setting up the code structure.

For structuring your code very well you have to follow these steps.

Create a directory called gx or whatever you want inside the src directory
Inside the gx directory, create two others one called signals and store.
Inside the signals directory you will create files that will contains your state declaration with actions that act to this state. (ie: counter.js)
Inside the store directory, just create an index.js file. We will see how to fill it.

Here is the result.

Second step: Creating your signals.

Inside the signals directory, create a file called counter.js for example.

import { createSignal } from "@dilane3/gx";

const counterSignal = createSignal({
  name: "counter",
  state: 0,
  actions: {
    increment: (state, payload) => {
      return state + payload;
    },

    decrement: (state, payload) => {
      return state - payload;
    },
  },
});

export default counterSignal;

If you want to use async actions, you can learn more about it on the documentation

Third step: Creating your store.

Inside the store directory, create an index.js file.

import { createStore } from "@dilane3/gx";
import counterSignal from "../signals/counter";

export default createStore([counterSignal]);

Fourth step: Using your store.

Inside your App.js file, import your store and wrap your application with the GXProvider component.

import React from "react";
import store from "./gx/store";
import GXProvider from "@dilane3/gx";

function App() {
  return (
    <GXProvider store={store}>
      {
        // Your application here
      }
    </GXProvider>
  );
}

export default App;

Fifth step: Using your signals.

Create a component called Counter inside the Counter.js file. Then import two hooks from gx called useSignal and useActions like follow.

import React from "react";
import { useSignal, useActions } from "@dilane3/gx";

function Counter() {
  // State
  const counter = useSignal("counter");

  // Actions
  const { increment, decrement } = useActions("counter");

  return (
    <div>
      <h1>Counter App</h1>

      <p>Count: {counter}</p>

      <button onClick={() => increment(1)}>Increment</button>
      <button onClick={() => decrement(1)}>Decrement</button>
    </div>
  );
}

export default Counter;

Note that the useSignal hook takes the name of the signal as a parameter and return the state contained inside that signal.

The useAction hook takes the name of the signal too and returns an object that contains all the actions of this signal.

Actually, if you click on the increment button, the counter will increase by one and if you click on the decrement button, the counter will decrease by one.

Sixth step: Adding operations to your signals.

This feature comes with the version 1.3.0 of gx. It allows you to add operations to your signals. Operations are functions that use your current state and apply some filters on it. They return the result of the operation without changing the state.

For example, if you want to know if the counter is even or odd, you can create an operation called isEven like follow.

import { createSignal } from "@dilane3/gx";

const counterSignal = createSignal({
  name: "counter",
  state: 0,
  actions: {
    increment: (state, payload) => {
      return state + payload;
    },

    decrement: (state, payload) => {
      return state - payload;
    },
  },

  // Operations section
  operations: {
    isEven: (state) => {
      return state % 2 === 0;
    },
  },
});

export default counterSignal;

Then, you can use it inside your component like follow.

import React from "react";
import { useSignal, useActions, useOperations } from "@dilane3/gx";

function Counter() {
  // State
  const counter = useSignal("counter");

  // Actions
  const { increment, decrement } = useActions("counter");

  // Operations
  const { isEven } = useOperations("counter");

  return (
    <div>
      <h1>Counter App</h1>

      <p>Count: {counter}</p>

      <p>is even: {isEven() ? "yes" : "no"}</p>

      <button onClick={() => increment(1)}>Increment</button>
      <button onClick={() => decrement(1)}>Decrement</button>
    </div>
  );
}

export default Counter;

API

`createSignal`

This function takes an object as a parameter and returns a signal.

The object must contain the following properties:

Properties	Type	Description
`name`	`string`	The name of the signal. It must be unique.
`state`	`any`	The initial state of the signal.
`actions`	`object`	An object that contains all the actions of the signal.

Structure of the actions object:

{
  actionName: (state, payload) => {
    // Do something with the state and the payload
    return state;
  };
}

All actions must return the new state of the signal.

`createStore`

This function takes an array of signals as a parameter and returns a store.

const store = createStore([signal1, signal2, signal3]);

`GXProvider`

This component takes a store as a parameter and wraps your application with it.

const App = () => (
  <GXProvider store={store}>
    {
      // Your application here
    }
  </GXProvider>
);

`useSignal`

This hook takes the name of the signal as a parameter and returns the state contained inside that signal.

const counter = useSignal("counter");

`useActions`

This hook takes the name of the signal as a the first parameter and returns an object that contains all the actions of this signal.

const { increment, decrement } = useActions("counter");

`useAction`

This hook takes the name of the signal as the first parameter and the name of the action as the second one and then return that action.

const increment = useAction("counter", "increment");

See more on the documentation

TypeScript Support

GX support TypeScript, so that you can use it directly into your application.

See how to integrate it on the documentation website

License

MIT

Author

Github: @dilane3
Twitter: @dilanekombou
LinkedIn: @dilanekombou
website: dilane3.com

Contributing

Contributions, issues and feature requests are welcome! See the Contributing Guide.

react-gx/gx