@react-pakistan/util-functions 1.25.2 → 1.25.4

package/api/stellar-solutions/currency/cache.d.ts

@@ -24,13 +24,18 @@ export declare const getCachedCurrenciesSync: () => {
  * - If currencies exist but are older than 1 week, fetch fresh data and update cache
  * - If currencies don't exist in cache, fetch from API and cache them
  *
+ * @param searchQuery - Optional search query to filter currencies
+ * @param pageLimit - Number of currencies to fetch (default: 100)
  * @returns Promise<{count:number, items: CurrencyBE[]}> - Paged currencies
  *
  * @example
  * const currencies = await getCachedCurrencies();
  * console.log(currencies.items[0].label);
+ *
+ * // With search
+ * const filtered = await getCachedCurrencies('USD');
  */
-export declare const getCachedCurrencies: () => Promise<{
+export declare const getCachedCurrencies: (searchQuery?: string, pageLimit?: number) => Promise<{
     count: number;
     items: CurrencyBE[];
 }>;

package/api/stellar-solutions/currency/cache.js

@@ -35,6 +35,15 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
         if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
     }
 };
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isCurrenciesCacheStale = exports.preloadCurrencies = exports.invalidateCurrenciesCache = exports.getCachedCurrencyByCode = exports.getCachedCurrencyById = exports.getCachedCurrencies = exports.getCachedCurrenciesSync = void 0;
 var constants_1 = require("../constants");
@@ -88,56 +97,86 @@ exports.getCachedCurrenciesSync = getCachedCurrenciesSync;
  * - If currencies exist but are older than 1 week, fetch fresh data and update cache
  * - If currencies don't exist in cache, fetch from API and cache them
  *
+ * @param searchQuery - Optional search query to filter currencies
+ * @param pageLimit - Number of currencies to fetch (default: 100)
  * @returns Promise<{count:number, items: CurrencyBE[]}> - Paged currencies
  *
  * @example
  * const currencies = await getCachedCurrencies();
  * console.log(currencies.items[0].label);
+ *
+ * // With search
+ * const filtered = await getCachedCurrencies('USD');
  */
-var getCachedCurrencies = function () { return __awaiter(void 0, void 0, void 0, function () {
-    var cachedData, currentTime, cachedTime, ageInMs, response, updatedCache, error_1;
-    var _a;
-    return __generator(this, function (_b) {
-        switch (_b.label) {
-            case 0:
-                _b.trys.push([0, 2, , 3]);
-                cachedData = (0, get_storage_value_1.getStorageValue)(type_1.LS_KEYS.CURRENCIES);
-                currentTime = new Date().getTime();
-                // Check if cached data exists and is still fresh
-                if (cachedData) {
-                    cachedTime = new Date(cachedData.cachedAt).getTime();
-                    ageInMs = currentTime - cachedTime;
-                    // If cached data is less than 1 week old, return it
-                    if (ageInMs < constants_1.ONE_WEEK_IN_MS) {
-                        return [2 /*return*/, {
-                                count: cachedData.currencies.length,
-                                items: cachedData.currencies,
-                            }];
+var getCachedCurrencies = function (searchQuery_1) {
+    var args_1 = [];
+    for (var _i = 1; _i < arguments.length; _i++) {
+        args_1[_i - 1] = arguments[_i];
+    }
+    return __awaiter(void 0, __spreadArray([searchQuery_1], args_1, true), void 0, function (searchQuery, pageLimit) {
+        var response_1, cachedData, currentTime, cachedTime, ageInMs, response, updatedCache, error_1;
+        var _a;
+        if (pageLimit === void 0) { pageLimit = 100; }
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    _b.trys.push([0, 4, , 5]);
+                    if (!(searchQuery && searchQuery.trim())) return [3 /*break*/, 2];
+                    return [4 /*yield*/, (0, fetch_data_1.fetchData)({
+                            url: constants_1.API_ROUTES.CURRENCIES,
+                            body: JSON.stringify({
+                                searchQuery: searchQuery,
+                                pageLimit: pageLimit,
+                                currentPage: 1,
+                            }),
+                            method: api_methods_1.API_METHODS.POST,
+                        })];
+                case 1:
+                    response_1 = _b.sent();
+                    return [2 /*return*/, (response_1 === null || response_1 === void 0 ? void 0 : response_1.data) || { count: 0, items: [] }];
+                case 2:
+                    cachedData = (0, get_storage_value_1.getStorageValue)(type_1.LS_KEYS.CURRENCIES);
+                    currentTime = new Date().getTime();
+                    // Check if cached data exists and is still fresh
+                    if (cachedData) {
+                        cachedTime = new Date(cachedData.cachedAt).getTime();
+                        ageInMs = currentTime - cachedTime;
+                        // If cached data is less than 1 week old, return it
+                        if (ageInMs < constants_1.ONE_WEEK_IN_MS) {
+                            return [2 /*return*/, {
+                                    count: cachedData.currencies.length,
+                                    items: cachedData.currencies,
+                                }];
+                        }
                     }
-                }
-                return [4 /*yield*/, (0, fetch_data_1.fetchData)({
-                        url: constants_1.API_ROUTES.CURRENCIES,
-                        method: api_methods_1.API_METHODS.GET,
-                    })];
-            case 1:
-                response = _b.sent();
-                if ((_a = response === null || response === void 0 ? void 0 : response.data) === null || _a === void 0 ? void 0 : _a.items) {
-                    updatedCache = {
-                        currencies: response.data.items,
-                        cachedAt: new Date().toISOString(),
-                    };
-                    (0, set_storage_value_1.setStorageValue)(type_1.LS_KEYS.CURRENCIES, updatedCache);
-                    return [2 /*return*/, response.data];
-                }
-                return [2 /*return*/, { count: 0, items: [] }];
-            case 2:
-                error_1 = _b.sent();
-                console.error('Error fetching currencies:', error_1);
-                return [2 /*return*/, { count: 0, items: [] }];
-            case 3: return [2 /*return*/];
-        }
+                    return [4 /*yield*/, (0, fetch_data_1.fetchData)({
+                            url: constants_1.API_ROUTES.CURRENCIES,
+                            body: JSON.stringify({
+                                pageLimit: pageLimit,
+                                currentPage: 1,
+                            }),
+                            method: api_methods_1.API_METHODS.POST,
+                        })];
+                case 3:
+                    response = _b.sent();
+                    if ((_a = response === null || response === void 0 ? void 0 : response.data) === null || _a === void 0 ? void 0 : _a.items) {
+                        updatedCache = {
+                            currencies: response.data.items,
+                            cachedAt: new Date().toISOString(),
+                        };
+                        (0, set_storage_value_1.setStorageValue)(type_1.LS_KEYS.CURRENCIES, updatedCache);
+                        return [2 /*return*/, response.data];
+                    }
+                    return [2 /*return*/, { count: 0, items: [] }];
+                case 4:
+                    error_1 = _b.sent();
+                    console.error('Error fetching currencies:', error_1);
+                    return [2 /*return*/, { count: 0, items: [] }];
+                case 5: return [2 /*return*/];
+            }
+        });
     });
-}); };
+};
 exports.getCachedCurrencies = getCachedCurrencies;
 /**
  * Utility function to get a specific currency by ID from cache

package/constants/api-methods.d.ts

@@ -1,7 +1,11 @@
 export declare enum API_METHODS {
+    CONNECT = "CONNECT",
     DELETE = "DELETE",
     GET = "GET",
+    HEAD = "HEAD",
+    OPTIONS = "OPTIONS",
     PATCH = "PATCH",
     POST = "POST",
-    UPDATE = "UPDATE"
+    PUT = "PUT",
+    TRACE = "TRACE"
 }

package/constants/api-methods.js

@@ -3,9 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.API_METHODS = void 0;
 var API_METHODS;
 (function (API_METHODS) {
+    API_METHODS["CONNECT"] = "CONNECT";
     API_METHODS["DELETE"] = "DELETE";
     API_METHODS["GET"] = "GET";
+    API_METHODS["HEAD"] = "HEAD";
+    API_METHODS["OPTIONS"] = "OPTIONS";
     API_METHODS["PATCH"] = "PATCH";
     API_METHODS["POST"] = "POST";
-    API_METHODS["UPDATE"] = "UPDATE";
+    API_METHODS["PUT"] = "PUT";
+    API_METHODS["TRACE"] = "TRACE";
 })(API_METHODS || (exports.API_METHODS = API_METHODS = {}));

package/hooks/use-fetch.d.ts

@@ -7,6 +7,7 @@ export interface FetchResult {
 export interface FetchConfig extends RequestInit {
     autoFetch?: boolean;
     callback?: (result: FetchResult) => void;
+    params?: Record<string, any>;
 }
 export interface Return {
     apiResult: API_RESULT | undefined;

package/hooks/use-fetch.js

@@ -93,34 +93,67 @@ var useFetch = function (url, config, deps) {
         };
     }, []);
     var fetchNow = (0, react_1.useCallback)(function (overrideUrl, overrideOptions) { return __awaiter(void 0, void 0, void 0, function () {
-        var finalUrl, finalOptions, controller, response, parsed, _a, err, err_1;
-        return __generator(this, function (_b) {
-            switch (_b.label) {
+        var finalUrl, _a, defaultParams, restDefaultOptions, _b, overrideParams, restOverrideOptions, mergedParams, finalOptions, method, hashIndex, hash, basePart, searchIndex, pathname, existingSearch, searchParams_1, newSearch, controller, response, parsed, _c, err, err_1;
+        return __generator(this, function (_d) {
+            switch (_d.label) {
                 case 0:
                     finalUrl = overrideUrl || url;
-                    finalOptions = __assign(__assign(__assign({}, defaultOptions), overrideOptions), { headers: __assign(__assign({}, defaultOptions.headers), ((overrideOptions === null || overrideOptions === void 0 ? void 0 : overrideOptions.headers) || {})) });
+                    _a = defaultOptions || {}, defaultParams = _a.params, restDefaultOptions = __rest(_a, ["params"]);
+                    _b = overrideOptions || {}, overrideParams = _b.params, restOverrideOptions = __rest(_b, ["params"]);
+                    mergedParams = __assign(__assign({}, (defaultParams || {})), (overrideParams || {}));
+                    finalOptions = __assign(__assign(__assign({}, restDefaultOptions), restOverrideOptions), { headers: __assign(__assign({}, (restDefaultOptions.headers || {})), (restOverrideOptions.headers || {})) });
+                    method = (finalOptions.method || 'GET')
+                        .toString()
+                        .toUpperCase();
+                    if (method === 'GET' &&
+                        mergedParams &&
+                        Object.keys(mergedParams).length) {
+                        hashIndex = finalUrl.indexOf('#');
+                        hash = hashIndex >= 0 ? finalUrl.slice(hashIndex) : '';
+                        basePart = hashIndex >= 0 ? finalUrl.slice(0, hashIndex) : finalUrl;
+                        searchIndex = basePart.indexOf('?');
+                        pathname = searchIndex >= 0 ? basePart.slice(0, searchIndex) : basePart;
+                        existingSearch = searchIndex >= 0 ? basePart.slice(searchIndex + 1) : '';
+                        searchParams_1 = new URLSearchParams(existingSearch);
+                        Object.entries(mergedParams).forEach(function (_a) {
+                            var key = _a[0], value = _a[1];
+                            if (value == null)
+                                return;
+                            if (Array.isArray(value)) {
+                                value.forEach(function (v) { return searchParams_1.append(key, String(v)); });
+                            }
+                            else if (typeof value === 'object') {
+                                searchParams_1.append(key, JSON.stringify(value));
+                            }
+                            else {
+                                searchParams_1.append(key, String(value));
+                            }
+                        });
+                        newSearch = searchParams_1.toString();
+                        finalUrl = pathname + (newSearch ? "?".concat(newSearch) : '') + hash;
+                    }
                     setLoading(true);
                     setError(null);
                     setData(null);
                     controller = new AbortController();
                     abortControllerRef.current = controller;
                     finalOptions.signal = controller.signal;
-                    _b.label = 1;
+                    _d.label = 1;
                 case 1:
-                    _b.trys.push([1, 7, 8, 9]);
+                    _d.trys.push([1, 7, 8, 9]);
                     return [4 /*yield*/, fetch(finalUrl, finalOptions)];
                 case 2:
-                    response = _b.sent();
+                    response = _d.sent();
                     parsed = null;
-                    _b.label = 3;
+                    _d.label = 3;
                 case 3:
-                    _b.trys.push([3, 5, , 6]);
+                    _d.trys.push([3, 5, , 6]);
                     return [4 /*yield*/, response.json()];
                 case 4:
-                    parsed = _b.sent();
+                    parsed = _d.sent();
                     return [3 /*break*/, 6];
                 case 5:
-                    _a = _b.sent();
+                    _c = _d.sent();
                     // non-json or empty body
                     parsed = null;
                     return [3 /*break*/, 6];
@@ -152,7 +185,7 @@ var useFetch = function (url, config, deps) {
                     }
                     return [3 /*break*/, 9];
                 case 7:
-                    err_1 = _b.sent();
+                    err_1 = _d.sent();
                     if (isMounted.current) {
                         setError(err_1);
                         setData(null);

package/hooks/use-module-entity-v2.d.ts

@@ -0,0 +1,94 @@
+/**
+ * useModuleEntityV2
+ *
+ * Summary
+ * - A convenience hook that manages common module/entity operations: list, get-by-id,
+ *   create/update, and delete. It composes `useFetch` for HTTP calls and `useDebounce`
+ *   for debouncing search queries.
+ *
+ * Main features
+ * - List: performs a GET to `listUrl` with `listParams`. The hook listens to
+ *   `searchQuery` (debounced) and `listDeps` to re-run the list fetch.
+ * - Get by ID: performs a GET to `unitByIdUrl` with `byIdParams` and returns
+ *   `byIdFetchNow`, `byIdLoading`, and `byIdError`.
+ * - Create/Update: performs a PUT to `unitUrl` with a JSON body `updateParams`.
+ *   On successful create/update the hook triggers a coalesced list refresh.
+ * - Delete: performs a DELETE to `unitUrl` with a JSON body `deleteParams` and
+ *   triggers a coalesced list refresh when the operation succeeds.
+ * - Refresh batching: `refreshList(delay)` coalesces multiple rapid updates/deletes
+ *   using a short timeout (default 300ms) to avoid unnecessary list reloads.
+ *
+ * Parameters (object)
+ * - `byIdCallback(data)`, `byIdDeps`, `byIdParams`
+ * - `deleteCallback(data)`, `deleteDeps`, `deleteParams`
+ * - `listCallback(data)`, `listDeps`, `listParams`, `listUrl`
+ * - `searchQuery` (string) — debounced before influencing the list fetch
+ * - `unitByIdUrl`, `unitUrl`
+ * - `updateCallback(data)`, `updateDeps`, `updateParams`
+ *
+ * Return values
+ * - `byIdFetchNow(url?, config?)`, `byIdLoading`, `byIdError`
+ * - `listFetchNow(url?, config?)`, `listLoading`, `listError`
+ * - `updateFetchNow(url?, config?)`, `updateLoading`, `updateError`
+ * - `deleteFetchNow(url?, config?)`, `deleteLoading`, `deleteError`
+ *
+ * Behavior notes
+ * - All callbacks receive an object `{ data, error, status, ok }` from `useFetch`.
+ * - Callbacks are wrapped so that any errors they throw are swallowed; this
+ *   ensures the hook's refresh logic still runs reliably.
+ * - `refreshList()` calls `listFetchNow(undefined, { method: 'POST', params: listParams })`
+ *   to explicitly re-query the list endpoint with the current `listParams`.
+ * - Network calls are delegated to `useFetch`; callers can call the returned
+ *   `*FetchNow` functions directly with an override URL or config.
+ *
+ * Example
+ * const { listFetchNow, updateFetchNow } = useModuleEntityV2({
+ *   listUrl: '/items',
+ *   listParams: { page: 1 },
+ *   listCallback: (res) => console.log(res),
+ *   unitUrl: '/items',
+ *   updateCallback: () => {},
+ *   updateParams: {}
+ * });
+ */
+import { FetchConfig } from './use-fetch';
+export interface CallbackParams {
+    data: any;
+    error: any;
+    status?: number;
+    ok?: boolean;
+}
+interface Params {
+    byIdCallback: (d: CallbackParams) => void;
+    byIdDeps?: Array<any> | Array<string>;
+    byIdParams: object;
+    deleteCallback?: (d: CallbackParams) => void;
+    deleteDeps?: Array<any> | Array<string>;
+    deleteParams?: object;
+    listCallback: (d: CallbackParams) => void;
+    listDeps?: Array<any> | Array<string>;
+    listParams: object;
+    listUrl: string;
+    searchQuery: string;
+    unitByIdUrl: string;
+    unitUrl: string;
+    updateCallback: (d: CallbackParams) => void;
+    updateDeps?: Array<any> | Array<string>;
+    updateParams: object;
+}
+interface Return {
+    byIdError?: Error;
+    byIdFetchNow: (url?: string, config?: FetchConfig) => void;
+    byIdLoading: boolean;
+    deleteError?: Error;
+    deleteFetchNow?: (url?: string, config?: FetchConfig) => void;
+    deleteLoading: boolean;
+    listError?: Error;
+    listFetchNow: (url?: string, config?: FetchConfig) => void;
+    listLoading: boolean;
+    updateError?: Error;
+    updateFetchNow: (url?: string, config?: FetchConfig) => void;
+    updateLoading: boolean;
+}
+export declare const useModuleEntityV2: ({ byIdCallback, byIdDeps, byIdParams, deleteCallback, deleteDeps, deleteParams, listCallback, listDeps, listParams, listUrl, searchQuery, unitByIdUrl, unitUrl, updateCallback, updateDeps, updateParams, }: Params) => Return;
+export {};

package/hooks/use-module-entity-v2.js

@@ -0,0 +1,176 @@
+"use strict";
+/**
+ * useModuleEntityV2
+ *
+ * Summary
+ * - A convenience hook that manages common module/entity operations: list, get-by-id,
+ *   create/update, and delete. It composes `useFetch` for HTTP calls and `useDebounce`
+ *   for debouncing search queries.
+ *
+ * Main features
+ * - List: performs a GET to `listUrl` with `listParams`. The hook listens to
+ *   `searchQuery` (debounced) and `listDeps` to re-run the list fetch.
+ * - Get by ID: performs a GET to `unitByIdUrl` with `byIdParams` and returns
+ *   `byIdFetchNow`, `byIdLoading`, and `byIdError`.
+ * - Create/Update: performs a PUT to `unitUrl` with a JSON body `updateParams`.
+ *   On successful create/update the hook triggers a coalesced list refresh.
+ * - Delete: performs a DELETE to `unitUrl` with a JSON body `deleteParams` and
+ *   triggers a coalesced list refresh when the operation succeeds.
+ * - Refresh batching: `refreshList(delay)` coalesces multiple rapid updates/deletes
+ *   using a short timeout (default 300ms) to avoid unnecessary list reloads.
+ *
+ * Parameters (object)
+ * - `byIdCallback(data)`, `byIdDeps`, `byIdParams`
+ * - `deleteCallback(data)`, `deleteDeps`, `deleteParams`
+ * - `listCallback(data)`, `listDeps`, `listParams`, `listUrl`
+ * - `searchQuery` (string) — debounced before influencing the list fetch
+ * - `unitByIdUrl`, `unitUrl`
+ * - `updateCallback(data)`, `updateDeps`, `updateParams`
+ *
+ * Return values
+ * - `byIdFetchNow(url?, config?)`, `byIdLoading`, `byIdError`
+ * - `listFetchNow(url?, config?)`, `listLoading`, `listError`
+ * - `updateFetchNow(url?, config?)`, `updateLoading`, `updateError`
+ * - `deleteFetchNow(url?, config?)`, `deleteLoading`, `deleteError`
+ *
+ * Behavior notes
+ * - All callbacks receive an object `{ data, error, status, ok }` from `useFetch`.
+ * - Callbacks are wrapped so that any errors they throw are swallowed; this
+ *   ensures the hook's refresh logic still runs reliably.
+ * - `refreshList()` calls `listFetchNow(undefined, { method: 'POST', params: listParams })`
+ *   to explicitly re-query the list endpoint with the current `listParams`.
+ * - Network calls are delegated to `useFetch`; callers can call the returned
+ *   `*FetchNow` functions directly with an override URL or config.
+ *
+ * Example
+ * const { listFetchNow, updateFetchNow } = useModuleEntityV2({
+ *   listUrl: '/items',
+ *   listParams: { page: 1 },
+ *   listCallback: (res) => console.log(res),
+ *   unitUrl: '/items',
+ *   updateCallback: () => {},
+ *   updateParams: {}
+ * });
+ */
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useModuleEntityV2 = void 0;
+var react_1 = require("react");
+var constants_1 = require("../constants");
+var use_fetch_1 = require("./use-fetch");
+var use_debounce_1 = require("./use-debounce");
+var useModuleEntityV2 = function (_a) {
+    var byIdCallback = _a.byIdCallback, _b = _a.byIdDeps, byIdDeps = _b === void 0 ? [] : _b, byIdParams = _a.byIdParams, deleteCallback = _a.deleteCallback, _c = _a.deleteDeps, deleteDeps = _c === void 0 ? [] : _c, deleteParams = _a.deleteParams, listCallback = _a.listCallback, _d = _a.listDeps, listDeps = _d === void 0 ? [] : _d, listParams = _a.listParams, listUrl = _a.listUrl, searchQuery = _a.searchQuery, unitByIdUrl = _a.unitByIdUrl, unitUrl = _a.unitUrl, updateCallback = _a.updateCallback, _e = _a.updateDeps, updateDeps = _e === void 0 ? [] : _e, updateParams = _a.updateParams;
+    var debouncedQuery = (0, use_debounce_1.useDebounce)(searchQuery, 800);
+    // debounced list refresh to batch multiple updates/deletes
+    var refreshTimerRef = (0, react_1.useRef)(null);
+    (0, react_1.useEffect)(function () { return function () {
+        if (refreshTimerRef.current) {
+            globalThis.clearTimeout(refreshTimerRef.current);
+            refreshTimerRef.current = null;
+        }
+    }; }, []);
+    // list
+    var _f = (0, use_fetch_1.useFetch)(listUrl, {
+        method: constants_1.API_METHODS.GET,
+        params: listParams,
+        callback: listCallback,
+    }, __spreadArray([debouncedQuery, listParams], listDeps, true)), listError = _f.error, listFetchNow = _f.fetchNow, listLoading = _f.loading;
+    var refreshList = function (delay) {
+        if (delay === void 0) { delay = 300; }
+        if (refreshTimerRef.current) {
+            globalThis.clearTimeout(refreshTimerRef.current);
+        }
+        refreshTimerRef.current = globalThis.setTimeout(function () {
+            try {
+                // pass current list params explicitly so the fetch uses the latest values
+                listFetchNow(undefined, {
+                    method: constants_1.API_METHODS.POST,
+                    params: listParams,
+                });
+            }
+            catch (_a) {
+                // noop
+            }
+            refreshTimerRef.current = null;
+        }, delay);
+    };
+    // create / edit
+    var _g = (0, use_fetch_1.useFetch)(unitUrl, {
+        method: constants_1.API_METHODS.PUT,
+        body: JSON.stringify(updateParams),
+        callback: function (d) {
+            if (updateCallback) {
+                try {
+                    updateCallback(d);
+                }
+                catch (_a) {
+                    // swallow callback errors to ensure list refresh still runs
+                    // caller's callback is responsible for its own error handling
+                }
+            }
+            // refresh the list after update/create only when the operation succeeded
+            try {
+                if (d && d.ok) {
+                    refreshList();
+                }
+            }
+            catch (_b) {
+                // noop
+            }
+        },
+    }, __spreadArray([], updateDeps, true)), updateError = _g.error, updateLoading = _g.loading, updateFetchNow = _g.fetchNow;
+    // by id
+    var _h = (0, use_fetch_1.useFetch)(unitByIdUrl, {
+        method: constants_1.API_METHODS.GET,
+        params: byIdParams,
+        callback: byIdCallback,
+    }, __spreadArray([], byIdDeps, true)), byIdError = _h.error, byIdLoading = _h.loading, byIdFetchNow = _h.fetchNow;
+    // delete
+    var _j = (0, use_fetch_1.useFetch)(unitUrl, {
+        method: constants_1.API_METHODS.DELETE,
+        body: JSON.stringify(deleteParams),
+        callback: function (d) {
+            if (deleteCallback) {
+                try {
+                    deleteCallback(d);
+                }
+                catch (_a) {
+                    // swallow callback errors to ensure list refresh still runs
+                }
+            }
+            // refresh the list after delete only when the operation succeeded
+            try {
+                if (d && d.ok) {
+                    refreshList();
+                }
+            }
+            catch (_b) {
+                // noop
+            }
+        },
+    }, __spreadArray([], deleteDeps, true)), deleteError = _j.error, deleteLoading = _j.loading, deleteFetchNow = _j.fetchNow;
+    return {
+        byIdError: byIdError,
+        byIdFetchNow: byIdFetchNow,
+        byIdLoading: byIdLoading,
+        deleteError: deleteError,
+        deleteFetchNow: deleteFetchNow,
+        deleteLoading: deleteLoading,
+        listError: listError,
+        listFetchNow: listFetchNow,
+        listLoading: listLoading,
+        updateError: updateError,
+        updateFetchNow: updateFetchNow,
+        updateLoading: updateLoading,
+    };
+};
+exports.useModuleEntityV2 = useModuleEntityV2;

package/hooks/use-module-entity.d.ts

@@ -1,3 +1,57 @@
+/**
+ * useModuleEntity
+ *
+ * Summary
+ * - A convenience hook that manages common module/entity operations: list, get-by-id,
+ *   create/update, and delete. It composes `useFetch` for HTTP calls and `useDebounce`
+ *   for debouncing search queries.
+ *
+ * Main features
+ * - List: performs a POST to `listUrl` with a JSON body `listParams` and re-runs
+ *   when `searchQuery` (debounced) or `listDeps` change.
+ * - Get by ID: performs a POST to `unitByIdUrl` with `byIdParams` in the JSON body
+ *   and exposes `byIdFetchNow`, `byIdLoading`, and `byIdError`.
+ * - Create/Update: performs a POST to `unitUrl` with a JSON body `updateParams`.
+ *   On successful create/update the hook triggers a coalesced list refresh.
+ * - Delete: performs a DELETE to `unitUrl` with a JSON body `deleteParams` and
+ *   triggers a coalesced list refresh when the operation succeeds.
+ * - Refresh batching: `refreshList(delay)` coalesces multiple rapid updates/deletes
+ *   using a short timeout (default 300ms) to avoid unnecessary list reloads.
+ *
+ * Parameters (object)
+ * - `byIdCallback(data)`, `byIdDeps`, `byIdParams`
+ * - `deleteCallback(data)`, `deleteDeps`, `deleteParams`
+ * - `listCallback(data)`, `listDeps`, `listParams`, `listUrl`
+ * - `searchQuery` (string) — debounced before influencing the list fetch
+ * - `unitByIdUrl`, `unitUrl`
+ * - `updateCallback(data)`, `updateDeps`, `updateParams`
+ *
+ * Return values
+ * - `byIdFetchNow(url?, config?)`, `byIdLoading`, `byIdError`
+ * - `listFetchNow(url?, config?)`, `listLoading`, `listError`
+ * - `updateFetchNow(url?, config?)`, `updateLoading`, `updateError`
+ * - `deleteFetchNow(url?, config?)`, `deleteLoading`, `deleteError`
+ *
+ * Behavior notes
+ * - All requests that accept parameters send them in the JSON request body (stringified).
+ * - All callbacks receive an object `{ data, error, status, ok }` from `useFetch`.
+ * - Callbacks are wrapped so thrown errors are swallowed to ensure refresh logic
+ *   still runs reliably.
+ * - `refreshList()` calls `listFetchNow(undefined, { method: 'POST', body: JSON.stringify(listParams) })`
+ *   to explicitly re-query the list endpoint with the current `listParams`.
+ * - Network calls are delegated to `useFetch`; callers can invoke the returned
+ *   `*FetchNow` functions directly with an override URL or config.
+ *
+ * Example
+ * const { listFetchNow, updateFetchNow } = useModuleEntity({
+ *   listUrl: '/items',
+ *   listParams: { page: 1 },
+ *   listCallback: (res) => console.log(res),
+ *   unitUrl: '/items',
+ *   updateCallback: () => {},
+ *   updateParams: {}
+ * });
+ */
 import { FetchConfig } from './use-fetch';
 export interface CallbackParams {
     data: any;

package/hooks/use-module-entity.js

@@ -1,4 +1,58 @@
 "use strict";
+/**
+ * useModuleEntity
+ *
+ * Summary
+ * - A convenience hook that manages common module/entity operations: list, get-by-id,
+ *   create/update, and delete. It composes `useFetch` for HTTP calls and `useDebounce`
+ *   for debouncing search queries.
+ *
+ * Main features
+ * - List: performs a POST to `listUrl` with a JSON body `listParams` and re-runs
+ *   when `searchQuery` (debounced) or `listDeps` change.
+ * - Get by ID: performs a POST to `unitByIdUrl` with `byIdParams` in the JSON body
+ *   and exposes `byIdFetchNow`, `byIdLoading`, and `byIdError`.
+ * - Create/Update: performs a POST to `unitUrl` with a JSON body `updateParams`.
+ *   On successful create/update the hook triggers a coalesced list refresh.
+ * - Delete: performs a DELETE to `unitUrl` with a JSON body `deleteParams` and
+ *   triggers a coalesced list refresh when the operation succeeds.
+ * - Refresh batching: `refreshList(delay)` coalesces multiple rapid updates/deletes
+ *   using a short timeout (default 300ms) to avoid unnecessary list reloads.
+ *
+ * Parameters (object)
+ * - `byIdCallback(data)`, `byIdDeps`, `byIdParams`
+ * - `deleteCallback(data)`, `deleteDeps`, `deleteParams`
+ * - `listCallback(data)`, `listDeps`, `listParams`, `listUrl`
+ * - `searchQuery` (string) — debounced before influencing the list fetch
+ * - `unitByIdUrl`, `unitUrl`
+ * - `updateCallback(data)`, `updateDeps`, `updateParams`
+ *
+ * Return values
+ * - `byIdFetchNow(url?, config?)`, `byIdLoading`, `byIdError`
+ * - `listFetchNow(url?, config?)`, `listLoading`, `listError`
+ * - `updateFetchNow(url?, config?)`, `updateLoading`, `updateError`
+ * - `deleteFetchNow(url?, config?)`, `deleteLoading`, `deleteError`
+ *
+ * Behavior notes
+ * - All requests that accept parameters send them in the JSON request body (stringified).
+ * - All callbacks receive an object `{ data, error, status, ok }` from `useFetch`.
+ * - Callbacks are wrapped so thrown errors are swallowed to ensure refresh logic
+ *   still runs reliably.
+ * - `refreshList()` calls `listFetchNow(undefined, { method: 'POST', body: JSON.stringify(listParams) })`
+ *   to explicitly re-query the list endpoint with the current `listParams`.
+ * - Network calls are delegated to `useFetch`; callers can invoke the returned
+ *   `*FetchNow` functions directly with an override URL or config.
+ *
+ * Example
+ * const { listFetchNow, updateFetchNow } = useModuleEntity({
+ *   listUrl: '/items',
+ *   listParams: { page: 1 },
+ *   listCallback: (res) => console.log(res),
+ *   unitUrl: '/items',
+ *   updateCallback: () => {},
+ *   updateParams: {}
+ * });
+ */
 var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
     if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
         if (ar || !(i in from)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-pakistan/util-functions",
-  "version": "1.25.2",
+  "version": "1.25.4",
   "description": "A library of all util functions",
   "main": "index.js",
   "scripts": {