https://github.com/devnax/react-state-bucket
Effortlessly manage React application states with react-state-bucket, a lightweight yet powerful state management library.
https://github.com/devnax/react-state-bucket
react-global-state react-state react-state-management reactjs
Last synced: 10 months ago
JSON representation
Effortlessly manage React application states with react-state-bucket, a lightweight yet powerful state management library.
- Host: GitHub
- URL: https://github.com/devnax/react-state-bucket
- Owner: devnax
- Created: 2024-12-23T07:30:00.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-03T09:50:27.000Z (12 months ago)
- Last Synced: 2025-04-11T22:16:23.891Z (10 months ago)
- Topics: react-global-state, react-state, react-state-management, reactjs
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/react-state-bucket
- Size: 177 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
React State Bucket
Effortlessly manage React application states with **react-state-bucket**, a lightweight yet powerful state management library.
---
## 🚀 Features
- **Global State Management**: Manage state across your entire React application with ease.
- **CRUD Operations**: Create, Read, Update, and Delete state values effortlessly.
- **Multiple Storage Options**: Store state in "memory," "session storage," "local storage," or "URL parameters."
- **Reactivity**: Automatically update components when the state changes.
- **Custom Hooks**: Seamlessly integrate with React’s functional components.
- **TypeScript Support**: Fully typed for a better development experience.
- **Lightweight**: Small bundle size with no unnecessary dependencies.
---
## 📦 Installation
Install the package via npm or yarn:
```bash
# Using npm
npm install react-state-bucket
# Using yarn
yarn add react-state-bucket
```
---
## 🔧 Setup and Usage
### Step 1: Create a State Bucket
Define your initial state and actions:
```javascript
import { createBucket } from 'react-state-bucket';
const initialState = {
count: 0,
user: 'Guest',
};
export const useGlobalState = createBucket(initialState);
```
### Step 2: Use the State Bucket in a Component
Access state and actions in your React components:
```javascript
import React from 'react';
import { useGlobalState } from './state';
const App = () => {
const globalState = useGlobalState();
return (
Global State Management
Count: {globalState.get('count')}
globalState.set('count', globalState.get('count') + 1)}>Increment
globalState.delete('count')}>Reset Count
{JSON.stringify(globalState.getState(), null, 2)}
);
};
export default App;
```
---
## 🌟 Advanced Features
### Using Multiple Buckets
```javascript
const useUserBucket = createBucket({ name: '', age: 0 });
const useSettingsBucket = createBucket({ theme: 'light', notifications: true });
function Profile() {
const userBucket = useUserBucket();
const settingsBucket = useSettingsBucket();
return (
User Profile
userBucket.set('name', 'John Doe')}>Set Name
settingsBucket.set('theme', 'dark')}>Change Theme
User State: {JSON.stringify(userBucket.getState(), null, 2)}
Current Theme: {settingsBucket.get('theme')}
);
}
```
### Persistent Storage Options
```javascript
const usePersistentBucket = createBucket(
{ token: '', language: 'en' },
{ store: 'local' }
);
function PersistentExample() {
const persistentBucket = usePersistentBucket();
return (
Persistent Bucket
persistentBucket.set('token', 'abc123')}>Set Token
Token: {persistentBucket.get('token')}
);
}
```
### Reusing State Across Components
```javascript
import React from 'react';
import { createBucket } from 'react-state-bucket';
const useGlobalState = createBucket({ count: 0, user: 'Guest' });
function Counter() {
const globalState = useGlobalState();
return (
Counter Component
Count: {globalState.get('count')}
globalState.set('count', globalState.get('count') + 1)}>Increment Count
);
}
function UserDisplay() {
const globalState = useGlobalState();
return (
User Component
Current User: {globalState.get('user')}
globalState.set('user', 'John Doe')}>Set User to John Doe
);
}
function App() {
return (
Global State Example
Global State: {JSON.stringify(useGlobalState().getState(), null, 2)}
);
}
export default App;
```
---
## 📘 API Reference
### `createBucket(initial: object, option?: BucketOptions)`
Creates a new bucket for managing the global state.
#### Parameters
| Name | Type | Description |
| --------- | --------- | ----------------------------------------- |
| `initial` | `object` | Initial state values. |
| `option` | `object?` | Optional configuration (default: memory). |
#### `BucketOptions`
`BucketOptions` allows you to configure how and where the state is stored. It includes:
| Property | Type | Description |
| -------- | ------------------------------------- | ---------------------------------------------- |
| `store` | `'memory', 'session', 'local', 'url'` | Specifies the storage mechanism for the state. |
### Returned Functions
#### State Management
| Function | Description |
| ----------------- | ----------------------------------------------------- |
| `set(key, value)` | Sets the value of a specific key in the state. |
| `get(key)` | Retrieves the value of a specific key from the state. |
| `delete(key)` | Removes a key-value pair from the state. |
| `clear()` | Clears all state values. |
| `getState()` | Returns the entire state as an object. |
| `setState(state)` | Updates the state with a partial object. |
#### Change Detection
| Function | Description |
| ---------------- | ------------------------------------------- |
| `isChange(key)` | Checks if a specific key has been modified. |
| `getChanges()` | Returns an array of keys that have changed. |
| `clearChanges()` | Resets the change detection for all keys. |
---
## 🤝 Contributing
Contributions are welcome! Please check out the [contribution guidelines](https://github.com/devnax/react-state-bucket).
---
## 📄 License
This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).
---
## 📞 Support
For help or suggestions, feel free to open an issue on [GitHub](https://github.com/devnax/react-state-bucket/issues) or contact us via [devnaxrul@gmail.com](mailto:devnaxrul@gmail.com).