@highcharts/grid-pro 2.1.1 → 2.3.0

package/es-modules/Grid/Pro/Data/DataSourceHelper.js

@@ -0,0 +1,246 @@
+/* *
+ *
+ *  Remote Data Provider class
+ *
+ *  (c) 2020-2025 Highsoft AS
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ *  Authors:
+ *  - Dawid Dragula
+ *
+ * */
+'use strict';
+import { defined } from '../../../Shared/Utilities.js';
+import T from '../../../Core/Templating.js';
+const { format } = T;
+/* *
+ *
+ *  Definitions
+ *
+ * */
+/**
+ * Mapping from Grid filter operators to standard API filter conditions.
+ */
+const filterOperatorMap = {
+    '==': 'equals',
+    '===': 'equals',
+    '!=': 'doesNotEqual',
+    '!==': 'doesNotEqual',
+    '>': 'greaterThan',
+    '>=': 'greaterThanOrEqualTo',
+    '<': 'lessThan',
+    '<=': 'lessThanOrEqualTo',
+    contains: 'contains',
+    startsWith: 'beginsWith',
+    endsWith: 'endsWith',
+    empty: 'empty'
+};
+/**
+ * Recursively extracts filter conditions from the Grid's FilterCondition
+ * structure into a flat array of API filter conditions.
+ *
+ * @param condition
+ * The filter condition from the Grid's filtering modifier.
+ *
+ * @param filterColumns
+ * The array to accumulate filter conditions into.
+ *
+ * @returns
+ * The accumulated filter conditions array.
+ */
+function extractFilterConditions(condition, filterColumns = []) {
+    if (!condition) {
+        return filterColumns;
+    }
+    if (condition.operator === 'and' || condition.operator === 'or') {
+        // Logical condition - extract from nested conditions
+        if (condition.conditions) {
+            for (const subCondition of condition.conditions) {
+                extractFilterConditions(subCondition, filterColumns);
+            }
+        }
+    }
+    else if (condition.columnId) {
+        // Single condition
+        const mappedOperator = filterOperatorMap[condition.operator] || condition.operator;
+        filterColumns.push({
+            id: condition.columnId,
+            condition: mappedOperator,
+            value: condition.value
+        });
+    }
+    return filterColumns;
+}
+/**
+ * Returns the active sortings from the query state.
+ *
+ * @param state
+ * The query state.
+ *
+ * @returns
+ * The active sortings.
+ */
+const getActiveSortings = (state) => {
+    const { currentSortings, currentSorting } = state.query.sorting;
+    return (currentSortings ?? (currentSorting ? [currentSorting] : [])).filter((sorting) => defined(sorting?.columnId) && defined(sorting.order));
+};
+const defaultTemplateVariables = {
+    page: (state) => (Math.floor(state.offset / (state.limit || 1)) + 1).toFixed(),
+    pageSize: (state) => state.limit.toFixed(),
+    offset: (state) => state.offset.toFixed(),
+    limit: (state) => state.limit.toFixed(),
+    format: () => 'js',
+    filter: (state) => {
+        const filterColumns = [];
+        const filterCondition = state.query.filtering.modifier?.options?.condition;
+        if (filterCondition) {
+            extractFilterConditions(filterCondition, filterColumns);
+        }
+        if (!filterColumns.length) {
+            return '';
+        }
+        return JSON.stringify({ columns: filterColumns });
+    },
+    sortBy: (state) => {
+        const sortings = getActiveSortings(state);
+        if (!sortings.length) {
+            return '';
+        }
+        return sortings.map((sorting) => sorting.columnId).join(',');
+    },
+    sortOrder: (state) => {
+        const sortings = getActiveSortings(state);
+        if (!sortings.length) {
+            return '';
+        }
+        const sortOrders = sortings.map((sorting) => sorting.order);
+        const uniqueOrders = Array.from(new Set(sortOrders));
+        return uniqueOrders.length === 1 ?
+            uniqueOrders[0] :
+            sortOrders.join(',');
+    }
+};
+const defaultParseResponse = async (res) => {
+    if (!res.ok) {
+        let message = `DataSourceHelper: request failed with status ${res.status} ${res.statusText}`;
+        try {
+            const body = await res.text();
+            if (body) {
+                message += ` - ${body}`;
+            }
+        }
+        catch {
+            // Ignore response body parsing errors for error responses.
+        }
+        throw new Error(message);
+    }
+    const { data, meta } = await res.json();
+    return {
+        columns: data || {},
+        totalRowCount: meta?.totalRowCount || 0,
+        rowIds: meta?.rowIds
+    };
+};
+/**
+ * Builds a URL with query parameters for fetching data from the remote server.
+ *
+ * @param options
+ * The options for building the URL.
+ *
+ * @param state
+ * The query state containing the query, offset and limit.
+ *
+ * @returns
+ * The complete URL string with all query parameters.
+ */
+export function buildUrl(options, state) {
+    const { urlTemplate, templateVariables, omitEmpty } = options;
+    const variables = {
+        ...defaultTemplateVariables,
+        ...templateVariables
+    };
+    const context = {};
+    // Populate context with template variables in form of getter functions
+    // so that only the variables that are actually used in the URL are
+    // evaluated.
+    Object.keys(variables).forEach((key) => {
+        const value = variables[key];
+        Object.defineProperty(context, key, {
+            enumerable: true,
+            get: () => value(state)
+        });
+    });
+    const res = format(urlTemplate, context);
+    if (omitEmpty ?? true) {
+        return res.replace(/&([^=&]+)=([^&]*)/g, (_, key, value) => (value ? `&${key}=${value}` : ''));
+    }
+    return res;
+}
+/**
+ * Fetches data from the remote server using the data source options.
+ *
+ * @param options
+ * The options for fetching data from the remote server.
+ *
+ * @param state
+ * The query state containing the query, offset and limit.
+ *
+ * @returns
+ * The fetched data.
+ */
+export async function dataSourceFetch(options, state) {
+    const { parseResponse = defaultParseResponse, fetchTimeout = 30000 } = options;
+    try {
+        const url = buildUrl(options, state);
+        const controller = fetchTimeout > 0 ? new AbortController() : null;
+        const externalSignal = state.signal;
+        let timeoutId;
+        if (controller && externalSignal) {
+            if (externalSignal.aborted) {
+                controller.abort();
+            }
+            else {
+                externalSignal.addEventListener('abort', () => {
+                    controller.abort();
+                }, { once: true });
+            }
+        }
+        if (controller) {
+            timeoutId = setTimeout(() => {
+                controller.abort();
+            }, fetchTimeout);
+        }
+        try {
+            const signal = controller?.signal ?? externalSignal;
+            const res = signal ?
+                await fetch(url, { signal }) :
+                await fetch(url);
+            const data = await parseResponse(res);
+            return data;
+        }
+        finally {
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+        }
+    }
+    catch (err) {
+        if (err instanceof DOMException && err.name === 'AbortError') {
+            return {
+                columns: {},
+                totalRowCount: 0,
+                rowIds: []
+            };
+        }
+        // eslint-disable-next-line no-console
+        console.error('Error fetching data from remote server.\n', err);
+        return {
+            columns: {},
+            totalRowCount: 0,
+            rowIds: []
+        };
+    }
+}

package/es-modules/Grid/Pro/Data/QuerySerializer.d.ts

@@ -0,0 +1,46 @@
+export interface QueryFingerprintInput {
+    sorting: {
+        modifier?: {
+            options?: unknown;
+        };
+    };
+    filtering: {
+        modifier?: {
+            options?: unknown;
+        };
+    };
+    pagination: {
+        enabled: boolean;
+        currentPage: number;
+        currentPageSize: number;
+    };
+}
+/**
+ * Creates a deterministic fingerprint of the current query state.
+ *
+ * @param input
+ * Minimal query-like object (duck-typed) containing sorting, filtering and
+ * pagination state.
+ */
+export declare function createQueryFingerprint(input: QueryFingerprintInput): string;
+/**
+ * Serializes a filter condition into a deterministic string.
+ *
+ * @param condition
+ * Filter condition (serializable object, callback, or primitive).
+ */
+export declare function serializeFilterCondition(condition: unknown): string;
+/**
+ * Serializes an arbitrary value into a deterministic string.
+ *
+ * @param value
+ * Value to serialize.
+ */
+export declare function serializeValue(value: unknown): string;
+/**
+ * Small deterministic hash for strings (djb2-ish), returned as base36.
+ *
+ * @param str
+ * String to hash.
+ */
+export declare function hashString(str: string): string;

package/es-modules/Grid/Pro/Data/QuerySerializer.js

@@ -0,0 +1,169 @@
+/* *
+ *
+ *  Grid Query Serializer
+ *
+ *  (c) 2020-2026 Highsoft AS
+ *
+ *  A commercial license may be required depending on use.
+ *  See www.highcharts.com/license
+ *
+ *  Authors:
+ *  - Dawid Dragula
+ *
+ * */
+'use strict';
+/* *
+ *
+ *  Functions
+ *
+ * */
+/**
+ * Creates a deterministic fingerprint of the current query state.
+ *
+ * @param input
+ * Minimal query-like object (duck-typed) containing sorting, filtering and
+ * pagination state.
+ */
+export function createQueryFingerprint(input) {
+    const sortingOptions = input.sorting.modifier?.options || null;
+    const filteringOptions = input.filtering.modifier?.options || null;
+    const paginationOptions = {
+        enabled: input.pagination.enabled,
+        currentPage: input.pagination.currentPage,
+        currentPageSize: input.pagination.currentPageSize
+    };
+    const sortingPart = serializeValue(sortingOptions);
+    const paginationPart = serializeValue(paginationOptions);
+    const filteringPart = serializeValue(filteringOptions);
+    const raw = `s=${sortingPart}|p=${paginationPart}|f=${filteringPart}`;
+    return hashString(raw);
+}
+/**
+ * Serializes function identity deterministically (name + hash of source).
+ *
+ * @param fn
+ * Function to serialize.
+ */
+function serializeFunction(fn) {
+    if (typeof fn !== 'function') {
+        return '';
+    }
+    let src = '';
+    try {
+        src = Function.prototype.toString.call(fn);
+    }
+    catch {
+        src = '';
+    }
+    return `fn:${fn.name || ''}:${hashString(src)}`;
+}
+/**
+ * Serializes a filter condition into a deterministic string.
+ *
+ * @param condition
+ * Filter condition (serializable object, callback, or primitive).
+ */
+export function serializeFilterCondition(condition) {
+    if (!condition) {
+        return '';
+    }
+    if (typeof condition === 'function') {
+        return serializeFunction(condition);
+    }
+    if (typeof condition !== 'object') {
+        return serializeValue(condition);
+    }
+    const c = condition;
+    const op = String(c.operator || '');
+    if (op === 'and' || op === 'or') {
+        const subs = Array.isArray(c.conditions) ? c.conditions : [];
+        const parts = subs
+            .map((sub) => serializeFilterCondition(sub))
+            .sort(); // Commutative -> stable
+        return `${op}(${parts.join(',')})`;
+    }
+    if (op === 'not') {
+        return `not(${serializeFilterCondition(c.condition)})`;
+    }
+    const col = serializeValue(c.columnId);
+    const val = serializeValue(c.value);
+    const ignoreCase = serializeValue(c.ignoreCase);
+    // Comparison / string condition
+    return `${op}:${col}:${val}:${ignoreCase}`;
+}
+/**
+ * Serializes an arbitrary value into a deterministic string.
+ *
+ * @param value
+ * Value to serialize.
+ */
+export function serializeValue(value) {
+    if (value === null) {
+        return 'null';
+    }
+    if (typeof value === 'undefined') {
+        return 'undef';
+    }
+    if (typeof value === 'string') {
+        // Escape to keep delimiters stable
+        return `str:${encodeURIComponent(value)}`;
+    }
+    if (typeof value === 'number') {
+        if (Number.isNaN(value)) {
+            return 'num:NaN';
+        }
+        if (value === Number.POSITIVE_INFINITY) {
+            return 'num:Infinity';
+        }
+        if (value === Number.NEGATIVE_INFINITY) {
+            return 'num:-Infinity';
+        }
+        return `num:${value}`;
+    }
+    if (typeof value === 'boolean') {
+        return value ? 'bool:1' : 'bool:0';
+    }
+    if (typeof value === 'bigint') {
+        return `big:${String(value)}`;
+    }
+    if (value instanceof Date) {
+        return `date:${value.toISOString()}`;
+    }
+    if (Array.isArray(value)) {
+        return `arr:[${value.map(serializeValue).join(',')}]`;
+    }
+    if (typeof value === 'function') {
+        const fn = value;
+        let src = '';
+        try {
+            src = Function.prototype.toString.call(fn);
+        }
+        catch {
+            src = '';
+        }
+        return `fn:${fn.name || ''}:${hashString(src)}`;
+    }
+    // Fallback: deterministic key order
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    const parts = [];
+    for (let i = 0, iEnd = keys.length; i < iEnd; ++i) {
+        const k = keys[i];
+        parts.push(`${encodeURIComponent(k)}=${serializeValue(obj[k])}`);
+    }
+    return `obj:{${parts.join(',')}}`;
+}
+/**
+ * Small deterministic hash for strings (djb2-ish), returned as base36.
+ *
+ * @param str
+ * String to hash.
+ */
+export function hashString(str) {
+    let hash = 5381;
+    for (let i = 0, iEnd = str.length; i < iEnd; ++i) {
+        hash = ((hash << 5) + hash) ^ str.charCodeAt(i);
+    }
+    // Convert to unsigned 32-bit and base36 for compactness
+    return (hash >>> 0).toString(36);
+}

package/es-modules/Grid/Pro/Data/RemoteDataProvider.d.ts

@@ -0,0 +1,187 @@
+import type { RowObject as RowObjectType, Column as DataTableColumnType, CellType as DataTableCellType } from '../../../Data/DataTable';
+import type { DataProviderOptions, RowId } from '../../Core/Data/DataProvider';
+import type { ColumnDataType } from '../../Core/Table/Column';
+import type QueryingController from '../../Core/Querying/QueryingController';
+import type { DataSourceOptions } from './DataSourceHelper';
+import { DataProvider } from '../../Core/Data/DataProvider.js';
+/**
+ * Remote data provider for the Grid.
+ *
+ * Fetches tabular data from a remote API in chunks and exposes it through the
+ * standard `DataProvider` interface used by the Grid viewport.
+ *
+ * - Caches fetched chunks (optionally with an LRU eviction policy).
+ * - Deduplicates concurrent requests for the same chunk.
+ * - Uses a query fingerprint to invalidate caches when the query changes.
+ */
+export declare class RemoteDataProvider extends DataProvider {
+    private static readonly DEFAULT_CHUNK_SIZE;
+    readonly options: RemoteDataProviderOptions;
+    /**
+     * Total row count before pagination (from API metadata `totalRowCount`).
+     */
+    private prePaginationRowCount;
+    /**
+     * Current row count after pagination (actual rows returned in the chunk).
+     * When pagination is disabled, this equals prePaginationRowCount.
+     */
+    private rowCount;
+    /**
+     * Array of column IDs that have been fetched from the remote server.
+     */
+    private columnIds;
+    /**
+     * Cached chunks are used to store the data for the chunks that have been
+     * fetched from the remote server.
+     */
+    private dataChunks;
+    /**
+     * Pending chunks are used to deduplicate concurrent requests for the same
+     * chunk.
+     */
+    private pendingChunks;
+    /**
+     * Reverse lookup map from rowId to { chunkIndex, localIndex } for O(1)
+     * lookup in getRowIndex.
+     */
+    private rowIdToChunkInfo;
+    /**
+     * Fingerprint of the last applied query; used to avoid clearing caches
+     * when the query did not actually change.
+     */
+    private lastQueryFingerprint;
+    /**
+     * Epoch used to invalidate stale in-flight requests when the query changes.
+     */
+    private requestEpoch;
+    /**
+     * Abort controllers for in-flight requests (latest-only policy).
+     */
+    private pendingControllers;
+    /**
+     * Returns the effective chunk size.
+     * When pagination is enabled, uses the page size as chunk size,
+     * so that one chunk = one page.
+     */
+    private get maxChunkSize();
+    private get requestPolicy();
+    private abortPendingRequests;
+    private getChunkForRowIndex;
+    /**
+     * Gets the chunk index for a given row index.
+     * When pagination is enabled, all rows are in chunk 0.
+     *
+     * @param rowIndex
+     * The row index passed from the grid.
+     *
+     * @returns
+     * The chunk index.
+     */
+    private getChunkIndexForRow;
+    /**
+     * Gets the local index within the cached chunk data.
+     * When pagination is enabled, rowIndex is already 0-based within the page.
+     * When disabled, need to calculate offset within the chunk.
+     *
+     * @param rowIndex
+     * The row index passed from the grid.
+     *
+     * @returns
+     * The local index within the chunk.
+     */
+    private getLocalIndexInChunk;
+    /**
+     * Evicts the least recently used chunk if the cache limit is reached.
+     * Also cleans up the reverse lookup map for evicted rowIds.
+     */
+    private evictLRUChunkIfNeeded;
+    /**
+     * Fetches a chunk from the remote server and caches it.
+     * Deduplicates concurrent requests for the same chunk.
+     *
+     * @param chunkIndex
+     * The index of the chunk to fetch.
+     *
+     * @returns
+     * The cached chunk.
+     */
+    private fetchChunk;
+    getColumnIds(): Promise<string[]>;
+    getRowId(rowIndex: number): Promise<RowId | undefined>;
+    getRowIndex(rowId: RowId): Promise<number | undefined>;
+    getRowObject(rowIndex: number): Promise<RowObjectType | undefined>;
+    getPrePaginationRowCount(): Promise<number>;
+    getRowCount(): Promise<number>;
+    getValue(columnId: string, rowIndex: number): Promise<DataTableCellType>;
+    setValue(value: DataTableCellType, columnId: string, rowId: RowId): Promise<void>;
+    /**
+     * Gets a row object from the local cache without fetching.
+     * Returns undefined if the row is not cached.
+     *
+     * @param rowIndex
+     * The row index as passed from the grid.
+     *
+     * @returns
+     * The row object or undefined if not in cache.
+     */
+    private getRowObjectFromCache;
+    getColumnDataType(columnId: string): Promise<ColumnDataType>;
+    applyQuery(): Promise<void>;
+    destroy(): void;
+}
+export interface RemoteFetchCallbackResult {
+    columns: Record<string, DataTableColumnType>;
+    totalRowCount: number;
+    rowIds?: RowId[];
+}
+export interface DataChunk {
+    index: number;
+    data: Record<string, DataTableColumnType>;
+    rowIds: RowId[];
+}
+export interface RemoteDataProviderOptions extends DataProviderOptions {
+    providerType: 'remote';
+    /**
+     * Serialized data source configuration, alternatively to `fetchCallback`.
+     */
+    dataSource?: DataSourceOptions;
+    /**
+     * Custom callback to fetch data from the remote server. Has higher priority
+     * than `dataSource`.
+     */
+    fetchCallback?: (this: RemoteDataProvider, query: QueryingController, offset: number, limit: number, signal?: AbortSignal) => Promise<RemoteFetchCallbackResult>;
+    /**
+     * Callback to persist value changes to the remote server. If not provided,
+     * cell value editing will not be possible.
+     *
+     * The callback receives the column ID, row ID and value to set.
+     */
+    setValueCallback?: (this: RemoteDataProvider, columnId: string, rowId: RowId, value: DataTableCellType) => Promise<void>;
+    /**
+     * The number of rows to fetch per chunk.
+     */
+    chunkSize?: number;
+    /**
+     * Maximum number of chunks to keep in memory. When exceeded, the least
+     * recently used (LRU) chunk is evicted. If not set, all chunks are kept.
+     */
+    chunksLimit?: number;
+    /**
+     * Request policy for rapid query changes. `latest` aborts or ignores
+     * in-flight requests so only the final query updates the cache.
+     * @default 'latest'
+     */
+    requestPolicy?: 'latest' | 'all';
+    /**
+     * The column ID that contains the stable, unique row IDs. If not
+     * provided, the row IDs will be extracted from the `result.rowIds` property
+     * if available. If `result.rowIds` is also not defined, the row IDs will
+     * default to the indices of the rows in their display order.
+     */
+    idColumn?: string;
+}
+declare module '../../Core/Data/DataProviderType' {
+    interface DataProviderTypeRegistry {
+        remote: typeof RemoteDataProvider;
+    }
+}