README

Stateful.js

Simple. Predictable. Promise-ful.
Stateful is a promise based predicate data store. It requires almost zero-setup and provides a simple API to interact with the created "Pools".

What's a Pool?

A pool is an object that can store any type of data as a key-value pair. For example, a pool named "Todos" can be created to store a list of Todos. A pool has access to a number of methods that are used to add, update or remove data from the pool. Every value in the pool must have a key even if the payload is empty.

Installation

Install using a package manager such as Yarn:

yarn add @_agco/stateful

Usage

The library exposes simple APIs for data manipulation and management:

// Modules
import { Pool } from "@_agco/stateful";

// Pools
const Todos = new Pool({ name: "Todos" });

This will create a Pool named "Todos" in the global state tree. Now we can utilize this pool to store and update data by using its prototypes:

get(key: string | array)

Returns the data in the pool.
Accepts a parameter key which can be a string or an array of keys i.e. Array<string>
It returns a promise, and the successful response is the requested data.

// Get all pool properties
Todos.get().then(state => {
  // statements
});

// Get a specific property
Todos.get("todo1").then(state => {
  // statements
});

// Get multiple properties
Todos.get(["todo1", "todo2", "todoN"]).then(state => {
  // statements
});

update(key: string | array: required, payload: any)

Adds or Updates the data in the pool.
Accepts two parameters, a key and a payload.
The key can be a string or an array of objects i.e. { key, payload }, where key is required.
It returns a promise, and the successful response is the snapshot of the updated pool.

// Add a property to the pool
Todos.update("amount", 1000).then(newstate => {
  // statements
});

// Add multiple properties to the pool
Todos
  .update([
    { key: "todo1", payload: "buy grocery" },
    { key: "todo2", payload: "dinner with mom" }
  ]).then(newstate => {
  // statements
  });

has(key: string: required)

Checks whether a property exists in the pool.
It returns the value of the property if it exists, otherwise, returns false.

// Check if "todo1" exists in pool
Todos.has("todo1"); // returns {...} or false

remove(key: string OR regex: required)

Removes one or more properties by passing the key as a parameter.
It returns a promise, and the successful response is the snapshot of the updated pool.

// Remove a specific property
Todos.remove("todo").then(newstate => {
  // statements
});

// Remove multiple properties using regex
Todos.remove(/todo_i/).then(newstate => {
  // statements
});

reset()

Empties the pool

// Empty the pool
Todos.reset(); // returns {}

subscribe(method: function: required)

Registers a callback which will be exectued whenever the pool is updated.

// assign a method to be called when the pool is updated.
Todos.subscribe(() => {
  // statements
});

Usage no npm install needed!