statestore.js

A state management library for reactively and selectively updating parts of applications.

Installation

yarn add statestorejs

or with npm

npm install statestorejs

Go to usage in reactjs and react native apps

The basic idea behind statestore.js

Given an internal state (an object), every part of the application should be able not only to access the object
but also be able to subscribe selectively to changes made in the values of the object. The figure below shows a practical example of how statestorejs ensures selectivity in triggering change events.

In the figure below, both componnent A and B subscribes to be updated when there are changes in the values of the object. Component B does not depend on value B or changes in value B has no effect on component B therefore, never updates (or re-executed) until there's a change in value A. That is how statestorejs ensure selectivity in updates (and/or re-renders in Reactjs) applications.

A simple demo in any JavaScript or TypeScript applications

This is a test with the usage of statestore.js to pass data from one function to the other.

import { createStore, getStore, subscribe, updateStore } from "statestorejs";

type UserInfo = { username: string, fulname: string}
function App(){
    const provider = 'storage_provider_name'
    const storename = 'store_name'
    createStore<UserInfo>(provider, storename, { username: 'KBismark', fullname: 'Bismark Yamoah'});

    //Simulates userinfo update after 2 secods
    setTimeout(() => {
        // Change username and course all subscribers listening to changes in the 'username' field
        updateStore<UserInfo>(provider, storename, {actors: ['username'], store: {username: 'KBis'}})
    }, 2000);

    // Show current user info
    ShowUserInfo()
}


// Logs user info when user info is updated in the App method
function ShowUserInfo(){
    const provider = 'storage_provider_name'
    const storename = 'store_name'
    const actualProps = getStore<UserInfo>(provider, storename);
    console.log(actualProps);

    // Performs some task
    SomeCPUIntensiveTask() 
    
    // Subscribe to changes in username only
    subscribe<UserInfo>(
        provider, storename,
        // Subscribe to the store and listen to changes in only the 'username' field
        { watch: ['username'], action: (store)=>console.log(store.username, store.fullname) }
    )
}

function SomeCPUIntensiveTask(){
    console.log('Performed some intensive task...');
}

App(); // Start app

APIs and Methods

createStore(provider, storeId, storedata)

Sets a store in a storage provider. If no storage provider with the name provider name given exists, a new storage provider with provider name given is created before the store is created.

@param provider Storage provider's name

@param storeId Store identifier. A unique string that is used to access a store from a storage provider.

@param storedata The data to be stored

   import { createStore } from 'statestorejs'

   type User = {username: string; age: number};

   createStore<User>('some_provider', 'some_store', {username: 'John', age: 34})    

getStore(provider, storeId, cb)

Gets a copy of a store's data from a storage provider. This function returns a copy of the store if no callback is provided. If a callback is provided, then it returns the value returned by the callback. If no such store exists in the storage provider, null is returned.

@param provider Storage provider's name

@param storeId Store identifier. A unique string that is used to access a store from a storage provider.

@param cb Optional callback that receives a copy of the store as argument if the store exists. This callback has no effect if store does not exist.

   import { getStore } from 'statestorejs'

   type User = {username: string; age: number};

   const { age, username, fullname } = getStore<User>('some_provider', 'some_store', (store)=>{
       return {...store, fullname: `${store.username}${store.age}`}
   })    

updateStore(provider, storeId, options)

Updates and trigger listners of a store data.

@param provider Storage provider's name

@param storeId Store identifier. A unique string that is used to access a store from a storage provider.

@param options Update configuration object.

  import { updateStore } from 'statestorejs'

  type User = {username: string; age: number};

  updateStore<User>('some_provider', 'some_store', {
      actors: ['username'], // Only listeners of 'username' should be triggerd
      store: {useraname: 'James'}
  })    

subscribe(provider, storeId, options)

Subscribe to changes in a store's data or specific fields in the store. This method returns a sunscription id that can be used to unsubscribe to the service. Make sure to unsubscribe when not needed.

@param provider Storage provider's name

@param storeId Store identifier. A unique string that is used to access a store from a storage provider.

@param options Subscription configuration object.

  import { subscribe } from 'statestorejs'

  type User = {username: string; age: number};

  const subscriptionId = subscribe<User>('some_provider', 'some_store', {
      watch: ['username'],
      action: (store)=>{
          console.log(store.username, store.age)
      }
  })    

unsubscribe(provider, storeId, subscriptionId)

Unsubscribe to changes in a store's data.

@param provider Storage provider's name

@param storeId Store identifier. A unique string that is used to access a store from a storage provider.

@param subscriptionId The subscriptionId of the subscription to cancel.

 import { unsubscribe } from 'statestorejs'

 unsubscribe('some_provider', 'some_store', subscriptionId)    

deleteStore(provider, storeId)

Removes a store from a storage provider

@param provider Storage provider's name

@param storeId Store identifier. A unique string that is used to access a store from a storage provider.

    import { deleteStore } from 'statestorejs'

    deleteStore('some_provider', 'some_store')    

deleteProvider(provider)

Clears and removes a storage provider if exists.

@param provider Storage provider's name

   import { deleteProvider } from 'statestorejs'

   deleteProvider('some_provider')    

Usage in Reactjs and React Native

The following two methods ar specifically to be used in reactjs applications.

configureForReact(React)

Configures and setup statestorejs for use in react or react native.

    import React from 'react'
    import { configureForReact } from 'statestorejs'
    // Configure statestorejs
    configureForReact(React);    

useStateStore(provider, storeId, watch)

A react hook that takes care of subscription and unsubscriptions automatically. The hook allows components to subscribe to stores when mounted and unsubscibe when unmounted.

@param provider Storage provider's name

@param storeId Store identifier. A unique string that is used to access a store from a storage provider.

@param watch Optional array of fields to watch for changes in a store's object. When empty, [], the method only returns the store's data without any subscription. When not provided or undefined, causes component to update on changes in the value of any of the fields in the store's object.

    import React from 'react'
    import { configureForReact, createStore, useStateStore } from 'statestorejs'
    // Configure statestorejs
    configureForReact(React);   
    
    type User = {username: string; age: number};

    createStore<User>('some_provider', 'some_store', {username: 'John', age: 34})
    
    const UserDetails = ()=>{
        // Subscribes and watches the 
        const {username} = useStateStore<User>('some_provider', 'some_store', ['username']);

        return (/* ... */)
    }