septor-store 0.0.1

package/README.md

@@ -0,0 +1,265 @@
+# Vue 3 + TypeScript + Vite
+
+# septor-store
+
+Description (Full)
+septor-store is a structured and scalable state management solution built on top of Pinia for Vue 3. It embraces the Plain Old Module (POM) pattern to simplify how developers—junior or senior—write, organize, and scale their application state. Whether you're just starting out or architecting large Vue applications, this tool helps you keep your stores clean, predictable, and easy to maintain.
+
+### Features
+
+### 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          |
+
+- Automatic API Call Queue Management Prevents multiple simultaneous calls to the same endpoint by tracking ongoing requests.
+- Session Storage Caching Support Optionally caches API responses in sessionStorage for faster retrieval and offline resilience.
+- Dynamic State Generation Creates and manages state slices dynamically based on API response keys, supporting scalable state organization.
+- Paginated Data Handling Includes helper methods to extract page numbers from URLs and manage paginated API responses (stubbed but     extensible).
+- State Reload and Refresh Controls            Supports forced reload of API data with configurable delay timers to prevent rapid repeat requests.
+- Flexible Callback Integration Allows injection of custom callback functions to extend or modify store behavior after state updates.
+- Error Handling and Logging Centralizes error capturing and logs API call issues for easier debugging and maintenance.
+- Loading State Management Automatically tracks and exposes loading status for UI feedback during asynchronous operations.
+- Generic Data Validation Includes utility methods to validate object/array length and type, improving robustness.
+- Built-in Sleep/Delay Utility Supports asynchronous delay for throttling or debouncing API requests.
+- Fast, cache-friendly state access
+- Lightweight reactivity
+- Data-ready views
+- Seamless session recovery
+
+---
+
+### Features (comming Soon)
+
+**Here are some possible future features to consider adding and highlighting:**
+
+- Optimistic UI Updates to immediately reflect user changes before API confirmation.
+- Automatic Retry Mechanism for failed API calls with configurable backoff.
+- Global State Reset and Clear Functions for user logout or data purge scenarios.
+- Integration with Vue Devtools for enhanced debugging.
+- TypeScript Support fully typed throughout for safer development.
+- Support for Different Storage Backends like localStorage, IndexedDB, or custom persistence.
+- Reduces server load and ensures consistent state by ignoring duplicate in-flight requests.
+
+---
+
+### 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.
+
+---
+
+### 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
+
+```bash
+npm install septor-store
+
+# septor-store
+```
+
+### Usage **EXAMPLE 1**
+
+.env file
+
+variable
+
+ VITE_BACKEND_URL=<http://127.0.0.1:8000/api>
+always  api will come like this
+
+## Step 1
+
+<http://127.0.0.1:8000/api/and-your-endpoint>
+
+```bash
+// main.ts
+import { createApp } from 'vue';
+import { createPinia } from 'pinia';
+import App from './App.vue';
+const app = createApp(App);
+const pinia = createPinia();
+app.use(pinia);
+```
+
+## Step 2
+
+```bash
+// functions.ts
+import { pomPinia,setBearerToken,getBearerToken } from "septor-store"
+
+const usePomStore = pomPinia('myCustomStoreId')|| pomPinia();
+    const pomStore = usePomStore();
+    // Example: Call API and store data
+    const fetchData = async () => {
+      const data = await pomStore.stateGenaratorApi({
+        reload: true,// if false ,Once the data is colleted  never call again  And if true   call the data in all stuation
+        StateStore: 'users',
+        reqs: { url: '/api/users', method: 'get',data:{} }, //data:{sex:male} is not required
+        time: 5,// if the state not empty  time taken to recall again the api
+      });
+      console.log('Fetched data:', data);
+    };
+    return {fetchData};
+  }
+```
+
+## Step 3
+
+```bash
+componets.vue
+<script>
+import {onMounted} from 'vue'
+import { pomPinia,setBearerToken,getBearerToken } from "septor-store"
+
+const usePomStore = pomPinia('myCustomStoreId')|| pomPinia();
+import fetchData from './functions.ts'
+onMounted(()=>{
+    fetchData()
+})
+</script>
+  <template>
+  <div>
+    <!-- all the users  result  bellow -->
+    <h1> {{ fetchData.users }}</h1>  
+  </div>
+</template>
+```
+
+### Usage **EXAMPLE 2**
+
+```bash
+# mUse avoid using this  while posting data 
+<script setup>
+import { onMounted, ref } from 'vue'
+import { pomPinia,setBearerToken,getBearerToken } from "septor-store"
+
+const pomStore = pomPinia('user-post-demo')
+// Create your POM store instance 😇 
+
+// Reactive reference for user list
+const users = ref([])
+
+onMounted(async () => {
+  await pomStore.stateGenaratorApi({
+    StateStore: 'users',
+    reqs: { url: '/api/users', method: 'get', },
+    # mStore: { mUse: true },
+  })
+
+  // Fetch the result from the state
+  users.value = pomStore.users?.payload || []
+})
+</script>
+
+<template>
+  <div>
+    <h2 class="text-xl font-bold mb-4">👥 User List</h2>
+    <div v-if="pomStore.Loading" class="text-blue-500">Loading users...</div>
+    <ul v-else>
+      <li v-for="user in users" :key="user.id" class="mb-2">
+        {{ user.name }} - {{ user.email }}
+      </li>
+    </ul>
+  </div>
+</template>
+
+<style scoped>
+ul {
+  list-style-type: none;
+  padding: 0;
+}
+</style>
+
+
+~~~
+### Usage **EXAMPLE 3**  data quick access 😃
+
+```bash
+store.stateGenaratorApi(
+  {
+    StateStore: 'users',
+    reqs: { url: '/api/users', method: 'get' },
+    // mStore: { mUse: true }, //  mStore: { mUse: true } is not required
+  },
+  (existingData) => {
+    console.log('💡 Instant access to cached/previous data:', existingData)
+    
+    if (existingData?.length) {
+      renderUsers(existingData)
+    }
+  }
+)
+
+```
+
+### Usage **EXAMPLE 3**  Posting data 🤭
+
+``` bash
+<template>
+  <div>
+    <h2>Add User</h2>
+    <form @submit.prevent="handleSubmit">
+      <input v-model="user.name" placeholder="Name" required />
+      <input v-model="user.email" placeholder="Email" required />
+      <button :disabled="store.Loading">Submit</button>
+    </form>
+
+    <div v-if="store.Loading">Loading...</div>
+    <div v-if="result">Success: {{ result.message }}</div>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { pomPinia,setBearerToken,getBearerToken } from "septor-store"
+
+const store = pomPinia('user-post-demo')
+const user = ref({ name: '', email: '' })
+const result = ref(null)
+
+const handleSubmit = async () => {
+  const config = {
+    StateStore: 'createUserResult',
+    reqs: {
+      url: '/api/users', // your POST endpoint
+      method: 'post',
+      data: user.value,
+    },
+    // mStore: { mUse: false },  can be removed 
+    reload: true,
+  }
+
+  const res = await store.stateGenaratorApi(config, (oldData) => {
+    console.log('Previous post result if any:', oldData)
+  })
+
+  result.value = res
+}
+</script>
+
+```

package/dist/index.cjs

@@ -0,0 +1,308 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.js
+var index_exports = {};
+__export(index_exports, {
+  generateParams: () => generateParams,
+  getBearerToken: () => getBearerToken,
+  pomPinia: () => createPomStore,
+  setBearerToken: () => setBearerToken,
+  useFetch: () => useFetch
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/StoreManager/pomStateManagement.js
+var import_pinia = require("pinia");
+
+// src/utils/custom-axios.js
+var import_axios = __toESM(require("axios"), 1);
+
+// src/utils/abortHandler.js
+var AbortHandler = {
+  abortController: new AbortController(),
+  abortHttpRequests() {
+    this.abortController.abort();
+    this.abortController = new AbortController();
+    custom_axios_default.defaults.signal = this.abortController.signal;
+  }
+};
+var abortHandler_default = AbortHandler;
+
+// src/utils/custom-axios.js
+var import_meta = {};
+var baseURL = typeof import_meta !== "undefined" ? import_meta.env.VITE_BACKEND_URL ?? "" : void 0;
+var customAxios = import_axios.default.create({
+  baseURL,
+  signal: abortHandler_default.abortController.signal
+  // Signal that is assiciated with any request to be made with this axios instance
+});
+var requestHandler = (request) => {
+  const tokenData = getBearerToken();
+  const token = (tokenData == null ? void 0 : tokenData.token) ?? null;
+  const expiresIn = (tokenData == null ? void 0 : tokenData.expiresIn) ?? null;
+  if (expiresIn) {
+    const timestamp = (tokenData == null ? void 0 : tokenData.timestamp) ?? null;
+    const now = Date.now();
+    if (expiresIn && now - timestamp > expiresIn * 1e3) {
+      console.warn("Token has expired.");
+      localStorage.removeItem("logginToken");
+      return null;
+    }
+  }
+  if (token) {
+    request.headers.Authorization = `Bearer ${token}`;
+  }
+  if (request.data instanceof FormData) {
+    const formData = request.data;
+    request.data = formData;
+  } else if (request.data) {
+    request.data = { ...request.data ?? {} };
+  }
+  return request;
+};
+customAxios.interceptors.response.use(
+  (response) => response,
+  // Resolve response as is
+  (error) => {
+    var _a;
+    console.log("Error.....", error);
+    if (((_a = error.response) == null ? void 0 : _a.status) === 401) {
+    }
+    return Promise.reject(error);
+  }
+);
+customAxios.interceptors.request.use(
+  requestHandler,
+  (error) => Promise.reject(error)
+);
+var custom_axios_default = customAxios;
+
+// src/utils/useFetch.js
+var useFetch = async ({ url, method, data }) => {
+  let _data = data ?? {};
+  try {
+    let response = null;
+    const uniformMethod = method.toLowerCase();
+    if (uniformMethod === "get") {
+      const params = generateParams(_data ?? {});
+      response = await custom_axios_default.get(`${url}${params}`);
+    } else {
+      response = await custom_axios_default.post(url, _data);
+    }
+    return (response == null ? void 0 : response.data) ?? { Empty: "Empty" };
+  } catch (err) {
+    console.error(err);
+    return { success: false, error: err };
+  }
+};
+var generateParams = (params = {}) => {
+  let data = "?";
+  for (let key in params) {
+    if (Object.hasOwnProperty.call(params, key)) {
+      if (params[key]) {
+        if (Array.isArray(params[key])) {
+          const elements = params[key];
+          for (const ele of elements) {
+            data += `${key}[]=${ele}&`;
+          }
+        } else {
+          data += `${key}=${params[key]}&`;
+        }
+      }
+    }
+  }
+  return data.slice(0, -1);
+};
+function setBearerToken(name = { token: null }) {
+  if (typeof name !== "object" || name === null || Array.isArray(name))
+    throw new TypeError("setBearerToken expects an object {token} with a 'token' property.");
+  const tokenObj = { token: null, ...name, timestamp: Date.now() };
+  localStorage.setItem("logginToken", JSON.stringify(tokenObj));
+}
+function getBearerToken() {
+  const token = localStorage.getItem("logginToken");
+  try {
+    return token ? JSON.parse(token) : null;
+  } catch (e) {
+    console.error("Invalid token format in localStorage:", e);
+    return null;
+  }
+}
+
+// src/StoreManager/pomStateManagement.js
+function createPomStore(piniaStore = "7286204094", callBack = null) {
+  const storeId = "POM" + piniaStore;
+  const piniaData = (0, import_pinia.defineStore)(storeId, {
+    state: () => {
+      const StateObjectsContainer = {
+        CheckQueriesInQue: {},
+        StateValue: {},
+        Loading: true,
+        isThereAnyDataChangeInAform: false
+      };
+      return StateObjectsContainer;
+    },
+    getters: {
+      stateItems: (state) => (TagetState) => {
+        return state[TagetState] = state[TagetState];
+      }
+      // store.getStateItem(key1) usage to ge the ge
+      // getStateItem: (state) => (stateKey=nu) => state[stateKey],
+    },
+    actions: {
+      validateObjectLength(object) {
+        if (Array.isArray(object)) {
+          return object.length;
+        } else if (typeof object == "object") {
+          const lng = Object.keys(object);
+          return lng.length;
+        }
+        return 0;
+      },
+      pageNumber(pageUrl) {
+        const inputString = pageUrl;
+        const regex = /\?(page)+=\d+/;
+        const match = regex.exec(inputString);
+        if (match) {
+          const matchedPattern = match[0];
+          const dataBack = matchedPattern.split("?page=").join().replace(/[^\d]/, "");
+          return dataBack;
+        } else return "1";
+      },
+      sleep(timer) {
+        return new Promise((r) => setTimeout(r, timer));
+      },
+      async CallApiData(StateStore, callApi, dataParams, pagnated, mStore = {}) {
+        if (!this.CheckQueriesInQue[callApi]) {
+          this.CheckQueriesInQue[callApi] = callApi;
+          let [res] = await Promise.all([
+            useFetch(dataParams)
+          ]);
+          if (res) {
+            this[StateStore] = res;
+            if (mStore == null ? void 0 : mStore.mUse) {
+              const checkType = typeof res === "object" ? JSON.stringify(res) : res;
+              sessionStorage.setItem(StateStore, JSON.stringify(checkType));
+            }
+            delete this.CheckQueriesInQue[callApi];
+          } else {
+            delete this.CheckQueriesInQue[callApi];
+            console.error(res);
+          }
+          this.Loading = false;
+          return res;
+        }
+        this.Loading = false;
+        return this[StateStore] ?? [];
+      },
+      async parseData(dataResponseName = "xxx", mStore = { mUse: false, reset: false }) {
+        try {
+          if (mStore == null ? void 0 : mStore.reset) {
+            sessionStorage.removeItem(dataResponseName);
+          }
+          if (mStore == null ? void 0 : mStore.mUse) {
+            const thisData = JSON.parse(
+              JSON.parse(sessionStorage.getItem(dataResponseName) || {})
+            );
+            return thisData;
+          }
+        } catch (error) {
+        }
+        return this[dataResponseName];
+      },
+      async stateGenaratorApi(dd = { reload: true, StateStore: "", reqs: {}, time: 5, pagnated: false, mStore: { mUse: 0 } }, fasterDataCollection = null) {
+        this.Loading = true;
+        const { reload, StateStore, reqs, time, pagnated, mStore } = dd;
+        const callApi = JSON.stringify(reqs);
+        const StateVariable = await this.parseData(StateStore, mStore);
+        this[StateStore] = StateVariable ?? [];
+        if (this.StateValue[StateStore]) {
+          this.StateValue[StateStore] = false;
+          this[StateStore] = false;
+        }
+        if (this.CheckQueriesInQue[callApi]) {
+          console.warn(`************************************* dont call this api again ${reqs["url"]} \u{1F6E9}\uFE0F *************************************`, reqs);
+          return;
+        }
+        try {
+          const counters = this.validateObjectLength(StateVariable);
+          if (typeof fasterDataCollection == "function")
+            fasterDataCollection(StateVariable);
+          if (counters > 0) {
+            if (reload) {
+              const delay = await this.sleep(1e3 * time);
+              return await this.CallApiData(
+                StateStore,
+                callApi,
+                reqs,
+                pagnated,
+                mStore
+              );
+            }
+            this.Loading = false;
+            return this[StateStore];
+          } else {
+            this.Loading = true;
+          }
+          return await this.CallApiData(
+            StateStore,
+            callApi,
+            reqs,
+            pagnated,
+            mStore
+          );
+        } catch (error) {
+          if (this.CheckQueriesInQue[callApi])
+            delete this.CheckQueriesInQue[callApi];
+        }
+      },
+      Creator() {
+        if (typeof callBack === "function") {
+          return callBack(this);
+        }
+      },
+      DriveManual() {
+        return function() {
+          return this;
+        };
+      },
+      pagenatedData() {
+      }
+    }
+  });
+  return piniaData();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  generateParams,
+  getBearerToken,
+  pomPinia,
+  setBearerToken,
+  useFetch
+});