zustore (*Global State Manager*)

A lightweight, flexible global state management library for React applications, built on top of ContextApi. This library provides an intuitive API for managing global state, dispatching actions, and keeping your application state organized.

Table of Contents

• Features
• Installation
• Usage
• Available Hooks
• Global State Example
• Custom Actions
• License
• Contact

Features

• 🌀 Simple global state management with ContextApi.
• ⚡ Dynamic action dispatching.
• 💾 Temporary state support for transient updates.
• 🔄 Reset and dirty state management.
• 🚫 Add state without re-rendering: Modify or add new state slices without triggering the updated value until you render it.

Installation

Install the package via NPM or Yarn:

npm install zustore
# or
yarn add zustore

Usage

Setup

create the provider if you want to add a initial state or make a actions

if you don’t need the initial state and make a actions don’t add the StateProvider

"use client"; // don’t forget to add use clint if you are in a next.js

import { ReactNode } from "react";
import { CreateDispatchType, initial } from "zustore";

const initialState = {
  name: "Ibrahim",
  info: {
    age: 22,
  },
};

// Define the createDispatch function
const createDispatch: CreateDispatchType = (name, payload, tools) => {
  const { dispatch, addState, reset } = tools;

  // Action functions
  const setAge = () => {
    const age = payload.value;
    dispatch({ age }, "info"); // Example of using addState
  };

  const lang = () => {
    const { lang } = payload;
    addState({ lang }, "info2"); // Example of using addState
  };

  // Switch based on the function name
  switch (name) {
    case "setAge":
      return setAge();
    case "lang":
      return lang();
    default:
      console.log("No matching action for:", name);
      break;
  }
};

const StateProvider = initial(initialState, createDispatch);

const Root = ({
  children,
}: Readonly<{
  children: ReactNode;
}>) => {
  return <StateProvider>{children}</StateProvider>;
};

export default Root;

Then import the hooks and start managing your global state:

import React from "react";
import { useDispatch, useSelector } from "zustore";

const App = () => {
  const { dispatch, dispatcher, addState } = useDispatch();

  // Accessing state
  const name = useSelector("info.name", "Default Name");
  const age = useSelector("info.age", 0);

  // or can get multiple
  const [name, age] = useSelector(
    ["info.name", "info.age"],
    ["Default Name", 0]
  );

  const updateAge = () => {
    dispatcher("setAge", { value: 22 }); // Dispatch an action to update age
    addState({ job: "front end" }); // this will add a value to state and  not be render until the first dispatch
    // update state
    dispatch({ name: "Ibrahim" }, "info");
    // or
    dispatch({ name: "Ibrahim" });
  };

  return (
    <div>
      <h1>{name}</h1>
      <p>Age: {age}</p>
      <button onClick={updateAge}>Update Age</button>
    </div>
  );
};

export default App;

Available Hooks

useDispatch

Provides access to dispatch and state-management methods.

import { useDispatch } from "zustore";

const { dispatch, dispatcher, reset, dirty, addState } = useDispatch();

Methods:

• dispatch: Directly update or replace state.
• dispatcher(action, payload): Dispatch an action using the predefined createDispatch logic.
• reset(keys): Reset specific state slices to their initial values.
• dirty(keys): Remove specific keys from the state.
• addState(newState, key?): Add or update state slices dynamically.

useSelector

Access specific parts of the global state.

import { useSelector } from "zustore";

const value = useSelector("key", "defaultValue");

• key: The state key to retrieve.
• defaultValue: Fallback value if the key does not exist.

Global State Example

Customize your initial global state in global-state.ts:

export const globalState = {
  info: {
    name: "John Doe",
    age: 25,
  },
  settings: {
    theme: "light",
    language: "en",
  },
};

Custom Actions

Define actions in createDispatch:

import { CreateDispatch } from "zustore";

const createDispatch = CreateDispatch(({ name, payload, tools }) => {
  const { dispatch, addState, state } = tools;

  const setAge = () => {
    const age = payload.value;
    dispatch({ age }, "info");
  };

  switch (name) {
    /*
      actions => return all actions that you logged
      when you call dispatcher("setAge", { value: 28 })
      (setAge) is the action
    */
    case "setAge":
      return setAge();
    case "lang":
      return lang();
    default:
      console.log("not found");
      break;
  }
});

Dispatch actions using dispatcher:

import { useDispatch } from "zustore";
const { dispatcher } = useDispatch();
dispatcher("setAge", { value: 28 });

Reset the value to the initial value in global state reset:

import { useDispatch } from "zustore";
const { reset } = useDispatch();
reset("key");
// or
reset(["key1", "key2"]);

Dirty the value in the state remove the a value in the state dirty:

import { useDispatch } from "zustore";
const { dirty } = useDispatch();
dirty("key");
// or
dirty(["key1", "key2"]);

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contact

For any inquiries, feedback, or support, feel free to reach out to us through the following channels:

• 📧 Email: [email protected]
• 💼 LinkedIn: Ebrahim Abdelrazik

We appreciate your interest in zustore and are happy to assist with any questions or issues you may have.