storecontrol v1.1.5

StoreControl.js

Overview

StoreControl.js aims to provide a simple store management interface to manage the stores in your web app.

There are many popular modules with similar functionality like Redux, MobX or Vuex. These modules are very useful and provide a more stable store management container for a more complicated apps. For a simple app, however, they seem overkill.

This is why StoreControl.js exist.

Install

With NPM:

npm install storecontrol

With <script> include:

Download the files and include it in your HTML. Generally, the .min version is for production use.

Usage

const state = new StoreControl();

Methods

.set(key, value)

Use this method to set a new store property and value.

The key argument accepts any value that has a type of string, object, number, function, and symbol.

// String
state.set('a', 'a')

// Any object instance (except null)
const b = []
state.set(b, 'b')

// Number type (except Infinity)
const c = 0
state.set(c, 'c')

const d = Symbol()
state.set(d, 'd')

// Any function instance
const e = function(){}
state.set(e, 'e')

// Symbol
const f = Symbol()
state.set(f, 'f')

Using null, Infinity, -Infinity, NaN, undefined, true, and false as key will throw a TypeError.

The value argument accepts any value.

.get(key)

Here, the key argument accepts any value. It's just that when you use any key value that is not supported in the .set() method, you will always get null returned.

Be careful that whenever you use any object/function/symbol instance as key when you use .set(), you must always use the same reference to get the value back.

If we use the snippet above:

const g = Symbol()
state.get(g)
// -> null

state.get(d)
// -> 'd'

/**
 * Because g === b is false.
 * Same concept applies to object/function instance.
 */

When using string or number as key, if you set the value using literal expression, you should get it back also by using literal expression. If you use its respective constructor, the object/function/symbol concept as shown above applies.

state.get('a')
// -> 'a'

state.get(new String('a'))
// -> null

.has(key)

This method checks whether a key already exist. Returns true if yes, otherwise false.

state.has(e)
// -> true

state.has(function(){})
// -> false

.branch(id)

This method creates a store branch in the existing StoreControl instance.

Basically, a branch is just setting a key (id) and automatically sets a new StoreControl instance as value. It's similar to setting state.set(id, {}). However, if you do not use the .branch method provided, your store value cannot enjoy the API provided by StoreControl.

Same rules of key argument applies for id argument here.

const branchX = state.branch('x');
// -> StoreBranch {}

The StoreBranch constructor is a private constructor and is not accessible publically.

.of(id)

This method retrieves a StoreControl's branch for you.

state.of('x')
// -> StoreBranch {}

state.of('x') === branchX
// -> true

state.of(c)
// -> TypeError

.isBranch(id)

Checks if the id passed as argument links to a StoreBranch in the current level of the instance. Returns true if yes, false otherwise.

state.isBranch('x')
// -> true

state.isBranch(d)
// -> false

.size()

Returns the size of the state.

state.size()
// -> 7

If the length of any internal property of StoreControl instance is modified without using the methods provided, using .size() will throw a RangeError.

.asMap()

Returns the entire StoreControl tree as a literal object. The returned object will be the native object thus does not have access to the StoreControl API.

The returned object will not be an accurate representation of the StoreControl instance if any object/function/symbol instance is used as key.

state.asMap()
// -> { ... }

.delete(key)

This method deletes the key and value from the store. Returns true if successful, false otherwise.

Same concept of key applies here.

state.delete(e)
// -> true

state.delete('x')
// -> true

state.delete(1)
// -> false

.clear()

This method completely clears your store and cannot be recovered.

state.clear()
state.size()
// -> 0

Properties

.keys

Returns all the keys set in the instance as an array.

.values

Returns all the values set in the instance as an array.

.entries

Returns all the keys and values as an array of key-value pair arrays.