README
Store
Lightweight JavaScript store to store state and subscribe to state changes.
Installation
npm i @olefjaerestad/store
API/examples
Create a state store
The Store class takes two parameters:
- The initial state: An object containing state that can be subscribed to. Must contain all properties up front (values can be undefined).
- The actions: An object containing functions that can perform CRUD operations on the state. You decide for yourself whether you want to use this or modify the state directly. Can contain both sync and async functions, but to be able to access
this
within, they must not be arrow functions.
import { Store } from '@olefjaerestad/store';
const store = new Store(
{
foo: 'bar',
lorem: 'ipsum',
myObj: {
baz: 'Hello',
foo: 'bar',
},
myArr: [1, 2, 3],
someAsyncVal: 'baz',
},
{
setFoo: function(val) { // To have access to 'this', it must not be arrow function.
this.state.foo = val
},
setSomeAsyncVal: async function(val) {
const newValue = await somePromise(val);
this.state.someAsyncVal = newValue;
}
}
);
Update state
Using actions:
store.actions.setFoo('Hello World');
Or directly:
store.state.foo = 'Hello World';
Access state
const myObj = store.state.myObj;
Access actions
store.actions.setFoo('Hello World');
Subscribe to state changes
Subscribe to all state changes:
const myCallback = (prop, value, prevValue, obj, state) => console.log(prop, value, prevValue, obj, state);
store.subscribe(myCallback); // myCallback will fire whenever a property of store.state changes.
store.state.foo = 'I\'m a new value'; // myCallback is fired.
Subscribe to changes to specific state properties (could be useful for avoiding firing unnecessarily many callbacks = performance increase):
const myCallback = (prop, value, prevValue, obj, state) => console.log(prop, value, prevValue, obj, state);
store.subscribe(['foo'], myCallback); // myCallback will fire whenever store.state.foo changes.
store.state.foo = 'I\'m a new value'; // myCallback is fired.
store.state.lorem = 'I\'m a new value'; // myCallback is not fired.
Note: Subscribed callbacks will fire on changes only to direct properties of store.state, i.e.
store.state.myObj
, but notstore.state.myObj.baz
.
Note 2: Subscribed callbacks will fire after the new value is set.
Unsubscribe from state changes
const myCallback = (prop, value, prevValue, obj, state) => console.log('myCallback is fired');
store.subscribe(myCallback); // myCallback will fire whenever a property of store.state changes.
store.state.foo = 'I\'m a new value'; // 'myCallback is fired' is logged.
store.unsubscribe(myCallback);
store.state.foo = 'I\'m another new value'; // 'myCallback is fired' is no longer logged, since we unsubscribed.
Changes to nested properties (objects, arrays)
Wrong:
// Changing the value of an object property.
const myCallback = (prop, value, prevValue, obj, state) => console.log('myCallback is fired');
store.subscribe(myCallback); // myCallback will fire whenever a property of store.state changes.
store.state.myObj.baz = 'I\'m a new value'; // 'myCallback is fired' won't be logged. Only changes to direct properties of store.state will trigger subscribe callbacks.
// Adding a value to an array.
const myCallback = (prop, value, prevValue, obj, state) => console.log('myCallback is fired');
store.subscribe(myCallback); // myCallback will fire whenever a property of store.state changes.
store.state.myArr.push(4); // 'myCallback is fired' won't be logged. Only changes to direct properties of store.state will trigger subscribe callbacks.
Correct:
// Changing the value of an object property.
const myCallback = (prop, value, prevValue, obj, state) => console.log('myCallback is fired');
store.subscribe(myCallback); // myCallback will fire whenever a property of store.state changes.
store.state.myObj = {...store.state.myObj, baz: 'I\'m a new value'}; // 'myCallback is fired' is logged.
// Adding a value to an array.
const myCallback = (prop, value, prevValue, obj, state) => console.log('myCallback is fired');
store.subscribe(myCallback); // myCallback will fire whenever a property of store.state changes.
store.state.myArr = [...store.state.myArr, 4]; // 'myCallback is fired' is logged.
Typescript
The package supports typings through a .d.ts file. The following named exports are exported from the package:
- Store: class that creates a store.
- ISubscribeCallback: interface for the subscribe callbacks.
Browser support
Browser | Supported? |
---|---|
Chrome >= 60 | ✅ |
Firefox >= 55 | ✅ |
Safari >= 11.1 | ✅ |
Opera >= 47 | ✅ |
Edge >= 79 | ✅ |
Internet Explorer | ❌ |
Chrome for Android > 60 | ✅ |
Firefox for Android > 55 | ✅ |
Opera for Android > 44 | ✅ |
Safari for iOS > 11.3 | ✅ |
Node.js > 8.3.0 | ✅ |
Browser support is mainly affected by use of the following:
Developing
npm i
&
npm run dev
Then just start editing the code in /src
. If using an editor with good TypeScript support (e.g. VS Code), any errors will be inlined in the code as well.
Note: Dev produces no output files.
Testing
Unit testing:
npm run test
Note: Unit tests will fail to run if there are errors in the tests themselves.
Integration testing:
npm run test:browsers
This will open a separate window where you can choose which browser to test in. Note that browsers are limited to browsers that are installed on your system and supported by Cypress.
Building
npm run build
Note: Build will fail and report if there are errors.
Publishing
Publish to npm:
npm run publish:npm
Note: requires being logged in to npm locally.