@levi-gemcommerce/analytics 0.0.0-test.1

package/dist/esm/core/gemxql/helpers/formatAnalyticData.mjs

@@ -0,0 +1,78 @@
+"use client"
+import { calcPercentageString } from '../../../utils/percentage.mjs';
+import { NONE_VALUE } from '../constants/analytic-data.mjs';
+import '../constants/row-reader-mode.mjs';
+import { EAnalyticDataType, EAnalyticColumnKey } from '../types/analytic-data.mjs';
+import '../types/analytic-source.mjs';
+import '../types/extra-condition.mjs';
+import '../types/field-filters.mjs';
+import '../types/field-operators.mjs';
+import '../types/group-with-clause.mjs';
+import '../types/order-by.mjs';
+import '../types/page-fields.mjs';
+import '../types/row-reader-mode.mjs';
+import '../types/time-dimension.mjs';
+import { numberWithCommas } from '../../../utils/number.mjs';
+import '../../../utils/dayjs.mjs';
+import { getFormattedByInterval, AnalyticInterval, getTimeDurationLabel } from '../../../utils/analytics.mjs';
+import '../../../types/template.mjs';
+import { formatAnalyticDate } from './formatAnalyticDate.mjs';
+
+const formatAnalyticData = ({ value, formatter, getTextPrice, name, }) => {
+    const dataTypeIsObjectOrArray = value !== null && (typeof value === 'object' || Array.isArray(value));
+    if (dataTypeIsObjectOrArray)
+        return value;
+    switch (formatter) {
+        case EAnalyticDataType.INTEGER: {
+            return numberWithCommas((value ?? 0).toString());
+        }
+        case EAnalyticDataType.CURRENCY: {
+            if (!getTextPrice)
+                return `${value ?? 0}`;
+            return getTextPrice(value, false);
+        }
+        case EAnalyticDataType.DATE: {
+            return formatAnalyticDate(value);
+        }
+        case EAnalyticDataType.PERCENT: {
+            if (typeof value !== 'number')
+                return calcPercentageString(0, 1, 2) ?? '';
+            return calcPercentageString(value / 100, 1, 2) ?? '';
+        }
+        case EAnalyticDataType.DURATION: {
+            return getTimeDurationLabel(Number(value));
+        }
+        case EAnalyticDataType.STRING: {
+            const fallbackValue = name === EAnalyticColumnKey.CAMPAIGNS ? '' : NONE_VALUE;
+            return value ?? fallbackValue;
+        }
+        case EAnalyticDataType.DAY: {
+            return getFormattedByInterval(value, AnalyticInterval.DAY, { isExpandDetail: true });
+        }
+        case EAnalyticDataType.HOUR: {
+            return getFormattedByInterval(value, AnalyticInterval.HOUR, { isExpandDetail: true });
+        }
+        case EAnalyticDataType.MONTH: {
+            return getFormattedByInterval(value, AnalyticInterval.MONTH, { isExpandDetail: true });
+        }
+        case EAnalyticDataType.YEAR: {
+            return getFormattedByInterval(value, AnalyticInterval.YEAR);
+        }
+        case EAnalyticDataType.WEEK: {
+            return getFormattedByInterval(value, AnalyticInterval.WEEK, { isExpandDetail: true });
+        }
+        case EAnalyticDataType.QUARTER: {
+            return getFormattedByInterval(value, AnalyticInterval.QUARTER, {
+                isExpandDetail: true,
+            });
+        }
+        case EAnalyticDataType.OBJECT:
+        case EAnalyticDataType.ARRAY: {
+            return value;
+        }
+        default:
+            return `${value}`;
+    }
+};
+
+export { formatAnalyticData };

package/dist/esm/core/gemxql/helpers/formatAnalyticDate.d.ts

@@ -0,0 +1 @@
+export declare const formatAnalyticDate: (dateString: string | number | null) => string;

package/dist/esm/core/gemxql/helpers/formatAnalyticDate.js

@@ -0,0 +1,28 @@
+"use client"
+import { dayjsTz } from '../../../utils/dayjs.js';
+import '../../../utils/analytics.js';
+import '../../../types/template.js';
+
+const formatAnalyticDate = (dateString) => {
+    if (!dateString)
+        return 'None';
+    const date = dayjsTz(dateString);
+    const now = dayjsTz();
+    const yesterday = dayjsTz().subtract(1, 'day');
+    const isToday = date.format('YYYY-MM-DD') === now.format('YYYY-MM-DD');
+    const isYesterday = date.format('YYYY-MM-DD') === yesterday.format('YYYY-MM-DD');
+    if (isToday) {
+        return `Today at ${date.format('HH:mm')}`;
+    }
+    if (isYesterday) {
+        return `Yesterday at ${date.format('HH:mm')}`;
+    }
+    const daysDiff = now.diff(date, 'day');
+    const isWithinWeek = daysDiff >= 0 && daysDiff < 7;
+    if (isWithinWeek) {
+        return `${date.format('dddd')} at ${date.format('HH:mm')}`;
+    }
+    return `${date.format('MMM D')} at ${date.format('hh:mm a')}`;
+};
+
+export { formatAnalyticDate };

package/dist/esm/core/gemxql/helpers/formatAnalyticDate.mjs

@@ -0,0 +1,28 @@
+"use client"
+import { dayjsTz } from '../../../utils/dayjs.mjs';
+import '../../../utils/analytics.mjs';
+import '../../../types/template.mjs';
+
+const formatAnalyticDate = (dateString) => {
+    if (!dateString)
+        return 'None';
+    const date = dayjsTz(dateString);
+    const now = dayjsTz();
+    const yesterday = dayjsTz().subtract(1, 'day');
+    const isToday = date.format('YYYY-MM-DD') === now.format('YYYY-MM-DD');
+    const isYesterday = date.format('YYYY-MM-DD') === yesterday.format('YYYY-MM-DD');
+    if (isToday) {
+        return `Today at ${date.format('HH:mm')}`;
+    }
+    if (isYesterday) {
+        return `Yesterday at ${date.format('HH:mm')}`;
+    }
+    const daysDiff = now.diff(date, 'day');
+    const isWithinWeek = daysDiff >= 0 && daysDiff < 7;
+    if (isWithinWeek) {
+        return `${date.format('dddd')} at ${date.format('HH:mm')}`;
+    }
+    return `${date.format('MMM D')} at ${date.format('hh:mm a')}`;
+};
+
+export { formatAnalyticDate };

package/dist/esm/core/gemxql/helpers/getTimeDimension.d.ts

@@ -0,0 +1,3 @@
+import type { Dayjs } from '../../../utils';
+import { ETimeDimension } from '../types';
+export declare const getTimeDimensionByDate: (startDate: Dayjs, endDate: Dayjs) => ETimeDimension;

package/dist/esm/core/gemxql/helpers/getTimeDimension.js

@@ -0,0 +1,22 @@
+"use client"
+import '../types/analytic-data.js';
+import '../types/analytic-source.js';
+import '../types/extra-condition.js';
+import '../types/field-filters.js';
+import '../types/field-operators.js';
+import '../types/group-with-clause.js';
+import '../types/order-by.js';
+import '../types/page-fields.js';
+import '../types/row-reader-mode.js';
+import { ETimeDimension } from '../types/time-dimension.js';
+
+const getTimeDimensionByDate = (startDate, endDate) => {
+    const durationInDays = endDate.diff(startDate, 'day');
+    if (durationInDays <= 3)
+        return ETimeDimension.HOUR;
+    if (durationInDays <= 93)
+        return ETimeDimension.DAY;
+    return ETimeDimension.MONTH;
+};
+
+export { getTimeDimensionByDate };

package/dist/esm/core/gemxql/helpers/getTimeDimension.mjs

@@ -0,0 +1,22 @@
+"use client"
+import '../types/analytic-data.mjs';
+import '../types/analytic-source.mjs';
+import '../types/extra-condition.mjs';
+import '../types/field-filters.mjs';
+import '../types/field-operators.mjs';
+import '../types/group-with-clause.mjs';
+import '../types/order-by.mjs';
+import '../types/page-fields.mjs';
+import '../types/row-reader-mode.mjs';
+import { ETimeDimension } from '../types/time-dimension.mjs';
+
+const getTimeDimensionByDate = (startDate, endDate) => {
+    const durationInDays = endDate.diff(startDate, 'day');
+    if (durationInDays <= 3)
+        return ETimeDimension.HOUR;
+    if (durationInDays <= 93)
+        return ETimeDimension.DAY;
+    return ETimeDimension.MONTH;
+};
+
+export { getTimeDimensionByDate };

package/dist/esm/core/gemxql/helpers/hasMetricData.d.ts

@@ -0,0 +1 @@
+export declare const hasMetricData: (metric?: Record<string, unknown>) => boolean;

package/dist/esm/core/gemxql/helpers/hasMetricData.js

@@ -0,0 +1,8 @@
+"use client"
+const SESSION_KEY = 'sessions';
+const hasMetricData = (metric) => {
+    const sessions = metric?.[SESSION_KEY];
+    return typeof sessions === 'number' && sessions > 0;
+};
+
+export { hasMetricData };

package/dist/esm/core/gemxql/helpers/hasMetricData.mjs

@@ -0,0 +1,8 @@
+"use client"
+const SESSION_KEY = 'sessions';
+const hasMetricData = (metric) => {
+    const sessions = metric?.[SESSION_KEY];
+    return typeof sessions === 'number' && sessions > 0;
+};
+
+export { hasMetricData };

package/dist/esm/core/gemxql/helpers/index.d.ts

@@ -0,0 +1,8 @@
+export * from './columnKeys';
+export * from './extractQueryData';
+export * from './formatAnalyticData';
+export * from './formatAnalyticDate';
+export * from './getTimeDimension';
+export * from './hasMetricData';
+export * from './parseJsonFields';
+export * from './readNumeric';

package/dist/esm/core/gemxql/helpers/parseJsonFields.d.ts

@@ -0,0 +1,9 @@
+import type { IPageItemsPayload } from '../types';
+export interface IBreakdownItem<T extends string = string> {
+    type: T;
+    total: number;
+}
+export declare const parseJsonObject: <T extends object>(value: unknown) => T | null;
+export declare const parseJsonArray: <T>(raw: unknown) => T[] | undefined;
+export declare const parseBreakdownItems: <T extends string = string>(raw: unknown) => IBreakdownItem<T>[] | undefined;
+export declare const parsePageItems: (value: unknown) => IPageItemsPayload | null;

package/dist/esm/core/gemxql/helpers/parseJsonFields.js

@@ -0,0 +1,32 @@
+"use client"
+const parseRawJson = (raw) => {
+    if (!raw)
+        return undefined;
+    return typeof raw === 'string' ? JSON.parse(raw) : raw;
+};
+const parseJsonObject = (value) => {
+    try {
+        const parsed = parseRawJson(value);
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+};
+const parseJsonArray = (raw) => {
+    try {
+        const parsed = parseRawJson(raw);
+        if (!Array.isArray(parsed))
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+};
+const parseBreakdownItems = (raw) => parseJsonArray(raw)?.map((item) => ({ ...item, total: Number(item.total) }));
+const parsePageItems = (value) => parseJsonObject(value);
+
+export { parseBreakdownItems, parseJsonArray, parseJsonObject, parsePageItems };

package/dist/esm/core/gemxql/helpers/parseJsonFields.mjs

@@ -0,0 +1,32 @@
+"use client"
+const parseRawJson = (raw) => {
+    if (!raw)
+        return undefined;
+    return typeof raw === 'string' ? JSON.parse(raw) : raw;
+};
+const parseJsonObject = (value) => {
+    try {
+        const parsed = parseRawJson(value);
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+};
+const parseJsonArray = (raw) => {
+    try {
+        const parsed = parseRawJson(raw);
+        if (!Array.isArray(parsed))
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+};
+const parseBreakdownItems = (raw) => parseJsonArray(raw)?.map((item) => ({ ...item, total: Number(item.total) }));
+const parsePageItems = (value) => parseJsonObject(value);
+
+export { parseBreakdownItems, parseJsonArray, parseJsonObject, parsePageItems };

package/dist/esm/core/gemxql/helpers/readNumeric.d.ts

@@ -0,0 +1,3 @@
+import { ERowReaderMode } from '../types';
+export declare const readNumeric: (metric: Record<string, unknown> | undefined, key: string) => number;
+export declare const createNumericRowReader: (row: Record<string, unknown>, mode?: ERowReaderMode) => (key: string) => number;

package/dist/esm/core/gemxql/helpers/readNumeric.js

@@ -0,0 +1,36 @@
+"use client"
+import { ROW_READER_MODE_CONFIG } from '../constants/row-reader-mode.js';
+import '../types/analytic-data.js';
+import '../types/analytic-source.js';
+import '../types/extra-condition.js';
+import '../types/field-filters.js';
+import '../types/field-operators.js';
+import '../types/group-with-clause.js';
+import '../types/order-by.js';
+import '../types/page-fields.js';
+import { ERowReaderMode } from '../types/row-reader-mode.js';
+import '../types/time-dimension.js';
+
+const readNumeric = (metric, key) => {
+    const raw = metric?.[key];
+    if (typeof raw === 'number')
+        return raw;
+    if (typeof raw === 'string') {
+        const n = parseFloat(raw);
+        return isNaN(n) ? 0 : n;
+    }
+    return 0;
+};
+const createNumericRowReader = (row, mode = ERowReaderMode.DEFAULT) => (key) => {
+    const { prefix, suffix } = ROW_READER_MODE_CONFIG[mode];
+    const v = row[`${prefix}${key}${suffix}`];
+    if (typeof v === 'number')
+        return v;
+    if (typeof v === 'string') {
+        const n = parseFloat(v);
+        return isNaN(n) ? 0 : n;
+    }
+    return 0;
+};
+
+export { createNumericRowReader, readNumeric };

package/dist/esm/core/gemxql/helpers/readNumeric.mjs

@@ -0,0 +1,36 @@
+"use client"
+import { ROW_READER_MODE_CONFIG } from '../constants/row-reader-mode.mjs';
+import '../types/analytic-data.mjs';
+import '../types/analytic-source.mjs';
+import '../types/extra-condition.mjs';
+import '../types/field-filters.mjs';
+import '../types/field-operators.mjs';
+import '../types/group-with-clause.mjs';
+import '../types/order-by.mjs';
+import '../types/page-fields.mjs';
+import { ERowReaderMode } from '../types/row-reader-mode.mjs';
+import '../types/time-dimension.mjs';
+
+const readNumeric = (metric, key) => {
+    const raw = metric?.[key];
+    if (typeof raw === 'number')
+        return raw;
+    if (typeof raw === 'string') {
+        const n = parseFloat(raw);
+        return isNaN(n) ? 0 : n;
+    }
+    return 0;
+};
+const createNumericRowReader = (row, mode = ERowReaderMode.DEFAULT) => (key) => {
+    const { prefix, suffix } = ROW_READER_MODE_CONFIG[mode];
+    const v = row[`${prefix}${key}${suffix}`];
+    if (typeof v === 'number')
+        return v;
+    if (typeof v === 'string') {
+        const n = parseFloat(v);
+        return isNaN(n) ? 0 : n;
+    }
+    return 0;
+};
+
+export { createNumericRowReader, readNumeric };

package/dist/esm/core/gemxql/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export * from './useAnalyticData';
+export * from './useGemXQlPagination';

package/dist/esm/core/gemxql/hooks/useAnalyticData.d.ts

@@ -0,0 +1,27 @@
+import type { IGetTextPrice } from '../helpers/formatAnalyticData';
+import type { AnalyticValueType } from '../types';
+interface IFormatDataParams {
+    value: AnalyticValueType;
+    formatter?: string;
+    name?: string;
+}
+type MetricRecord = Record<string, unknown>;
+interface IComputeMetricParams {
+    metric?: MetricRecord;
+    previousMetric?: MetricRecord;
+    metricKey: string;
+    formatter?: string;
+}
+interface IComputeMetricResult {
+    value: AnalyticValueType;
+    change: number | string;
+}
+interface IUseAnalyticDataReturn {
+    formatData: (params: IFormatDataParams) => AnalyticValueType;
+    computeMetric: (params: IComputeMetricParams) => IComputeMetricResult;
+}
+interface IUseAnalyticDataParams {
+    getTextPrice?: IGetTextPrice;
+}
+export declare const useAnalyticData: ({ getTextPrice: getTextPriceParam, }?: IUseAnalyticDataParams) => IUseAnalyticDataReturn;
+export {};

package/dist/esm/core/gemxql/hooks/useAnalyticData.js

@@ -0,0 +1,44 @@
+"use client"
+import { useConvertMoneyContext } from '../../../providers/ConvertMoneyProvider.js';
+import { PLACEHOLDER_VALUE } from '../constants/analytic-data.js';
+import '../constants/row-reader-mode.js';
+import { formatAnalyticData } from '../helpers/formatAnalyticData.js';
+import '../../../utils/dayjs.js';
+import '../../../utils/analytics.js';
+import '../../../types/template.js';
+import '../types/analytic-data.js';
+import '../types/analytic-source.js';
+import '../types/extra-condition.js';
+import '../types/field-filters.js';
+import '../types/field-operators.js';
+import '../types/group-with-clause.js';
+import '../types/order-by.js';
+import '../types/page-fields.js';
+import '../types/row-reader-mode.js';
+import '../types/time-dimension.js';
+import { hasMetricData } from '../helpers/hasMetricData.js';
+import { readNumeric } from '../helpers/readNumeric.js';
+
+const useAnalyticData = ({ getTextPrice: getTextPriceParam, } = {}) => {
+    const { getTextPrice: getTextPriceCtx } = useConvertMoneyContext();
+    const getTextPrice = getTextPriceParam ?? getTextPriceCtx;
+    const formatData = ({ value, formatter, name }) => {
+        return formatAnalyticData({ value, formatter, getTextPrice, name });
+    };
+    const computeMetric = ({ metric, previousMetric, metricKey, formatter, }) => {
+        if (!hasMetricData(metric))
+            return { value: 0, change: PLACEHOLDER_VALUE };
+        const currentValue = readNumeric(metric, metricKey);
+        const previousValue = readNumeric(previousMetric, metricKey);
+        const value = formatData({ value: currentValue, formatter, name: metricKey });
+        if (currentValue === 0 && previousValue !== 0)
+            return { value, change: -100 };
+        if (previousValue === 0)
+            return { value, change: PLACEHOLDER_VALUE };
+        const change = ((currentValue - previousValue) / previousValue) * 100;
+        return { value, change };
+    };
+    return { formatData, computeMetric };
+};
+
+export { useAnalyticData };

package/dist/esm/core/gemxql/hooks/useAnalyticData.mjs

@@ -0,0 +1,44 @@
+"use client"
+import { useConvertMoneyContext } from '../../../providers/ConvertMoneyProvider.mjs';
+import { PLACEHOLDER_VALUE } from '../constants/analytic-data.mjs';
+import '../constants/row-reader-mode.mjs';
+import { formatAnalyticData } from '../helpers/formatAnalyticData.mjs';
+import '../../../utils/dayjs.mjs';
+import '../../../utils/analytics.mjs';
+import '../../../types/template.mjs';
+import '../types/analytic-data.mjs';
+import '../types/analytic-source.mjs';
+import '../types/extra-condition.mjs';
+import '../types/field-filters.mjs';
+import '../types/field-operators.mjs';
+import '../types/group-with-clause.mjs';
+import '../types/order-by.mjs';
+import '../types/page-fields.mjs';
+import '../types/row-reader-mode.mjs';
+import '../types/time-dimension.mjs';
+import { hasMetricData } from '../helpers/hasMetricData.mjs';
+import { readNumeric } from '../helpers/readNumeric.mjs';
+
+const useAnalyticData = ({ getTextPrice: getTextPriceParam, } = {}) => {
+    const { getTextPrice: getTextPriceCtx } = useConvertMoneyContext();
+    const getTextPrice = getTextPriceParam ?? getTextPriceCtx;
+    const formatData = ({ value, formatter, name }) => {
+        return formatAnalyticData({ value, formatter, getTextPrice, name });
+    };
+    const computeMetric = ({ metric, previousMetric, metricKey, formatter, }) => {
+        if (!hasMetricData(metric))
+            return { value: 0, change: PLACEHOLDER_VALUE };
+        const currentValue = readNumeric(metric, metricKey);
+        const previousValue = readNumeric(previousMetric, metricKey);
+        const value = formatData({ value: currentValue, formatter, name: metricKey });
+        if (currentValue === 0 && previousValue !== 0)
+            return { value, change: -100 };
+        if (previousValue === 0)
+            return { value, change: PLACEHOLDER_VALUE };
+        const change = ((currentValue - previousValue) / previousValue) * 100;
+        return { value, change };
+    };
+    return { formatData, computeMetric };
+};
+
+export { useAnalyticData };

package/dist/esm/core/gemxql/hooks/useGemXQlPagination.d.ts

@@ -0,0 +1,17 @@
+import type { GPaginationProps } from '../../../shared/components/GPagination/GPagination';
+import { GPaginationDirection } from '../../../shared/components/GPagination/GPagination';
+export { GPaginationDirection, GPaginationProps };
+interface IUseGemXQlPaginationProps {
+    resetKey: unknown;
+    itemsPerPage: number;
+}
+interface IBuildPaginationPropsParams {
+    totalRecords: number;
+    isLoading?: boolean;
+}
+interface IUseGemXQlPaginationReturn {
+    currentPage: number;
+    offset: number;
+    buildPagination: (params: IBuildPaginationPropsParams) => GPaginationProps;
+}
+export declare const useGemXQlPagination: ({ resetKey, itemsPerPage, }: IUseGemXQlPaginationProps) => IUseGemXQlPaginationReturn;

package/dist/esm/core/gemxql/hooks/useGemXQlPagination.js

@@ -0,0 +1,47 @@
+"use client"
+import { GPaginationDirection } from '../../../shared/components/GPagination/GPagination.js';
+import { useState, useMemo, useRef, useCallback, useEffect } from 'react';
+
+const useGemXQlPagination = ({ resetKey, itemsPerPage, }) => {
+    const [currentPage, setCurrentPage] = useState(1);
+    // Serialize so object/array reset keys compare by value, not by reference.
+    const serializedResetKey = useMemo(() => {
+        if (resetKey === undefined)
+            return undefined;
+        try {
+            return JSON.stringify(resetKey);
+        }
+        catch {
+            return String(resetKey);
+        }
+    }, [resetKey]);
+    const previousResetKeyRef = useRef();
+    const shouldResetPagination = currentPage > 1 && previousResetKeyRef.current !== undefined && previousResetKeyRef.current !== serializedResetKey;
+    const effectivePage = shouldResetPagination ? 1 : currentPage;
+    const offset = (effectivePage - 1) * itemsPerPage;
+    const handlePageChange = useCallback((totalPages) => (direction) => {
+        setCurrentPage((prevPage) => {
+            const isNextPage = direction === GPaginationDirection.NEXT;
+            const nextPage = isNextPage ? prevPage + 1 : prevPage - 1;
+            return Math.min(Math.max(nextPage, 1), totalPages);
+        });
+    }, []);
+    useEffect(() => {
+        if (previousResetKeyRef.current !== serializedResetKey) {
+            previousResetKeyRef.current = serializedResetKey;
+            setCurrentPage(1);
+        }
+    }, [serializedResetKey]);
+    const buildPagination = useCallback(({ totalRecords, isLoading }) => {
+        const totalPages = Math.max(1, Math.ceil(totalRecords / itemsPerPage));
+        return {
+            currentPage: effectivePage,
+            totalPages,
+            loading: isLoading,
+            handlePageChange: handlePageChange(totalPages),
+        };
+    }, [effectivePage, itemsPerPage, handlePageChange]);
+    return { currentPage: effectivePage, offset, buildPagination };
+};
+
+export { GPaginationDirection, useGemXQlPagination };

package/dist/esm/core/gemxql/hooks/useGemXQlPagination.mjs

@@ -0,0 +1,47 @@
+"use client"
+import { GPaginationDirection } from '../../../shared/components/GPagination/GPagination.mjs';
+import { useState, useMemo, useRef, useCallback, useEffect } from 'react';
+
+const useGemXQlPagination = ({ resetKey, itemsPerPage, }) => {
+    const [currentPage, setCurrentPage] = useState(1);
+    // Serialize so object/array reset keys compare by value, not by reference.
+    const serializedResetKey = useMemo(() => {
+        if (resetKey === undefined)
+            return undefined;
+        try {
+            return JSON.stringify(resetKey);
+        }
+        catch {
+            return String(resetKey);
+        }
+    }, [resetKey]);
+    const previousResetKeyRef = useRef();
+    const shouldResetPagination = currentPage > 1 && previousResetKeyRef.current !== undefined && previousResetKeyRef.current !== serializedResetKey;
+    const effectivePage = shouldResetPagination ? 1 : currentPage;
+    const offset = (effectivePage - 1) * itemsPerPage;
+    const handlePageChange = useCallback((totalPages) => (direction) => {
+        setCurrentPage((prevPage) => {
+            const isNextPage = direction === GPaginationDirection.NEXT;
+            const nextPage = isNextPage ? prevPage + 1 : prevPage - 1;
+            return Math.min(Math.max(nextPage, 1), totalPages);
+        });
+    }, []);
+    useEffect(() => {
+        if (previousResetKeyRef.current !== serializedResetKey) {
+            previousResetKeyRef.current = serializedResetKey;
+            setCurrentPage(1);
+        }
+    }, [serializedResetKey]);
+    const buildPagination = useCallback(({ totalRecords, isLoading }) => {
+        const totalPages = Math.max(1, Math.ceil(totalRecords / itemsPerPage));
+        return {
+            currentPage: effectivePage,
+            totalPages,
+            loading: isLoading,
+            handlePageChange: handlePageChange(totalPages),
+        };
+    }, [effectivePage, itemsPerPage, handlePageChange]);
+    return { currentPage: effectivePage, offset, buildPagination };
+};
+
+export { GPaginationDirection, useGemXQlPagination };

package/dist/esm/core/gemxql/index.d.ts

@@ -0,0 +1,7 @@
+export * from './builder';
+export * from './constants';
+export * from './helpers';
+export * from './types';
+export * from './api';
+export * from './graphql';
+export * from './hooks';