State reactive
@version 1.3.0, By LaKaf Librairies.
A small library for managing state and reactive elements in JS application using registrations and action listeners.
Getting started
Installation
npm i -S @lakaflibrairies/state-reactive
Demo
Here is sample code showing to use state-reactive.
const { Reactive } = require("state-reactive");
const reactive = new Reactive({ foo: "bar" });
const registration = reactive.register((state) => {
// each time the state will change, the new state will le logged in the console.
console.log(state);
});
reactive.setState({ foo: "new bar" });
How it works ?
state-reactive provides you with two classes: Reactive and Store.
Store includes Reactive and other features for creating mutations
, actions
using them, dispatching (via dispatch
) to trigger a specific action, and adding action listeners (via addActionListener
).
Reactive
Creating a reactive object using Reactive class is quite simple.
const { Reactive } = require("state-reactive");
const initialValue = { foo: "bar", toto: "tata" };
const reactiveEl = new Reactive(initialValue);
// Note: We recommand to initialize Reactive object with a JSON value as in the example above.
1 - Register method
To react when state of reactive object change, use the code below.
const initialValue = { foo: "bar", toto: "tata" };
const reactiveEl = new Reactive(initialValue);
// register method allows you to react when state of your reactive
// element changes by using callback function as parameter. The current
// state is provided in the callback parameter.
reactiveEl.register((state) => {
// your code here.
});
2 - Registration
When you register to watch any change on the state using register method, it returns an object (a registration) which can be used to unregister or call registration callback anywhere.
const registration = reactiveEl.register((state) => {
// your code here.
});
console.log(registration);
/*
// Logged in the console
{
unregister: [Function: unregister],
callHandler: [Function: callHandler]
}
*/
3 - Remove registration
To remove registration, use unregsiter method provides on registration object.
const registration = reactiveEl.register((state) => {
// your code here.
});
registration.unregister();
4 - Registration callback
This is how you can call your registration callback anywhere in your code.
registration.callHander();
Note
: registration.callHandler
must be called before register.unregister
, otherwise nothing will happen.
registration = reactiveEl.register(...);
registration.callHandler(); // Registration callback will be called.
registration.unregsiter(); // Registration callback will be removed.
registration.callHandler(); // Nothing will happen.
5 - Get state of reactive element
Reactive class provides a property call state
to get the value of the current state.
console.log(reactiveEl.state);
/* Logged in console
{ foo: "bar", toto: "tata" }
*/
6 - Set state of reactive element
State of Reactive object can't be updated using setter state
. Instead, you can use setState
method.
reactiveEl.setState(value);
// Make sure that the value with which we update the state is a JSON
// with all (or some) properties of the initial state.
7 - Reset state
To reset state of your reactive element, your can simply set state with the initial value, if this initial value has been store in a variable or a constant.
reactiveEl.setState(initialValue); // This will set state with the initial value.
Or, you can use to resetState
method provided.
reactiveEl.resetState();
8 - Reach value of specific key
This method is used to reach the value of specific point in state tree based on the key parameter.
note
: If the key parameter points on unreachable value, then an error will be triggered or undefined will be returned instead.
const initialValue = {
foo: "bar",
toto: "tata",
big: {
foo: "sub-bar",
sub: {
titi: 421,
town: "Douala"
}
}
};
const reactiveEl = new Reactive(initialValue);
console.log(reactiveEl.reachValueOf("big.sub.town"));
// Log in console
// Douala
Store
Creating a store object using Store class.
const store = new Store(config);
config
config
value is a JSON that contains configuration of your store. config
must contain exactly 3 properties and 1 optional.
-
state
: must be a JSON like the initial value in the Reactive object. -
mutations
: must be a JSON which contains functions as properties. Each function must have two parameters. The first current state provided and the second (optional) is value to use to update state. Mutation must ever return the new state to update. -
actions
: must be a JSON which contains functions as properties. Each function must have two parameters. The firstcontext
provided and the second (optional) is value to use to update state, usingcommit
. Action must ever return a Promise. -
empty
(optional) : must be an array of string that represents a list of actions that can be dispatched without payload and not required any configuration in actions and mutations blocs.
Note
: context
is an object provided in all action function, which contains to properties : commit
and state
.
Note
: commit
is a way to call mutation for update state. commit
takes two parameters (one is optional). The first is mutation name and the second is the payload that mutation will used to update state.
Note
: context.state
contains the previous version of state before commit new state.
state
Go to Reactive section for more informations.
snapshot
store.snapshot
represents the value of your state at a specific time.
addActionListener
Somewhere in your code, you can add action listener like this.
// addActionListener takes 3 parameters (the last is optional).
store.addActionListener(...);
// The first is the action name
// The second is the callback to provide when action will be dispatched. This callback may have one object in parameter, which contains one property (``state``) that represents the value of the state after action being ran.
// The last (optional) is the configuration (JSON object) of your listener which contains one property named "once" (false by default) that specify if listener will be called one time only.
This is sample code of addActionListener method
store
.addActionListener("setFirstName", ({ state }) => {
// your code here...
}, { once: true })
.addActionListener("action-name", ({ state }) => {
// code here
});
dispatch
dispatch method is a way you can update the state of your store anywhere in your code. Executing dispatch triggers the execution of all action listeners associated with the dispatched action. dispatch ever returns a Promise and takes two parameters depending on the implementation of the associated action.
First parameter is the action name provided in the store configuration on the action scope. Second parameter is the payload, depending on the payload of the implementation of the associated action.
This is sample code of dispatch
store.dispatch("setLastName", "NEW LAST NAME").then(() => {
// your code here
}).catch(e => {
console.log(e);
});
You can listen empty action by dispatching it without payload.
emit
This method is used to trigger an action at a specific moment by providing a payload.
store.emit("action-name", { foo: "bar" });
listenAction
This method is used to listen to an emitted action. It means that the provided callback cb will not be registered in the store actions and be executed when action will be called.
store
.listenAction("action-name", ({ data, unregister }) => {
// code here...
})
.ilstenAction("new-action", (event) => {
// code here...
});