react-smart-crud 0.1.8 → 0.2.0

package/README.md

@@ -1,23 +1,18 @@
+# react-smart-crud
 
-
-# react-smart-crud 
-
- 
-A **minimal, smart, optimistic CRUD helper for React**  
+A **minimal, smart CRUD helper for React**
 No Redux. No Zustand. No boilerplate.
 
-**Designed for api management systems**.
-
+**Designed for API management systems**.
 
 ## ✨ Features
 
-- ⚡ 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
+* 🧠 Global cache (shared across components)
+* ♻️ Automatic re-fetch & sync after mutations
+* 🔐 Optional auth token support
+* 🔔 Optional toast / notification support
+* 🧩 Zero external state library
+* ✨ Very small API surface
 
 ---
 
@@ -29,9 +24,9 @@ npm create vite@latest my-project
 cd my-project
 
 npm install react-smart-crud
-````
+```
 
-Optional dependency:
+Optional dependency for notifications:
 
 ```bash
 npm install react-hot-toast
@@ -43,14 +38,14 @@ npm install react-hot-toast
 
 Create a setup file **once** in your app.
 
-### 📄 `src/smartCrudConfig.js`
+### 📄 `src/main.jsx`
 
 ```js
 import { setupCrud } from "react-smart-crud";
 import toast from "react-hot-toast";
 
 setupCrud({
-  baseUrl: "https://jsonplaceholder.typicode.com",
+  baseUrl: "https://api.example.com/",
   getToken: () => localStorage.getItem("token"),
   notify: (type, message) => {
     if (type === "success") toast.success(message);
@@ -58,12 +53,8 @@ setupCrud({
   },
 });
 ```
-
-### 📄 `main.jsx`
-
 ```js
-import "./smartCrudConfig";
-```
+ ```
 
 ⚠️ **Do this only once** in your app.
 
@@ -91,19 +82,7 @@ const { data, loading, error } = useCrud("users");
 createItem("users", { name: "John" });
 ```
 
-### With optimistic UI
-
-```js
-createItem(
-  "users",
-  { name: "John" },
-  {
-    optimistic: (data) => data,
-    onSuccess: () => console.log("Created"),
-    onError: (err) => console.error(err),
-  }
-);
-```
+> After creation, the library **refetches the data automatically** to keep your cache in sync.
 
 ---
 
@@ -113,6 +92,8 @@ createItem(
 updateItem("users", 1, { name: "Updated" });
 ```
 
+> After update, all subscribers automatically get the latest data.
+
 ---
 
 ## ❌ Delete (DELETE)
@@ -121,6 +102,8 @@ updateItem("users", 1, { name: "Updated" });
 deleteItem("users", 1);
 ```
 
+> After deletion, cache and UI are automatically updated.
+
 ---
 
 ## 📂 Example Endpoints
@@ -156,9 +139,7 @@ deleteItem("users", 1);
 
 MIT © Tarequl Islam
 
-
-
-
+---
 
 ## ✅  REAL-WORLD EXAMPLE (Vite + React)
 
@@ -201,121 +182,6 @@ export default function UserPage() {
     </div>
   );
 }
-````
-
- 
----
-
-## 🔥 Optimistic UI – Full Explanation (ADD THIS)
-
-### 🎯 Why Optimistic UI?
-
-Optimistic UI means:
-
-> **Server response আসার আগেই UI update হবে**
-> Error হলে auto rollback হবে
-
-react-smart-crud এ এটা **fully optional**।
-
----
-
-## 🧠 Optimistic Options Structure
-
-Every mutation (`createItem`, `updateItem`, `deleteItem`) supports:
-
-```ts
-{
-  optimistic?: Function
-  onSuccess?: Function
-  onError?: Function
-}
-```
-
----
-
-## 🟢 CREATE with Optimistic UI
-
-### Example
-
-```js
-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)
-
-### 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();
-    },
-
-    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 with Manual Error Handling
-
-```js
-deleteItem("users", user.id, {
-  onSuccess: () => toast.success("Deleted"),
-  onError: (err) => toast.error(err.message),
-});
 ```
 
 ---
@@ -326,11 +192,7 @@ You can use:
 
 * react-hot-toast
 
----
-
-## 🔧 One-time Setup for Toast
-
-### `src/smartCrudConfig.js`
+### One-time Setup for Toast
 
 ```js
 import { setupCrud } from "react-smart-crud";
@@ -348,66 +210,13 @@ setupCrud({
 
 ---
 
-## 🧠 Manual vs Automatic Notifications
-
-### Automatic (inside library)
-
-```js
-notify("success", "Deleted");
-```
-
-### Manual (recommended)
-
-```js
-createItem("users", data, {
-  onSuccess: () => toast.success("Created"),
-  onError: (err) => toast.error(err.message),
-});
-```
-
-✔ Full control
-✔ Better UX
-✔ No magic
-
----
+## 💡 Best Practices
 
-# 🧩 Summary Table (ADD THIS)
-
-| Action     | Optimistic         | Rollback | Manual Toast |
-| ---------- | ------------------ | -------- | ------------ |
-| createItem | ✅                  | ✅        | ✅            |
-| updateItem | ✅                  | ✅        | ✅            |
-| deleteItem | ❌ (instant remove) | ✅        | ✅            |
-
----
-
-# 💡 Best Practices (Pro Tips)
-
-✔ Always return **full object** from optimistic update
-
-✔ Keep optimistic logic **UI-only**
-
-✔ Never trust optimistic data as server truth
+✔ Keep mutations simple and rely on **automatic refetch**
 
 ✔ Handle toast in component, not inside library
 
----
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+✔ Use `useCrud` in multiple components — all stay in sync
 
 ---
 
@@ -422,7 +231,7 @@ Global store cache
    ↓
 API request (once)
    ↓
-All subscribers auto update
+All subscribers auto update after mutations
 ```
 
 👉 Multiple components → **same data, no duplicate fetch**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-smart-crud",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "Minimal optimistic CRUD helper for React without useState, useEffect, or prop drilling",
   "type": "./src/index.d.ts",
   "main": "./src/index.js",

package/src/actions.js

@@ -1,138 +1,49 @@
 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
-      );
-      if (options.onSuccess) {
-        options.onSuccess(serverData);
-      } else {
-        notify("success", "Created", { url, data: serverData });
-      }
-      options.onSuccess?.(serverData);
-    })
-    .catch((error) => {
-      // 🔴 rollback
-      entry.data = entry.data.filter((i) => !i._temp);
-
-      if (options.onError) {
-        options.onError?.(error);
-      } else {
-        notify("error", error.message || "Create failed", {
-          url,
-          error,
-        });
-      }
-    })
-    .finally(() => {
-      entry.subscribers.forEach((fn) => fn());
+export async function createItem(url, data, options = {}) {
+  try {
+    const serverData = await request(url, {
+      method: "POST",
+      body: JSON.stringify(data),
     });
+    options.onSuccess?.(serverData);
+    return serverData;
+  } catch (err) {
+    options.onError?.(err);
+    throw err;
+  }
 }
+
 /* ================= UPDATE ================= */
-export function updateItem(url, id, data, options = {}) {
+export async 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
-      );
-      if (options.onSuccess) {
-        options.onSuccess(serverData);
-      } else {
-        notify("success", "Updated", { url, id, data: serverData });
-      }
-    })
-    .catch((error) => {
-      entry.data = backup;
-      if (options.onError) {
-        options.onError?.(error);
-      } else {
-        notify("error", error.message || "Update failed", {
-          url,
-          id,
-          error,
-        });
-      }
-    })
-    .finally(() => entry.subscribers.forEach((fn) => fn()));
-}
-/* ================= DELETE ================= */
-export function deleteItem(url, id, options = {}) {
-  const entry = getEntry(url);
-  const backup = [...entry.data];
+      entry.fetched = false; // 🔥
 
-  // 🟢 Optimistic delete
-  entry.data = entry.data.filter((i) => i.id !== id);
-  entry.subscribers.forEach((fn) => fn());
-
-  request(`${url}/${id}`, { method: "DELETE" })
-    .then(() => {
-      if (options.onSuccess) {
-        options.onSuccess();
-      } else {
-        notify("success", "Deleted", { action: "delete", url, id });
-      }
+      options.onSuccess?.(serverData);
     })
     .catch((error) => {
-      // 🔴 rollback
-      entry.data = backup;
+      options.onError?.(error);
+    })
+    .finally(() => {
       entry.subscribers.forEach((fn) => fn());
-
-      if (options.onError) {
-        options.onError(error);
-      } else {
-        notify("error", error.message || "Delete failed", {
-          action: "delete",
-          url,
-          id,
-          error,
-        });
-      }
     });
 }
+/* ================= DELETE ================= */
+export async function deleteItem(url, id, options = {}) {
+  try {
+    const res = await request(`${url}/${id}`, { method: "DELETE" });
+    options.onSuccess?.(res);
+    return res;
+  } catch (err) {
+    options.onError?.(err);
+    throw err;
+  }
+}

package/src/http.js

@@ -1,35 +1,44 @@
 import { config } from "./config";
+import { normalizeResponse } from "./normalizeResponse";
 
 export async function request(url, options = {}) {
+  const method = (options.method || "GET").toUpperCase();
+
   const headers = {
     "Content-Type": "application/json",
     ...(options.headers || {}),
   };
 
-  // 🔐 token optional
   if (config.getToken) {
     const token = config.getToken();
-    if (token) {
-      headers.Authorization = `Bearer ${token}`;
-    }
+    if (token) headers.Authorization = `Bearer ${token}`;
   }
 
   const res = await fetch(config.baseUrl + url, {
     ...options,
+    method,
     headers,
   });
 
-  // 🟢 body safe parse
-  const data = await res.json().catch(() => ({}));
+  const json = await res.json().catch(() => ({}));
 
-  // 🔴 IMPORTANT FIX
   if (!res.ok) {
     throw {
       status: res.status,
-      message: data.message || "Something went wrong",
-      data,
+      message: json.message || "Something went wrong",
+      data: json,
     };
   }
+  // 🧠 ONLY normalize for GET
+  if (method === "GET") {
+    try {
+      return normalizeResponse(json);
+    } catch (e) {
+      console.error("Normalize failed", json);
+      return [];
+    }
+  }
 
-  return data;
+  // POST / PUT / DELETE → raw
+  return json;
 }

package/src/index.js

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

package/src/normalizeResponse.js

@@ -0,0 +1,58 @@
+function isPlainObject(obj) {
+  return Object.prototype.toString.call(obj) === "[object Object]";
+}
+
+function isDataArray(arr) {
+  if (!Array.isArray(arr)) return false;
+  if (arr.length === 0) return false; // ⚠️ empty ignore
+
+  const first = arr[0];
+
+  // primitive array reject
+  if (!isPlainObject(first)) return false;
+
+  // strong CRUD hint
+  if ("id" in first || "_id" in first) return true;
+
+  // fallback: object array
+  return true;
+}
+
+export function normalizeResponse(input) {
+  // 1️⃣ Direct array
+  if (Array.isArray(input)) return input;
+
+  if (!isPlainObject(input)) return [];
+
+  const found = [];
+
+  function scan(obj, depth = 0) {
+    if (depth > 5) return; // 🔒 infinite loop protection
+
+    for (const value of Object.values(obj)) {
+      if (Array.isArray(value) && isDataArray(value)) {
+        found.push(value);
+      } else if (isPlainObject(value)) {
+        scan(value, depth + 1);
+      }
+    }
+  }
+
+  scan(input);
+
+  // 2️⃣ One clear candidate
+  if (found.length === 1) return found[0];
+
+  // 3️⃣ Multiple → biggest meaningful
+  if (found.length > 1) {
+    return found.sort((a, b) => b.length - a.length)[0];
+  }
+
+  // 4️⃣ Single object (GET by id)
+  if ("id" in input || "_id" in input) {
+    return [input];
+  }
+
+  // 5️⃣ Fallback
+  return [];
+}

package/src/notify.js

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

package/src/store.js

@@ -1,12 +1,12 @@
 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,
+      fetched: false,      
       subscribers: new Set(),
     });
   }

package/src/useCrud.js

@@ -6,34 +6,41 @@ export function useCrud(url) {
   const entry = getEntry(url);
   const [, force] = useState(0);
 
+  const refetch = () => {
+    if (entry.loading) return;
+
+    entry.loading = true;
+    entry.subscribers.forEach((fn) => fn());
+
+    request(url)
+      .then((data) => {
+        entry.data = data;
+        entry.error = null;
+      })
+      .catch(() => {
+        entry.error = "Failed";
+      })
+      .finally(() => {
+        entry.loading = false;
+        entry.subscribers.forEach((fn) => fn());
+      });
+  };
+
   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());
-        });
+    if (entry.data.length === 0 && !entry.loading) {
+      refetch(); // 🔥 initial fetch
     }
 
     return () => entry.subscribers.delete(rerender);
   }, [url]);
 
-  // 🔑 IMPORTANT: return new reference
   return {
     data: entry.data,
     loading: entry.loading,
     error: entry.error,
+    refetch, // ✅ IMPORTANT
   };
 }