react-smart-crud 0.1.0 → 0.1.1

package/README.md

@@ -1,388 +1,430 @@
 
-# react-smart-crud   
-Smart, minimal, and developer-controlled CRUD engine for React — with **Optimistic UI**, **zero prop-drilling**, and **no state management headache**.
 
----
+# react-smart-crud 
+
+ 
+A **minimal, smart, optimistic CRUD helper for React**  
+No Redux. No Zustand. No boilerplate.
 
-## 🔥 What is react-smart-crud?
+**Designed for api management systems**.
 
-`react-smart-crud` is a **lightweight state + CRUD utility** designed to remove the most painful parts of React CRUD development:
 
-- ❌ No more endless `useState`
-- ❌ No more `useEffect` refetch loops
-- ❌ No prop drilling between components
-- ❌ No forced toast / UI library
-- ❌ No Redux / React Query overhead
+## ✨ Features
 
-👉 You write **business logic**, not plumbing.
+- ⚡ Optimistic UI (instant update)
+- 🧠 Global cache (shared across components)
+- ♻️ Auto re-fetch & sync
+- 🔐 Optional auth token support
+- 🔔 Optional toast / notification support
+- 🧩 Zero external state library
+- 🪶 Very small API surface
 
 ---
 
-## 🧠 Core Idea (Very Important)
+## 📦 Installation
 
-> **One shared store per resource.  
-Optimistic first.  
-Server truth always wins.  
-Developer controls UI & UX.**
+```bash
+npm create vite@latest my-project
 
-- Data lives in a **central in-memory store**
-- Any component subscribed to that store updates automatically
-- CRUD actions update UI instantly (optimistic)
-- Server response finalizes or rolls back state
-- Errors come directly from backend
+cd my-project
+
+npm install react-smart-crud
+````
+
+Optional dependency:
+
+```bash
+npm install react-hot-toast
+```
 
 ---
 
-## 😵 Problems This Library Solves
+## ⚙️ One-time Setup (Required)
 
-### Before (Typical React CRUD)
-- `useState` in parent
-- `useEffect` for fetch
-- Props passed through 3–4 components
-- Re-fetch list after every mutation
-- Toast logic mixed with API logic
-- Server error message lost
+Create a setup file **once** in your app.
 
-### After (react-smart-crud)
-- ✅ No `useState` for list data
-- ✅ No `useEffect` refetch
-- ✅ No props drilling
-- ✅ Instant UI update
-- ✅ Manual toast control
-- ✅ Real server error shown
+### 📄 `src/smartCrudConfig.js`
 
----
+```js
+import { setupCrud } from "react-smart-crud";
+import toast from "react-hot-toast";
+
+setupCrud({
+  baseUrl: "https://jsonplaceholder.typicode.com",
+  getToken: () => localStorage.getItem("token"),
+  notify: (type, message) => {
+    if (type === "success") toast.success(message);
+    if (type === "error") toast.error(message);
+  },
+});
+```
 
-## ✨ Key Features
+### 📄 `main.jsx`
 
-✅ Optimistic Create / Update / Delete  
-✅ No `useState` needed for CRUD data  
-✅ No `useEffect` dependency hell  
-✅ No props drilling between components  
-✅ Works across **multiple components automatically**  
-✅ Manual toast / notification control  
-✅ Backend error message preserved  
-✅ Automatic rollback on failure  
-✅ REST API friendly  
-✅ Extremely small & fast  
+```js
+import "./smartCrudConfig";
+```
+
+⚠️ **Do this only once** in your app.
 
 ---
 
-## 👥 Who Is This For?
+## 🧠 useCrud Hook
+
+```js
+const { data, loading, error } = useCrud("users");
+```
 
-### Perfect for:
-- React dashboard projects
-- Admin panels
-- School / ERP / CRM systems
-- MERN stack apps
-- Freelancers & agencies
-- Developers tired of over-engineering
+### Returned values
 
-### Not meant for:
-- Offline-first apps
-- GraphQL heavy caching
-- Real-time sync systems
+| key     | type    | description   |
+| ------- | ------- | ------------- |
+| data    | array   | cached data   |
+| loading | boolean | request state |
+| error   | any     | error info    |
 
 ---
 
-## 🆚 Comparison With Existing Solutions
+## ✍️ Create (POST)
 
-| Feature | react-smart-crud | React Query | Redux |
-|------|------------------|-------------|-------|
-| useState needed | ❌ No | ❌ No | ❌ No |
-| useEffect needed | ❌ No | ❌ No | ❌ No |
-| Prop drilling | ❌ No | ❌ No | ❌ No |
-| Optimistic UI | ✅ Simple | ⚠️ Complex | ⚠️ Manual |
-| Toast control | ✅ Full | ❌ Indirect | ❌ Indirect |
-| Boilerplate | 🔥 Very Low | Medium | High |
-| Learning curve | ⭐ Easy | ⭐⭐ Medium | ⭐⭐⭐ Hard |
+```js
+createItem("users", { name: "John" });
+```
+
+### With optimistic UI
+
+```js
+createItem(
+  "users",
+  { name: "John" },
+  {
+    optimistic: (data) => data,
+    onSuccess: () => console.log("Created"),
+    onError: (err) => console.error(err),
+  }
+);
+```
 
 ---
 
-## 📦 Installation
+## 🔄 Update (PUT)
 
-``` 
-npm install react-smart-crud
+```js
+updateItem("users", 1, { name: "Updated" });
 ```
 
+---
 
-Optional (for UI notifications)
+## ❌ Delete (DELETE)
 
-```
-npm install react-hot-toast
+```js
+deleteItem("users", 1);
 ```
 
+---
 
-⚠️ **Toast library is NOT required**
+## 📂 Example Endpoints
 
-You can use:
+| Action | Endpoint          |
+| ------ | ----------------- |
+| Fetch  | GET /users        |
+| Create | POST /users       |
+| Update | PUT /users/:id    |
+| Delete | DELETE /users/:id |
 
-* Modal
-* Alert
-* Snackbar
-* Custom UI
-* Or nothing at all
+---
+
+## 🧪 Works With
+
+* REST APIs
+* Laravel / Express / Django
+* Admin dashboards
+* School / Business management systems
+* Small to mid projects
 
 ---
 
-## 🗂️ Recommended Folder Structure
+## 🧩 Philosophy
 
-```txt
-src/
- ├─ smart-crud/
- │   ├─ config.js     # baseUrl & token config
- │   ├─ http.js       # fetch wrapper
- │   ├─ store.js      # central data store
- │   ├─ crud.js       # create / update / delete
- │   └─ index.js      # exports
-```
+> Simple cache + smart subscribers
+> No unnecessary abstraction
+> Let React re-render naturally
 
 ---
 
-## ⚙️ Configuration
+## 📄 License
 
-### `config.js`
+MIT © Tarequl Islam
 
-```js
-export const config = {
-  baseUrl: "",
-  getToken: null,
-  notify: null // ✅ toast handler
-}
 
-export function setupCrud(options = {}) {
-  config.baseUrl = options.baseUrl || ""
-  config.getToken = options.getToken || null
-  config.notify = options.notify || null
-}
 
-```
 
-### Why this design?
 
-* `baseUrl` → auto applied everywhere
-* `getToken` → optional, dynamic
-* Works with:
+## ✅  REAL-WORLD EXAMPLE (Vite + React)
 
-  * JWT
-  * Cookie-based auth
-  * Public APIs
+### 📄 `UserPage.jsx`
 
----
+```jsx
+import { useCrud, createItem, deleteItem } from "react-smart-crud";
 
-## 🌐 HTTP Layer (Server Error Safe)
+export default function UserPage() {
+  const { data: users, loading, error } = useCrud("users");
 
-```js
-import { config } from "./config";
-
-export async function request(url, options = {}) {
-  const headers = {
-    "Content-Type": "application/json",
-    ...(options.headers || {}),
-  };
-
-  // 🔐 token optional
-  if (config.getToken) {
-    const token = config.getToken();
-    if (token) {
-      headers.Authorization = `Bearer ${token}`;
-    }
-  }
+  if (loading) return <p>Loading...</p>;
+  if (error) return <p>Something went wrong</p>;
 
-  const res = await fetch(config.baseUrl + url, {
-    ...options,
-    headers,
-  });
-
-  // 🟢 body safe parse
-  const data = await res.json().catch(() => ({}));
-
-  // 🔴 IMPORTANT FIX
-  if (!res.ok) {
-    throw {
-      status: res.status,
-      message: data.message || "Something went wrong",
-      data,
-    };
-  }
+  return (
+    <div style={{ padding: 20 }}>
+      <h2>Users</h2>
 
-  return data;
+      <button
+        onClick={() =>
+          createItem("users", {
+            name: "New User",
+            email: "test@mail.com",
+          })
+        }
+      >
+        ➕ Add User
+      </button>
+
+      <ul>
+        {users.map((u) => (
+          <li key={u.id}>
+            {u.name}
+            <button onClick={() => deleteItem("users", u.id)}>
+              ❌
+            </button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
 }
+````
 
-```
+ 
+---
 
-### Benefits
+## 🔥 Optimistic UI – Full Explanation (ADD THIS)
 
-✔ Backend error message preserved
-✔ UI controls error display
-✔ No generic error forcing
+### 🎯 Why Optimistic UI?
 
----
+Optimistic UI means:
 
-## 🧠 Store Concept (No useState, No Props)
+> **Server response আসার আগেই UI update হবে**
+> Error হলে auto rollback হবে
 
-* One store per resource
-* Shared across all components
-* Subscribers auto re-render
+react-smart-crud এ এটা **fully optional**।
 
-### What you DON’T do anymore
+---
 
-* ❌ No `useState` for lists
-* ❌ No `useEffect` for fetching
-* ❌ No prop drilling
-* ❌ No manual syncing
+## 🧠 Optimistic Options Structure
+
+Every mutation (`createItem`, `updateItem`, `deleteItem`) supports:
+
+```ts
+{
+  optimistic?: Function
+  onSuccess?: Function
+  onError?: Function
+}
+```
 
 ---
 
-## ✍️ Usage Examples
+## 🟢 CREATE with Optimistic UI
 
-### CREATE (Optimistic + Toast)
+### Example
 
 ```js
- createItem(
-        "users",
-        {
-          email: form.email,
-          password: form.password,
-        },
-        {
-          optimistic: (data) => ({
-            email: data.email,
-            role: "user",
-          }),
-
-          onSuccess: () => toast.success("User created"),
-          onError: () => toast.error("Failed to create"),
-        }
-      );
+createItem(
+  "users",
+  {
+    email: form.email,
+    password: form.password,
+  },
+  {
+    // 🔮 optimistic preview data
+    optimistic: (data) => ({
+      email: data.email,
+      role: "user",
+    }),
+
+    onSuccess: () => toast.success("User created"),
+    onError: () => toast.error("Failed to create"),
+  }
+);
 ```
 
+### How it works
+
+
+1. Temporary item added instantly
+2. `_temp: true` flag attached
+3. Server response merges into same item
+4. Error হলে rollback
+
+
 ---
+ 
+
+## 🔄 UPDATE with Optimistic UI (Advanced)
 
-### UPDATE (Optimistic Patch)
+### Example
 
 ```js
 updateItem(
-        "users",
-        editingUser.id,
-        {
-          email: form.email,
-          role: form.role,
-        },
-        {
-          optimistic: (old, patch) => ({
-            ...old,
-            email: patch.email,
-            role: patch.role,
-          }),
-          onSuccess: () => {
-            toast.success("Profile updated");
-            clearEdit(); // ✅ Clear 
-          },
-          onError: (err) => toast.error(err.message),
-        }
-      );
+  "users",
+  editingUser.id,
+  {
+    email: form.email,
+    role: form.role,
+  },
+  {
+    optimistic: (old, patch) => ({
+      ...old,
+      email: patch.email,
+      role: patch.role,
+    }),
+
+    onSuccess: () => {
+      toast.success("Profile updated");
+      clearEdit();
+    },
+
+    onError: (err) => toast.error(err.message),
+  }
+);
+```
+
+### Optimistic function signature
+
+```ts
+optimistic: (oldItem, newData) => updatedItem
 ```
 
+✔ You control exactly how UI changes
+✔ Useful for forms, partial updates, toggle switches
+
 ---
 
-### DELETE
+## ❌ DELETE with Manual Error Handling
 
 ```js
-deleteItem("users", id, {
+deleteItem("users", user.id, {
+  onSuccess: () => toast.success("Deleted"),
   onError: (err) => toast.error(err.message),
 });
 ```
 
 ---
 
-## ⚡ Optimistic UI Flow
+## 🔔 Toast / Notification Integration
 
-1. UI updates instantly
-2. API request is sent
-3. Server success → finalize data
-4. Server error → rollback
-5. Subscribers re-render automatically
+You can use:
 
-No refetch
-No flicker
-No confusion
+* react-hot-toast
 
 ---
 
-## ❗ Error Handling (Real Server Message)
+## 🔧 One-time Setup for Toast
 
-### Backend
+### `src/smartCrudConfig.js`
 
 ```js
-res.status(400).json({ message: "Invalid role" });
+import { setupCrud } from "react-smart-crud";
+import toast from "react-hot-toast";
+
+setupCrud({
+  baseUrl: "https://your-api.com",
+
+  notify: (type, message) => {
+    if (type === "success") toast.success(message);
+    if (type === "error") toast.error(message);
+  },
+});
 ```
 
-### Frontend
+---
+
+## 🧠 Manual vs Automatic Notifications
+
+### Automatic (inside library)
+
+```js
+notify("success", "Deleted");
+```
+
+### Manual (recommended)
 
 ```js
-onError: (err) => toast.error(err.message);
+createItem("users", data, {
+  onSuccess: () => toast.success("Created"),
+  onError: (err) => toast.error(err.message),
+});
 ```
 
-✔ User sees exact server message
-✔ You control UX
+✔ Full control
+✔ Better UX
+✔ No magic
 
 ---
 
-## 🧩 Why No useEffect?
+# 🧩 Summary Table (ADD THIS)
 
-* Data already exists in store
-* Subscribers handle re-render
-* No dependency array bugs
-* No infinite loops
+| Action     | Optimistic         | Rollback | Manual Toast |
+| ---------- | ------------------ | -------- | ------------ |
+| createItem | ✅                  | ✅        | ✅            |
+| updateItem | ✅                  | ✅        | ✅            |
+| deleteItem | ❌ (instant remove) | ✅        | ✅            |
 
 ---
 
-## 🧩 Why No useState?
+# 💡 Best Practices (Pro Tips)
 
-* CRUD data is shared
-* Multiple components use same data
-* Manual syncing is fragile
+✔ Always return **full object** from optimistic update
 
----
+✔ Keep optimistic logic **UI-only**
 
-## 🧩 Why No Prop Drilling?
+✔ Never trust optimistic data as server truth
 
-* Store is global per resource
-* Components subscribe directly
-* Clean and scalable
+✔ Handle toast in component, not inside library
 
 ---
 
-## 🚀 Best Use Cases
 
-* Admin dashboards
-* Management systems
-* Internal tools
-* CRUD-heavy applications
-* Rapid MVPs
 
----
 
-## ❤️ Philosophy
 
-> Simple tools scale better than complex abstractions.
 
-No magic
-No hidden behavior
-Just predictable CRUD
 
----
 
-## 📄 License
 
-MIT — free to use, modify, and ship.
+
+
+
+
+
+
+
 
 ---
 
-## 🙌 Final Note
+## ✅ How it works (Mental Model)
+
+```
+Component
+   ↓
+useCrud("users")
+   ↓
+Global store cache
+   ↓
+API request (once)
+   ↓
+All subscribers auto update
+```
 
-If you understand basic React,
-you already understand **react-smart-crud**.
+👉 Multiple components → **same data, no duplicate fetch**
 
-Happy coding 🚀
+---

package/package.json

@@ -1,13 +1,10 @@
 {
   "name": "react-smart-crud",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Minimal optimistic CRUD helper for React without useState, useEffect, or prop drilling",
-  "main": "dist/index.js",
-  "module": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
+  "type": "./src/index.d.ts",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
   "keywords": [
     "react",
     "crud",
@@ -17,15 +14,21 @@
     "admin-dashboard"
   ],
   "author": "Tarequl Islam",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/tareq-dev/react-smart-crud"
+  "exports": {
+    ".": "./src/index.js"
   },
+  "files": [
+    "src"
+  ],
   "peerDependencies": {
     "react": ">=16.8"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tareq-dev/react-smart-crud.git"
+  },
   "devDependencies": {
     "vite": "^7.3.0"
-  }
+  },
+  "license": "MIT"
 }

package/src/actions.js

@@ -0,0 +1,114 @@
+import { getEntry } from "./store";
+import { request } from "./http";
+import { notify } from "./notify";
+
+/* ================= CREATE ================= */
+
+export function createItem(url, data, options = {}) {
+  const entry = getEntry(url);
+
+  /* ========== OPTIMISTIC ========== */
+  const optimisticData = options.optimistic ? options.optimistic(data) : data;
+
+  const tempItem = {
+    id: Date.now(),
+    ...optimisticData,
+    _temp: true,
+  };
+
+  entry.data = [tempItem, ...entry.data];
+  entry.subscribers.forEach((fn) => fn());
+
+  /* ========== REQUEST ========== */
+  request(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(data),
+  })
+    .then((serverData) => {
+      // ✅ MERGE — replace না
+      entry.data = entry.data.map((item) =>
+        item._temp ? { ...item, ...serverData, _temp: false } : item
+      );
+      notify("success", "Created", { url, data: serverData });
+      options.onSuccess?.(serverData);
+    })
+    .catch((error) => {
+      // 🔴 rollback
+      entry.data = entry.data.filter((i) => !i._temp);
+      notify("error", error.message || "Create failed", {
+        url,
+        error,
+      });
+      options.onError?.(error);
+    })
+    .finally(() => {
+      entry.subscribers.forEach((fn) => fn());
+    });
+}
+
+/* ================= UPDATE ================= */
+export function updateItem(url, id, data, options = {}) {
+  const entry = getEntry(url);
+  const backup = [...entry.data];
+
+  // 🟢 OPTIMISTIC UPDATE
+  entry.data = entry.data.map((item) =>
+    item.id === id
+      ? {
+          ...(options.optimistic
+            ? options.optimistic(item, data)
+            : { ...item, ...data }),
+          _updating: true,
+        }
+      : item
+  );
+
+  entry.subscribers.forEach((fn) => fn());
+
+  request(`${url}/${id}`, {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(data),
+  })
+    .then((serverData) => {
+      // 🔵 Merge server data, overwrite না
+      entry.data = entry.data.map((item) =>
+        item.id === id ? { ...item, ...serverData, _updating: false } : item
+      );
+      notify("success", "Updated", { url, id, data: serverData });
+      options.onSuccess?.(serverData);
+    })
+    .catch((error) => {
+      entry.data = backup;
+
+      notify("error", error.message || "Update failed", {
+        url,
+        id,
+        error,
+      });
+
+      options.onError?.(error);
+    })
+    .finally(() => entry.subscribers.forEach((fn) => fn()));
+}
+
+/* ================= DELETE ================= */
+export function deleteItem(url, id, options = {}) {
+  const entry = getEntry(url);
+  const backup = [...entry.data];
+
+  entry.data = entry.data.filter((i) => i.id !== id);
+  entry.subscribers.forEach((fn) => fn());
+
+  request(`${url}/${id}`, { method: "DELETE" })
+    .then(() => {
+      options.onSuccess?.();
+      notify("success", "Deleted");
+    })
+    .catch((error) => {
+      entry.data = backup;
+      entry.subscribers.forEach((fn) => fn());
+      options.onError?.(error);
+    });
+}

package/src/config.js

@@ -0,0 +1,11 @@
+export const config = {
+  baseUrl: "",
+  getToken: null,
+  notify: null // ✅ toast handler
+}
+
+export function setupCrud(options = {}) {
+  config.baseUrl = options.baseUrl || ""
+  config.getToken = options.getToken || null
+  config.notify = options.notify || null
+}

package/src/http.js

@@ -0,0 +1,35 @@
+import { config } from "./config";
+
+export async function request(url, options = {}) {
+  const headers = {
+    "Content-Type": "application/json",
+    ...(options.headers || {}),
+  };
+
+  // 🔐 token optional
+  if (config.getToken) {
+    const token = config.getToken();
+    if (token) {
+      headers.Authorization = `Bearer ${token}`;
+    }
+  }
+
+  const res = await fetch(config.baseUrl + url, {
+    ...options,
+    headers,
+  });
+
+  // 🟢 body safe parse
+  const data = await res.json().catch(() => ({}));
+
+  // 🔴 IMPORTANT FIX
+  if (!res.ok) {
+    throw {
+      status: res.status,
+      message: data.message || "Something went wrong",
+      data,
+    };
+  }
+
+  return data;
+}

package/src/index.d.ts

@@ -0,0 +1,32 @@
+declare module "react-smart-crud" {
+  export function setupCrud(options: {
+    baseUrl?: string;
+    getToken?: () => string | null;
+    notify?: (type: string, message: string, meta?: any) => void;
+  }): void;
+
+  export function useCrud<T = any>(url: string): {
+    data: T[];
+    loading: boolean;
+    error: any;
+  };
+
+  export function createItem(
+    url: string,
+    data: any,
+    options?: any
+  ): void;
+
+  export function updateItem(
+    url: string,
+    id: number | string,
+    data: any,
+    options?: any
+  ): void;
+
+  export function deleteItem(
+    url: string,
+    id: number | string,
+    options?: any
+  ): void;
+}

package/src/index.js

@@ -0,0 +1,3 @@
+export { setupCrud } from "./config";
+export { useCrud } from "./useCrud";
+export { createItem, updateItem, deleteItem } from "./actions";

package/src/notify.js

@@ -0,0 +1,7 @@
+import { config } from "./config";
+
+export function notify(type, message, meta = {}) {
+  if (typeof config.notify === "function") {
+    config.notify(type, message, meta);
+  }
+}

package/src/store.js

@@ -0,0 +1,14 @@
+export const store = new Map();
+
+export function getEntry(key) {
+  // console.log("ENTRY KEY:", key);
+  if (!store.has(key)) {
+    store.set(key, {
+      data: [],
+      loading: false,
+      error: null,
+      subscribers: new Set(),
+    });
+  }
+  return store.get(key);
+}

package/src/useCrud.js

@@ -0,0 +1,39 @@
+import { useEffect, useState } from "react";
+import { getEntry } from "./store";
+import { request } from "./http";
+
+export function useCrud(url) {
+  const entry = getEntry(url);
+  const [, force] = useState(0);
+
+  useEffect(() => {
+    const rerender = () => force((x) => x + 1);
+    entry.subscribers.add(rerender);
+
+    if (!entry.loading && entry.data.length === 0) {
+      entry.loading = true;
+
+      request(url)
+        .then((data) => {
+          entry.data = data;
+          entry.error = null;
+        })
+        .catch(() => {
+          entry.error = "Failed";
+        })
+        .finally(() => {
+          entry.loading = false;
+          entry.subscribers.forEach((fn) => fn());
+        });
+    }
+
+    return () => entry.subscribers.delete(rerender);
+  }, [url]);
+
+  // 🔑 IMPORTANT: return new reference
+  return {
+    data: entry.data,
+    loading: entry.loading,
+    error: entry.error,
+  };
+}