A synchronous shared state object that you read and write by path and that dispatches events whenever it changes. It works in browsers, React Native and Node.
Every read and write in SyncState happens immediately, so the state is reliable and predictable:
- Reads see the latest write. After
set()returns, the nextget()returns the new value. Updates are never queued, batched or deferred. - Listeners run before
set()returns.before-set,setandchangefire in that order, in the same call stack, so by the time your next line runs, every subscriber has already reacted. - No promises or timing bugs. There's nothing to
await, and no stale reads or race conditions between a write and the code that depends on it. - Easy to debug. A stack trace from inside a listener leads straight back to the
set()that caused it.
state.set('count', 1);
state.get('count'); // 1, right awaynpm install --save @atomic-reactor/sync-stateimport { SyncState } from '@atomic-reactor/sync-state';
const state = new SyncState({ user: { name: 'Ada' }, tasks: [] });
state.addEventListener('change', (e) => {
console.log(e.path, e.previous, '→', e.value);
});
state.get('user.name'); // 'Ada'
state.get(['tasks', 0], null); // null (the default)
state.set('user', { age: 36 }); // merges: { name: 'Ada', age: 36 }
state.set('tasks', ['write docs']); // replaces
state.set({ theme: 'dark' }); // merges into the whole state
state.set('theme', 'light', true); // silent: no eventsReturns the value at path, or defaultValue if nothing is there. With no path, it returns the whole state. A path is a dotted string ('user.name') or an array (['tasks', 0]). Each call dispatches get.
Sets the value at path. With no path, the value is merged into the whole state. If both the old and the new value are plain objects, they are merged one level deep. Any other value (an array, Date, class instance, primitive and so on) replaces the old one. Pass silent = true to skip events. Returns the state, so calls can be chained.
Each set dispatches these events:
| Event | When | Detail |
|---|---|---|
before-set |
before the value is written | { path, value } |
set |
after every set, whether it changed or not | { path, value } |
change |
only if the value actually changed | { path, value, previous } |
The detail fields are set on the event object itself, for example e.path.
Holds values that shouldn't trigger re-renders, such as an in-flight request. It has object-path methods (get, has, …), and its set and del dispatch cache-set and cache-del.
Holds named constants. Keys are stored in upper case. The defaults are BUSY, ERROR and READY.
state.Enums.set('done', 'done');
state.Enums.set({ idle: 'idle' });
state.Enums.get('done'); // 'done'
state.Enums.DONE; // 'done'
state.Enums.BUSY; // 'busy'Enums.set returns the updated Enums, so you can chain calls or read the new value straight away.
Adds fn to the state as a method bound to it.
Dispatches a custom event to the state's listeners.
SyncState extends EventTarget from @atomic-reactor/event-handle, which this package also re-exports along with Event, AppEvent and Listener.
MIT