Skip to content

AsyncValues

See the Async values guide for examples and configuration details.

Options

asyncValues

Can be set at: grid

Source code

asyncValues.asyncValues : boolean | object

The asyncValues option configures the AsyncValues plugin, which computes cell values asynchronously, from promises, and shows a pending and an error state per cell.

You can set the asyncValues option to one of the following:

SettingDescription
false (default)Disable the AsyncValues plugin
trueEnable the AsyncValues plugin with the defaults
An objectEnable the AsyncValues plugin and configure it

If you set the asyncValues option to an object, you can configure the following settings:

SettingPossible valuesDescription
flush'microtask' (default), 'frame', or a numberWhen settled requests are written: right after the task they settled in, once per animation frame, or after a number of milliseconds that collects results
concurrencyA number (default: 6), or InfinityThe maximum number of sources running at once (a batch counts as one); further requests stay pending until a slot frees
copyPendingAs'previous' (default) or 'empty'What copying a pending cell puts on the clipboard
saveToDataProviderfalse (default) or trueSaves each resolved value through the dataProvider onRowsUpdate callback, one updateRows() call per flush

The plugin can’t be enabled together with the nestedRows option, because NestedRows moves rows without keeping their physical indexes.

Read more:

Default: false
Since: 19.0.0
Example

// enable the `AsyncValues` plugin
asyncValues: true,
// write results once per animation frame, and run at most four requests at once
asyncValues: {
flush: 'frame',
concurrency: 4,
},

Members

DEFAULT_SETTINGS

Source code

AsyncValues.DEFAULT_SETTINGS

Returns the default settings applied when the plugin is enabled without explicit configuration.

LICENSE

Source code

AsyncValues.LICENSE

Returns the license token of the plugin, its display name, where it is checked, and the tokens it requires.

PLUGIN_KEY

Source code

AsyncValues.PLUGIN_KEY

Returns the plugin key used to identify this plugin in Handsontable settings.

PLUGIN_PRIORITY

Source code

AsyncValues.PLUGIN_PRIORITY

Returns the priority order used to determine the order in which plugins are initialized.

SETTINGS_VALIDATORS

Source code

AsyncValues.SETTINGS_VALIDATORS

Returns an object of validator functions used to type-check each settings property at runtime.

Methods

cancel

Source code

asyncValues.cancel(row, column)

Cancels the pending request of a cell, or clears its error state.

Emits: Hooks#event:afterAsyncValueCancel
Since: 19.0.0

ParamTypeDescription
rownumberVisual row index.
columnnumberVisual column index.

cancelAll

Source code

asyncValues.cancelAll()

Cancels every pending request and clears every error state.

Emits: Hooks#event:afterAsyncValueCancel
Since: 19.0.0

cancelAt

Source code

asyncValues.cancelAt(cell)

Cancels the pending request of a cell, or clears its error state, by visual coordinates, physical row, or row id (see AsyncValues#setAsyncValueAt).

Emits: Hooks#event:afterAsyncValueCancel
Since: 19.0.0

ParamTypeDescription
cellobjectThe cell.

countErrors

Source code

asyncValues.countErrors() ⇒ number

Returns the number of cells whose last request failed.

Since: 19.0.0

countPending

Source code

asyncValues.countPending() ⇒ number

Returns the number of cells that have a pending request.

Since: 19.0.0

destroy

Source code

asyncValues.destroy()

Destroys the plugin instance. Pending requests and batches are aborted, and their promises resolve as canceled with the 'disabled' reason.

disablePlugin

Source code

asyncValues.disablePlugin()

Disables the plugin functionality for this Handsontable instance. Cancels every pending request and clears every error state.

enablePlugin

Source code

asyncValues.enablePlugin()

Enables the plugin functionality for this Handsontable instance.

getAsyncState

Source code

asyncValues.getAsyncState(row, column) ⇒ object | null

Returns the state of a cell: { status: 'pending' }, { status: 'error', error, message }, or null when the cell has no pending request and no error.

Since: 19.0.0

ParamTypeDescription
rownumberVisual row index.
columnnumberVisual column index.

getAsyncStateAt

Source code

asyncValues.getAsyncStateAt(cell) ⇒ object | null

Returns the state of a cell, by visual coordinates, physical row, or row id (see AsyncValues#getAsyncState).

Since: 19.0.0

ParamTypeDescription
cellobjectThe cell.

getErrorCells

Source code

asyncValues.getErrorCells() ⇒ Array<object>

Lists the cells whose last request failed.

Since: 19.0.0

Returns: Array<object> - The cells, as { physicalRow, prop, rowId } objects.

getPendingCells

Source code

asyncValues.getPendingCells() ⇒ Array<object>

Lists the cells that have a pending request.

Since: 19.0.0

Returns: Array<object> - The cells, as { physicalRow, prop, rowId } objects.

isEnabled

Source code

asyncValues.isEnabled() ⇒ boolean

Checks if the plugin is enabled in the Handsontable settings.

isPending

Source code

asyncValues.isPending(row, column) ⇒ boolean

Checks whether a cell has a pending request.

Since: 19.0.0

ParamTypeDescription
rownumberVisual row index.
columnnumberVisual column index.

isPendingAt

Source code

asyncValues.isPendingAt(cell) ⇒ boolean

Checks whether a cell has a pending request, by visual coordinates, physical row, or row id (see AsyncValues#setAsyncValueAt).

Since: 19.0.0

ParamTypeDescription
cellobjectThe cell.

retry

Source code

asyncValues.retry(row, column) ⇒ Promise<object> | null

Starts a failed cell’s request again, with the source and the options it failed with.

Throws:

  • Error When a hook listener throws, once the cells are started.

Emits: Hooks#event:beforeAsyncValueStart, Hooks#event:afterAsyncValueStart
Since: 19.0.0

ParamTypeDescription
rownumberVisual row index.
columnnumberVisual column index.

Returns: Promise<object> | null - A promise of how the new request ended, or null when the cell has no error, or no source to retry (a plain promise, or keepSource: false).

retryAt

Source code

asyncValues.retryAt(cell) ⇒ Promise<object> | null

Starts a failed cell’s request again, by visual coordinates, physical row, or row id (see AsyncValues#retry).

Throws:

  • Error When a hook listener throws, once the cells are started.

Emits: Hooks#event:beforeAsyncValueStart, Hooks#event:afterAsyncValueStart
Since: 19.0.0

ParamTypeDescription
cellobjectThe cell.

Returns: Promise<object> | null - A promise of how the new request ended, or null.

retryErrors

Source code

asyncValues.retryErrors() ⇒ Promise<Array<object>>

Starts the requests of every failed cell again. Cells that failed in one batch are retried in batches again.

Throws:

  • Error When a hook listener throws, once the cells are started.

Emits: Hooks#event:beforeAsyncValueStart, Hooks#event:afterAsyncValueStart
Since: 19.0.0

Returns: Promise<Array<object>> - A promise of the results of the retried cells.

setAsyncValue

Source code

asyncValues.setAsyncValue(row, column, source, [options]) ⇒ Promise<object>

Starts an asynchronous computation of a cell’s value, by visual coordinates.

The cell shows the pending state until the request settles. A request already pending for the cell is canceled first, and an error state is cleared.

The returned promise resolves with { status: 'resolved' } once the plugin passes the value to the grid. A beforeChange listener or the cell’s validator can still change or reject it, and an asynchronous validator delays the write.

Throws:

  • Error When the plugin is disabled, or the coordinates point outside the grid. A hook listener’s error is thrown too, once the call has started its other cells.

Emits: Hooks#event:beforeAsyncValueStart, Hooks#event:afterAsyncValueCancel, Hooks#event:afterAsyncValueStart
Since: 19.0.0

ParamTypeDescription
rownumberVisual row index.
columnnumberVisual column index.
sourcefunction
Promise
A function that returns a promise of the value, or the promise itself. The function receives an object with the signal (an AbortSignal), row, column, physicalRow, prop, and rowId of the cell.
[options]objectoptional The request options: dependsOn, source, meta, undo, and keepSource.

Returns: Promise<object> - A promise that never rejects. It resolves with an object that describes how the request ended: { status: 'resolved', value }, { status: 'rejected', error, message }, or { status: 'canceled', reason }.

setAsyncValueAt

Source code

asyncValues.setAsyncValueAt(cell, source, [options]) ⇒ Promise<object>

Starts an asynchronous computation of a cell’s value, by visual coordinates ({ row, column }), by physical row ({ physicalRow, prop }), or by row id ({ rowId, prop }). A physical row or a row id also reaches a row that is filtered out or trimmed.

Throws:

  • Error When the plugin is disabled, or the cell does not exist. A hook listener’s error is thrown too, once the call has started its other cells.

Emits: Hooks#event:beforeAsyncValueStart, Hooks#event:afterAsyncValueCancel, Hooks#event:afterAsyncValueStart
Since: 19.0.0

ParamTypeDescription
cellobjectThe cell.
sourcefunction
Promise
A function that returns a promise of the value, or the promise itself (see AsyncValues#setAsyncValue).
[options]objectoptional The request options (see AsyncValues#setAsyncValue).

Returns: Promise<object> - A promise of how the request ended (see AsyncValues#setAsyncValue).

setAsyncValues

Source code

asyncValues.setAsyncValues(rowFrom, columnFrom, rowTo, columnTo, source, [options]) ⇒ Promise<Array<object>>

Starts an asynchronous computation for every cell of a range of visual coordinates, and renders once. The source function is called once per cell.

Throws:

  • Error When the plugin is disabled, or the range reaches outside the grid. A hook listener’s error is thrown too, once the call has started its other cells.

Emits: Hooks#event:beforeAsyncValueStart, Hooks#event:afterAsyncValueCancel, Hooks#event:afterAsyncValueStart
Since: 19.0.0

ParamTypeDescription
rowFromnumberVisual index of the first row.
columnFromnumberVisual index of the first column.
rowTonumberVisual index of the last row.
columnTonumberVisual index of the last column.
sourcefunctionA function that returns a promise of a cell’s value (see AsyncValues#setAsyncValue).
[options]objectoptional The request options, shared by every cell (see AsyncValues#setAsyncValue).

Returns: Promise<Array<object>> - A promise of the results, one per cell, in row-major order.

setAsyncValuesForRows

Source code

asyncValues.setAsyncValuesForRows(rows, prop, source, [options]) ⇒ Promise<Array<object>>

Starts an asynchronous computation of one column for many rows, by physical row or by row id. 'all' takes every row of the data, the rows that are filtered out or trimmed included. The source function is called once per cell.

Throws:

  • Error When the plugin is disabled, a row does not exist, or the column cannot hold values. A hook listener’s error is thrown too, once the call has started its other cells.

Emits: Hooks#event:beforeAsyncValueStart, Hooks#event:afterAsyncValueCancel, Hooks#event:afterAsyncValueStart
Since: 19.0.0

ParamTypeDescription
rowsstring
Array
'all', or the rows as { physicalRow } or { rowId } objects.
propstring
number
The property of the column.
sourcefunctionA function that returns a promise of a cell’s value (see AsyncValues#setAsyncValue).
[options]objectoptional The request options, shared by every cell (see AsyncValues#setAsyncValue).

Returns: Promise<Array<object>> - A promise of the results, one per row, in the order of rows.

setAsyncValuesInBatches

Source code

asyncValues.setAsyncValuesInBatches(rows, prop, source, [options]) ⇒ Promise<Array<object>>

Starts an asynchronous computation of one column for many rows, with one call of source per batch of up to batchSize cells (default 25). Rows are given as in AsyncValues#setAsyncValuesForRows.

source receives the cells’ contexts and the batch’s AbortSignal, and resolves with an array aligned with the cells: an element that is an Error rejects that cell, and a missing element rejects it with an empty message. A rejection, or an answer that is not an array, rejects every cell of the batch. Each cell settles on its own, and the batch’s signal aborts only when every cell of the batch was canceled. A batch takes one concurrency slot. A row listed twice is computed once.

Throws:

  • Error When the plugin is disabled, a row does not exist, or the column cannot hold values. A hook listener’s error is thrown too, once the call has started its other cells.

Emits: Hooks#event:beforeAsyncValueStart, Hooks#event:afterAsyncValueCancel, Hooks#event:afterAsyncValueStart
Since: 19.0.0

ParamTypeDescription
rowsstring
Array
'all', or the rows as { physicalRow } or { rowId } objects.
propstring
number
The property of the column.
sourcefunctionA function that receives the cells and a signal, and returns a promise of their values.
[options]objectoptional The request options (see AsyncValues#setAsyncValue), and batchSize.

Returns: Promise<Array<object>> - A promise of the results, one per row, in the order of rows.

updatePlugin

Source code

asyncValues.updatePlugin()

Updates the plugin’s state. This method is executed when updateSettings() is invoked with the asyncValues option. The requests keep running, because the framework wrappers send the option again on every update; a raised concurrency starts the queued sources that now fit.