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:

# 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:

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:

import React from 'react';
import { useGlobalState } from './state';

const App = () => {
  const globalState = useGlobalState();

  return (
    <div>
      <h1>Global State Management</h1>
      <p>Count: {globalState.get('count')}</p>
      <button onClick={() => globalState.set('count', globalState.get('count') + 1)}>Increment</button>
      <button onClick={() => globalState.delete('count')}>Reset Count</button>
      <pre>{JSON.stringify(globalState.getState(), null, 2)}</pre>
    </div>
  );
};

export default App;

---

🌟 Advanced Features

Using Multiple Buckets

const useUserBucket = createBucket({ name: '', age: 0 });
const useSettingsBucket = createBucket({ theme: 'light', notifications: true });

function Profile() {
  const userBucket = useUserBucket();
  const settingsBucket = useSettingsBucket();

  return (
    <div>
      <h1>User Profile</h1>
      <button onClick={() => userBucket.set('name', 'John Doe')}>Set Name</button>
      <button onClick={() => settingsBucket.set('theme', 'dark')}>Change Theme</button>
      <pre>User State: {JSON.stringify(userBucket.getState(), null, 2)}</pre>
      <p>Current Theme: {settingsBucket.get('theme')}</p>
    </div>
  );
}

Persistent Storage Options

const usePersistentBucket = createBucket(
  { token: '', language: 'en' },
  { store: 'local' }
);

function PersistentExample() {
  const persistentBucket = usePersistentBucket();

  return (
    <div>
      <h1>Persistent Bucket</h1>
      <button onClick={() => persistentBucket.set('token', 'abc123')}>Set Token</button>
      <p>Token: {persistentBucket.get('token')}</p>
    </div>
  );
}

Reusing State Across Components

import React from 'react';
import { createBucket } from 'react-state-bucket';

const useGlobalState = createBucket({ count: 0, user: 'Guest' });

function Counter() {
  const globalState = useGlobalState();

  return (
    <div>
      <h2>Counter Component</h2>
      <p>Count: {globalState.get('count')}</p>
      <button onClick={() => globalState.set('count', globalState.get('count') + 1)}>Increment Count</button>
    </div>
  );
}

function UserDisplay() {
  const globalState = useGlobalState();

  return (
    <div>
      <h2>User Component</h2>
      <p>Current User: {globalState.get('user')}</p>
      <button onClick={() => globalState.set('user', 'John Doe')}>Set User to John Doe</button>
    </div>
  );
}

function App() {
  return (
    <div>
      <h1>Global State Example</h1>
      <Counter />
      <UserDisplay />
      <pre>Global State: {JSON.stringify(useGlobalState().getState(), null, 2)}</pre>
    </div>
  );
}

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.

---

📄 License

This project is licensed under the MIT License.

---

📞 Support

For help or suggestions, feel free to open an issue on GitHub or contact us via [e-mail].