nhb-toolbox 4.0.91 → 4.1.0

package/dist/cjs/index.js

@@ -4,8 +4,8 @@ exports.getFibonacciNumbers = exports.getFibonacci = exports.generateFibonacci =
 exports.convertHslaToRgba = exports.convertHslaToHex8 = exports.convertHexToRgb = exports.convertHexToHsl = exports.convertHex8ToRgba = exports.convertHex8ToHsla = exports.convertColorCode = exports.generateRandomHSLColor = exports.generateRandomColorInHexRGB = exports.getColorForInitial = exports.getNumbersInRange = exports.roundToNearestInterval = exports.roundToNearest = exports.roundNumberToNearestInterval = exports.roundNumber = exports.numberToOrdinal = exports.getRandomFloat = exports.getRandomDecimal = exports.getOrdinalNumber = exports.getOrdinal = exports.formatCurrency = exports.convertToOrdinal = exports.convertNumberToOrdinal = exports.convertNumberToCurrency = exports.clampNumber = exports.cardinalToOrdinal = exports.isPrimeNumber = exports.isPrime = exports.getPrimeNumbers = exports.findPrimeNumbers = exports.numberToWords = exports.numericToRoman = exports.convertToRomanNumerals = exports.convertNumberToWords = exports.isPerfectSquare = exports.isParOfFibonacciSeries = exports.isParOfFibonacci = exports.isOddNumber = exports.isOdd = exports.isMultiple = exports.isInvalidNumbers = exports.isFibonacci = exports.isEvenNumber = exports.isEven = exports.areInvalidNumbers = exports.getNthFibonacci = exports.getMemoizedFibonacciSeries = exports.getMemoizedFibonacci = exports.getFibonacciSeriesMemo = exports.getFibonacciSeries = void 0;
 exports.extractDuplicates = exports.createOptionsArray = exports.sortAnArray = exports.Finder = exports.shuffleArray = exports.isValidEmptyArray = exports.isInvalidOrEmptyArray = exports.getLastArrayElement = exports.flattenArray = exports.filterArrayOfObjects = exports.minutesToUTCOffset = exports.getTotalMinutesFromUTC = exports.getTotalMinutesFromTime = exports.getTotalMinutes = exports.getTimeStringFromUTC = exports.getMinutesFromUTC = exports.getCurrentTime = exports.getCurrentDateTime = exports.formatUTCOffset = exports.extractTotalMinutesFromTime = exports.extractTimeStringFromUTC = exports.extractTimeFromUTC = exports.extractMinutesFromUTC = exports.extractHourMinute = exports.convertMinutesToUTCOffset = exports.chronusts = exports.chronusjs = exports.chronus = exports.chronosts = exports.chronosjs = exports.chronos = exports.Chronus = exports.Chronos = exports.isValidUTCOffSet = exports.isValidUTC = exports.isValidTimeString = exports.isValidTime = exports.isLeapYear = exports.greet = exports.getGreeting = exports.generateGreeting = exports.Colour = exports.Color = exports.convertRgbToRgba = exports.convertRgbToHsl = exports.convertRgbToHex = exports.convertRgbaToHsla = exports.convertRgbaToHex8 = exports.convertHslToRgb = exports.convertHslToHex = void 0;
 exports.remapFields = exports.pickObjectFieldsByCondition = exports.pickObjectFields = exports.pickFieldsByCondition = exports.pickFields = exports.convertObjectValues = exports.sanitizeData = exports.parseStringifiedValues = exports.parseStringifiedPrimitives = exports.parseStringifiedObjectValues = exports.parsePrimitives = exports.parsePrimitiveData = exports.parseObjectValues = exports.parseJsonToObject = exports.mergeObjects = exports.mergeAndFlattenObjects = exports.flattenObjectKeyValue = exports.flattenObjectDotNotation = exports.extractUpdatedFields = exports.extractUpdatedAndNewFields = exports.extractNewFields = exports.countObjectFields = exports.cloneObject = exports.isValidFormData = exports.isOriginFileObj = exports.isFileUpload = exports.isFileList = exports.isFileArray = exports.isCustomFileArray = exports.isCustomFile = exports.serializeForm = exports.parseFormData = exports.createFormData = exports.createControlledFormData = exports.convertIntoFormData = exports.naturalSortForString = exports.naturalSort = exports.compareSorter = exports.compareNaturally = exports.splitArray = exports.rotateArray = exports.removeDuplicatesFromArray = exports.removeDuplicates = exports.moveArrayElement = exports.getMissingElements = exports.getDuplicatesFromArray = exports.getDuplicates = exports.findMissingElements = exports.extractMissingElements = exports.extractDuplicatesFromArray = void 0;
-exports.isBigInt = exports.isArrayWithLength = exports.isArrayOfType = exports.isArray = exports.doesReturnPromise = exports.isUndefined = exports.isTruthy = exports.isSymbol = exports.isString = exports.isPrimitive = exports.isPositiveInteger = exports.isNumber = exports.isNull = exports.isNonEmptyString = exports.isInteger = exports.isFalsy = exports.isBoolean = exports.throttleAction = exports.parsePrimitivesDeep = exports.parseJsonDeep = exports.parseJSON = exports.isDeepEqual = exports.getStaticMethodsCount = exports.getStaticMethodNames = exports.getInstanceMethodsCount = exports.getInstanceMethodNames = exports.getClassDetails = exports.deepParsePrimitives = exports.debounceAction = exports.countStaticMethods = exports.countInstanceMethods = exports.convertArrayToString = exports.saveToSessionStorage = exports.saveToLocalStorage = exports.removeFromSessionStorage = exports.removeFromLocalStorage = exports.getFromSessionStorage = exports.getFromLocalStorage = exports.toggleFullScreen = exports.smoothScrollTo = exports.copyToClipboard = exports.updateQueryParam = exports.getQueryStringAsObject = exports.queryStringToObject = exports.parseQueryString = exports.getQueryParams = exports.generateQueryParams = exports.formatQueryParams = exports.createQueryParams = exports.remapObjectFields = void 0;
-exports.isValidURL = exports.isValidEmail = exports.isUUID = exports.isURL = exports.isPhoneNumber = exports.isNumericString = exports.isNodeEnvironment = exports.isNodeENV = exports.isNode = exports.isIPAddress = exports.isExpectedNodeENV = exports.isEnvironment = exports.isEmailArray = exports.isEmail = exports.isDateString = exports.isBrowser = exports.isBase64 = exports.isValidSet = exports.isValidObject = exports.isValidMap = exports.isValidJSON = exports.isValidArray = exports.isSet = exports.isReturningPromise = exports.isRegularExpression = exports.isRegExp = exports.isPromise = exports.isObjectWithKeys = exports.isObjectEmpty = exports.isObject = exports.isNotEmptyObject = exports.isMethodDescriptor = exports.isMethod = exports.isMap = exports.isJSONObject = exports.isJSON = exports.isFunction = exports.isError = exports.isEmptyObjectGuard = exports.isEmptyObject = exports.isDate = void 0;
+exports.isArrayWithLength = exports.isArrayOfType = exports.isArray = exports.doesReturnPromise = exports.isUndefined = exports.isTruthy = exports.isSymbol = exports.isString = exports.isPrimitive = exports.isPositiveInteger = exports.isNumber = exports.isNull = exports.isNonEmptyString = exports.isInteger = exports.isFalsy = exports.isBoolean = exports.Paginator = exports.throttleAction = exports.parsePrimitivesDeep = exports.parseJsonDeep = exports.parseJSON = exports.isDeepEqual = exports.getStaticMethodsCount = exports.getStaticMethodNames = exports.getInstanceMethodsCount = exports.getInstanceMethodNames = exports.getClassDetails = exports.deepParsePrimitives = exports.debounceAction = exports.countStaticMethods = exports.countInstanceMethods = exports.convertArrayToString = exports.saveToSessionStorage = exports.saveToLocalStorage = exports.removeFromSessionStorage = exports.removeFromLocalStorage = exports.getFromSessionStorage = exports.getFromLocalStorage = exports.toggleFullScreen = exports.smoothScrollTo = exports.copyToClipboard = exports.updateQueryParam = exports.getQueryStringAsObject = exports.queryStringToObject = exports.parseQueryString = exports.getQueryParams = exports.generateQueryParams = exports.formatQueryParams = exports.createQueryParams = exports.remapObjectFields = void 0;
+exports.isValidURL = exports.isValidEmail = exports.isUUID = exports.isURL = exports.isPhoneNumber = exports.isNumericString = exports.isNodeEnvironment = exports.isNodeENV = exports.isNode = exports.isIPAddress = exports.isExpectedNodeENV = exports.isEnvironment = exports.isEmailArray = exports.isEmail = exports.isDateString = exports.isBrowser = exports.isBase64 = exports.isValidSet = exports.isValidObject = exports.isValidMap = exports.isValidJSON = exports.isValidArray = exports.isSet = exports.isReturningPromise = exports.isRegularExpression = exports.isRegExp = exports.isPromise = exports.isObjectWithKeys = exports.isObjectEmpty = exports.isObject = exports.isNotEmptyObject = exports.isMethodDescriptor = exports.isMethod = exports.isMap = exports.isJSONObject = exports.isJSON = exports.isFunction = exports.isError = exports.isEmptyObjectGuard = exports.isEmptyObject = exports.isDate = exports.isBigInt = void 0;
 // ! String Utilities
 var basics_1 = require("./string/basics");
 Object.defineProperty(exports, "capitalizeString", { enumerable: true, get: function () { return basics_1.capitalizeString; } });
@@ -288,6 +288,8 @@ Object.defineProperty(exports, "parseJSON", { enumerable: true, get: function ()
 Object.defineProperty(exports, "parseJsonDeep", { enumerable: true, get: function () { return utils_4.parseJSON; } });
 Object.defineProperty(exports, "parsePrimitivesDeep", { enumerable: true, get: function () { return utils_4.deepParsePrimitives; } });
 Object.defineProperty(exports, "throttleAction", { enumerable: true, get: function () { return utils_4.throttleAction; } });
+var Paginator_1 = require("./utils/Paginator");
+Object.defineProperty(exports, "Paginator", { enumerable: true, get: function () { return Paginator_1.Paginator; } });
 // ! Primitive Type Guards
 var primitives_1 = require("./guards/primitives");
 Object.defineProperty(exports, "isBoolean", { enumerable: true, get: function () { return primitives_1.isBoolean; } });

package/dist/cjs/utils/Paginator.js

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Paginator = void 0;
+/** * Generates pagination logic, offsets, metadata and other pagination logic(s) for APIs and UIs. */
+class Paginator {
+    #totalItems;
+    #perPage;
+    #currentPage;
+    /**
+     * * Creates an instance of the Paginator.
+     * @param options - The options for pagination.
+     */
+    constructor(options) {
+        const { totalItems, itemsPerPage = 10, currentPage = 1, } = options ?? {};
+        this.#totalItems = Math.max(0, Number(totalItems));
+        this.#perPage = Math.max(1, Number(itemsPerPage));
+        this.#currentPage = Math.max(1, Number(currentPage));
+    }
+    /**
+     * @instance Returns a new Paginator instance with the given page number.
+     * * This method does not modify the current instance.
+     * - **N.B.** *If the provided page is out of range, it will be clamped between 1 and the last page.*
+     * @param page - The new current page to use.
+     * @returns A new Paginator instance with the updated (clamped) page.
+     */
+    withPage(page) {
+        const safePage = Math.min(Math.max(1, page), this.totalPages());
+        return new Paginator({
+            totalItems: this.#totalItems,
+            itemsPerPage: this.#perPage,
+            currentPage: safePage,
+        });
+    }
+    /**
+     * @instance Returns a new Paginator instance with the given items per page.
+     * - **N.B.** *If the value is less than `1`, it will be clamped to 1.*
+     * @param perPage - New items per page value.
+     * @returns A new Paginator instance with updated items per page.
+     */
+    withPerPage(perPage) {
+        const safePerPage = Math.max(1, perPage);
+        return new Paginator({
+            totalItems: this.#totalItems,
+            itemsPerPage: safePerPage,
+            currentPage: this.#currentPage,
+        });
+    }
+    /**
+     * @instance Returns a new Paginator instance with the given total items.
+     * - **N.B.** *If the value is `negative`, it will be clamped to `0`.*
+     * @param totalItems - New total items value.
+     * @returns A new Paginator instance with updated total items.
+     */
+    withTotalItems(totalItems) {
+        const safeTotalItems = Math.max(0, totalItems);
+        return new Paginator({
+            totalItems: safeTotalItems,
+            itemsPerPage: this.#perPage,
+            currentPage: this.#currentPage,
+        });
+    }
+    /**
+     * @instance Returns a new Paginator instance with updated pagination options.
+     * - **N.B.** *Any value provided will override the existing one, with clamping applied for safety.*
+     * @param options - Partial pagination options to override the current instance.
+     * @returns A new Paginator instance with merged and clamped options.
+     */
+    withOptions(options) {
+        const newTotalItems = Math.max(0, options.totalItems ? Number(options.totalItems) : this.#totalItems);
+        const newItemsPerPage = Math.max(1, options.itemsPerPage ? Number(options.itemsPerPage) : this.#perPage);
+        const totalPages = Math.ceil(newTotalItems / newItemsPerPage);
+        const newCurrentPage = Math.min(Math.max(1, options.currentPage ?
+            Number(options.currentPage)
+            : this.#currentPage), totalPages);
+        return new Paginator({
+            totalItems: newTotalItems,
+            itemsPerPage: newItemsPerPage,
+            currentPage: newCurrentPage,
+        });
+    }
+    /**
+     * @instance Calculates the offset (number of items to skip) based on the `current page` and `items per page`.
+     * @returns The number of items to skip.
+     */
+    offset() {
+        return (this.#currentPage - 1) * this.#perPage;
+    }
+    /**
+     * @instance Calculates the offset (number of items to skip) based on the `current page` and `items per page`.
+     * @alias of {@link offset}
+     * @returns The number of items to skip.
+     */
+    getOffset() {
+        return this.offset();
+    }
+    /**
+     * @instance Calculates the number of items to skip based on the `current page` and `items per page`.
+     * @alias of {@link offset}
+     * @returns The number of items to skip.
+     */
+    skipCount() {
+        return this.offset();
+    }
+    /**
+     * @instance Calculates the total number of pages based on `total items` and `items per page`.
+     * @returns The total number of pages.
+     */
+    totalPages() {
+        return Math.ceil(this.#totalItems / this.#perPage);
+    }
+    /**
+     * * Returns pagination metadata useful for API responses or UI rendering.
+     * @returns An object with pagination metadata.
+     */
+    getMeta() {
+        const totalPages = this.totalPages();
+        return {
+            totalItems: this.#totalItems,
+            currentPage: this.#currentPage,
+            itemsPerPage: this.#perPage,
+            totalPages,
+            hasPrev: this.hasPrevPage(),
+            hasNext: this.hasNextPage(),
+            isFirst: this.isFirstPage(),
+            isLast: this.isLastPage(),
+            offset: this.offset(),
+        };
+    }
+    /**
+     * @instance Returns the next page number if it exists.
+     * @returns The next page number or null if it's the last page.
+     */
+    nextPage() {
+        return this.#currentPage < this.totalPages() ?
+            this.#currentPage + 1
+            : null;
+    }
+    /**
+     * @instance Returns the previous page number if it exists.
+     * @returns The previous page number or null if it's the first page.
+     */
+    prevPage() {
+        return this.#currentPage > 1 ? this.#currentPage - 1 : null;
+    }
+    /**
+     * @instance Checks if the current page is the first page.
+     * @returns Whether the current page is the first page.
+     */
+    isFirstPage() {
+        return this.#currentPage === 1;
+    }
+    /**
+     * @instance Checks if the current page is the last page.
+     * @returns Whether the current page is the last page.
+     */
+    isLastPage() {
+        return this.#currentPage === this.totalPages();
+    }
+    /**
+     * @instance Checks if a previous page exists.
+     * @returns Whether a previous page exists.
+     */
+    hasPrevPage() {
+        return this.#currentPage > 1;
+    }
+    /**
+     * @instance Checks if a next page exists.
+     * @returns Whether a next page exists.
+     */
+    hasNextPage() {
+        return this.#currentPage < this.totalPages();
+    }
+    /**
+     * @instance Creates an array of page numbers for UI pagination display.
+     * @param options Options for customizing the page list.
+     * @returns An array of visible page numbers.
+     */
+    pageList(options = {}) {
+        const total = this.totalPages();
+        const edgeCount = Math.max(0, options.edgeCount ?? 1);
+        const siblingCount = Math.max(0, options.siblingCount ?? 1);
+        const start = Math.max(this.#currentPage - siblingCount, edgeCount + 1);
+        const end = Math.min(this.#currentPage + siblingCount, total - edgeCount);
+        const _getRange = (from, to) => {
+            return from > to ?
+                []
+                : Array.from({ length: to - from + 1 }, (_, i) => from + i);
+        };
+        const startPages = _getRange(1, edgeCount);
+        const middlePages = _getRange(start, end);
+        const endPages = _getRange(total - edgeCount + 1, total);
+        const pages = new Set([
+            ...startPages,
+            ...middlePages,
+            ...endPages,
+        ]);
+        return Array.from(pages).sort((a, b) => a - b);
+    }
+    /**
+     * @instance Returns the first page number.
+     * @returns Always returns 1.
+     */
+    firstPage() {
+        return 1;
+    }
+    /**
+     * @instance Returns the last page number based on total items and per page count.
+     * @returns The last page number.
+     */
+    lastPage() {
+        return this.totalPages();
+    }
+    /**
+     * @instance Checks if a page number is valid within the pagination range.
+     * @param page - The page number to validate.
+     * @returns Whether the page number is within range.
+     */
+    isPageValid(page) {
+        const p = Math.floor(page);
+        return p >= 1 && p <= this.totalPages();
+    }
+    /**
+     * @static Creates a new Paginator instance from a meta object.
+     * @param meta - A pagination metadata object.
+     * @returns A new Paginator instance.
+     */
+    static fromMeta(meta) {
+        return new Paginator({
+            totalItems: meta.totalItems,
+            itemsPerPage: meta.itemsPerPage,
+            currentPage: meta.currentPage,
+        });
+    }
+}
+exports.Paginator = Paginator;

package/dist/cjs/utils/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/dts/index.d.ts

@@ -38,6 +38,7 @@ export { generateQueryParams as createQueryParams, generateQueryParams as format
 export { copyToClipboard, smoothScrollTo, toggleFullScreen } from './dom/utils';
 export { getFromLocalStorage, getFromSessionStorage, removeFromLocalStorage, removeFromSessionStorage, saveToLocalStorage, saveToSessionStorage, } from './dom/storage';
 export { convertArrayToString, countInstanceMethods, countStaticMethods, debounceAction, deepParsePrimitives, getClassDetails, getInstanceMethodNames, countInstanceMethods as getInstanceMethodsCount, getStaticMethodNames, countStaticMethods as getStaticMethodsCount, isDeepEqual, parseJSON, parseJSON as parseJsonDeep, deepParsePrimitives as parsePrimitivesDeep, throttleAction, } from './utils';
+export { Paginator } from './utils/Paginator';
 export { isBoolean, isFalsy, isInteger, isNonEmptyString, isNull, isNumber, isPositiveInteger, isPrimitive, isString, isSymbol, isTruthy, isUndefined, } from './guards/primitives';
 export { isReturningPromise as doesReturnPromise, isArray, isArrayOfType, isValidArray as isArrayWithLength, isBigInt, isDate, isEmptyObject, isEmptyObject as isEmptyObjectGuard, isError, isFunction, isJSON, isJSON as isJSONObject, isMap, isMethodDescriptor as isMethod, isMethodDescriptor, isNotEmptyObject, isObject, isEmptyObject as isObjectEmpty, isObjectWithKeys, isPromise, isRegExp, isRegExp as isRegularExpression, isReturningPromise, isSet, isValidArray, isJSON as isValidJSON, isMap as isValidMap, isNotEmptyObject as isValidObject, isSet as isValidSet, } from './guards/non-primitives';
 export { isBase64, isBrowser, isDateString, isEmail, isEmailArray, isEnvironment, isEnvironment as isExpectedNodeENV, isIPAddress, isNode, isEnvironment as isNodeENV, isEnvironment as isNodeEnvironment, isNumericString, isPhoneNumber, isURL, isUUID, isEmail as isValidEmail, isURL as isValidURL, } from './guards/specials';

package/dist/dts/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/dts/utils/Paginator.d.ts

@@ -0,0 +1,125 @@
+import type { FromMetaOptions, PageListOptions, PaginatorMeta, PaginatorOptions } from './types';
+/** * Generates pagination logic, offsets, metadata and other pagination logic(s) for APIs and UIs. */
+export declare class Paginator {
+    #private;
+    /**
+     * * Creates an instance of the Paginator.
+     * @param options - The options for pagination.
+     */
+    constructor(options: PaginatorOptions);
+    /**
+     * @instance Returns a new Paginator instance with the given page number.
+     * * This method does not modify the current instance.
+     * - **N.B.** *If the provided page is out of range, it will be clamped between 1 and the last page.*
+     * @param page - The new current page to use.
+     * @returns A new Paginator instance with the updated (clamped) page.
+     */
+    withPage(page: number): Paginator;
+    /**
+     * @instance Returns a new Paginator instance with the given items per page.
+     * - **N.B.** *If the value is less than `1`, it will be clamped to 1.*
+     * @param perPage - New items per page value.
+     * @returns A new Paginator instance with updated items per page.
+     */
+    withPerPage(perPage: number): Paginator;
+    /**
+     * @instance Returns a new Paginator instance with the given total items.
+     * - **N.B.** *If the value is `negative`, it will be clamped to `0`.*
+     * @param totalItems - New total items value.
+     * @returns A new Paginator instance with updated total items.
+     */
+    withTotalItems(totalItems: number): Paginator;
+    /**
+     * @instance Returns a new Paginator instance with updated pagination options.
+     * - **N.B.** *Any value provided will override the existing one, with clamping applied for safety.*
+     * @param options - Partial pagination options to override the current instance.
+     * @returns A new Paginator instance with merged and clamped options.
+     */
+    withOptions(options: Partial<PaginatorOptions>): Paginator;
+    /**
+     * @instance Calculates the offset (number of items to skip) based on the `current page` and `items per page`.
+     * @returns The number of items to skip.
+     */
+    offset(): number;
+    /**
+     * @instance Calculates the offset (number of items to skip) based on the `current page` and `items per page`.
+     * @alias of {@link offset}
+     * @returns The number of items to skip.
+     */
+    getOffset(): number;
+    /**
+     * @instance Calculates the number of items to skip based on the `current page` and `items per page`.
+     * @alias of {@link offset}
+     * @returns The number of items to skip.
+     */
+    skipCount(): number;
+    /**
+     * @instance Calculates the total number of pages based on `total items` and `items per page`.
+     * @returns The total number of pages.
+     */
+    totalPages(): number;
+    /**
+     * * Returns pagination metadata useful for API responses or UI rendering.
+     * @returns An object with pagination metadata.
+     */
+    getMeta(): PaginatorMeta;
+    /**
+     * @instance Returns the next page number if it exists.
+     * @returns The next page number or null if it's the last page.
+     */
+    nextPage(): number | null;
+    /**
+     * @instance Returns the previous page number if it exists.
+     * @returns The previous page number or null if it's the first page.
+     */
+    prevPage(): number | null;
+    /**
+     * @instance Checks if the current page is the first page.
+     * @returns Whether the current page is the first page.
+     */
+    isFirstPage(): boolean;
+    /**
+     * @instance Checks if the current page is the last page.
+     * @returns Whether the current page is the last page.
+     */
+    isLastPage(): boolean;
+    /**
+     * @instance Checks if a previous page exists.
+     * @returns Whether a previous page exists.
+     */
+    hasPrevPage(): boolean;
+    /**
+     * @instance Checks if a next page exists.
+     * @returns Whether a next page exists.
+     */
+    hasNextPage(): boolean;
+    /**
+     * @instance Creates an array of page numbers for UI pagination display.
+     * @param options Options for customizing the page list.
+     * @returns An array of visible page numbers.
+     */
+    pageList(options?: PageListOptions): number[];
+    /**
+     * @instance Returns the first page number.
+     * @returns Always returns 1.
+     */
+    firstPage(): number;
+    /**
+     * @instance Returns the last page number based on total items and per page count.
+     * @returns The last page number.
+     */
+    lastPage(): number;
+    /**
+     * @instance Checks if a page number is valid within the pagination range.
+     * @param page - The page number to validate.
+     * @returns Whether the page number is within range.
+     */
+    isPageValid(page: number): boolean;
+    /**
+     * @static Creates a new Paginator instance from a meta object.
+     * @param meta - A pagination metadata object.
+     * @returns A new Paginator instance.
+     */
+    static fromMeta(meta: FromMetaOptions): Paginator;
+}
+//# sourceMappingURL=Paginator.d.ts.map

package/dist/dts/utils/Paginator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Paginator.d.ts","sourceRoot":"","sources":["../../../src/utils/Paginator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,eAAe,EACf,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,MAAM,SAAS,CAAC;AAEjB,sGAAsG;AACtG,qBAAa,SAAS;;IAKrB;;;OAGG;gBACS,OAAO,EAAE,gBAAgB;IAYrC;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS;IAUjC;;;;;OAKG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS;IASvC;;;;;OAKG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS;IAS7C;;;;;OAKG;IACH,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,SAAS;IA2B1D;;;OAGG;IACH,MAAM,IAAI,MAAM;IAIhB;;;;OAIG;IACH,SAAS,IAAI,MAAM;IAInB;;;;OAIG;IACH,SAAS,IAAI,MAAM;IAInB;;;OAGG;IACH,UAAU,IAAI,MAAM;IAIpB;;;OAGG;IACH,OAAO,IAAI,aAAa;IAexB;;;OAGG;IACH,QAAQ,IAAI,MAAM,GAAG,IAAI;IAMzB;;;OAGG;IACH,QAAQ,IAAI,MAAM,GAAG,IAAI;IAIzB;;;OAGG;IACH,WAAW,IAAI,OAAO;IAItB;;;OAGG;IACH,UAAU,IAAI,OAAO;IAIrB;;;OAGG;IACH,WAAW,IAAI,OAAO;IAItB;;;OAGG;IACH,WAAW,IAAI,OAAO;IAItB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,MAAM,EAAE;IA6BjD;;;OAGG;IACH,SAAS,IAAI,MAAM;IAInB;;;OAGG;IACH,QAAQ,IAAI,MAAM;IAIlB;;;;OAIG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAKlC;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,SAAS;CAOjD"}

package/dist/dts/utils/types.d.ts

@@ -0,0 +1,30 @@
+import type { Numeric } from '../types';
+export interface PaginatorOptions {
+    /** The total number of items. */
+    totalItems: Numeric;
+    /** Number of items per page. (Default is `10`). */
+    itemsPerPage?: Numeric;
+    /** Current active page. (Default is `1`). */
+    currentPage?: Numeric;
+}
+export interface PaginatorMeta {
+    totalItems: number;
+    currentPage: number;
+    itemsPerPage: number;
+    totalPages: number;
+    hasPrev: boolean;
+    hasNext: boolean;
+    isFirst: boolean;
+    isLast: boolean;
+    offset: number;
+}
+/** Options for `fromMeta` method. */
+export type FromMetaOptions = Pick<PaginatorMeta, 'totalItems' | 'itemsPerPage' | 'currentPage'>;
+/** Options for pageList method. */
+export interface PageListOptions {
+    /** Number of edge pages to always show (default 1). */
+    edgeCount?: number;
+    /** Number of siblings pages to show around the current page (default 1). */
+    siblingCount?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/dts/utils/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/utils/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExC,MAAM,WAAW,gBAAgB;IAChC,iCAAiC;IACjC,UAAU,EAAE,OAAO,CAAC;IACpB,mDAAmD;IACnD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CACf;AAED,qCAAqC;AACrC,MAAM,MAAM,eAAe,GAAG,IAAI,CACjC,aAAa,EACb,YAAY,GAAG,cAAc,GAAG,aAAa,CAC7C,CAAC;AAEF,mCAAmC;AACnC,MAAM,WAAW,eAAe;IAC/B,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB"}

package/dist/esm/index.js

@@ -47,6 +47,7 @@ export { copyToClipboard, smoothScrollTo, toggleFullScreen } from './dom/utils';
 export { getFromLocalStorage, getFromSessionStorage, removeFromLocalStorage, removeFromSessionStorage, saveToLocalStorage, saveToSessionStorage, } from './dom/storage';
 // ! Other Utilities
 export { convertArrayToString, countInstanceMethods, countStaticMethods, debounceAction, deepParsePrimitives, getClassDetails, getInstanceMethodNames, countInstanceMethods as getInstanceMethodsCount, getStaticMethodNames, countStaticMethods as getStaticMethodsCount, isDeepEqual, parseJSON, parseJSON as parseJsonDeep, deepParsePrimitives as parsePrimitivesDeep, throttleAction, } from './utils';
+export { Paginator } from './utils/Paginator';
 // ! Primitive Type Guards
 export { isBoolean, isFalsy, isInteger, isNonEmptyString, isNull, isNumber, isPositiveInteger, isPrimitive, isString, isSymbol, isTruthy, isUndefined, } from './guards/primitives';
 // ! Non-Primitive Type Guards

package/dist/esm/utils/Paginator.js

@@ -0,0 +1,231 @@
+/** * Generates pagination logic, offsets, metadata and other pagination logic(s) for APIs and UIs. */
+export class Paginator {
+    #totalItems;
+    #perPage;
+    #currentPage;
+    /**
+     * * Creates an instance of the Paginator.
+     * @param options - The options for pagination.
+     */
+    constructor(options) {
+        const { totalItems, itemsPerPage = 10, currentPage = 1, } = options ?? {};
+        this.#totalItems = Math.max(0, Number(totalItems));
+        this.#perPage = Math.max(1, Number(itemsPerPage));
+        this.#currentPage = Math.max(1, Number(currentPage));
+    }
+    /**
+     * @instance Returns a new Paginator instance with the given page number.
+     * * This method does not modify the current instance.
+     * - **N.B.** *If the provided page is out of range, it will be clamped between 1 and the last page.*
+     * @param page - The new current page to use.
+     * @returns A new Paginator instance with the updated (clamped) page.
+     */
+    withPage(page) {
+        const safePage = Math.min(Math.max(1, page), this.totalPages());
+        return new Paginator({
+            totalItems: this.#totalItems,
+            itemsPerPage: this.#perPage,
+            currentPage: safePage,
+        });
+    }
+    /**
+     * @instance Returns a new Paginator instance with the given items per page.
+     * - **N.B.** *If the value is less than `1`, it will be clamped to 1.*
+     * @param perPage - New items per page value.
+     * @returns A new Paginator instance with updated items per page.
+     */
+    withPerPage(perPage) {
+        const safePerPage = Math.max(1, perPage);
+        return new Paginator({
+            totalItems: this.#totalItems,
+            itemsPerPage: safePerPage,
+            currentPage: this.#currentPage,
+        });
+    }
+    /**
+     * @instance Returns a new Paginator instance with the given total items.
+     * - **N.B.** *If the value is `negative`, it will be clamped to `0`.*
+     * @param totalItems - New total items value.
+     * @returns A new Paginator instance with updated total items.
+     */
+    withTotalItems(totalItems) {
+        const safeTotalItems = Math.max(0, totalItems);
+        return new Paginator({
+            totalItems: safeTotalItems,
+            itemsPerPage: this.#perPage,
+            currentPage: this.#currentPage,
+        });
+    }
+    /**
+     * @instance Returns a new Paginator instance with updated pagination options.
+     * - **N.B.** *Any value provided will override the existing one, with clamping applied for safety.*
+     * @param options - Partial pagination options to override the current instance.
+     * @returns A new Paginator instance with merged and clamped options.
+     */
+    withOptions(options) {
+        const newTotalItems = Math.max(0, options.totalItems ? Number(options.totalItems) : this.#totalItems);
+        const newItemsPerPage = Math.max(1, options.itemsPerPage ? Number(options.itemsPerPage) : this.#perPage);
+        const totalPages = Math.ceil(newTotalItems / newItemsPerPage);
+        const newCurrentPage = Math.min(Math.max(1, options.currentPage ?
+            Number(options.currentPage)
+            : this.#currentPage), totalPages);
+        return new Paginator({
+            totalItems: newTotalItems,
+            itemsPerPage: newItemsPerPage,
+            currentPage: newCurrentPage,
+        });
+    }
+    /**
+     * @instance Calculates the offset (number of items to skip) based on the `current page` and `items per page`.
+     * @returns The number of items to skip.
+     */
+    offset() {
+        return (this.#currentPage - 1) * this.#perPage;
+    }
+    /**
+     * @instance Calculates the offset (number of items to skip) based on the `current page` and `items per page`.
+     * @alias of {@link offset}
+     * @returns The number of items to skip.
+     */
+    getOffset() {
+        return this.offset();
+    }
+    /**
+     * @instance Calculates the number of items to skip based on the `current page` and `items per page`.
+     * @alias of {@link offset}
+     * @returns The number of items to skip.
+     */
+    skipCount() {
+        return this.offset();
+    }
+    /**
+     * @instance Calculates the total number of pages based on `total items` and `items per page`.
+     * @returns The total number of pages.
+     */
+    totalPages() {
+        return Math.ceil(this.#totalItems / this.#perPage);
+    }
+    /**
+     * * Returns pagination metadata useful for API responses or UI rendering.
+     * @returns An object with pagination metadata.
+     */
+    getMeta() {
+        const totalPages = this.totalPages();
+        return {
+            totalItems: this.#totalItems,
+            currentPage: this.#currentPage,
+            itemsPerPage: this.#perPage,
+            totalPages,
+            hasPrev: this.hasPrevPage(),
+            hasNext: this.hasNextPage(),
+            isFirst: this.isFirstPage(),
+            isLast: this.isLastPage(),
+            offset: this.offset(),
+        };
+    }
+    /**
+     * @instance Returns the next page number if it exists.
+     * @returns The next page number or null if it's the last page.
+     */
+    nextPage() {
+        return this.#currentPage < this.totalPages() ?
+            this.#currentPage + 1
+            : null;
+    }
+    /**
+     * @instance Returns the previous page number if it exists.
+     * @returns The previous page number or null if it's the first page.
+     */
+    prevPage() {
+        return this.#currentPage > 1 ? this.#currentPage - 1 : null;
+    }
+    /**
+     * @instance Checks if the current page is the first page.
+     * @returns Whether the current page is the first page.
+     */
+    isFirstPage() {
+        return this.#currentPage === 1;
+    }
+    /**
+     * @instance Checks if the current page is the last page.
+     * @returns Whether the current page is the last page.
+     */
+    isLastPage() {
+        return this.#currentPage === this.totalPages();
+    }
+    /**
+     * @instance Checks if a previous page exists.
+     * @returns Whether a previous page exists.
+     */
+    hasPrevPage() {
+        return this.#currentPage > 1;
+    }
+    /**
+     * @instance Checks if a next page exists.
+     * @returns Whether a next page exists.
+     */
+    hasNextPage() {
+        return this.#currentPage < this.totalPages();
+    }
+    /**
+     * @instance Creates an array of page numbers for UI pagination display.
+     * @param options Options for customizing the page list.
+     * @returns An array of visible page numbers.
+     */
+    pageList(options = {}) {
+        const total = this.totalPages();
+        const edgeCount = Math.max(0, options.edgeCount ?? 1);
+        const siblingCount = Math.max(0, options.siblingCount ?? 1);
+        const start = Math.max(this.#currentPage - siblingCount, edgeCount + 1);
+        const end = Math.min(this.#currentPage + siblingCount, total - edgeCount);
+        const _getRange = (from, to) => {
+            return from > to ?
+                []
+                : Array.from({ length: to - from + 1 }, (_, i) => from + i);
+        };
+        const startPages = _getRange(1, edgeCount);
+        const middlePages = _getRange(start, end);
+        const endPages = _getRange(total - edgeCount + 1, total);
+        const pages = new Set([
+            ...startPages,
+            ...middlePages,
+            ...endPages,
+        ]);
+        return Array.from(pages).sort((a, b) => a - b);
+    }
+    /**
+     * @instance Returns the first page number.
+     * @returns Always returns 1.
+     */
+    firstPage() {
+        return 1;
+    }
+    /**
+     * @instance Returns the last page number based on total items and per page count.
+     * @returns The last page number.
+     */
+    lastPage() {
+        return this.totalPages();
+    }
+    /**
+     * @instance Checks if a page number is valid within the pagination range.
+     * @param page - The page number to validate.
+     * @returns Whether the page number is within range.
+     */
+    isPageValid(page) {
+        const p = Math.floor(page);
+        return p >= 1 && p <= this.totalPages();
+    }
+    /**
+     * @static Creates a new Paginator instance from a meta object.
+     * @param meta - A pagination metadata object.
+     * @returns A new Paginator instance.
+     */
+    static fromMeta(meta) {
+        return new Paginator({
+            totalItems: meta.totalItems,
+            itemsPerPage: meta.itemsPerPage,
+            currentPage: meta.currentPage,
+        });
+    }
+}

package/dist/esm/utils/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nhb-toolbox",
-  "version": "4.0.91",
+  "version": "4.1.00",
   "description": "A versatile collection of smart, efficient, and reusable utility functions and classes for everyday development needs.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -112,6 +112,10 @@
     "./string/types": {
       "types": "./dist/dts/string/types.d.ts",
       "default": "./dist/dts/string/types.d.ts"
+    },
+    "./utils/types": {
+      "types": "./dist/dts/utils/types.d.ts",
+      "default": "./dist/dts/utils/types.d.ts"
     }
   },
   "typesVersions": {
@@ -139,6 +143,9 @@
       ],
       "string/types": [
         "dist/dts/string/types.d.ts"
+      ],
+      "utils/types": [
+        "dist/dts/utils/types.d.ts"
       ]
     }
   },