@aegisjsproject/state
Version:
A simple state manager library
95 lines (74 loc) • 4.55 kB
Markdown
# `@aegisjsproject/state`
A lightweight state management library that persists state across navigation within the same session. It leverages `history.state`
for easy integration into web applications and synchronizes state across tabs or windows within the same origin using `BroadcastChannel`.
[](https://github.com/AegisJSProject/state/actions/workflows/codeql-analysis.yml)
[](https://github.com/AegisJSProject/state/blob/master/LICENSE)
[](https://github.com/AegisJSProject/state/commits/master)
[](https://github.com/AegisJSProject/state/releases)
[](https://github.com/sponsors/shgysk8zer0)
[](https://www.npmjs.com/package/@aegisjsproject/state)
[](https://www.npmjs.com/package/@aegisjsproject/state)
[](https://github.com/shgysk8zer0)
[](https://twitter.com/shgysk8zer0)
[](https://liberapay.com/shgysk8zer0/donate "Donate using Liberapay")
- - -
- [Code of Conduct](./.github/CODE_OF_CONDUCT.md)
- [Contributing](./.github/CONTRIBUTING.md)
<!-- - [Security Policy](./.github/SECURITY.md) -->
## Features
- **Session persistence:** State persists across navigation, staying in sync with the browser's session history.
- **Multi-tab synchronization:** Keeps state in sync across multiple tabs or windows on the same origin using `BroadcastChannel`.
- **Efficient state updates:** Only updates when necessary, ensuring minimal performance overhead.
- **Flexible API:** Includes utilities for observing state changes, managing key-specific states, and clearing state.
## Installation
```bash
npm install @aegisjsproject/state
```
## CDN and importmap
You do not even need to `npm install` this or use any build process. You may either import it directly from a CDN
or use an [importmap](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap).
```html
<script type="importmap">
{
"imports": {
"@aegisjsproject/state": "https://unpkg.com/@aegisjsproject/state[@version]/state.js"
}
}
</script>
```
## Example
```js
import { setState, getState, observeStateChanges, manageState, watchState } from '@aegisjsproject/state';
// Enables syncing of state across tabs/windows
watchState();
// Set state
setState('key', 'value');
// Get state
const value = getState('key');
// Observe state changes
observeStateChanges(({ diff, state }) => {
console.log('State changed:', diff, state);
});
// Observe state changes to only specific state keys
observeStateChanges(({ state }) => {
console.log('State changed:', {
foo: state.foo,
bar: state.bar,
});
}, 'foo', 'bar');
// Manage state with reactive pattern
const [state, setStateValue] = manageState('key', 'defaultValue');
console.log(state.valueOf()); // Logs the state value from the wrapper object
setStateValue('newValue'); // Updates the state
```
> [!IMPORTANT]
> This is **NOT** to be confused with eg `useState()` in React or anything like that. There is no
> transpilation step involved. Although `manageState()` does return a tuple of `[value, setValue]`,
> it takes a key and an initial value, and the `value` is an object which wraps the current value.
> You can use the value via things like `setValue(value + 1)` thanks to `[Symbol.toPrimitive]`, however.