Usage
Signature:
final class BufferingDataProvider<K, D> implements DataProvider<K, D>
Generic Parameters
Parameter Description K Type of key D Type of data
Typescript Import Format
//This class is exported directly as module. To import it
import BufferingDataProvider= require("ojs/ojbufferingdataprovider");
For additional information visit:
Final classes in JET
Classes in JET are generally final and do not support subclassing. At the moment, final is not enforced. However, this will likely change in an upcoming JET release.
Constructor
new BufferingDataProvider(dataProvider, options)
Parameters:
Name | Type | Argument | Description |
---|---|---|---|
dataProvider |
DataProvider.<K, D> | The underlying DataProvider that provides the original data. | |
options |
BufferingDataProvider.Options.<K, D> |
<optional> |
Options for the BufferingDataProvider |
Methods
-
addEventListener(eventType: string, listener: EventListener): void
-
Add a callback function to listen for a specific event type.
Parameters:
Name Type Description eventType
string The event type to listen for. listener
EventListener The callback function that receives the event notification. -
addItem(item: Item<K, D>): void
-
Create a buffer entry for adding a row. The entry initially has a status of 'unsubmitted'.
If a "remove" entry already exists:
- If the "remove" entry does not have data, it will be changed to an "update" entry with the new data.
-
If the "remove" entry has data, it will be compared to the new data passed to this method.
If the data are the same, the "remove" entry will be removed and no new entry will be created.
If the data are different, the "remove" entry will be changed to an "update" entry with the new data.
Application can call setItemStatus to change the status of the entry to 'submitting' or 'submitted'. There can be at most one entry in 'unsubmitted' status and one entry in 'submitting' status with the same key. This allows application to keep track of additional changes to a row while submitting previous changes.
Note: Starting in 12.0.1, addItem supports passing in an item which has null key. If the key is null then a string typed v4 UUID key is generated for the key. It is expected that the application will later call setItemStatus with the newKey parameter to pass in the real key once it becomes available after commit. The newKey will then be stored in an internal map with the generated key and then when the underlying DataProvider subsequently dispatches an add mutation event which contains the new key then the BufferingDataProvider will include a remove mutation which will remove the row with the generated key. If a non-string typed or non-v4 UUID generated key is desired then please use the constructor option: keyGenerator.
Parameters:
Name Type Description item
Item.<K, D> an Item object that represents the row. - Since:
- 9.0.0
Throws:
if an "add" or "update" entry already exists for the same key.- Type
- Error
-
containsKeys(parameters : FetchByKeysParameters<K>) : Promise<ContainsKeysResults<K>>
-
Check if there are rows containing the specified keys. The resulting key map will only contain keys which were actually found.
Parameters:
Name Type Description parameters
FetchByKeysParameters contains by key parameters - Since:
- 4.2.0
Returns:
Returns Promise which resolves to ContainsKeysResults.
- Type
- Promise.<ContainsKeysResults>
Example
Check if keys 1001 and 556 are contained
let keySet = new Set(); keySet.add(1001); keySet.add(556); let value = await dataprovider.containsKeys({keys: keySet}); let results = value['results']; if (results.has(1001)) { console.log('Has key 1001'); } else if (results.has(556)) { console.log('Has key 556'); }
-
createOptimizedKeyMap(initialMap?: Map<K, D>): Map<K, D>
-
Return an empty Map which is optimized to store key value pairs
Optionally provided by certain DataProvider implementations for storing key/value pairs from the DataProvider in a performant fashion. Sometimes components will need to temporarily store a Map of keys provided by the DataProvider, for example, in the case of maintaining a Map of selected keys. Only the DataProvider is aware of the internal structure of keys such as whether they are primitives, Strings, or objects and how to do identity comparisons. Therefore, the DataProvider can optionally provide a Map implementation which can performantly store key/value pairs surfaced by the DataProvider.
Parameters:
Name Type Argument Description initialMap
Map.<any> <optional>
Optionally specify an initial map of key/values for the Map. If not specified, then return an empty Map. - Since:
- 6.2.0
Returns:
Returns a Map optimized for handling keys from the DataProvider.
- Type
- Map.<any>
Example
create empty key Map
// create optional parameter let initMap = new Map(); initMap.set('a', 'apple'); let keyMap = dataprovider.createOptimizedKeyMap(initMap);
-
createOptimizedKeySet(initialSet?: Set<K>): Set<K>
-
Return an empty Set which is optimized to store keys
Optionally provided by certain DataProvider implementations for storing keys from the DataProvider in a performant fashion. Sometimes components will need to temporarily store a Set of keys provided by the DataProvider, for example, in the case of maintaining a Set of selected keys. Only the DataProvider is aware of the internal structure of keys such as whether they are primitives, Strings, or objects and how to do identity comparisons. Therefore, the DataProvider can optionally provide a Set implementation which can performantly store keys surfaced by the DataProvider.
Parameters:
Name Type Argument Description initialSet
Set.<any> <optional>
Optionally specify an initial set of keys for the Set. If not specified, then return an empty Set. - Since:
- 6.2.0
Returns:
Returns a Set optimized for handling keys from the DataProvider.
- Type
- Set.<any>
Example
create empty key Set
// create optional initial parameter let initSet = new Set(); initSet.add('a'); let keySet = dataprovider.createOptimizedKeySet(initSet);
-
dispatchEvent(evt: Event): boolean
-
Dispatch an event and invoke any registered listeners.
Parameters:
Name Type Description event
Event The event object to dispatch. Returns:
Return false if a registered listener has cancelled the event. Return true otherwise.
- Type
- boolean
-
fetchByKeys(parameters : FetchByKeysParameters<K>) : Promise<FetchByKeysResults<K, D>>
-
Fetch rows by keys. The resulting key map will only contain keys which were actually found. Fetch can be aborted if an AbortSignal is specified when calling fetchByKeys.
Parameters:
Name Type Description parameters
FetchByKeysParameters fetch by key parameters - Since:
- 4.2.0
Returns:
Returns Promise which resolves to FetchByKeysResults.
- Type
- Promise.<FetchByKeysResults>
Examples
Fetch for keys 1001 and 556
let keySet = new Set(); keySet.add(1001); keySet.add(556); let value = await dataprovider.fetchByKeys({keys: keySet}); // get the data for key 1001 console.log(value.results.get(1001).data);
How to abort fetchByKeys
// abort on an AbortController instance will abort all requests that are associated // with the signal from that abortController. const abortController = new AbortController(); let keySet = new Set(); keySet.add(1001); keySet.add(556); // component passes AbortSignal as part of FetchByKeysParameters to fetchByKeys // on dataProvider try { let value = await dataprovider.fetchByKeys({keys: keySet, signal: abortController.signal}); } catch (err) { // if the data fetch has been aborted, retrieving data from the fetched result // will be rejected with DOMException named AbortError if (err.severity === 'info') { // if the data fetch has been aborted from a jet component as a performance concern, an AbortReason will be provided. console.log(err.message); } } // later when abort is desired, component can invoke abort() on the cached // abort controller to abort any outstanding data retrieval it requested // on asyncIterator. if (abort_is_desired) { abortController.abort(); }
-
fetchByOffset(parameters: FetchByOffsetParameters<D>): Promise<FetchByOffsetResults<K, D>>
-
Fetch rows by offset. Fetch can be aborted if an AbortSignal is specified when calling fetchByOffset.
A generic implementation of this method is available from FetchByOffsetMixin. It is for convenience and may not provide the most efficient implementation for your data provider. Classes that implement the DataProvider interface are encouraged to provide a more efficient implementation.
Parameters:
Name Type Description parameters
FetchByOffsetParameters fetch by offset parameters. If an unsupported matchBy value is included in FetchByOffsetParameters, an error will be thrown. - Since:
- 4.2.0
Returns:
Returns Promise which resolves to FetchByOffsetResults.
- Type
- Promise.<FetchByOffsetResults>
Examples
Fetch by offset 5 rows starting at index 2
let result = await dataprovider.fetchByOffset({size: 5, offset: 2}); let results = result['results']; let data = results.map(function(value) { return value['data']; }); let keys = results.map(function(value) { return value['metadata']['key']; });
How to abort fetchByOffset
// abort on an AbortController instance will abort all requests that are associated // with the signal from that abortController. const abortController = new AbortController(); // component passes AbortSignal as part of FetchByOffsetParameters to fetchByOffset // on dataProvider try { let value = await dataprovider.fetchByOffset({ size: 5, offset: 2, signal: abortController.signal }); } catch (err) { // if the data fetch has been aborted, retrieving data from the fetched result // will be rejected with DOMException named AbortError if (err.severity === 'info') { // if the data fetch has been aborted from a jet component as a performance concern, an AbortReason will be provided. console.log(err.message); } } // later when abort is desired, component can invoke abort() on the cached // abort controller to abort any outstanding data retrieval it requested // on asyncIterator. if (abort_is_desired) { abortController.abort(); }
-
fetchFirst(parameters?: FetchListParameters<D>): AsyncIterable<FetchListResult<K, D>>
-
Get an AsyncIterable object for iterating the data.
AsyncIterable contains a Symbol.asyncIterator method that returns an AsyncIterator. AsyncIterator contains a “next” method for fetching the next block of data.
The "next" method returns a promise that resolves to an object, which contains a "value" property for the data and a "done" property that is set to true when there is no more data to be fetched. The "done" property should be set to true only if there is no "value" in the result. Note that "done" only reflects whether the iterator is done at the time "next" is called. Future calls to "next" may or may not return more rows for a mutable data source.
Please see the DataProvider documentation for more information on custom implementations.
Parameters:
Name Type Argument Description params
FetchListParameters <optional>
fetch parameters - See:
-
- https://github.com/tc39/proposal-async-iteration for further information on AsyncIterable.
Returns:
AsyncIterable with FetchListResult
- Type
- AsyncIterable.<FetchListResult>
Example
Get an asyncIterator and then fetch first block of data by executing next() on the iterator. Subsequent blocks can be fetched by executing next() again.
let asyncIterator = dataprovider.fetchFirst(options)[Symbol.asyncIterator](); let result = await asyncIterator.next(); let value = result.value; let data = value.data; let keys = value.metadata.map(function(val) { return val.key; }); // true or false for done let done = result.done;
-
getCapability(capabilityName: string): any
-
Determines whether this DataProvider defines a certain feature.
Parameters:
Name Type Description capabilityName
string capability name. Defined capability names are: "dedup", "eventFiltering", "fetchByKeys", "fetchByOffset", "fetchCapability", "fetchFirst", "filter", and "sort". - Since:
- 4.2.0
Returns:
capability information or null if undefined
- If capabilityName is "dedup", returns a DedupCapability object.
- If capabilityName is "eventFiltering", returns a EventFilteringCapability object.
- If capabilityName is "fetchByKeys", returns a FetchByKeysCapability object.
- If capabilityName is "fetchByOffset", returns a FetchByOffsetCapability object.
- If capabilityName is "fetchCapability", returns a FetchCapability object. (Deprecated since 10.0.0. Use specific fetch capabilityName (fetchByKeys/fetchByOffset/fetchFirst) instead.)
- If capabilityName is "fetchFirst", returns a FetchFirstCapability object.
- If capabilityName is "filter", returns a FilterCapability object.
- If capabilityName is "sort", returns a SortCapability object.
- Type
- Object
Example
Check what kind of fetchByKeys is defined.
let capabilityInfo = dataprovider.getCapability('fetchByKeys'); if (capabilityInfo.implementation == 'iteration') { // the DataProvider supports iteration for fetchByKeys ...
-
getSubmittableItems(): Array<BufferingDataProvider.EditItem<K, D>>
-
Get the list of all submittable edit items.
Caller should call setItemStatus to change the status to "submitting" when ready to submit. Once the edit item for a key is moved to 'submitting', new edit for the same key will be tracked separately. There can be at most one "submitting" edit item and one "unsubmitted" edit item for the same key. Since we are using key to tracking edit, the key value should be immutable. We could not update the key value in "updateItem".
- Since:
- 9.0.0
Returns:
an array of all submittable edit items. Each edit item implements the EditItem interface.
- Type
- Array.<BufferingDataProvider.EditItem.<K, D>>
-
getTotalSize : {Promise.<number>}
-
Return the total number of rows in this dataprovider
Returns:
Returns a Promise which resolves to the total number of rows. -1 is unknown row count.
- Type
- Promise.<number>
Example
Get the total rows
let value = await dataprovider.getTotalSize(); if (value === -1) { // we don't know the total row count } else { // the total count console.log(value); }
-
isEmpty(): 'yes' | 'no' | 'unknown'
-
Returns a string that indicates if this data provider is empty. Valid values are:
- "yes": this data provider is empty.
- "no": this data provider is not empty.
- "unknown": it is not known if this data provider is empty until a fetch is made.
- Since:
- 4.2.0
Returns:
string that indicates if this data provider is empty
- Type
- "yes" | "no" | "unknown"
Example
Check if empty
let isEmpty = dataprovider.isEmpty(); console.log('DataProvider is empty: ' + isEmpty);
-
removeEventListener(eventType: string, listener: EventListener): void
-
Remove a listener previously registered with addEventListener.
Parameters:
Name Type Description eventType
string The event type that the listener was registered for. listener
EventListener The callback function that was registered. -
removeItem(item: ItemWithOptionalData<K, D>): void
-
Create a buffer entry for removing a row. The entry initially has a status of 'unsubmitted'.
If an "add" entry already exists, it will be deleted.
If an "update" entry already exists, it will be changed to a "remove" entry.Application can call setItemStatus to change the status of the entry to 'submitting' or 'submitted'. There can be at most one entry in 'unsubmitted' status and one entry in 'submitting' status with the same key. This allows application to keep track of additional changes to a row while submitting previous changes.
Parameters:
Name Type Description item
ItemWithOptionalData an ItemWithOptionalData object that represents the row. - Since:
- 9.0.0
Throws:
if a "remove" entry already exists for the same key.- Type
- Error
-
resetAllUnsubmittedItems
-
Reset all rows by discarding all 'unsubmitted' edit items, so that the data from the underlying DataProvider will be used.
- Since:
- 9.0.0
-
resetUnsubmittedItem(key: K): void
-
Reset a row by discarding any 'unsubmitted' edit item for the row, so that the data from the underlying DataProvider will be used.
Parameters:
Name Type Description key
K The key of the row to reset. - Since:
- 9.0.0
-
setItemStatus(editItem: BufferingDataProvider.EditItem<K, D>, newStatus: 'unsubmitted' | 'submitting' | 'submitted', error?: ItemMessage, mewKey?: K): void
-
Set the status of an edit item.
Application should set an edit item to 'submitting' before committing its change to the data source. This will prevent any new edit item with the same key from being changed to 'submitting'.
When setting an edit item from 'submitting' back to 'unsubmitted' (usually upon submission error), and there is another 'unsubmitted' entry for the same key (this happens when edit is allowed while an edit item is submitting), the error will be set on the new 'unsubmitted' entry and the current 'submitting' entry will be disposed.
when setting an edit item to 'submitted', the edit item will be removed from the buffer.
Parameters:
Name Type Argument Description editItem
BufferingDataProvider.EditItem.<K, D> The edit item to set status on. This should implement the EditItem interface and is usually one of the items returned by the getSubmittableItems method. newStatus
'unsubmitted' | 'submitting' | 'submitted' the new status of the edit item. If an edit item is marked as "submitted", it will be removed at the DataProvider's discretion. error
ItemMessage <nullable>
an optional error message. newKey
K <nullable>
an optional new key for the item. This is used in cases where addItem was called with a null key which will cause BufferingDataProvider to generate a key. Passing in the real key when it becomes available will enable BufferingDataProvider to map the real and generated keys so that a subsequent add mutation event for the real key will result in BufferingDataProvider also including a remove for the generated key. - Since:
- 9.0.0
-
updateItem(item: Item<K, D>): void
-
Create a buffer entry for updating a row. The entry initially has a status of 'unsubmitted'.
If an "add" or "update" entry already exists, the data of the entry will be changed.
Application can call setItemStatus to change the status of the entry to 'submitting' or 'submitted'. There can be at most one entry in 'unsubmitted' status and one entry in 'submitting' status with the same key. This allows application to keep track of additional changes to a row while submitting previous changes.
Parameters:
Name Type Description item
Item.<K, D> an Item object that represents the row. - Since:
- 9.0.0
Throws:
if a "remove" entry already exists for the same key.- Type
- Error
Type Definitions
-
Options<K, D>
Signature:
{ keyGenerator?: (value: Partial<D>) => K }
Properties:
Name | Type | Argument | Description |
---|---|---|---|
keyGenerator |
Function |
<optional> |
Optional keyGenerator to use when a null key is passed in for addItem(). By default, BufferingDataProvider will generate a v4 UUID string. Please use this option to supply your own key generator. The key generator function takes value as parameter and returns a key. |