Full State

Full State is a lightweight JavaScript library that provides a state management solution with support for asynchronous updates, middleware, and batched updates. It is designed to simplify state management in your JavaScript applications.

Features

• Immutable State: Create immutable state objects to prevent accidental state mutations.
• Asynchronous Updates: Update the state asynchronously and handle side effects.
• Middleware Support: Apply middleware functions to intercept and modify state updates.
• Batched Updates: Perform multiple state updates and notify listeners in a batch for improved performance.
• Lightweight: The library is less than 15KB in size.
• Perssistent State: Persist state to local storage or json files and restore it on page reload.
• Lestiners: Subscribe to state changes and get notified when the state changes.

Installation

Install the full-state library using npm:

Installation

Install the full-state library using npm:

npm install full-state

Usage

// Import the State class from the 'full-state' package
const { State } = require("full-state");

const myState = new State(
  {
    counter: 0,
    user: {
      name: "John",
      age: 25,
      email: "[email protected]",
    },
  },
  { immutable: true }
);

// Get the current state
console.log({ state: myState.state });
// { counter: 0, user: { name: 'John', age: 25, email: '[email protected]' } }

// Update the counter
myState.set("counter", 1);

// Get the updated state
console.log({ state: myState.state });
// { counter: 1, user: { name: 'John', age: 25, email: '[email protected]' } }

// Update the user object
myState.set("user.name", "Jane");

// Get the updated state
console.log({ state: myState.state });
// { counter: 1, user: { name: 'Jane', age: 25, email: '[email protected]' } }

// Add a new property to the user object
myState.set("user.phone", "111-222-333");

console.log({ state: myState.state });
// { counter: 1, user: { name: 'Jane', age: 25, email: '[email protected]' } }

myState.setState({
  counter: 0,
});

// Get the updated state
console.log({ state: myState.state });
// { counter: 0 }

// Create a new instance of the State class and use lestiners
const state = new State();

// Set an update callback to be notified when the state changes
state.setUpdateCallback((newState) => {
  console.log("State updated:", newState);
});

// Subscribe to state changes
const listener = (newState) => {
  console.log("State change detected:", newState);
};
state.subscribe(listener);

// Perform state updates
state.set("counter", 1);
state.put("todos", ["Task 1", "Task 2"]);

// Asynchronously update the state
state
  .setState({ counter: 2 })
  .then(() => {
    console.log("State updated asynchronously");
  })
  .catch((error) => {
    console.error("Error updating state:", error);
  });

// Apply middleware to intercept state updates
const middleware = (currentState, setPath) => {
  console.log("Middleware triggered:", currentState);
  // Modify state or perform side effects
  setPath("counter", 3);
};
state
  .applyMiddleware(middleware)
  .then(() => {
    console.log("Middleware applied");
  })
  .catch((error) => {
    console.error("Error applying middleware:", error);
  });

// Batch state updates
state.batchUpdate(() => {
  state.set("counter", 4);
  state.put("todos", ["Task 3", "Task 4"]);
});

// Unsubscribe from state changes
state.unsubscribe(listener);

// Create a new instance of the State class persist state to local storage
const state = new State(
  {
    counter: 0,
  },
  {
    persist: {
      type: "local",
      key: "my-state",
      enabled: true,
    },
  }
);

// Get the persisted state
console.log({ state: state.state });
// { counter: 0 }

// Update the state
state.set("counter", 1);

// Get the updated state
console.log({ state: state.state });
// { counter: 1 }

// Create a new instance of the State class persist state to a json file
const state = new State(
  {
    counter: 0,
  },
  {
    persist: {
      type: "file",
      path: "./state.json",
      enabled: true,
    },
  }
);

// Get the persisted state
console.log({ state: state.state });
// { counter: 0 }

// Update the state
state.set("counter", 1);

// Get the updated state
console.log({ state: state.state });
// { counter: 1 }

API

State

The State class is the main class of the full-state library. It provides methods to create, update, and persist state objects.

Constructor

new State(initialState, options);

The State class constructor accepts two arguments:

Properties

• initialState: The initial state object.

• options: An object containing the following properties:

  • immutable: A boolean value indicating whether the state object should be immutable. The default value is false.

  • persist: An object containing the following properties:

    • type: The type of the persistence mechanism. The default value is local.

    • key: The key to use when persisting the state to local storage. The default value is state.

    • path: The path to use when persisting the state to a json file. The default value is ./state.json.

    • enabled: A boolean value indicating whether the state should be persisted. The default value is false.

Methods

• set(path, value)

state.set(path, value);

The set method updates the state object at the specified path with the specified value.

path: The path to the property to update and you can use nested path for example.

state.set("user.name", "John");

value: The value to set.

• put(path, value)

state.put(path, value);

The put method updates the state object at the specified path with the specified value.

path: The path to the property to update and you can use nested path for example.

state.put("user.name", "John");

value: The value to set.

deferent between set and put is set will replace the value at the specified path with the specified value and put will merge the value at the specified path with the specified value.

const state = new State({
  user: {
    name: "John",
    age: 25,
  },
});

state.put("user", { name: "Jane" });
console.log(state.get("user")); // { name: 'Jane', age: 25 }

state.set("user", { age: state.get("user.age") + 1 });
console.log(state.get("user")); // { age: 26 }

• get(path)

state.get(path);

The get method returns the value at the specified path.

path: The path to the property to get and you can use nested path for example.

state.get("user.name");

• setState(newState)

state.setState(newState);

The setState method replaces the current state object with the specified state object.

newState: The new state object.

• applyMiddleware(middleware)

state.applyMiddleware(middleware);

The applyMiddleware method applies the specified middleware function to the state object.

middleware: The middleware function to apply.

• batchUpdate(callback)

state.batchUpdate(callback);

The batchUpdate method batches state updates.

callback: The callback function to execute.

• subscribe(listener)

state.subscribe(listener);

The subscribe method subscribes to state changes.

listener: The listener function to execute when the state changes.

• unsubscribe(listener)

state.unsubscribe(listener);

The unsubscribe method unsubscribes from state changes.

listener: The listener function to unsubscribe.

• setUpdateCallback(callback)

state.setUpdateCallback(callback);

The setUpdateCallback method sets the update callback function.

callback: The callback function to execute when the state changes.

• watch(path, callback)

state.watch(path, callback);

The watch method watches for changes to the specified path.

path: The path to watch.

callback: The callback function to execute when the path changes.