AsyncValues
See the Async values guide for examples and configuration details.
Options
asyncValues
Can be set at: grid
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:
| Setting | Description |
|---|---|
false (default) | Disable the AsyncValues plugin |
true | Enable the AsyncValues plugin with the defaults |
| An object | Enable the AsyncValues plugin and configure it |
If you set the asyncValues option to an object, you can configure the following settings:
| Setting | Possible values | Description |
|---|---|---|
flush | 'microtask' (default), 'frame', or a number | When settled requests are written: right after the task they settled in, once per animation frame, or after a number of milliseconds that collects results |
concurrency | A number (default: 6), or Infinity | The 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 |
saveToDataProvider | false (default) or true | Saves 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` pluginasyncValues: true,
// write results once per animation frame, and run at most four requests at onceasyncValues: { flush: 'frame', concurrency: 4,},Members
DEFAULT_SETTINGS
AsyncValues.DEFAULT_SETTINGS
Returns the default settings applied when the plugin is enabled without explicit configuration.
LICENSE
AsyncValues.LICENSE
Returns the license token of the plugin, its display name, where it is checked, and the tokens it requires.
PLUGIN_KEY
AsyncValues.PLUGIN_KEY
Returns the plugin key used to identify this plugin in Handsontable settings.
PLUGIN_PRIORITY
AsyncValues.PLUGIN_PRIORITY
Returns the priority order used to determine the order in which plugins are initialized.
SETTINGS_VALIDATORS
AsyncValues.SETTINGS_VALIDATORS
Returns an object of validator functions used to type-check each settings property at runtime.
Methods
cancel
asyncValues.cancel(row, column)
Cancels the pending request of a cell, or clears its error state.
Emits: Hooks#event:afterAsyncValueCancel
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| row | number | Visual row index. |
| column | number | Visual column index. |
cancelAll
asyncValues.cancelAll()
Cancels every pending request and clears every error state.
Emits: Hooks#event:afterAsyncValueCancel
Since: 19.0.0
cancelAt
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
| Param | Type | Description |
|---|---|---|
| cell | object | The cell. |
countErrors
asyncValues.countErrors() ⇒ number
Returns the number of cells whose last request failed.
Since: 19.0.0
countPending
asyncValues.countPending() ⇒ number
Returns the number of cells that have a pending request.
Since: 19.0.0
destroy
asyncValues.destroy()
Destroys the plugin instance. Pending requests and batches are aborted, and their promises resolve
as canceled with the 'disabled' reason.
disablePlugin
asyncValues.disablePlugin()
Disables the plugin functionality for this Handsontable instance. Cancels every pending request and clears every error state.
enablePlugin
asyncValues.enablePlugin()
Enables the plugin functionality for this Handsontable instance.
getAsyncState
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
| Param | Type | Description |
|---|---|---|
| row | number | Visual row index. |
| column | number | Visual column index. |
getAsyncStateAt
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
| Param | Type | Description |
|---|---|---|
| cell | object | The cell. |
getErrorCells
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
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
asyncValues.isEnabled() ⇒ boolean
Checks if the plugin is enabled in the Handsontable settings.
isPending
asyncValues.isPending(row, column) ⇒ boolean
Checks whether a cell has a pending request.
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| row | number | Visual row index. |
| column | number | Visual column index. |
isPendingAt
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
| Param | Type | Description |
|---|---|---|
| cell | object | The cell. |
retry
asyncValues.retry(row, column) ⇒ Promise<object> | null
Starts a failed cell’s request again, with the source and the options it failed with.
Throws:
ErrorWhen a hook listener throws, once the cells are started.
Emits: Hooks#event:beforeAsyncValueStart, Hooks#event:afterAsyncValueStart
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| row | number | Visual row index. |
| column | number | Visual 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
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:
ErrorWhen a hook listener throws, once the cells are started.
Emits: Hooks#event:beforeAsyncValueStart, Hooks#event:afterAsyncValueStart
Since: 19.0.0
| Param | Type | Description |
|---|---|---|
| cell | object | The cell. |
Returns: Promise<object> | null - A promise of how the new request ended, or null.
retryErrors
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:
ErrorWhen 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
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:
ErrorWhen 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
| Param | Type | Description |
|---|---|---|
| row | number | Visual row index. |
| column | number | Visual column index. |
| source | function 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] | object | optional 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
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:
ErrorWhen 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
| Param | Type | Description |
|---|---|---|
| cell | object | The cell. |
| source | function Promise | A function that returns a promise of the value, or the promise itself (see AsyncValues#setAsyncValue). |
| [options] | object | optional The request options (see AsyncValues#setAsyncValue). |
Returns: Promise<object> - A promise of how the request ended (see AsyncValues#setAsyncValue).
setAsyncValues
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:
ErrorWhen 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
| Param | Type | Description |
|---|---|---|
| rowFrom | number | Visual index of the first row. |
| columnFrom | number | Visual index of the first column. |
| rowTo | number | Visual index of the last row. |
| columnTo | number | Visual index of the last column. |
| source | function | A function that returns a promise of a cell’s value (see AsyncValues#setAsyncValue). |
| [options] | object | optional 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
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:
ErrorWhen 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
| Param | Type | Description |
|---|---|---|
| rows | string Array | 'all', or the rows as { physicalRow } or { rowId } objects. |
| prop | string number | The property of the column. |
| source | function | A function that returns a promise of a cell’s value (see AsyncValues#setAsyncValue). |
| [options] | object | optional 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
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:
ErrorWhen 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
| Param | Type | Description |
|---|---|---|
| rows | string Array | 'all', or the rows as { physicalRow } or { rowId } objects. |
| prop | string number | The property of the column. |
| source | function | A function that receives the cells and a signal, and returns a promise of their values. |
| [options] | object | optional 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
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.