[
{
"path": ".github/FUNDING.yml",
"content": "patreon: yezyilomo\n"
},
{
"path": ".github/workflows/node.js.yml",
"content": "# This workflow will do a clean install of node dependencies, build the source code and run tests across different versions of node\n# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions\n\nname: Node.js CI\n\non:\n push:\n branches: [ master ]\n pull_request:\n branches: [ master ]\n\njobs:\n build:\n\n runs-on: ubuntu-latest\n\n strategy:\n matrix:\n node-version: [16.x, 18.x, 19.x, 20.x]\n # See supported Node.js release schedule at https://nodejs.org/en/about/releases/\n\n steps:\n - uses: actions/checkout@v2\n - name: Use Node.js ${{ matrix.node-version }}\n uses: actions/setup-node@v2\n with:\n node-version: ${{ matrix.node-version }}\n - run: npm ci\n - run: npm test # Run tests \n"
},
{
"path": ".gitignore",
"content": "# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.\n\n# dependencies\n/node_modules\n/.pnp\n.pnp.js\n\n# testing\n/coverage\n\n# production\n/build\n/dist\n\n# misc\n.DS_Store\n.env.local\n.env.development.local\n.env.test.local\n.env.production.local\n\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\n"
},
{
"path": "LICENSE",
"content": "MIT License\n\nCopyright (c) 2020 Yezy Ilomo\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n"
},
{
"path": "README.md",
"content": "# [State Pool](https://yezyilomo.github.io/state-pool/)\n\n\n[](https://bundlephobia.com/result?p=state-pool)\n[](https://www.npmjs.com/package/state-pool)\n[](https://www.npmjs.com/package/state-pool)\n\nTransform your React app with our state management library! Declare global and local states like variables, powered by the magic of React hooks 🪄✨\n\n## Features & Advantages\n- Simple, familiar, flexible and very minimal core API but powerful\n- Built-in support for state persistence\n- Very easy to learn because its API is very similar to react state hook's API\n- Support selecting deeply nested state\n- Support creating state dynamically\n- Can be used outside react components\n- Doesn't wrap your app in context providers\n- Very organized API, You can do almost everything with a single import\n\nWant to see how this library is making all that possible?\n\nCheck out the full documentation at [yezyilomo.github.io/state-pool](https://yezyilomo.github.io/state-pool/)\n\nYou can also try live examples [Here](https://yezyilomo.github.io/state-pool-examples)\n \n\n## How it Works\n1. Create a state\n\n2. Subscribe a component(s) to the state created\n\n3. If a component wants to update the state, it sends update request\n\n4. When a state receives update request, it performs the update and send signal to all components subscribed to it for them to update themselves(re-render)\n\n \n\n## Installation\n```sh\nnpm install state-pool\n```\n\nOr \n\n```sh\nyarn add state-pool\n```\n\n \n\n## Getting Started\nUsing **state-pool** to manage state is very simple, all you need to do is\n1. Create and initialize a state by using `createState`\n2. Use your state in your component through `useState` hooks\n\nThese two steps summarises pretty much everything you need to use **state-pool**.\n\nBelow are few examples showing how to use **state-pool** to manage states.\n\n```jsx\n// Example 1.\nimport React from 'react';\nimport { createState } from 'state-pool';\n\n\nconst count = createState(0); // Create \"count\" state and initialize it with 0\n\n\nfunction ClicksCounter(props){\n // Use \"count\" state\n const [count, setCount] = count.useState();\n\n const incrementCount = (e) => {\n setCount(count+1)\n }\n\n return (\n
\n Count: {count}\n \n \n
\n );\n}\n\nReactDOM.render(ClicksCounter, document.querySelector(\"#root\"));\n```\n\n \n\nThe other way to do it is using `useState` from `state-pool`\n```jsx\n// Example 2.\nimport React from 'react';\nimport { createState, useState } from 'state-pool';\n\n\nconst count = createState(0); // Create \"count\" state and initialize it with 0\n\n\nfunction ClicksCounter(props){\n // Use \"count\" state\n const [count, setCount] = useState(count);\n\n const incrementCount = (e) => {\n setCount(count+1)\n }\n\n return (\n
\n Count: {count}\n \n \n
\n );\n}\n\nReactDOM.render(ClicksCounter, document.querySelector(\"#root\"));\n```\n\n \n\n## What about local state?\nWith **state-pool**, state are just like variables, if declared on a global scope, it’s a global state and if declared on local scope it’s a local state, so the difference between global state and local state in **state-pool** lies where you declare them just like variables.\n\nHere is an example for managing local state\n```jsx\n// Example 1.\nimport React from 'react';\nimport { useState } from 'state-pool';\n\n\nfunction ClicksCounter(props){\n // Here `useState` hook will create \"count\" state and initialize it with 0\n // Note: the `useState` hook used here is impored from state-pool and not react\n const [count, setCount] = useState(0);\n\n const incrementCount = (e) => {\n setCount(count+1)\n }\n\n return (\n
\n Count: {count}\n \n \n
\n );\n}\n\nReactDOM.render(ClicksCounter, document.querySelector(\"#root\"));\n```\n \n\nIf you don't want **state-pool's** `useState` to collide with **React's** `useState` you can import `StatePool` and use the hook from there,\n\nHere is an example\n```jsx\n// Example 2.\nimport React from 'react';\nimport StatePool from 'state-pool';\n\n\nfunction ClicksCounter(props){\n // Here `useState` hook will create \"count\" state and initialize it with 0\n const [count, setCount] = StatePool.useState(0);\n\n const incrementCount = (e) => {\n setCount(count+1)\n }\n\n return (\n
\n Count: {count}\n \n \n
\n );\n}\n\nReactDOM.render(ClicksCounter, document.querySelector(\"#root\"));\n```\n\n \n\n## Isn't `StatePool.useState` the same thing as `React.useState`?\n**Definitely. not!...**\n\nBoth can be used to manage local state, and that's where the similarity ends. `StatePool.useState` offers more features, for one it offers a simple way to update nested data unlike `React.useState`, it's also flexible as it's used to manage both global state and local state. So you could say `React.useState` is a subset of `StatePool.useState`.\n\nHere is an example of `StatePool.useState` in action, updating nested data\n```jsx\n// Example 2.\nimport React from 'react';\nimport StatePool from 'state-pool';\n\n\nconst user = StatePool.createState({name: \"Yezy\", age: 25});\n\nfunction UserInfo(props){\n const [user, setUser, updateUser] = StatePool.useState(user);\n\n const updateName = (e) => {\n updateUser(user => {\n user.name = e.target.value;\n });\n }\n\n return (\n
\n Name: {user.name}\n \n \n
\n );\n}\n\nReactDOM.render(UserInfo, document.querySelector(\"#root\"));\n```\n\nWith `React.useState` you would need to recreate `user` object when updating `user.name`, but with `StatePool.useState` you don't need that, you just update the value right away. \n\nThat's one advantage of using `StatePool.useState` but there are many more, you'll learn when going through [**documentation**đź“ť](https://yezyilomo.github.io/state-pool/).\n\n\n\n## Store based example\nIf you have many states and you would like to organize them into a store, **state-pool** allows you to do that too and provides a ton of features on top of it.\n\nHere are steps for managing state with a store\n1. Create a store(which is basically a container for your state)\n1. Create and initialize a state by using `store.setState`\n2. Use your state in your component through `store.useState` hooks\n\nThese three steps summarises pretty much everything you need to manage state with a store.\n\nBelow are few examples of store in action\n\n```jsx\n// Example 1.\nimport { createStore } from 'state-pool';\n\n\nconst store = createStore(); // Create store for storing our state\nstore.setState(\"count\", 0); // Create \"count\" state and add it to the store\n\nfunction ClicksCounter(props){\n // Use \"count\" state\n const [count, setCount] = store.useState(\"count\");\n\n return (\n
\n Count: {count}\n \n \n
\n );\n}\n```\n\n \n\n```jsx\n// Example 2.\nimport { createStore } from 'state-pool';\n\n\n// Instead of using createStore and store.setState,\n// you can combine store creation and initialization as follows\n\nconst store = createStore({\"user\", {name: \"Yezy\", age: 25}}); // create store and initialize it with user\n\nfunction UserInfo(props){\n const [user, setUser, updateUser] = store.useState(\"user\");\n\n const updateName = (e) => {\n updateUser(user => {\n user.name = e.target.value;\n });\n }\n\n return (\n
\n );\n}\n\nReactDOM.render(UserInfo, document.querySelector(\"#root\"));\n```\nFrom the code above, when you click `Reset Store` button `store.clear` will remove all states from the store and create them again by executing `initializeStore`. This might come in handy when you need to clear all data when user logs out of your application.\n\n\n**NOTE:** both `store.remove` and `store.clear` when executed causes all components subscribed to states which are removed to rerender.\n"
},
{
"path": "website/docs/api_reference/high_level_api/store.getState.md",
"content": "---\nsidebar_position: 5\n---\n\n# store.getState\n`store.getState` is used to get a state object from a store, it accepts one required parameter which is a key(string) and another optional parameters which is the configuration object(available configurations are `default` and `persist` works just like in `store.setState`). When called, `store.getState` returns a state object.\n\n```js\n// Signature\nstore.getState(key: String, config?: {default: Any, persist: Boolean})\n```\n\nHere is how to use it\n\n```js\nconst State = store.getState(key);\n```\n\n"
},
{
"path": "website/docs/api_reference/high_level_api/store.getStateValue.md",
"content": "---\nsidebar_position: 12\n---\n\n# store.getStateValue\nThis method is used to get state value directly from a store given its key, it's equivalent of calling `store.getState(key).getValue(selector?)`. You can pass `selector` too if you want to select part of the state.\n\n```js\nconst userName = store.getStateValue(\"user\", (user) => user.name);\n```"
},
{
"path": "website/docs/api_reference/high_level_api/store.has.md",
"content": "---\nsidebar_position: 10\n---\n\n# store.has\n`store.has` is a method for checking if a state is available in a store. If you try to get a state from a store with `store.getState(key)` and it’s not available, state-pool will throw an error, so we need a good way to handle this, i.e check if a state is available first, then access it, This is where `store.has` swoops in.\n\nHere is an example of `store.has` in action\n\n\n```js\n// We want to access user state in a store but first we have to check if it's available\nif(store.has(\"user\")) {\n const user = store.getState(\"user\");\n}\nelse {\n // There is not user state in a store\n}\n\n```"
},
{
"path": "website/docs/api_reference/high_level_api/store.items.md",
"content": "---\nsidebar_position: 11\n---\n\n# store.items\n`store.items` is used to iterate over an entire store, it returns an array containing `key`, `value` and `persist` for each state in a store.\n\n\nHere is how to use it.\n\n```js\nstore.items().map(([key, value, persist]) => {\n // Do whatever you want with these values\n})\n```"
},
{
"path": "website/docs/api_reference/high_level_api/store.persist.md",
"content": "---\nsidebar_position: 9\n---\n\n# store.persist\nSometimes you might want to save your states in a permanent storage probably because you might not want to lose them when your application is closed(i.e you want to retain them when your application starts).\n\n**State pool** makes it very easy to save your states in your preferred permanent storage, all you need to do is:\n\n1. Tell **state-pool** how to save your state by using `store.persist`\n2. Use `persist` configuration to tell state-pool to save your state in your preferred storage when creating your state.\n\nWhen telling **state-pool** how to save state to a permanent storage we need to implement four functions which are \n\n1. `saveState`: This is for saving your state to your preferred permanent storage, it should accept a `key` as the first parameter, `value` as the second parameter and `isInitialSet` as the third parameter, the third parameter is boolean which tells if the state is being saved for the first time(initial set) or it's just an update. This function is called automatically when `store.setState` is executed and when the state changes\n2. `loadState`: This is used for loading state from your preferred permanent storage, it should accept a `key` as the first parameter and `noState` as the second parameter which is a constant(empty) to return if the state is not available from your permanent storage. This function is called when `store.setState` needs an initial value from your storage to populate a state\n3. `removeState`: This is used for removing state from a permanent storage, it should accept a `key` as the only parameter. This function is called when `store.remove` is executed\n4. `clear`: This is used for clearing an entire permanent storage, it doesn’t accept any parameter. This function is called when `store.clear` is executed.\n\nNow the way to implement these is by calling `store.persist` and pass them as shown below \n\n```js\nstore.persist({\n saveState: function(key, value, isInitialSet){/*your code to save state */},\n loadState: function(key, noState){/*your code to load state */},\n removeState: function(key){/*your code to remove state */},\n clear: function(){/*your code to clear storage */}\n})\n```\n\nAfter implementing these four functions you're good to go, you won’t need to worry about calling them, **state-pool** will be doing that for you automatically so that you can focus on using your states.\n\nAs discussed earlier both `store.setState`, `store.useState` and `store.useReducer` accepts an optional configuration parameter, `persist` being one of configurations, this is the one which is used to tell **state-pool** whether to save your state to a permanent storage or not. i.e\n\n```js\nstore.setState(\n key: String,\n initialState: Any,\n config?: {persist: Boolean}\n)\n```\n\n```js\nstore.useState(\n key: String,\n config?: {default: Any, persist: Boolean, ...otherConfigs}\n)\n```\n\n```js\nstore.useReducer(\n reducer: Function,\n key: String,\n config?: {default: Any, persist: Boolean, ...otherConfigs}\n)\n```\n\nBy default the value of `persist` in all cases is false(which means it doesn't save states to a permanent storage), so if you want to activate it, you have to set it to be true.\n\nWhat's even better about **state-pool** is that you get the freedom to choose what to save in your permanent storage and what's not to, so you don't need to save the whole store in your permanent storage, but if you want to save the whole store you can use `PERSIST_ENTIRE_STORE` configuration.\n\nBelow is an example showing how you could implement state persistance in local storage.\n\n```js\nimport { createStore } from 'state-pool';\n\nconst store = createStore();\n\nfunction debounce(func, timeout) {\n let timer;\n return (...args) => {\n clearTimeout(timer);\n timer = setTimeout(() => { func.apply(this, args); }, timeout);\n };\n}\n\nstore.persist({\n PERSIST_ENTIRE_STORE: true, // Use this only if you want to persist the entire store\n saveState: function (key, value, isInitialSet) {\n \n const doStateSaving = () => {\n try {\n const serializedState = JSON.stringify(value);\n window.localStorage.setItem(key, serializedState);\n } catch {\n // Ignore write errors\n }\n }\n\n if (isInitialSet) {\n // Here we don't debounce saving state since it's the initial set\n // so it's called only once and we need our storage to be updated\n // right away\n doStateSaving();\n }\n else {\n // Here we debounce saving state because it's the update and this function\n // is called every time the store state changes. However, it should not\n // be called too often because it triggers the expensive `JSON.stringify` operation.\n const DEBOUNCE_TIME = 1000 // In milliseconds\n // Debounce doStateSaving before calling it\n const processStateSaving = debounce(doStateSaving, DEBOUNCE_TIME);\n processStateSaving() // save State\n }\n },\n loadState: function (key, noState) {\n try {\n const serializedState = window.localStorage.getItem(key);\n if (serializedState === null) {\n // No state saved\n return noState;\n }\n return JSON.parse(serializedState);\n } catch (err) {\n // Failed to load state\n return undefined\n }\n },\n removeState: function (key) {\n window.localStorage.removeItem(key);\n },\n clear: function () {\n window.localStorage.clear();\n }\n})\n```\n\n:::important\n\nWhen you set `PERSIST_ENTIRE_STORE = true`, **state-pool** will be persisting all your states to the permanent storage by default unless you explicitly specify `persist = false` when initializing your state.\n\n:::"
},
{
"path": "website/docs/api_reference/high_level_api/store.remove.md",
"content": "---\nsidebar_position: 7\n---\n\n# store.remove\nThis is used to remove a state from a store if you don't need it anymore or you want to reload/reset it. It accepts a key for a state or a list of keys to remove and a function to run after removal.\n\n:::important\n\nThe function runs before components subscribed to removed state(s) re-renders.\n\n:::\n\n```js\n// Signature\nstore.remove(key: String, fn: Function)\n```\n\nBelow is an example showing how to use it\n\n```jsx\nimport React from 'react';\nimport { createStore } from 'state-pool';\n\n\nconst store = createStore();\nstore.setState(\"count\", 0);\n\nfunction ClicksCounter(props){\n const [count, setCount, updateCount] = store.useState(\"count\");\n\n const incrementCount = (e) => {\n setCount(count+1);\n }\n\n const reinitializeCountState = () => {\n store.setState(\"count\", 0);\n }\n\n const resetCounter = (e) => {\n store.remove(\"count\", reinitializeCountState)\n }\n\n return (\n
\n Count: {count}\n \n \n \n
\n );\n}\n\nReactDOM.render(ClicksCounter, document.querySelector(\"#root\"));\n```\n\nFrom an example above, when you click `Reset` button `store.remove` will remove `count` state and create it again by executing `initializeStore`.\n\n\n**NOTE:** If we had more than one state to delete we could do\n\n```js\nstore.remove([key1, key2, key3, ...], initializeStore);\n```\n"
},
{
"path": "website/docs/api_reference/high_level_api/store.setState.md",
"content": "---\nsidebar_position: 2\n---\n\n# store.setState\nThis is used to create a state and map it to a key so that you won't need to use it directly, instead you use a key to get it. `store.setState` takes two required parameters, a key(string) to map to a state object and the initial value or state initializer, In addition to those two parameters it takes a third optional parameter which is the configuration object. `persist` is the only available config which is the flag to determine whether to save/persist state in a permanent storage or not.\n\n```js\n// Signature\nstore.setState(key: String, initialState: Any, config?: {persist: Boolean});\n\n// Or with lazy state initializer\n\nstore.setState(key: String, stateInitializer: () => Any, config?: {persist: Boolean})\n```\n\nHere is how to use it\n\n```js\nconst userState = {\n name: \"Yezy\",\n age: 25,\n email: \"yezy@me.com\"\n}\nstore.setState(\"user\", userState);\n```\n\n:::important\n\n`store.setState` should be used outside of a react component.\n\n:::\n\n"
},
{
"path": "website/docs/api_reference/high_level_api/store.subscribe.md",
"content": "---\nsidebar_position: 6\n---\n\n# store.subscribe\nIf you want to listen to changes in a store you can subscribe to it by using `store.subscribe`. it accepts an observer function. For example \n\n```js\n// Subscribe to store changes\nconst unsubscribe = store.subscribe(function(key: String, value: Any){\n // key is the key for a state that has changed \n // value is the new value of a state\n})\n\n// You can unsubscribe by calling the result\nunsubscribe();\n```\n\nIf you want to subscribe to a single state you can use \n\n```js\n// Subscribe to store changes\nconst unsubscribe = store.getState(key).subscribe(function(value){\n // value is the new value of a state\n})\n\n// You can unsubscribe by calling the result\nunsubscribe();\n```\n\nYou can even subscribe to a deeply nested state by using a selector as \n\n```js\nstore.getState(key).subscribe({\n observer: function(value){\n // value is the new value of a state \n },\n selector: function(value){\n return selected_state\n })\n})\n```\nWith this observer function will only be called when the selected state changes.\n\n\nAnother way to subscribe to nested state or derived state is to call `select` on a state then subscribe to it as\n\n```js\nstore.getState(key).select(state => selected_state).subscribe(value =>{\n // Do your thing here\n }\n)\n```"
},
{
"path": "website/docs/api_reference/high_level_api/store.useReducer.md",
"content": "---\nsidebar_position: 4\n---\n\n# store.useReducer\nThis is an alternative to `store.useState`, it works just like `React.useReducer` hook(If you’re familiar with `React.useReducer`, you already know how this works). It accepts a reducer and a key for the state as parameters, it returns the current state paired with a dispatch method plus the state object, but in most cases you won't be using `stateObject` so you'll be okay with just `[state, dispatch]`.. In addition to the two parameters it also accept another optinal perameter which is the configuration object, available configurations are `default`, `persist`, `selector` & `patcher` they work exactly the same just like in `store.useState`.\n\n```js\n// Signature\nstore.useReducer(\n reducer: Function,\n key: String,\n config?: {default: Any, persist: Boolean, selector: Function, patcher: Function}\n)\n```\n\nBelow is a simple example showing how to use `store.useReducer` hook\n\n```js\nconst initialState = {\n name: \"Yezy\",\n age: 25,\n email: \"yezy@me.com\"\n}\n\nstore.setState(\"user\", initialState);\n\nfunction myReducer(state, action){\n // This could be any reducer\n // Do whatever you want to do here\n return newState\n}\n\nfunction Component(props){\n const [name, dispatch] = store.useReducer(myReducer, \"user\");\n\n // Other stuff ...\n}\n```\n\n\nBelow is an example with `selector` and `patcher` parameters\n\n```js\nconst initialState = {\n name: \"Yezy\",\n age: 25,\n email: \"yezy@me.com\"\n}\n\nstore.setState(\"user\", initialState);\n\n\nfunction myReducer(state, action){\n // This could be any reducer\n // Do whatever you want to do here\n return newState\n}\n\nfunction UserInfo(props){\n const selector = (user) => user.name;\n const patcher = (user, name) => {user.name = name};\n \n const [name, dispatch] = store.useReducer(myReducer, \"user\", {selector, patcher});\n\n // Other stuff\n}\n```\n"
},
{
"path": "website/docs/api_reference/high_level_api/store.useState.md",
"content": "---\nsidebar_position: 3\n---\n\n# store.useState\n`store.useState` is a hook that's used to get a state from a store, it's a way for a component to subscribe to a state from a store. `store.useState` works just like `React.useState` hook but it accepts a key for the state and returns an array of `[state, setState, updateState, stateObject]` rather than `[state, setState]`, In most cases you won't be using `stateObject` so you'll be okay with `[state, setState, updateState]`. In addition to the key parameter it also accept another optional parameter which is the config object, available configurations are `default`, `persist`, `selector` & `patcher`, these will be discussed in detail later.\n\n```js\n// Signature\nstore.useState(\n key: String,\n config?: {default: Any, persist: Boolean, selector: Function, patcher: Function}\n)\n\n// Or with lazy state initializer as \n\nstore.useState(\n key: String,\n config?: {default: () => Any, persist: Boolean, selector: Function, patcher: Function}\n)\n```\n\nBelow is an example showing how to use `store.useState` hook\n\n```js\nconst initialState = {\n name: \"Yezy\",\n age: 25,\n email: \"yezy@me.com\"\n}\n\nstore.setState(\"user\", initialState);\n\nfunction Component(props){\n const [user, setUser, updateUser] = store.useState(\"user\");\n // Other stuff\n}\n```\n\nHere `updateUser` is a higher order function which accepts another function for updating user as an argument(this another functions takes user(old state) as the argument). So to update any value on user you could do\n\n```js\nupdateUser(function(user){\n user.name = \"Yezy Ilomo\";\n user.age = 26;\n})\n```\n\nOr you could just use `setUser` instead of `updateUser` i.e\n\n```js\nsetUser({name: \"Yezy Ilomo\", age: 26, email: \"yezy@me.com\"});\n```\n\nOr\n\n```js\nsetUser(function(user){\n return {\n name: \"Yezy Ilomo\",\n age: 26,\n email: user.email\n }\n})\n```\n\nAs stated earlier `store.useState` takes a second optional parameter which is a configuration object, available configurations are:\n- `default` - This is used to specify the default value if you want `store.useState` to create a state if it doesn't find the one for the key specified in the first argument. For example\n\n ```js\n const [user, setUser, updateUser] = store.useState(\"user\", {default: null});\n\n // You can also use lazy initialization on `default` option as\n const [user, setUser, updateUser] = store.useState(\n \"user\", \n {default: () => { \n // your expensive computation here\n return null // Return your initial state\n }}); \n ```\n\n This piece of code means, get the state for the key \"user\" if it's not available in a store, create one and assign it the value `null`.\n\n- Also in addition to `default` configuration there is `persist` configuration which is the flag to determine whether to save/persist state in your preferred storage or not. Here `persist` configuration is only used if `store.useState` is going to create state dynamically(by using `default` config).\n \n\nOther allowed configurations are `selector` & `patcher`. These are used for specifying a way to select deeply nested state and update it.\n\n- `selector` should be a function which takes one parameter which is the state and returns a selected value. The purpose of this is to subscribe to a deeply nested state or derived state.\n\n- `patcher` should be a function which takes two parameters, the first is the state and the second is the selected value. The purpose of this is to merge back the selected value to the state once it's updated.\n\n Example.\n ```jsx\n const initialState = {\n name: \"Yezy\",\n age: 25,\n email: \"yezy@me.com\"\n }\n \n store.setState(\"user\", initialState);\n \n \n function UserName(props){\n const selector = (user) => user.name; // Subscribe to user.name only\n const patcher = (user, name) => {user.name = name}; // Update user.name\n \n const [name, setName] = store.useState(\"user\", {selector: selector, patcher: patcher});\n \n const handleNameChange = (e) => {\n setName(e.target.value);\n }\n \n return (\n
\n Name: {name}\n \n \n
\n );\n }\n ```\n"
},
{
"path": "website/docs/api_reference/intro.md",
"content": "---\nsidebar_position: 1\n---\n\n# Intro\nState pool API is divided into two parts. \n1. High Level API(Store based API)\n2. Low Level API(Non-Store based API)\n\nIn a high level API, states are stored in a container that we call \"store\". With high level API, State pool allows you to create as many stores as you want and use them anywhere in your application, it doesn't enforce having a single central store.\n\nHere is a simple example using high level API\n\n```jsx\nimport React from 'react';\nimport { createStore } from 'state-pool';\n\n// Create a store\nconst store = createStore();\n\n// Create count state and initialize it with 0\nconst count = store.setState(\"count\", 0);\n\nfunction ClicksCounter(props){\n // Use count state\n const [count, setCount] = store.useState(\"count\");\n\n const incrementCount = (e) => {\n setCount(count+1);\n }\n\n return (\n
\n Count: {count}\n \n \n
\n );\n}\n\nReactDOM.render(ClicksCounter, document.querySelector(\"#root\"));\n```\n\n \n\nOn the other hand, low level API doesn't use the concept of a store, You simply store your state wherever you want. In low level API **state-pool** doesn't care where you store your state as long as you can access them, for-instance I could choose to store my state in a global variable and it would still work just fine.\n\nSo basically the low level API gives you a way to create and use state, it doesn't matter where you store them as long as you can access them.\n\nHere is the same example as the previous one re-written using low level API\n\n```jsx\nimport React from 'react';\nimport { createState } from 'state-pool';\n\n\n// Create count state and initialize it with 0\nconst count = createState(0);\n\nfunction ClicksCounter(props){\n // Use count state\n const [count, setCount] = count.useState();\n\n const incrementCount = (e) => {\n setCount(count+1);\n }\n\n return (\n
\n Count: {count}\n \n \n
\n );\n}\n\nReactDOM.render(ClicksCounter, document.querySelector(\"#root\"));\n```\n\nOr if you want to import `useState` from **state-pool**\n\n```jsx\nimport React from 'react';\nimport { createState, useState } from 'state-pool';\n\n\n// Create count state and initialize it with 0\nconst count = createState(0);\n\nfunction ClicksCounter(props){\n // Use count state\n const [count, setCount] = useState(count);\n\n const incrementCount = (e) => {\n setCount(count+1);\n }\n\n return (\n
\n Count: {count}\n \n \n
\n );\n}\n\nReactDOM.render(ClicksCounter, document.querySelector(\"#root\"));\n```\n\nNow let's explore these two APIs\n"
},
{
"path": "website/docs/api_reference/low_level_api/_category_.json",
"content": "{\n \"label\": \"Low Level API\",\n \"position\": 3\n}\n "
},
{
"path": "website/docs/api_reference/low_level_api/createState.md",
"content": "---\nsidebar_position: 1\n---\n\n# createState\nThis is the basic unit of **state-pool**, it's a function which is used to create a state object, it accepts one parameter which is the initial value or initializer function.\n\n```js\n// Signature\ncreateState(initialValue: Any)\n\n// Or\n\ncreateState(initializer: () => Any)\n```\n\nHere is how to use it\n\n```js\nimport { createState } from 'state-pool';\n\nconst userName = createState(\"Yezy\");\n\n// Or if you have expensive computations during initialization you could use lazy initialization\n\nfunction lazyInitializer(){\n // Perform expensive computation here\n \n return \"Yezy\"; // Return your initial state\n}\n\nconst userName = createState(lazyInitializer);\n```\n\nHere are some of the mostly used methods available in a state object.\n\n- `useState`: This is used to subscribe a component to a state, it's a hook which should be used inside a react component.\n ```js\n // Signature\n state.useState(config?: {selector: Function, patcher: Function});\n ```\n- `useReducer`: This too is used to subscribe a component to a state, it's also a hook which should be used inside a react component.\n ```js\n // Signature\n state.useReducer(reducer: Function, config?: {selector: Function, patcher: Function});\n ```\n- `getValue`: This is used to get the value of a state\n ```js\n // Signature\n state.getValue(selector?: Function);\n ```\n- `setValue`: This is used to set the value of a state\n ```js\n // Signature\n state.setValue(value | stateUpdater: Any | Function, config?: {selector, patcher});\n ```\n- `updateValue`: This is used to update the value of a state\n ```js\n // Signature\n state.updateValue(updater: Function, config?: {selector, patcher});\n ```\n- `subscribe`: This is used to listen to all changes from a state\n ```js\n // Signature\n state.subscribe(observer: Function | Subscription: {observer, selector});\n ```\n- `select`: This is used to derive another state or select a deeply nested state\n ```js\n // Signature\n state.select(selector: Function);\n ```\n This returns `DerivedState` that you can subscribe to by calling `subscribe` on it as\n ```js\n // Signature\n state.select(selector: Function).subscribe(observer: Function);\n ```\n\nBelow is an example showing all of them in action\n```js\nimport { createState } from 'state-pool';\n\nconst count = createState(0);\n\ncount.useState() // This subscribe its component to count state\n\ncount.getValue() // This will give 0\n\ncount.setValue(1) // This set the value of count to 1\n\n// This will print whenever count change\nconst unsubscribe = count.subscribe(val => console.log(val)) \n\nunsubscribe() // This will unsubscribe the observer above\n\n// An example for nested state\nconst user = createState({name: \"Yezy\", weight: 65});\n\nuser.updateValue(user => {user.weight += 1}) // This will increment the weight\n\n// Select user name and subscribe to it,\n// this will be printing whenever user name changes\nuser.select(user => user.name).subscribe(name => console.log(name));\n```\n\n\n:::important\n\n`createState` should be used outside of a react component. \n\n:::\n\n:::tip\n\n`createState` is used to implement `store.setState` API. \n\n:::"
},
{
"path": "website/docs/api_reference/low_level_api/useReducer.md",
"content": "---\nsidebar_position: 3\n---\n\n# useReducer\nThis is an alternative to `useState`, it works just like `React.useReducer` hook(If you’re familiar with `React.useReducer`, you already know how this works). It accepts a reducer and a state object or initial state or state initializer as parameters, it returns the current state paired with a dispatch method plus the state object, but in most cases you won't be using `stateObject` so you'll be okay with `[state, dispatch]`. In addition to the two parameters it also accept another optinal perameter which is the configuration object, available configurations are `selector` and `patcher` they work exactly the same just like in `useState`.\n\n\n```js\n// Signature\nuseReducer(\n reducer: Function,\n state: State,\n config?: {selector: Function, patcher: Function}\n)\n\n// Or in local state as\n\nuseReducer(\n reducer: Function,\n initialState: Any,\n config?: {selector: Function, patcher: Function}\n)\n\n// Or with lazy state initializer\nuseReducer(\n reducer: Function,\n stateInitializer: () => Any,\n config?: {selector: Function, patcher: Function}\n)\n```\n\nBelow is a simple example showing how to use `useReducer`\n\n```js\nconst initialState = {\n name: \"Yezy\",\n age: 25,\n email: \"yezy@me.com\"\n}\n\nconst user = createState(initialState);\n\nfunction myReducer(state, action){\n // This could be any reducer\n // Do whatever you want to do here\n return newState\n}\n\nfunction Component(props){\n const [name, dispatch] = useReducer(myReducer, user);\n \n // Other stuff ...\n}\n```\n\nBelow is the same example with `selector` and `patcher` parameters\n\n```js\nconst initialState = {\n name: \"Yezy\",\n age: 25,\n email: \"yezy@me.com\"\n}\n\nconst user = createState(initialState);\n\n\nfunction myReducer(state, action){\n // This could be any reducer\n // Do whatever you want to do here\n return newState\n}\n\nfunction UserInfo(props){\n const selector = (user) => user.name;\n const patcher = (user, name) => {user.name = name};\n \n const [name, dispatch] = useReducer(myReducer, user, {selector, patcher});\n\n // Other stuffs\n}\n```\n\n\n# Using useReducer to manage local state\nJust like in `useState`, `useReducer` can be used to manage local state too.\n\nHere is an example for managing local state with `useReducer`\n```jsx\nimport React from 'react';\nimport { useReducer } from 'state-pool';\n\n\nconst myReducer = (state, action) => {\n // Your computaton here\n return action;\n}\n\nfunction ClicksCounter(props){\n // Here `useReducer` hook will create \"count\" state and initialize it with 0\n // Note: the `useReducer` hook used here is impored from state-pool and not react\n const [count, dispatch] = useReducer(myReducer, 0);\n\n const incrementCount = (e) => {\n dispatch(count+1)\n }\n\n return (\n
\n Count: {count}\n \n \n
\n );\n}\n\nReactDOM.render(ClicksCounter, document.querySelector(\"#root\"));\n```\n \n\nIf you don't want **state-pool's** `useState` to collide with **React's** `useState` you can import `StatePool` and use the hook from there,\n\n\n:::tip\n\n`useState` hook is derived from `useReducer` hook, also this hook is used to implement `store.useReducer`.\n\n:::"
},
{
"path": "website/docs/api_reference/low_level_api/useState.md",
"content": "---\nsidebar_position: 2\n---\n\n# useState\n`useState` is a hook that used within a react component to subscribe to a state. `useState` works just like `React.useState` hook but it accepts a state object or initial state or state initializer and returns an array of `[state, setState, updateState, stateObject]` rather than `[state, setState]`, In most cases you won't be using `stateObject` so you'll be okay with `[state, setState, updateState]`. In addition to a state object parameter it also accept another optional parameter which is the config object, available configurations are `selector` & `patcher`, these parameters works exactly the same as in `store.useState`. We could say `useState` is a low level implementation of `store.useState`.\n\n```js\n// Signature\nuseState(state: State, config?: {selector: Function, patcher: Function})\n\n// Or in local state as\n\nuseState(initialState: Any, config?: {selector: Function, patcher: Function})\n\n// Or with lazy state initializer\n\nuseState(stateInitializer: () => Any, config?: {selector: Function, patcher: Function})\n```\n\nBelow is a simple example showing how to use `useState` hook\n\n```jsx\nimport React from 'react';\nimport { createState, useState } from 'state-pool';\n\n\nconst initialState = {\n name: \"Yezy\",\n age: 25,\n email: \"yezy@me.com\"\n}\n\nconst user = createState(initialState);\n\nfunction Component(props){\n const [user, setUser, updateUser] = useState(user);\n // Other stuff ...\n}\n```\n\nBelow is the same example with `selector` and `patcher` configurations\n\n```jsx\nconst initialState = {\n name: \"Yezy\",\n age: 25,\n email: \"yezy@me.com\"\n}\n\nconst user = createState(initialState);\n\n\nfunction UserName(props){\n const selector = (user) => user.name; // Subscribe to user.name only\n const patcher = (user, name) => {user.name = name}; // Update user.name\n\n const [name, setName] = useState(user, {selector: selector, patcher: patcher});\n\n const handleNameChange = (e) => {\n setName(e.target.value);\n }\n\n return (\n
\n Name: {name}\n \n \n
\n );\n}\n```\n\n# Using useState to manage local state\nWith **state-pool**, state are just like variables, if declared on a global scope, it’s a global state and if declared on local scope it’s a local state, so the difference between global state and local state in **state-pool** lies where you declare them just like variables.\n\nHere is an example for managing local state with `useState`\n```jsx\nimport React from 'react';\nimport { useState } from 'state-pool';\n\n\nfunction ClicksCounter(props){\n // Here `useState` hook will create \"count\" state and initialize it with 0\n // Note: the `useState` hook used here is impored from state-pool and not react\n const [count, setCount] = useState(0);\n\n const incrementCount = (e) => {\n setCount(count+1)\n }\n\n return (\n
\n Count: {count}\n \n \n
\n );\n}\n\nReactDOM.render(ClicksCounter, document.querySelector(\"#root\"));\n```\n \n\nIf you don't want **state-pool's** `useState` to collide with **React's** `useState` you can import `StatePool` and use the hook from there,\n\nHere is an example\n```jsx\n// Example 2.\nimport React from 'react';\nimport StatePool from 'state-pool';\n\n\nfunction ClicksCounter(props){\n // Here `useState` hook will create \"count\" state and initialize it with 0\n const [count, setCount] = StatePool.useState(0);\n\n const incrementCount = (e) => {\n setCount(count+1)\n }\n\n return (\n
\n );\n}\n```\n\n:::tip\n\n`useState` is used to implement `store.useState` hook.\n\n:::"
},
{
"path": "website/docs/api_reference/typing-state.md",
"content": "---\nsidebar_position: 4\n---\n\n\n# Typing State\nAll state related functions support implicity and explicity typing.\n\nExamples\n\n```ts\nstore.setState('count', 0);\n\nstore.useState('count');\n\nstore.useReducer(reducer, 'count');\n\n// For none key based\nconst count = createState(0);\n\nuseState(count);\n\nuseReducer(reducer, count);\n\n\n// Typing with selector\nstore.setState<{name: string, age: number}>('user', {name: 'Yezy', age: 25});\n\nstore.useState('user', {selector: user => user.name});\nstore.useState('age', {selector: user => user.age});\n\nstore.useReducer(reducer, 'user', {selector: user => user.name});\nstore.useReducer(reducer, 'user', {selector: user => user.age});\n\n// For none key based\nconst user = createState<{name: string, age: number}>({name: 'Yezy', age: 25});\n\nuseState(user, {selector: user => user.name});\nuseState(user, {selector: user => user.age});\n\nuseReducer(reducer, user, {selector: user => user.name});\nuseReducer(reducer, user, {selector: user => user.age});\n```\n\n
\n\n# Blue print for typing hooks\n**Note:** `T` is for base/original state type, `ST` for selected state type and `A` for reducer action.\n\n```ts\n// useState.js (For useState)\n\nconst [state: T, setState: SetState, updateState: UpdateState, stateObj: State] = useState(state: State | T)\n\nconst [state: ST, setState: SetState, updateState: UpdateState, stateObj: State] = useState(state: State | T, { selector: Selector })\n\nconst [state: ST, setState: SetState