Package Exports

react-state-bucket
react-state-bucket/index.cjs
react-state-bucket/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (react-state-bucket) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

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.
Change Callbacks: React to every set or delete via the optional onChange hook.

📦 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.
`onChange`	`(key, value, type) => void`	Callback invoked after each `set`/`delete`. `type` is `'set'` or `'delete'`.

`onChange` Callback

Use onChange to observe bucket mutations—for example, to sync analytics or trigger side effects.

const useBucketWithLogger = createBucket(
  { count: 0 },
  {
    onChange: (key, value, type) => {
      console.log(`[bucket] ${type} -> ${key}`, value);
    },
  }
);

When set('count', 1) runs, the callback fires with (key='count', value=1, type='set'). Deletions invoke the same hook with type='delete' and value as undefined.

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 devnaxrul@gmail.com.