{"id":21469291,"url":"https://github.com/kbismark/statestore.js","last_synced_at":"2025-07-15T06:32:08.458Z","repository":{"id":245781396,"uuid":"819166963","full_name":"KBismark/statestore.js","owner":"KBismark","description":"A state management library for reactively and selectively updating parts of applications.","archived":false,"fork":false,"pushed_at":"2024-09-13T04:20:22.000Z","size":595,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-11-18T19:52:13.858Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://statestorejs.netlify.app/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KBismark.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-24T00:52:17.000Z","updated_at":"2024-09-12T04:45:30.000Z","dependencies_parsed_at":"2024-09-13T15:07:49.364Z","dependency_job_id":null,"html_url":"https://github.com/KBismark/statestore.js","commit_stats":null,"previous_names":["kbismark/statestore.js"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KBismark%2Fstatestore.js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KBismark%2Fstatestore.js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KBismark%2Fstatestore.js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KBismark%2Fstatestore.js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KBismark","download_url":"https://codeload.github.com/KBismark/statestore.js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226022607,"owners_count":17561313,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-23T09:15:03.543Z","updated_at":"2024-11-23T09:15:04.341Z","avatar_url":"https://github.com/KBismark.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# statestore.js\nA state management library for reactively and selectively updating parts of applications.    \n\n## Installation \n```bash\nyarn add statestorejs\n```\n**or with npm**    \n```bash\nnpm install statestorejs\n```    \n\n[Go to usage in reactjs and react native apps](#usage-in-reactjs-and-react-native)    \n\n\n\n## The basic idea behind statestore.js    \nGiven an internal state (an object), every part of the application should be able not only to access the object  \nbut also be able to subscribe selectively to changes made in the values of the object. The figure below shows a practical \nexample of how statestorejs ensures selectivity in triggering change events.     \n\nIn the figure below, both componnent `A` and `B` subscribes to be updated when there are changes in the values of the object. \nComponent `B` does not depend on `value B` or changes in `value B` has no effect on component `B` therefore, never updates (or re-executed) \nuntil there's a change in `value A`. That is how statestorejs ensure selectivity in updates (and/or re-renders in Reactjs) applications.   \n\n![Basic idea behind statestorejs](./files/figure3.png)\n\n## A simple demo in any JavaScript or TypeScript applications\nThis is a test with the usage of statestore.js to pass data from one function to the other.    \n\n```ts\n\nimport { createStore, getStore, subscribe, updateStore } from \"statestorejs\";\n\ntype UserInfo = { username: string, fulname: string}\nfunction App(){\n    const provider = 'storage_provider_name'\n    const storename = 'store_name'\n    createStore\u003cUserInfo\u003e(provider, storename, { username: 'KBismark', fullname: 'Bismark Yamoah'});\n\n    //Simulates userinfo update after 2 secods\n    setTimeout(() =\u003e {\n        // Change username and course all subscribers listening to changes in the 'username' field\n        updateStore\u003cUserInfo\u003e(provider, storename, {actors: ['username'], store: {username: 'KBis'}})\n    }, 2000);\n\n    // Show current user info\n    ShowUserInfo()\n}\n\n\n// Logs user info when user info is updated in the App method\nfunction ShowUserInfo(){\n    const provider = 'storage_provider_name'\n    const storename = 'store_name'\n    const actualProps = getStore\u003cUserInfo\u003e(provider, storename);\n    console.log(actualProps);\n\n    // Performs some task\n    SomeCPUIntensiveTask() \n    \n    // Subscribe to changes in username only\n    subscribe\u003cUserInfo\u003e(\n        provider, storename,\n        // Subscribe to the store and listen to changes in only the 'username' field\n        { watch: ['username'], action: (store)=\u003econsole.log(store.username, store.fullname) }\n    )\n}\n\nfunction SomeCPUIntensiveTask(){\n    console.log('Performed some intensive task...');\n}\n\nApp(); // Start app\n\n```\n\n\n## APIs and Methods\n\n### createStore(provider, storeId, storedata)    \n Sets a store in a storage provider. If no storage provider with the name `provider name given` exists, \n a new storage provider with `provider name given` is created before the store is created.    \n\n **@param** `provider` Storage provider's name    \n\n **@param** `storeId` Store identifier. A unique string that is used to access a store from a storage provider.    \n\n **@param** `storedata` The data to be stored        \n\n ```ts \n    import { createStore } from 'statestorejs'\n\n    type User = {username: string; age: number};\n\n    createStore\u003cUser\u003e('some_provider', 'some_store', {username: 'John', age: 34})    \n\n```\n\n\n### getStore(provider, storeId, cb)    \n 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. \nIf 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.    \n\n **@param** `provider` Storage provider's name    \n\n **@param** `storeId` Store identifier. A unique string that is used to access a store from a storage provider.    \n\n **@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.         \n\n ```ts \n    import { getStore } from 'statestorejs'\n\n    type User = {username: string; age: number};\n\n    const { age, username, fullname } = getStore\u003cUser\u003e('some_provider', 'some_store', (store)=\u003e{\n        return {...store, fullname: `${store.username}${store.age}`}\n    })    \n\n```\n\n### updateStore(provider, storeId, options)    \n Updates and trigger listners of a store data.    \n\n **@param** `provider` Storage provider's name    \n\n **@param** `storeId` Store identifier. A unique string that is used to access a store from a storage provider.    \n\n **@param** `options` Update configuration object.      \n\n  ```ts \n    import { updateStore } from 'statestorejs'\n\n    type User = {username: string; age: number};\n\n    updateStore\u003cUser\u003e('some_provider', 'some_store', {\n        actors: ['username'], // Only listeners of 'username' should be triggerd\n        store: {useraname: 'James'}\n    })    \n\n```   \n\n### subscribe(provider, storeId, options)    \nSubscribe to changes in a store's data or specific fields in the store. This method returns a sunscription id \nthat can be used to unsubscribe to the service. **Make sure to unsubscribe when not needed.**    \n\n **@param** `provider` Storage provider's name    \n\n **@param** `storeId` Store identifier. A unique string that is used to access a store from a storage provider.    \n\n **@param** `options` Subscription configuration object.     \n\n  ```ts \n    import { subscribe } from 'statestorejs'\n\n    type User = {username: string; age: number};\n\n    const subscriptionId = subscribe\u003cUser\u003e('some_provider', 'some_store', {\n        watch: ['username'],\n        action: (store)=\u003e{\n            console.log(store.username, store.age)\n        }\n    })    \n\n```\n\n ### unsubscribe(provider, storeId, subscriptionId)    \n Unsubscribe to changes in a store's data.    \n\n **@param** `provider` Storage provider's name    \n\n **@param** `storeId` Store identifier. A unique string that is used to access a store from a storage provider.    \n\n **@param** `subscriptionId` The subscriptionId of the subscription to cancel.    \n\n   ```ts \n    import { unsubscribe } from 'statestorejs'\n\n    unsubscribe('some_provider', 'some_store', subscriptionId)    \n\n```\n\n### deleteStore(provider, storeId)    \n Removes a store from a storage provider   \n\n **@param** `provider` Storage provider's name    \n\n **@param** `storeId` Store identifier. A unique string that is used to access a store from a storage provider.        \n\n```ts \n    import { deleteStore } from 'statestorejs'\n\n    deleteStore('some_provider', 'some_store')    \n\n```\n\n### deleteProvider(provider)    \nClears and removes a storage provider if exists.   \n\n **@param** `provider` Storage provider's name    \n\n ```ts \n    import { deleteProvider } from 'statestorejs'\n\n    deleteProvider('some_provider')    \n\n```\n\n\n## Usage in Reactjs and React Native\nThe following two methods ar specifically to be used in reactjs applications.    \n\n### configureForReact(React)    \nConfigures and setup statestorejs for use in react or react native.    \n```ts \n    import React from 'react'\n    import { configureForReact } from 'statestorejs'\n    // Configure statestorejs\n    configureForReact(React);    \n\n```     \n\n\n### useStateStore(provider, storeId, watch)    \nA react hook that takes care of subscription and unsubscriptions automatically. \nThe hook allows components to subscribe to stores when mounted and unsubscibe when unmounted.    \n\n **@param** `provider` Storage provider's name    \n\n **@param** `storeId` Store identifier. A unique string that is used to access a store from a storage provider.    \n\n **@param** `watch` Optional array of fields to watch for changes in a store's object. When empty, `[]`, the method \n only returns the store's data without any subscription. When not provided or undefined, causes component to update on changes in \n the value of any of the fields in the store's object.        \n\n```ts \n    import React from 'react'\n    import { configureForReact, createStore, useStateStore } from 'statestorejs'\n    // Configure statestorejs\n    configureForReact(React);   \n    \n    type User = {username: string; age: number};\n\n    createStore\u003cUser\u003e('some_provider', 'some_store', {username: 'John', age: 34})\n    \n    const UserDetails = ()=\u003e{\n        // Subscribes and watches the \n        const {username} = useStateStore\u003cUser\u003e('some_provider', 'some_store', ['username']);\n\n        return (/* ... */)\n    }\n\n```    \n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkbismark%2Fstatestore.js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkbismark%2Fstatestore.js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkbismark%2Fstatestore.js/lists"}