handsontable 17.1.0 → 18.0.0-rc2

package/plugins/dataProvider/query/crud.d.ts

@@ -0,0 +1,265 @@
+import type { HotInstance } from '../../../core/types';
+import type { RowUpdatePayload, RowsCreatePayload } from '../dataProvider';
+/**
+ * Row id option — a property name string, a resolver function, or absent.
+ */
+type RowIdOption = string | ((rowData: object | unknown[]) => unknown) | undefined | null;
+/**
+ * A single afterChange tuple: `[visualRow, prop, oldValue, newValue]`.
+ */
+type ChangeTuple = [number, string | number, unknown, unknown];
+/**
+ * Internal per-row update payload used inside CRUD helpers (fields are optional during construction).
+ */
+type InternalRowUpdatePayload = Partial<RowUpdatePayload>;
+/**
+ * Runs `beforeRowsMutation`. Return `false` from a listener to cancel.
+ *
+ * @param {Core} hot Handsontable instance.
+ * @param {string} operation Mutation kind (`create`, `update`, or `remove`).
+ * @param {object} payload Hook payload (`RowMutationPayload` in `types/plugins/dataProvider/dataProvider.d.ts`).
+ * @returns {boolean|undefined} `false` when cancelled.
+ */
+export declare function runBeforeRowsMutation(hot: HotInstance, operation: string, payload: object): false | undefined;
+/**
+ * Runs `afterRowsMutation`.
+ *
+ * @param {Core} hot Handsontable instance.
+ * @param {string} operation Mutation kind (`create`, `update`, or `remove`).
+ * @param {object} payload Hook payload (`RowMutationPayload` in `types/plugins/dataProvider/dataProvider.d.ts`).
+ * @returns {void}
+ */
+export declare function runAfterRowsMutation(hot: HotInstance, operation: string, payload: object): void;
+/**
+ * Runs `afterRowsMutationError`.
+ *
+ * @param {Core} hot Handsontable instance.
+ * @param {string} operation Mutation kind (`create`, `update`, or `remove`).
+ * @param {Error} err Failure from the server callback.
+ * @param {object} payload Hook payload (`RowMutationPayload` in `types/plugins/dataProvider/dataProvider.d.ts`).
+ * @returns {void}
+ */
+export declare function runAfterRowsMutationError(hot: HotInstance, operation: string, err: unknown, payload: object): void;
+/**
+ * Appends a mutation onto the queue so concurrent CRUD runs sequentially.
+ *
+ * @param {{ tail: Promise<void> }} state Mutable queue tail (mutated).
+ * @param {function(): Promise<void>|void} fn Async work for one mutation.
+ * @returns {Promise<void>}
+ */
+export declare function enqueueMutation(state: {
+    tail: Promise<void>;
+}, fn: () => Promise<void> | void): Promise<void>;
+/**
+ * Resolves stable row id from a row object using `rowId` option.
+ *
+ * @param {object|Array} rowData Source row.
+ * @param {string|Function|undefined|null} rowIdOption `rowId` from config.
+ * @returns {*|undefined}
+ */
+export declare function getRowIdFromRowData(rowData: object | unknown[], rowIdOption: RowIdOption): unknown;
+/**
+ * Row id for a visual row index.
+ *
+ * @param {Core} hot Handsontable instance.
+ * @param {string|Function|undefined|null} rowIdOption `rowId` from config.
+ * @param {number} visualRow Visual row index.
+ * @returns {*|undefined}
+ */
+export declare function getRowIdByVisualRow(hot: HotInstance, rowIdOption: RowIdOption, visualRow: number): unknown;
+/**
+ * True when a value cannot be used as a server row id (`null` and `undefined` only).
+ *
+ * @param {*} id Resolved row id.
+ * @returns {boolean}
+ */
+export declare function isMissingRowId(id: unknown): boolean;
+/**
+ * Finds a visual row index for a row id.
+ *
+ * @param {Core} hot Handsontable instance.
+ * @param {string|Function|undefined|null} rowIdOption `rowId` from config.
+ * @param {*} rowId Row id.
+ * @returns {number} Visual row index or -1 when not found.
+ */
+export declare function findVisualRowById(hot: HotInstance, rowIdOption: RowIdOption, rowId: unknown): number;
+/**
+ * Collects row ids (or row snapshots) for `remove_row` alter ranges, including grouped indices.
+ *
+ * @param {Core} hot Handsontable instance.
+ * @param {string|Function|undefined|null} rowIdOption `rowId` from config.
+ * @param {number|Array|undefined|null} index Visual start index or `[[index, amount], ...]`.
+ * @param {number} amount Row count when `index` is scalar.
+ * @returns {Array<*>}
+ * @throws {Error} When `rowId` resolves to null or undefined for a row in range.
+ */
+export declare function rowIdsFromAlterRemove(hot: HotInstance, rowIdOption: RowIdOption, index: number | [number, number][] | undefined | null, amount: number): unknown[];
+/**
+ * Builds `changes` map and merged `rowData` for one visual row from Handsontable change tuples.
+ *
+ * @param {Core} hot Handsontable instance.
+ * @param {Array} rowChanges Tuples `[visualRow, prop, oldVal, newVal]` for one row.
+ * @returns {{ changesObj: object, rowData: object|Array }}
+ */
+export declare function buildChangesAndRowData(hot: HotInstance, rowChanges: ChangeTuple[]): {
+    changesObj: Record<string | number, unknown>;
+    rowData: Record<string, unknown> | unknown[];
+};
+/**
+ * Reverts optimistic cell edits after a failed server update.
+ *
+ * @param {Core} hot Handsontable instance.
+ * @param {Array} changeTuples `[visualRow, prop, oldVal, newVal][]`.
+ * @returns {void}
+ */
+export declare function revertChangeTuples(hot: HotInstance, changeTuples: ChangeTuple[]): void;
+/**
+ * Whether every changed cell passes validator when `allowInvalid` is false.
+ *
+ * @param {Core} hot Handsontable instance.
+ * @param {number} visualRow Visual row index.
+ * @param {object} changes Prop-keyed new values.
+ * @returns {Promise<boolean>}
+ */
+export declare function validateRowChanges(hot: HotInstance, visualRow: number, changes: Record<string | number, unknown>): Promise<boolean>;
+/**
+ * True when `afterChange` should not enqueue a batched `onRowsUpdate`.
+ *
+ * @param {boolean} hasOnRowsUpdate Whether `onRowsUpdate` is configured.
+ * @param {Array} changes Change list from `afterChange`.
+ * @param {string} [source] Change source.
+ * @returns {boolean}
+ */
+export declare function shouldIgnoreAfterChangeForServerUpdate(hasOnRowsUpdate: boolean, changes: ChangeTuple[] | unknown[] | null, source?: string): boolean;
+/**
+ * Filters change tuples to those with real edits and passing cell `valid` meta.
+ *
+ * @param {Core} hot Handsontable instance.
+ * @param {Array} changes `[visualRow, prop, oldVal, newVal][]`.
+ * @returns {Array} Subset safe to send to the server update path.
+ */
+export declare function filterChangesForBatchedServerUpdate(hot: HotInstance, changes: ChangeTuple[] | unknown[] | null): ChangeTuple[];
+/**
+ * Builds `{ id, changes, rowData }` payloads for programmatic `updateRows`.
+ *
+ * @param {Core} hot Handsontable instance.
+ * @param {string|Function|undefined|null} rowIdOption `rowId` from config.
+ * @param {object[]} rows Caller payloads `{ id, changes, rowData? }`.
+ * @returns {object[]}
+ */
+export declare function buildManualUpdateRowPayloads(hot: HotInstance, rowIdOption: RowIdOption, rows: InternalRowUpdatePayload[]): InternalRowUpdatePayload[];
+/**
+ * Calls `onRowsUpdate`, success/error hooks, then re-fetches or re-renders.
+ *
+ * @param {Core} hot Handsontable instance.
+ * @param {{ getOnRowsUpdate: function(): *, fetchData: function(): Promise<*>, logError: function(...*): void, onRequestFailed?: function(string, Error): void }} callbacks Callbacks for IO and logging (`getOnRowsUpdate` returns `onRowsUpdate` or a falsy value). `onRequestFailed` receives `'update'` only; when `fetchData` rejects after a successful update, the caller's `fetchData` implementation is responsible for error UI (for example [[DataProvider#fetchData]] shows a notification and rethrows).
+ * @param {object[]} rowPayloads Per-row `RowUpdatePayload` objects (`types/plugins/dataProvider/dataProvider.d.ts`).
+ * @param {object} [options] Optional flags.
+ * @param {function(): void} [options.revertOptimistic] Restores previous cell values when the request fails.
+ * @returns {Promise<void>}
+ */
+type CommitRowsUpdateCallbacks = {
+    getOnRowsUpdate: () => ((payload: object[]) => Promise<void>) | undefined;
+    fetchData: () => Promise<unknown>;
+    logError: (...args: unknown[]) => void;
+    onRequestFailed?: (kind: string, err: unknown) => void;
+};
+/**
+ *
+ */
+export declare function commitRowsUpdate(hot: HotInstance, callbacks: CommitRowsUpdateCallbacks, rowPayloads: object[], options?: {
+    revertOptimistic?: () => void;
+}): Promise<void>;
+/**
+ * Runs `beforeRowsMutation`, validates each payload row, then calls `commitRowsUpdate` for programmatic `updateRows`.
+ *
+ * @param {Core} hot Handsontable instance.
+ * @param {object} ctx Row resolution and commit.
+ * @param {function(): string|Function|undefined|null} ctx.getRowIdOption Current `rowId` config.
+ * @param {function(object[]): Promise<void>} ctx.commitRowsUpdate Commits payloads after validation.
+ * @param {object[]} rowPayloads Per-row `{ id, changes, rowData }` payloads from `buildManualUpdateRowPayloads`.
+ * @returns {Promise<void>}
+ */
+type ManualUpdateCtx = {
+    getRowIdOption: () => RowIdOption;
+    commitRowsUpdate: (payloads: InternalRowUpdatePayload[]) => Promise<void>;
+};
+/**
+ *
+ */
+export declare function runManualUpdateRowsMutation(hot: HotInstance, ctx: ManualUpdateCtx, rowPayloads: InternalRowUpdatePayload[]): Promise<void>;
+/**
+ * Groups cell changes by row, validates, then commits a single batched `onRowsUpdate`.
+ *
+ * @param {Core} hot Handsontable instance.
+ * @param {object} ctx Row resolution and commit.
+ * @param {function(): string|Function|undefined|null} ctx.getRowIdOption Current `rowId` config.
+ * @param {function(object[], object): Promise<void>} ctx.commitRowsUpdate Commits payloads (e.g. server + refetch).
+ * @param {Array} changes Filtered change tuples `[visualRow, prop, oldVal, newVal][]`.
+ * @returns {Promise<void>}
+ */
+type UpdateFromChangesCtx = {
+    getRowIdOption: () => RowIdOption;
+    commitRowsUpdate: (payloads: InternalRowUpdatePayload[], opts?: {
+        revertOptimistic?: () => void;
+    }) => Promise<void>;
+};
+/**
+ *
+ */
+export declare function runUpdateFromChanges(hot: HotInstance, ctx: UpdateFromChangesCtx, changes: ChangeTuple[]): Promise<void>;
+/**
+ * Queues create/remove server calls with before/after mutation hooks.
+ *
+ * @param {object} ctx Queue and hooks.
+ * @param {function(function(): Promise<void>|void): Promise<void>} ctx.enqueueMutation - Serializes mutations.
+ * @param {function(string, object): boolean|undefined} ctx.runBeforeRowsMutation - Returns false when the hook cancels.
+ * @param {function(string, object): void} ctx.runAfterRowsMutation - Runs the success hook.
+ * @param {function(string, Error, object): void} ctx.runAfterRowsMutationError - Runs the error hook.
+ * @param {function(...*): void} ctx.logError - Logs mutation failures.
+ * @param {function(string, Error): void} [ctx.onRequestFailed] - `'create'|'remove'` when the server callback rejects. When `onSuccess` (refetch) fails, error UI is owned by that `fetchData` implementation (not `onRequestFailed`).
+ * @param {string} operation `'create'` or `'remove'`.
+ * @param {object} payload Hook payload.
+ * @param {function(): Promise<*>} userPromiseFn Server callback invocation.
+ * @param {function(): Promise<void>|void} onSuccess Runs after success (e.g. `fetchData`).
+ * @returns {Promise<void>}
+ */
+type QueueCrudCtx = {
+    enqueueMutation: (fn: () => Promise<void>) => Promise<void>;
+    runBeforeRowsMutation: (op: string, p: object) => false | undefined;
+    runAfterRowsMutation: (op: string, p: object) => void;
+    runAfterRowsMutationError: (op: string, err: unknown, p: object) => void;
+    logError: (...args: unknown[]) => void;
+    onRequestFailed?: (op: string, err: unknown) => void;
+};
+/**
+ *
+ */
+export declare function queueCrud(ctx: QueueCrudCtx, operation: string, payload: object, userPromiseFn: () => Promise<unknown>, onSuccess: () => Promise<void> | void): Promise<void>;
+type BeforeAlterForCrudCtx = {
+    hot: HotInstance;
+    getOnRowsCreate: () => ((payload: RowsCreatePayload) => Promise<unknown> | void) | undefined;
+    getOnRowsRemove: () => ((rowIds: unknown[]) => Promise<unknown> | void) | undefined;
+    getRowIdOption: () => RowIdOption;
+    getRowId: (visualRow: number) => unknown;
+    createRows: (payload: Partial<RowsCreatePayload>) => Promise<void> | void;
+    removeRows: (rowIds: unknown[]) => Promise<void> | void;
+};
+/**
+ * Handles `beforeAlter` for server-backed row insert/remove when DataProvider CRUD is configured.
+ *
+ * @param {object} ctx Context.
+ * @param {Core} ctx.hot - Handsontable instance.
+ * @param {function(): *} ctx.getOnRowsCreate - Returns configured `onRowsCreate` when present.
+ * @param {function(): *} ctx.getOnRowsRemove - Returns configured `onRowsRemove` when present.
+ * @param {function(): string|Function|undefined|null} ctx.getRowIdOption - Returns current `rowId` setting.
+ * @param {function(number): *} ctx.getRowId - Row id for a visual index (public API).
+ * @param {function(object): Promise<void>|void} ctx.createRows - Invokes server create path.
+ * @param {function(*|*[]): Promise<void>|void} ctx.removeRows - Invokes server remove path.
+ * @param {string} action Alter action name.
+ * @param {number|Array|undefined|null} index Row index, grouped `[[index, amount], ...]`, or undefined (alter default).
+ * @param {number} amount Row count when `index` is a number.
+ * @returns {boolean|undefined} False when alter is handled here.
+ */
+export declare function handleBeforeAlterForCrud(ctx: BeforeAlterForCrudCtx, action: string, index: number | [number, number][] | undefined | null, amount: number): false | undefined;
+export {};

package/plugins/dataProvider/query/crud.js

@@ -236,7 +236,11 @@ function shouldIgnoreAfterChangeForServerUpdate(hasOnRowsUpdate, changes, source
     return false;
 }
 function filterChangesForBatchedServerUpdate(hot, changes) {
-    const real = changes.filter((c)=>c[2] !== c[3]);
+    if (!changes) {
+        return [];
+    }
+    const tuples = changes;
+    const real = tuples.filter((c)=>c[2] !== c[3]);
     if (real.length === 0) {
         return [];
     }
@@ -315,7 +319,7 @@ async function runManualUpdateRowsMutation(hot, ctx, rowPayloads) {
         if (visualRow < 0) {
             return true;
         }
-        return validateRowChanges(hot, visualRow, p.changes);
+        return validateRowChanges(hot, visualRow, p.changes ?? {});
     }));
     if (validationResults.some((ok)=>!ok)) {
         runAfterRowsMutationError(hot, 'update', new Error('Row update validation failed'), payload);
@@ -415,9 +419,9 @@ function queueCrud(ctx, operation, payload, userPromiseFn, onSuccess) {
     }
     const position = action === 'insert_row_below' ? 'below' : 'above';
     const visualIndex = index ?? (position === 'below' ? n : 0);
-    createRows({
+    void createRows({
         position,
-        referenceRowId: visualIndex >= 0 ? getRowId(visualIndex) : undefined,
+        referenceRowId: typeof visualIndex === 'number' && visualIndex >= 0 ? getRowId(visualIndex) : undefined,
         rowsAmount: typeof amount === 'number' && amount >= 1 ? amount : 1
     });
     return false;
@@ -436,7 +440,7 @@ function queueCrud(ctx, operation, payload, userPromiseFn, onSuccess) {
     if (rowIds.length === 0) {
         return;
     }
-    removeRows(rowIds);
+    void removeRows(rowIds);
     return false;
 }
 function handleBeforeAlterForCrud(ctx, action, index, amount) {

package/plugins/dataProvider/query/crud.mjs

@@ -258,7 +258,11 @@ import { DATA_PROVIDER_BATCH_UPDATE_SOURCES, DATA_PROVIDER_ERROR_UPDATE_MISSING_
  * @param {Array} changes `[visualRow, prop, oldVal, newVal][]`.
  * @returns {Array} Subset safe to send to the server update path.
  */ export function filterChangesForBatchedServerUpdate(hot, changes) {
-    const real = changes.filter((c)=>c[2] !== c[3]);
+    if (!changes) {
+        return [];
+    }
+    const tuples = changes;
+    const real = tuples.filter((c)=>c[2] !== c[3]);
     if (real.length === 0) {
         return [];
     }
@@ -296,14 +300,7 @@ import { DATA_PROVIDER_BATCH_UPDATE_SOURCES, DATA_PROVIDER_ERROR_UPDATE_MISSING_
     });
 }
 /**
- * Calls `onRowsUpdate`, success/error hooks, then re-fetches or re-renders.
  *
- * @param {Core} hot Handsontable instance.
- * @param {{ getOnRowsUpdate: function(): *, fetchData: function(): Promise<*>, logError: function(...*): void, onRequestFailed?: function(string, Error): void }} callbacks Callbacks for IO and logging (`getOnRowsUpdate` returns `onRowsUpdate` or a falsy value). `onRequestFailed` receives `'update'` only; when `fetchData` rejects after a successful update, the caller's `fetchData` implementation is responsible for error UI (for example [[DataProvider#fetchData]] shows a notification and rethrows).
- * @param {object[]} rowPayloads Per-row `RowUpdatePayload` objects (`types/plugins/dataProvider/dataProvider.d.ts`).
- * @param {object} [options] Optional flags.
- * @param {function(): void} [options.revertOptimistic] Restores previous cell values when the request fails.
- * @returns {Promise<void>}
  */ export async function commitRowsUpdate(hot, callbacks, rowPayloads, options = {}) {
     const onRowsUpdate = callbacks.getOnRowsUpdate();
     if (!isFunction(onRowsUpdate)) {
@@ -340,14 +337,7 @@ import { DATA_PROVIDER_BATCH_UPDATE_SOURCES, DATA_PROVIDER_ERROR_UPDATE_MISSING_
     }
 }
 /**
- * Runs `beforeRowsMutation`, validates each payload row, then calls `commitRowsUpdate` for programmatic `updateRows`.
  *
- * @param {Core} hot Handsontable instance.
- * @param {object} ctx Row resolution and commit.
- * @param {function(): string|Function|undefined|null} ctx.getRowIdOption Current `rowId` config.
- * @param {function(object[]): Promise<void>} ctx.commitRowsUpdate Commits payloads after validation.
- * @param {object[]} rowPayloads Per-row `{ id, changes, rowData }` payloads from `buildManualUpdateRowPayloads`.
- * @returns {Promise<void>}
  */ export async function runManualUpdateRowsMutation(hot, ctx, rowPayloads) {
     const { getRowIdOption, commitRowsUpdate: commitUpdate } = ctx;
     const payload = {
@@ -362,7 +352,7 @@ import { DATA_PROVIDER_BATCH_UPDATE_SOURCES, DATA_PROVIDER_ERROR_UPDATE_MISSING_
         if (visualRow < 0) {
             return true;
         }
-        return validateRowChanges(hot, visualRow, p.changes);
+        return validateRowChanges(hot, visualRow, p.changes ?? {});
     }));
     if (validationResults.some((ok)=>!ok)) {
         runAfterRowsMutationError(hot, 'update', new Error('Row update validation failed'), payload);
@@ -372,14 +362,7 @@ import { DATA_PROVIDER_BATCH_UPDATE_SOURCES, DATA_PROVIDER_ERROR_UPDATE_MISSING_
     await commitUpdate(rowPayloads);
 }
 /**
- * Groups cell changes by row, validates, then commits a single batched `onRowsUpdate`.
  *
- * @param {Core} hot Handsontable instance.
- * @param {object} ctx Row resolution and commit.
- * @param {function(): string|Function|undefined|null} ctx.getRowIdOption Current `rowId` config.
- * @param {function(object[], object): Promise<void>} ctx.commitRowsUpdate Commits payloads (e.g. server + refetch).
- * @param {Array} changes Filtered change tuples `[visualRow, prop, oldVal, newVal][]`.
- * @returns {Promise<void>}
  */ export async function runUpdateFromChanges(hot, ctx, changes) {
     const { getRowIdOption, commitRowsUpdate: commitFn } = ctx;
     const byRow = new Map();
@@ -430,20 +413,7 @@ import { DATA_PROVIDER_BATCH_UPDATE_SOURCES, DATA_PROVIDER_ERROR_UPDATE_MISSING_
     });
 }
 /**
- * Queues create/remove server calls with before/after mutation hooks.
  *
- * @param {object} ctx Queue and hooks.
- * @param {function(function(): Promise<void>|void): Promise<void>} ctx.enqueueMutation - Serializes mutations.
- * @param {function(string, object): boolean|undefined} ctx.runBeforeRowsMutation - Returns false when the hook cancels.
- * @param {function(string, object): void} ctx.runAfterRowsMutation - Runs the success hook.
- * @param {function(string, Error, object): void} ctx.runAfterRowsMutationError - Runs the error hook.
- * @param {function(...*): void} ctx.logError - Logs mutation failures.
- * @param {function(string, Error): void} [ctx.onRequestFailed] - `'create'|'remove'` when the server callback rejects. When `onSuccess` (refetch) fails, error UI is owned by that `fetchData` implementation (not `onRequestFailed`).
- * @param {string} operation `'create'` or `'remove'`.
- * @param {object} payload Hook payload.
- * @param {function(): Promise<*>} userPromiseFn Server callback invocation.
- * @param {function(): Promise<void>|void} onSuccess Runs after success (e.g. `fetchData`).
- * @returns {Promise<void>}
  */ export function queueCrud(ctx, operation, payload, userPromiseFn, onSuccess) {
     const { enqueueMutation: enqueue, runBeforeRowsMutation: beforeMut, runAfterRowsMutation: afterMut, runAfterRowsMutationError: afterMutErr, logError: logErr, onRequestFailed } = ctx;
     return enqueue(async ()=>{
@@ -486,9 +456,9 @@ import { DATA_PROVIDER_BATCH_UPDATE_SOURCES, DATA_PROVIDER_ERROR_UPDATE_MISSING_
     }
     const position = action === 'insert_row_below' ? 'below' : 'above';
     const visualIndex = index ?? (position === 'below' ? n : 0);
-    createRows({
+    void createRows({
         position,
-        referenceRowId: visualIndex >= 0 ? getRowId(visualIndex) : undefined,
+        referenceRowId: typeof visualIndex === 'number' && visualIndex >= 0 ? getRowId(visualIndex) : undefined,
         rowsAmount: typeof amount === 'number' && amount >= 1 ? amount : 1
     });
     return false;
@@ -507,7 +477,7 @@ import { DATA_PROVIDER_BATCH_UPDATE_SOURCES, DATA_PROVIDER_ERROR_UPDATE_MISSING_
     if (rowIds.length === 0) {
         return;
     }
-    removeRows(rowIds);
+    void removeRows(rowIds);
     return false;
 }
 /**

package/plugins/dataProvider/query/filtering.d.mts

@@ -0,0 +1 @@
+export * from './filtering.js';

package/plugins/dataProvider/query/filtering.d.ts

@@ -0,0 +1,67 @@
+import type { HotInstance } from '../../../core/types';
+import type { ColumnConditions } from '../../filters/filters';
+/**
+ * Shape of a single column entry in the DataProvider server-side filter payload.
+ * Uses `prop` (column data key) instead of a numeric column index.
+ */
+interface FilterPayloadColumn {
+    prop: string;
+    operation: string;
+    conditions: {
+        name?: string;
+        args: unknown[];
+    }[];
+}
+/**
+ * Deep-clones DataProvider server filter payload for safe return from getters (mutations do not affect plugin state).
+ *
+ * @param {Array<{ prop: string, operation: string, conditions: Array<{ name?: string, args: Array<*> }> }>|null} filters Server filter columns from query parameters, or `null`.
+ * @returns {Array<{ prop: string, operation: string, conditions: Array<{ name?: string, args: Array<*> }> }>|null}
+ */
+export declare function cloneDataProviderFiltersPayload(filters: FilterPayloadColumn[] | null): FilterPayloadColumn[] | null;
+/**
+ * Converts Filters plugin condition stack (physical column indexes) to query filters (prop = column data key).
+ * Expects the same shape as [[Filters#exportConditions]] returns.
+ *
+ * @param {Core} hot Handsontable instance.
+ * @param {Array} conditionsStack Array of { column, operation, conditions } (same shape as exportConditions).
+ * @returns {Array<{ prop: string, operation: 'conjunction'|'disjunction'|'disjunctionWithExtraCondition', conditions: Array<{ name?: string, args: Array<*> }> }>|null} Payload or null when empty.
+ */
+export declare function conditionsStackToFiltersPayload(hot: HotInstance, conditionsStack: ColumnConditions[]): FilterPayloadColumn[] | null;
+/**
+ * Converts DataProvider `fetchRows` filter payload (prop keys) back to a Filters plugin condition stack (physical columns).
+ * Inverse of [[conditionsStackToFiltersPayload]] for restoring UI state after a successful fetch.
+ *
+ * @param {object} hot Handsontable instance.
+ * @param {Array<{ prop: string, operation: string, conditions: Array<{ name?: string, args: Array<*> }> }>|null} filtersPayload Filters from [[DataProviderQueryParameters]], or `null` when no column filters.
+ * @returns {Array<{ column: number, operation: string, conditions: Array<{ name: string, args: Array<*> }> }>} Shape accepted by [[Filters#importConditions]].
+ */
+export declare function filtersPayloadToConditionsStack(hot: HotInstance, filtersPayload: FilterPayloadColumn[] | null | undefined): ColumnConditions[];
+/**
+ * When `getFetchFn()` returns a function and the Filters plugin is enabled, sets `queryParameters.filters` from
+ * [[Filters#exportConditions]] (same mapping as server-side `beforeFilter`).
+ *
+ * @param {Core} hot Handsontable instance.
+ * @param {{ filters: * }} queryParameters Target object (mutated).
+ * @param {function(): Function|undefined} getFetchFn Returns `fetchRows` or a falsy value when not configured.
+ * @returns {void}
+ */
+export declare function applyFiltersFromFiltersPluginToQueryParameters(hot: HotInstance, queryParameters: {
+    filters: FilterPayloadColumn[] | null;
+}, getFetchFn: () => Function | undefined): void;
+/**
+ * Server-backed filter: write query `filters`, reset page, refetch; return false so Filters skip client-side row trimming.
+ *
+ * @param {object} ctx Hook context.
+ * @param {Core} ctx.hot Handsontable instance.
+ * @param {function(): boolean} ctx.hasFetchFn Whether `fetchRows` is configured.
+ * @param {function(Array|null): void} ctx.applyFiltersAndRefetch Receives payload from [[conditionsStackToFiltersPayload]] (or null), updates query and refetches.
+ * @param {Array} conditionsStack Exported filter conditions (column = physical index).
+ * @returns {boolean|void} False when the server path handled the filter.
+ */
+export declare function handleBeforeFilterForServer(ctx: {
+    hot: HotInstance;
+    hasFetchFn: () => boolean;
+    applyFiltersAndRefetch: (payload: FilterPayloadColumn[] | null) => void;
+}, conditionsStack: unknown[]): boolean | void;
+export {};

package/plugins/dataProvider/query/filtering.js

@@ -86,7 +86,7 @@ function filtersPayloadToConditionsStack(hot, filtersPayload) {
             column: physicalColumn,
             operation: col.operation,
             conditions: (col.conditions || []).map((c)=>({
-                    name: c.name,
+                    name: c.name ?? '',
                     args: Array.isArray(c.args) ? [
                         ...c.args
                     ] : []

package/plugins/dataProvider/query/filtering.mjs

@@ -78,7 +78,7 @@ const FILTERS_PLUGIN_KEY = 'filters';
             column: physicalColumn,
             operation: col.operation,
             conditions: (col.conditions || []).map((c)=>({
-                    name: c.name,
+                    name: c.name ?? '',
                     args: Array.isArray(c.args) ? [
                         ...c.args
                     ] : []

package/plugins/dataProvider/query/pagination.d.mts

@@ -0,0 +1 @@
+export * from './pagination.js';

package/plugins/dataProvider/query/pagination.d.ts

@@ -0,0 +1,99 @@
+import type { HotInstance } from '../../../core/types';
+interface PaginationPluginInterface {
+    enabled?: boolean;
+    getSetting(key: string): unknown;
+    getCurrentPage?(): number;
+    getCurrentPageSize?(): number | 'auto' | undefined;
+    revertPageTo?(page: number): void;
+    revertPageSizeTo?(pageSize: number | 'auto'): void;
+}
+/**
+ * Copies enabled Pagination `pageSize` and current page into query parameters.
+ *
+ * Uses [[Pagination#getCurrentPage]] and [[Pagination#getCurrentPageSize]] when present so refetches
+ * (e.g. after sort) keep the user-selected state without calling [[Pagination#getPaginationData]]
+ * (unsafe before DataProvider registers external-pagination hooks).
+ * Falls back to `pageSize` / `initialPage` from settings when the state getters are missing (tests)
+ * or return a non-numeric value (e.g. `'auto'`).
+ *
+ * @param {{
+ *   enabled?: boolean,
+ *   getSetting: function(string): *,
+ *   getCurrentPage?: function(): number,
+ *   getCurrentPageSize?: function(): number | 'auto' | undefined,
+ * }|null|undefined} paginationPlugin Pagination plugin instance.
+ * @param {{ page: number, pageSize: number }} queryParameters Target object (mutated).
+ * @returns {void}
+ */
+export declare function applyPaginationToQueryParameters(paginationPlugin: PaginationPluginInterface | null | undefined, queryParameters: {
+    page: number;
+    pageSize: number;
+}): void;
+/**
+ * Resolves page size for external pagination fetch when UI reports `'auto'` or invalid values.
+ *
+ * @param {number | 'auto'} newPageSize Value from Pagination hook.
+ * @param {number} fallbackPageSize Default when `newPageSize` is not a positive number.
+ * @returns {number}
+ */
+export declare function normalizeExternalPaginationPageSize(newPageSize: number | 'auto', fallbackPageSize: number): number;
+/**
+ * Copies Pagination `pageSize` / `initialPage` into query parameters when the plugin is enabled.
+ *
+ * @param {Core} hot Handsontable instance.
+ * @param {{ page: number, pageSize: number }} queryParameters Target object (mutated).
+ * @returns {void}
+ */
+export declare function applyPaginationToQueryFromPlugin(hot: HotInstance, queryParameters: {
+    page: number;
+    pageSize: number;
+}): void;
+/**
+ * Row header index offset for external paged data (1-based page, page size).
+ *
+ * @param {{ page: number, pageSize: number }} queryParameters Current query parameters.
+ * @param {number} visualRowIndex Visual row index in the current page.
+ * @param {number} [fallbackPageSize] Used when `pageSize` is not a positive number.
+ * @returns {number} Global row index for headers.
+ */
+export declare function getPagedRowHeaderIndex(queryParameters: {
+    page: number;
+    pageSize: number;
+}, visualRowIndex: number, fallbackPageSize?: number): number;
+/**
+ * Loads the requested page when Pagination runs in external paged mode.
+ *
+ * @param {object} ctx Context.
+ * @param {function(): boolean} ctx.isEnabled DataProvider enabled check.
+ * @param {Core} ctx.hot Handsontable instance.
+ * @param {function(): number} ctx.getQueryPage Current 1-based page from query parameters.
+ * @param {function(number): Promise<void>} ctx.goToPage Fetch given page.
+ * @param {number} oldPage Previous 1-based page.
+ * @param {number} newPage New 1-based page.
+ * @returns {void}
+ */
+export declare function handleAfterPageChangeExternalPagination(ctx: {
+    hot: HotInstance;
+    getQueryPage: () => number;
+    goToPage: (page: number) => Promise<void>;
+}, oldPage: number, newPage: number): void;
+/**
+ * Loads page 1 with the new page size when Pagination runs in external paged mode.
+ *
+ * @param {object} ctx Context.
+ * @param {function(): boolean} ctx.isEnabled DataProvider enabled check.
+ * @param {Core} ctx.hot Handsontable instance.
+ * @param {function(): number} ctx.getQueryPage Current 1-based page.
+ * @param {function(): number} ctx.getQueryPageSize Current page size.
+ * @param {function(number): Promise<void>} ctx.setPageSize Fetch with new page size (page 1).
+ * @param {number | 'auto'} oldPageSize Previous page size.
+ * @param {number | 'auto'} newPageSize New page size.
+ * @returns {void}
+ */
+export declare function handleAfterPageSizeChangeExternalPagination(ctx: {
+    hot: HotInstance;
+    getQueryPage: () => number;
+    getQueryPageSize: () => number;
+    setPageSize: (ps: number) => Promise<void>;
+}, oldPageSize: number | 'auto', newPageSize: number | 'auto'): void;
+export {};

package/plugins/dataProvider/query/sorting.d.mts

@@ -0,0 +1 @@
+export * from './sorting.js';