https://github.com/aegisjsproject/state
A simple state manager library
https://github.com/aegisjsproject/state
Last synced: 10 months ago
JSON representation
A simple state manager library
- Host: GitHub
- URL: https://github.com/aegisjsproject/state
- Owner: AegisJSProject
- License: mit
- Created: 2024-10-13T16:13:44.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-08-29T14:32:16.000Z (10 months ago)
- Last Synced: 2025-08-29T17:03:14.241Z (10 months ago)
- Language: JavaScript
- Homepage: https://npmjs.com/package/@aegisjsproject/state
- Size: 767 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# `@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)
## 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
{
"imports": {
"@aegisjsproject/state": "https://unpkg.com/@aegisjsproject/state[@version]/state.js"
}
}
```
## 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.