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 isfalse
. -
persist
: An object containing the following properties:-
type
: The type of the persistence mechanism. The default value islocal
. -
key
: The key to use when persisting the state to local storage. The default value isstate
. -
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 isfalse
.
-
-
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.