Full-state NPM

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: "john@example.com",
    },
  },
  { immutable: true }
);

// Get the current state
console.log({ state: myState.state });
// { counter: 0, user: { name: 'John', age: 25, email: 'john@example.com' } }

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

// Get the updated state
console.log({ state: myState.state });
// { counter: 1, user: { name: 'John', age: 25, email: 'john@example.com' } }

// 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: 'john@example.com' } }

// 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: 'john@example.com' } }

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 }