react-state-bucket 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Naxrul Ahmed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,181 @@
+# React Mini State
+
+`react-state-bucket` is a lightweight state management library for React. It allows developers to create global states that can be accessed and modified from any component. The state can be stored in memory, session storage, or the URL query parameters, providing flexibility for different use cases.
+
+## Features
+
+- Lightweight and easy-to-use global state management.
+- Supports three storage options: memory, session storage, and URL.
+- Fully TypeScript-supported API.
+- React hook-based implementation for seamless integration.
+- Ideal for both small and large-scale React applications.
+
+## Installation
+
+Install the package via npm or yarn:
+
+```bash
+npm install react-state-bucket
+```
+
+or
+
+```bash
+yarn add react-state-bucket
+```
+
+## Usage
+
+### Importing the Package
+
+The package is designed for use with React's client-side components. Start by importing the required functionality:
+
+```javascript
+"use client";
+import { createState } from "react-state-bucket";
+```
+
+### Creating a State
+
+Use the `createState` function to define a global state. Provide an initial state object and optionally specify the storage type (`"memory"`, `"session"`, or `"url"`).
+
+```javascript
+const useGlobalState = createState({
+  count: 0,
+  name: "React",
+}, {
+  store: "memory", // Optional: Defaults to "memory"
+});
+```
+
+### Using the State in Components
+
+Components can access and manipulate the state by calling the `useGlobalState` hook.
+
+#### Example:
+
+```javascript
+import React from "react";
+
+function Counter() {
+  const state = useGlobalState();
+
+  return (
+    <div>
+      <h1>Count: {state.get("count")}</h1>
+      <button onClick={() => state.set("count", state.get("count") + 1)}>
+        Increment
+      </button>
+      <button onClick={() => state.delete("count")}>Reset</button>
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <div>
+      <Counter />
+    </div>
+  );
+}
+
+export default App;
+```
+
+### State API
+
+When you call the hook returned by `createState`, you gain access to a set of utility methods:
+
+| Method            | Description                                                |
+| ----------------- | ---------------------------------------------------------- |
+| `set(key, value)` | Sets the value of a specific key in the state.             |
+| `get(key)`        | Gets the value of a specific key from the state.           |
+| `delete(key)`     | Deletes a specific key from the state.                     |
+| `clear()`         | Clears all keys from the state.                            |
+| `getState()`      | Retrieves the entire state object.                         |
+| `setState(state)` | Updates the state with a partial object.                   |
+| `isChange(key)`   | Checks if a specific key has changed since the last clear. |
+| `getChanges()`    | Retrieves an object representing all changed keys.         |
+| `clearChanges()`  | Clears the record of changes.                              |
+
+### Storage Options
+
+The `createState` function supports three storage types:
+
+1. **Memory (default):** Stores the state in memory for the duration of the session.
+2. **Session:** Persists the state in `sessionStorage` across page reloads.
+3. **URL:** Stores the state in the URL's query parameters, enabling sharable states.
+
+#### Example with URL Storage:
+
+```javascript
+const useURLState = createState({
+  theme: "light",
+}, {
+  store: "url",
+});
+
+function ThemeSwitcher() {
+  const state = useURLState();
+
+  return (
+    <button onClick={() => state.set("theme", state.get("theme") === "light" ? "dark" : "light")}>
+      Toggle Theme (Current: {state.get("theme")})
+    </button>
+  );
+}
+```
+
+## Real-World Example
+
+### Managing a Multi-Step Form
+
+```javascript
+const useFormState = createState({
+  step: 1,
+  formData: {},
+});
+
+function MultiStepForm() {
+  const state = useFormState();
+
+  const nextStep = () => state.set("step", state.get("step") + 1);
+  const prevStep = () => state.set("step", state.get("step") - 1);
+
+  return (
+    <div>
+      <h2>Step {state.get("step")}</h2>
+      <button onClick={prevStep} disabled={state.get("step") === 1}>Back</button>
+      <button onClick={nextStep}>Next</button>
+    </div>
+  );
+}
+```
+
+## Best Practices
+
+- Use `memory` storage for temporary UI states that don't need persistence.
+- Use `session` storage for states that should persist across page reloads but not sessions.
+- Use `url` storage for sharable states, like filters or query parameters.
+
+## FAQs
+
+### 1. Can I use `react-state-bucket` in a server-side rendered (SSR) application?
+Currently, `react-state-bucket` is designed for client-side use only.
+
+### 2. What happens if I try to set an undefined key?
+An error will be thrown, ensuring state integrity.
+
+### 3. Can I use this package with TypeScript?
+Yes, `react-state-bucket` fully supports TypeScript with type-safe APIs.
+
+## GitHub Repository
+
+Find the source code and contribute to the project on GitHub:
+[https://github.com/devnax/react-state-bucket.git](https://github.com/devnax/react-state-bucket.git)
+
+[![npm version](https://img.shields.io/npm/v/react-state-bucket.svg)](https://www.npmjs.com/package/react-state-bucket)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+type Option = {
+    store: "memory" | "session" | "url";
+};
+export declare const createState: <IT extends {
+    [key: string]: any;
+}>(initial: IT, option?: Option) => () => {
+    set: <T extends keyof IT>(key: T, value: IT[T]) => void;
+    get: <T extends keyof IT>(key: T) => IT[T];
+    delete: <T extends keyof IT>(key: T) => void;
+    clear: () => void;
+    getState: () => IT;
+    setState: (state: Partial<IT>) => void;
+    isChange: <T extends keyof IT>(key: T) => boolean;
+    getChanges: () => { [key in keyof IT]: boolean; };
+    clearChanges: () => void;
+};
+export {};

package/dist/index.js

@@ -0,0 +1,134 @@
+"use client";
+import { useEffect, useId, useState } from "react";
+export const createState = (initial, option) => {
+    const hooks = new Map();
+    let data = new Map();
+    let changes = new Map();
+    let url = new URL(window.location.href);
+    let _option = {
+        store: "memory",
+        ...option,
+    };
+    const setIntial = () => {
+        for (let key in initial) {
+            let value = initial[key];
+            switch (_option.store) {
+                case "memory":
+                    data.set(key, value);
+                    break;
+                case "session":
+                    if (!sessionStorage.getItem(key)) {
+                        sessionStorage.setItem(key, value);
+                    }
+                    break;
+                case "url":
+                    if (!url.searchParams.has(key)) {
+                        url.searchParams.set(key, value);
+                        window.history.replaceState(null, '', url.toString());
+                    }
+                    break;
+            }
+            changes.set(key, true);
+        }
+    };
+    setIntial();
+    const useHook = () => {
+        const id = useId();
+        const [, up] = useState(0);
+        useEffect(() => {
+            hooks.set(id, () => up(Math.random()));
+            return () => {
+                hooks.delete(id);
+            };
+        }, []);
+        const root = {
+            set: (key, value) => {
+                if (!(key in initial))
+                    throw new Error(`(${key}) Invalid key provided in the set function. Please verify the structure of the initial state data.`);
+                switch (_option.store) {
+                    case "memory":
+                        data.set(key, value);
+                        break;
+                    case "session":
+                        sessionStorage.setItem(key, value);
+                        break;
+                    case "url":
+                        url.searchParams.set(key, value);
+                        window.history.replaceState(null, '', url.toString());
+                        break;
+                }
+                changes.set(key, true);
+                hooks.forEach(d => d());
+            },
+            get: (key) => {
+                switch (_option.store) {
+                    case "memory":
+                        return data.get(key);
+                    case "session":
+                        return sessionStorage.getItem(key);
+                    case "url":
+                        return url.searchParams.get(key);
+                }
+            },
+            delete: (key) => {
+                switch (_option.store) {
+                    case "memory":
+                        data.delete(key);
+                        break;
+                    case "session":
+                        sessionStorage.removeItem(key);
+                        break;
+                    case "url":
+                        url.searchParams.delete(key);
+                        window.history.replaceState(null, '', url.toString());
+                        console.log(url.searchParams);
+                        break;
+                }
+                changes.set(key, true);
+                hooks.forEach(d => d());
+            },
+            clear: () => {
+                for (let key in initial) {
+                    root.delete(key);
+                    changes.set(key, true);
+                }
+                hooks.forEach(d => d());
+            },
+            getState: () => {
+                let d = {};
+                for (let key of data.keys()) {
+                    d[key] = root.get(key);
+                }
+                return d;
+            },
+            setState: (state) => {
+                for (let key in state) {
+                    if (!(key in initial))
+                        throw new Error(`(${key}) Invalid key provided in the setState function. Please verify the structure of the initial state data.`);
+                    root.set(key, state[key]);
+                    changes.set(key, true);
+                }
+                hooks.forEach(d => d());
+            },
+            isChange: (key) => Boolean(changes.get(key)),
+            getChanges: () => {
+                let _changes = {};
+                for (let key of changes.keys()) {
+                    const is = changes.get(key);
+                    if (is) {
+                        _changes[key] = true;
+                    }
+                }
+                return _changes;
+            },
+            clearChanges: () => {
+                for (let key of changes.keys()) {
+                    changes.set(key, false);
+                }
+            }
+        };
+        return root;
+    };
+    return useHook;
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "version": "1.0.0",
+  "name": "react-state-bucket",
+  "author": "Naxrul Ahmed",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "typings": "dist/index.d.ts",
+  "repository": {
+    "type": "github",
+    "url": "https://github.com/devnax/react-state-bucket.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=10"
+  },
+  "scripts": {
+    "start": "parcel   index.html",
+    "build": "npx rimraf ./dist && npx tsc",
+    "prepare": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=16"
+  },
+  "prettier": {
+    "printWidth": 80,
+    "semi": true,
+    "singleQuote": true,
+    "trailingComma": "es5"
+  },
+  "devDependencies": {
+    "@size-limit/preset-small-lib": "^11.1.4",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "parcel": "^2.12.0",
+    "process": "^0.11.10",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.5.3"
+  }
+}