septor-store-react 0.0.2

package/README.MD

@@ -0,0 +1,327 @@
+
+
+### Add Quick Summary Table
+
+| Feature                                   | Description                                  |
+|-------------------------------------------|----------------------------------------------|
+| API Deduplication                         | Prevents duplicate in-flight API calls       |
+| State Sync                                | Dynamically generates Pinia state per API    |
+| Caching                                   | SessionStorage support                       |
+| Pagination Helpers                        | Stubbed pagination extractors                |
+| Post + Submit Support                     | Easily manage POST data and track responses  |
+| Flexible Callbacks                        | Use custom callbacks on state update         |
+| Loading & Error States                    | Built-in support for loading/errors          |
+
+Key Features (Detailed)
+
+Automatic API Call Queue Management
+Prevents multiple simultaneous calls to the same endpoint by tracking ongoing requests.
+
+Session Storage Caching
+Optionally caches API responses for faster retrieval and offline resilience.
+
+Dynamic State Generation
+Automatically creates and manages state slices based on API response keys.
+
+Paginated Data Handling
+Includes helper methods to extract page numbers and manage paginated API responses.
+
+State Reload and Refresh Controls
+Supports forced reloads with configurable delays to prevent rapid repeat requests.
+
+Flexible Callback Integration
+Allows injecting custom callbacks for state updates.
+
+Error Handling and Logging
+Centralizes error capture and logs API issues for easier debugging.
+
+Loading State Management
+Tracks and exposes loading status for UI feedback during asynchronous operations.
+
+Generic Data Validation
+Utility methods for validating object/array length and type.
+
+Built-in Sleep/Delay Utility
+Useful for throttling or debouncing API requests.
+
+Fast, cache-friendly state access
+
+Lightweight reactivity
+
+Data-ready views
+
+Seamless session recovery
+---
+
+
+| Option        | Description                          |
+| ------------- | ------------------------------------ |
+| `stateKey`    | Where data is stored in global state |
+| `req`         | Axios request configuration          |
+| `reload`      | Force API reload                     |
+| `time`        | Delay before reload (seconds)        |
+| `mStore.mUse` | Enable sessionStorage caching        |
+
+
+stateGeneratorApi({
+  stateKey: "orders",
+  req: { url: "/orders" },
+  mStore: { mUse: true },
+});
+
+Data persists after refresh
+ Faster loading
+ Optional per request
+
+
+
+Access Store in Other Files
+```
+import usePomZStore from "septor-store-react";
+
+const store = usePomZStore();
+
+// Read
+console.log(store.orders);
+
+// Write
+store.YourGlobalState = "I have new data";
+```
+
+### can be ignored
+
+```bash
+setBearerToken({token:hellothere}); set Bearer token object 
+getBearerToken(); get Bearer token object
+*❌ These will now throw errors: *
+setBearerToken(null);
+setBearerToken("string");
+setBearerToken(123);
+setBearerToken(["array"]);
+
+*✅ These will now :*
+setBearerToken({ token: "abc123" });
+// Or with additional props
+setBearerToken({ token: "abc123", expiresIn: 3600 });
+```
+
+ Installation
+npm install zustand axios
+
+📁 Usage
+Import the store
+import usePomZStore from "septor-store-react";
+
+🧠 Basic Example
+import { useEffect } from "react";
+import usePomZStore from "septor-store-react";
+// stateKey: remember this should be an id
+
+export default function Users() {
+    
+  const { stateGeneratorApi, loading } = usePomZStore();
+
+  useEffect(() => {
+    stateGeneratorApi({
+      stateKey: "users",
+      req: {
+        url: "/users",
+        method: "GET",
+        ...
+      },
+    });
+  }, []);
+
+  if (loading) return <p>Loading...</p>;
+
+  return <p>Users loaded</p>;
+}
+
+🧩 Store State
+Name	Description
+loading	Global loading flag
+stateValue	Object holding all stored data
+checkQueriesInQue	Tracks active API requests
+isThereAnyDataChangeInAform	Tracks form/data changes
+🛠 Available Functions
+setStateValue(key, value)
+
+Store any value globally.
+
+setStateValue("profile", userData);
+
+getStateItem(key)
+
+Read stored data.
+
+const users = getStateItem("users");
+
+sleep(ms)
+
+Delay execution.
+
+await sleep(1000); // wait 1 second
+
+validateLength(obj)
+
+Check if data exists.
+
+validateLength([]); // 0
+validateLength({ a: 1 }); // 1
+import usePomZStore from "septor-store-react";
+  const { stateGeneratorApi } = usePomZStore();
+
+🌐 API Handling
+stateGeneratorApi(config, onData)
+
+This is the main function you’ll use to fetch API data.
+
+stateGeneratorApi(
+  {
+    stateKey: "products",
+    req: {
+      url: "/products",
+      method: "GET",
+    },
+    reload: false,
+    time: 0,
+    mStore: { mUse: true },
+  },
+  (data) => {
+    console.log("Received data:", data);
+  }
+);
+
+Configuration Options
+Option	Description
+stateKey	Where data is stored
+req	Axios request config
+reload	Force API reload
+time	Delay before reload (seconds)
+mStore.mUse	Enable sessionStorage
+💾 Session Storage Cache
+
+Enable caching like this:
+
+stateGeneratorApi({
+  stateKey: "orders", 
+  req: { url: "/orders" },
+  mStore: { mUse: true },
+});
+
+
+let use the state in other file 
+import usePomZStore from "septor-store-react";
+  const  store = usePomZStore();
+  store.orders
+
+
+ set the new state in the  store
+  store.YourGlobalState="I have  new data "
+
+
+let use the state in other file 
+import usePomZStore from "septor-store-react";
+  const  store = usePomZStore();
+  console.log(store.YourGlobalState)
+
+
+
+✔ Data persists after refresh
+✔ Faster loading
+✔ Optional per request
+
+🚫 Duplicate API Protection
+
+If the same API request is already running, it won’t run again.
+
+callApiData("users", "GET_USERS", { url: "/users" });
+
+### Team Rules
+- Do not call axios directly in components
+- Use `stateGeneratorApi` for all API calls
+- Use `STORE_KEYS` constants
+- Never mutate state directly
+
+
+This prevents:
+
+Double API calls
+
+Race conditions
+
+Wasted network requests
+
+🔔 Track Data Changes
+isThereAnyDataChangeInAform
+
+
+Useful for:
+
+Form dirty checks
+
+Save warnings
+
+Conditional reloads
+
+⚠️ Important Notes
+
+Axios instance is imported internally
+
+Designed for browser apps (uses sessionStorage)
+
+loading is global (not per request)
+
+TypeScript typings are recommended for large apps
+
+✅ Best Use Cases
+
+Admin dashboards
+
+Data-heavy React apps
+
+Forms with shared state
+
+Apps replacing Redux with simpler logic
+
+🏁 Summary
+
+PomZStore gives you:
+
+Global state
+
+Safe API calls
+
+Smart caching
+
+Minimal setup
+
+Simple store. Real-world features. Zero Redux boilerplate.
+
+Final Verdict
+This structure gives you:
+✔ Clean ownership
+✔ Easy reviews
+✔ Safe refactors
+✔ Scalable collaboration
+
+Simple enough for juniors. Powerful enough for seniors.# septor-store-react
+
+Team Rules
+
+Do not call Axios directly in components
+
+Use stateGeneratorApi for all API calls
+
+Use constants for stateKey
+
+Never mutate state directly
+### Note
+
+- This package is designed with both junior and senior developers in mind, making state management and API handling effortless and reliable. By intelligently preventing unnecessary and duplicate API calls, it optimizes your app’s performance and reduces network overhead — a huge win for user experience and resource management.
+It empowers your application with dynamic, flexible state generation and smart caching, so your data is always fresh yet efficiently retrieved. The built-in loading states and error handling simplify complex async workflows, letting you focus more on building features rather than wrestling with data consistency.
+Whether you're building a small project or scaling a large application, septor-store offers a clean, extensible, and maintainable approach to state management that saves you time, prevents bugs, and keeps your codebase organized.
+
+
+you Can use septor-store documentation
+``https://www.npmjs.com/package/septor-store?activeTab=readme``