imugi v1.0.0

Imugi Toolkit Documentation

Imugi is a versatile toolkit that provides a set of tools to manage and manipulate state in your applications. These tools are designed to be framework-agnostic, making them suitable for a wide range of projects. In this documentation, we will explain the core concepts and functionality of Imugi.

Table of Contents

1. Introduction to Imugi
2. Creating Atoms
3. Storage Functionality
4. Usage Examples

1. Introduction to Imugi

Imugi is a state management toolkit that simplifies the handling of application state. It is designed to be used in a wide variety of applications, regardless of the framework. Key features include:

• Creation of atoms, which serve as reactive state variables.
• Storage functionality for persisting state across sessions.
• Custom atom creation with your own logic.
• Convenient signal and state objects for handling state reactivity.

2. Creating Atoms

Atoms in Imugi are the fundamental building blocks for managing application state. They can be used like regular variables but are reactive, meaning changes to them trigger updates in components that use them. Here's how you can create atoms:

Basic Atom Creation

import { atom } from "./hooks";

const counter = atom(0);

Custom Atom Creation

You can create custom atoms with your own logic for getting and setting values:

import { customAtom } from "./hooks";

const customCounter = customAtom(10, {
  get(get, value) {
    // Custom logic for getting the value
    return value;
  },
  set(set, value, newValue) {
    // Custom logic for setting the value
  },
});

Storage Atom Creation

Storage atoms can persist their values in local storage, making them accessible from other tabs or windows:

import { storageAtom } from "./hooks";

const storedCounter = storageAtom("counter", ({ get }) => {
  return get(counter);
});

Cookie Atom Creation

Cookie atoms are similar to storage atoms but persist data as cookies:

import { cookieAtom } from "./hooks";

const cookieCounter = cookieAtom("counter", 0, {
  expires: new Date(Date.now() + 1000 * 60 * 60 * 24 * 365),
  path: "/",
});

3. Storage Functionality

Imugi provides storage functionality for persisting state across sessions. Storage atoms can be used like regular atoms and have the added benefit of data persistence. For example, the storedCounter atom is persisted in local storage and can be accessed from other tabs or windows:

const storedCounter = storageAtom("counter", ({ get }) => {
  return get(counter);
});

You can also create a custom storage atom using the StorageAtom class, as shown below:

class StorageAtom<T> extends Atom<T> {
  key: string;
  private isWindowDefined: boolean;

  constructor(key: string, args: T | ComputedFunction<T>) {
    super(args);
    this.isWindowDefined = typeof window !== "undefined";
    this.key = key;
    if (this.isWindowDefined) {
      const eventStorage = () => {
        try {
          const localValue = JSON.parse(localStorage.getItem(key) ?? "");
          this.update(localValue as T);
        } catch (error) {
          console.error(error);
        }
      };
      window.addEventListener("storage", eventStorage);
      eventStorage();
    }
  }
  update(value: T): void {
    super.update(value);
    if (!this.isWindowDefined) return;
    localStorage.setItem(this.key, JSON.stringify(value, null, 2));
  }
}

You can use this custom storage atom as follows:

const customStorageCounter = new StorageAtom("counter", 0);

4. Usage Examples

Imugi provides a simple and intuitive way to use atoms in your components. You can use the use method to get the current value and update it. Here are more usage examples:

Example 1: Using a Basic Atom

import { counter } from "./your-atom-file";

function example1() {
  const [count, setCount] = counter.use();

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>+1</button>
    </div>
  );
}

Example 2: Using a Custom Atom

import { customCounter } from "./your-atom-file";

function example2() {
  const [value, setValue] = customCounter.use();

  return (
    <div>
      <p>Value: {value}</p>
      <button onClick={() => setValue(value + 1)}>Increase</button>
    </div>
  );
}

Example 3: Using a Storage Atom

import { storedCounter } from "./your-atom-file";

function example3() {
  const [count, setCount] = storedCounter.use();

  return (
    <div>
      <p>Persisted Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>+1</button>
    </div>
  );
}

Example 4: Using a Cookie Atom

import { cookieCounter } from "./your-atom-file";

function example4() {
  const [count, setCount] = cookieCounter.use();

  return (
    <div>
      <p>Cookie Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>+1</button>
    </div>
  );
}

"Knowing yourself is the beginning of all wisdom." - Aristotle