DataSet

Vis.js comes with a flexible DataSet, which can be used to hold and manipulate unstructured data and listen for changes in the data. The DataSet is key/value based. Data items can be added, updated and removed from the DataSet, and one can subscribe to changes in the DataSet. The data in the DataSet can be filtered and ordered. Data can be normalized when appending it to the DataSet as well.

Example

The following example shows how to use a DataSet.

// create a DataSet
var options = {};
var data = new vis.DataSet(options);

// add items
// note that the data items can contain different properties and data formats
data.add([
  {id: 1, text: 'item 1', date: new Date(2013, 6, 20), group: 1, first: true},
  {id: 2, text: 'item 2', date: '2013-06-23', group: 2},
  {id: 3, text: 'item 3', date: '2013-06-25', group: 2},
  {id: 4, text: 'item 4'}
]);

// subscribe to any change in the DataSet
data.on('*', function (event, properties, senderId) {
  console.log('event', event, properties);
});

// update an existing item
data.update({id: 2, group: 1});

// remove an item
data.remove(4);

// get all ids
var ids = data.getIds();
console.log('ids', ids);

// get a specific item
var item1 = data.get(1);
console.log('item1', item1);

// retrieve a filtered subset of the data
var items = data.get({
  filter: function (item) {
    return item.group == 1;
  }
});
console.log('filtered items', items);

Type Parameters

Item extends PartItem<IdProp>

Item type that may or may not have an id.
IdProp extends string = "id"

Name of the property that contains the id.

Hierarchy

DataSetPart<Item, IdProp>
- DataSet

Implements

DataInterface<Item, IdProp>

Index

Constructors

constructor

Properties

Accessors

Methods

Constructors

constructor

new DataSet<Item, IdProp>(options?: DataSetInitialOptions<IdProp>): DataSet<Item, IdProp>
new DataSet<Item, IdProp>(data: Item[], options?: DataSetInitialOptions<IdProp>): DataSet<Item, IdProp>

Overrides DataSetPart<Item, IdProp>.constructor
Type Parameters
- Item extends Partial<Record<IdProp, OptId>>
- IdProp extends string = "id"
Parameters
- Optional options: DataSetInitialOptions<IdProp>
  
  DataSet configuration.
Returns DataSet<Item, IdProp>
Overrides DataSetPart<Item, IdProp>.constructor
Type Parameters
- Item extends Partial<Record<IdProp, OptId>>
- IdProp extends string = "id"
Parameters
- data: Item[]
  
  An initial set of items for the new instance.
- Optional options: DataSetInitialOptions<IdProp>
  
  DataSet configuration.
Returns DataSet<Item, IdProp>

Properties

Private _addItem

_addItem: any

Add a single item. Will fail when an item with the same id already exists.

param item: A new item to be added.
returns: Added item's id. An id is generated when it is not present in the item.

Private Readonly _data

_data: any

Private _filterFields

_filterFields: any

Private Readonly _idProp

_idProp: any

Private Readonly _options

_options: any

Private _queue

_queue: any

Private _remove

_remove: any

Remove an item by its id or reference.

param id: Id of an item or the item itself.
returns: The removed item if removed, null otherwise.

Private _sort

_sort: any

Sort the provided array with items.

param items: Items to be sorted in place.
param order: A field name or custom sort function.
typeparam T: The type of the items in the items array.

Private _updateItem

_updateItem: any

Update a single item: merge with existing item. Will fail when the item has no id, or when there does not exist an item with the same id.

param update: The new item
returns: The id of the updated item.

Optional flush

flush?: (() => void)

Type declaration

- (): void
- Flush all queued calls.
  
  Returns void

length

length: number

The number of items.

subscribe: { (event: "*", callback: (<N>(name: N, payload: EventPayloads<Item, IdProp>[N], senderId?: null | Id) => void)): void; (event: "add", callback: ((name: "add", payload: null | AddEventPayload, senderId?: null | Id) => void)): void; (event: "remove", callback: ((name: "remove", payload: null | RemoveEventPayload<Item, IdProp>, senderId?: null | Id) => void)): void; (event: "update", callback: ((name: "update", payload: null | UpdateEventPayload<Item, IdProp>, senderId?: null | Id) => void)): void }

Type declaration

- (event: "*", callback: (<N>(name: N, payload: EventPayloads<Item, IdProp>[N], senderId?: null | Id) => void)): void
- (event: "add", callback: ((name: "add", payload: null | AddEventPayload, senderId?: null | Id) => void)): void
- (event: "remove", callback: ((name: "remove", payload: null | RemoveEventPayload<Item, IdProp>, senderId?: null | Id) => void)): void
- (event: "update", callback: ((name: "update", payload: null | UpdateEventPayload<Item, IdProp>, senderId?: null | Id) => void)): void
- inheritdoc
  Parameters
  - event: "*"
  - callback: (<N>(name: N, payload: EventPayloads<Item, IdProp>[N], senderId?: null | Id) => void)
    - - <N>(name: N, payload: EventPayloads<Item, IdProp>[N], senderId?: null | Id): void
      - Type Parameters
        N extends keyof EventCallbacks<Item, IdProp>
        Parameters
        name: N
        
        The name of the event (EventName).
        
        payload: EventPayloads<Item, IdProp>[N]
        
        Data about the items affected by this event.
        
        Optional senderId: null | Id
        
        A senderId, optionally provided by the application code which triggered the event. If senderId is not provided, the argument will be null.
        
        Returns void
  Returns void
- inheritdoc
  Parameters
  - event: "add"
  - callback: ((name: "add", payload: null | AddEventPayload, senderId?: null | Id) => void)
    - - (name: "add", payload: null | AddEventPayload, senderId?: null | Id): void
      - Parameters
        name: "add"
        
        The name of the event (EventName).
        
        payload: null | AddEventPayload
        
        Data about the items affected by this event.
        
        Optional senderId: null | Id
        
        A senderId, optionally provided by the application code which triggered the event. If senderId is not provided, the argument will be null.
        
        Returns void
  Returns void
- inheritdoc
  Parameters
  - event: "remove"
  - callback: ((name: "remove", payload: null | RemoveEventPayload<Item, IdProp>, senderId?: null | Id) => void)
    - - (name: "remove", payload: null | RemoveEventPayload<Item, IdProp>, senderId?: null | Id): void
      - Parameters
        name: "remove"
        
        The name of the event (EventName).
        
        payload: null | RemoveEventPayload<Item, IdProp>
        
        Data about the items affected by this event.
        
        Optional senderId: null | Id
        
        A senderId, optionally provided by the application code which triggered the event. If senderId is not provided, the argument will be null.
        
        Returns void
  Returns void
- inheritdoc
  Parameters
  - event: "update"
  - callback: ((name: "update", payload: null | UpdateEventPayload<Item, IdProp>, senderId?: null | Id) => void)
    - - (name: "update", payload: null | UpdateEventPayload<Item, IdProp>, senderId?: null | Id): void
      - Parameters
        name: "update"
        
        The name of the event (EventName).
        
        payload: null | UpdateEventPayload<Item, IdProp>
        
        Data about the items affected by this event.
        
        Optional senderId: null | Id
        
        A senderId, optionally provided by the application code which triggered the event. If senderId is not provided, the argument will be null.
        
        Returns void
  Returns void

unsubscribe

unsubscribe: { (event: "*", callback: (<N>(name: N, payload: EventPayloads<Item, IdProp>[N], senderId?: null | Id) => void)): void; (event: "add", callback: ((name: "add", payload: null | AddEventPayload, senderId?: null | Id) => void)): void; (event: "remove", callback: ((name: "remove", payload: null | RemoveEventPayload<Item, IdProp>, senderId?: null | Id) => void)): void; (event: "update", callback: ((name: "update", payload: null | UpdateEventPayload<Item, IdProp>, senderId?: null | Id) => void)): void }

Type declaration

- (event: "*", callback: (<N>(name: N, payload: EventPayloads<Item, IdProp>[N], senderId?: null | Id) => void)): void
- (event: "add", callback: ((name: "add", payload: null | AddEventPayload, senderId?: null | Id) => void)): void
- (event: "remove", callback: ((name: "remove", payload: null | RemoveEventPayload<Item, IdProp>, senderId?: null | Id) => void)): void
- (event: "update", callback: ((name: "update", payload: null | UpdateEventPayload<Item, IdProp>, senderId?: null | Id) => void)): void
- inheritdoc
  Parameters
  - event: "*"
  - callback: (<N>(name: N, payload: EventPayloads<Item, IdProp>[N], senderId?: null | Id) => void)
    - - <N>(name: N, payload: EventPayloads<Item, IdProp>[N], senderId?: null | Id): void
      - Type Parameters
        N extends keyof EventCallbacks<Item, IdProp>
        Parameters
        name: N
        
        The name of the event (EventName).
        
        payload: EventPayloads<Item, IdProp>[N]
        
        Data about the items affected by this event.
        
        Optional senderId: null | Id
        
        A senderId, optionally provided by the application code which triggered the event. If senderId is not provided, the argument will be null.
        
        Returns void
  Returns void
- inheritdoc
  Parameters
  - event: "add"
  - callback: ((name: "add", payload: null | AddEventPayload, senderId?: null | Id) => void)
    - - (name: "add", payload: null | AddEventPayload, senderId?: null | Id): void
      - Parameters
        name: "add"
        
        The name of the event (EventName).
        
        payload: null | AddEventPayload
        
        Data about the items affected by this event.
        
        Optional senderId: null | Id
        
        A senderId, optionally provided by the application code which triggered the event. If senderId is not provided, the argument will be null.
        
        Returns void
  Returns void
- inheritdoc
  Parameters
  - event: "remove"
  - callback: ((name: "remove", payload: null | RemoveEventPayload<Item, IdProp>, senderId?: null | Id) => void)
    - - (name: "remove", payload: null | RemoveEventPayload<Item, IdProp>, senderId?: null | Id): void
      - Parameters
        name: "remove"
        
        The name of the event (EventName).
        
        payload: null | RemoveEventPayload<Item, IdProp>
        
        Data about the items affected by this event.
        
        Optional senderId: null | Id
        
        A senderId, optionally provided by the application code which triggered the event. If senderId is not provided, the argument will be null.
        
        Returns void
  Returns void
- inheritdoc
  Parameters
  - event: "update"
  - callback: ((name: "update", payload: null | UpdateEventPayload<Item, IdProp>, senderId?: null | Id) => void)
    - - (name: "update", payload: null | UpdateEventPayload<Item, IdProp>, senderId?: null | Id): void
      - Parameters
        name: "update"
        
        The name of the event (EventName).
        
        payload: null | UpdateEventPayload<Item, IdProp>
        
        Data about the items affected by this event.
        
        Optional senderId: null | Id
        
        A senderId, optionally provided by the application code which triggered the event. If senderId is not provided, the argument will be null.
        
        Returns void
  Returns void

Accessors

idProp

get idProp(): IdProp

Implementation of DataInterface.idProp

The key of id property.

Returns IdProp

testLeakData

get testLeakData(): Map<Id, FullItem<Item, IdProp>>

Returns Map<Id, FullItem<Item, IdProp>>

testLeakIdProp

get testLeakIdProp(): IdProp

Returns IdProp

testLeakOptions

get testLeakOptions(): DataSetInitialOptions<IdProp>

Returns DataSetInitialOptions<IdProp>

testLeakQueue

get testLeakQueue(): null | Queue<this>
set testLeakQueue(v: null | Queue<this>): void

Returns null | Queue<this>
Parameters
- v: null | Queue<this>
Returns void

testLeakSubscribers

get testLeakSubscribers(): any

Inherited from DataSetPart.testLeakSubscribers
Returns any

Methods

Protected _trigger

_trigger(event: "add", payload: AddEventPayload, senderId?: null | Id): void
_trigger(event: "update", payload: UpdateEventPayload<Item, IdProp>, senderId?: null | Id): void
_trigger(event: "remove", payload: RemoveEventPayload<Item, IdProp>, senderId?: null | Id): void

Inherited from DataSetPart._trigger
Parameters
- event: "add"
- payload: AddEventPayload
- Optional senderId: null | Id
Returns void
Inherited from DataSetPart._trigger
Parameters
- event: "update"
- payload: UpdateEventPayload<Item, IdProp>
- Optional senderId: null | Id
Returns void
Inherited from DataSetPart._trigger
Parameters
- event: "remove"
- payload: RemoveEventPayload<Item, IdProp>
- Optional senderId: null | Id
Returns void

add

add(data: Item | Item[], senderId?: null | Id): (string | number)[]

Add a data item or an array with items.
After the items are added to the DataSet, the DataSet will trigger an event add. When a senderId is provided, this id will be passed with the triggered event to all subscribers.

Example
```
// create a DataSet
const data = new vis.DataSet()

// add items
const ids = data.add([
  { id: 1, text: 'item 1' },
  { id: 2, text: 'item 2' },
  { text: 'item without an id' }
])

console.log(ids) // [1, 2, '<UUIDv4>']
```
throws
When an item with the same id as any of the added items already exists.
Parameters
- data: Item | Item[]
  
  Items to be added (ids will be generated if missing).
- Optional senderId: null | Id
  
  Sender id.
Returns (string | number)[]
addedIds - Array with the ids (generated if not present) of the added items.

clear

clear(senderId?: null | Id): Id[]

Clear the entire data set.

After the items are removed, the DataSet will trigger an event remove for all removed items. When a senderId is provided, this id will be passed with the triggered event to all subscribers.

Parameters
- Optional senderId: null | Id
  
  Sender id.
Returns Id[]
removedIds - The ids of all removed items.

distinct

distinct<T>(prop: T): Item[T][]
distinct(prop: string): unknown[]

Type Parameters
- T extends string | number | symbol
Parameters
- prop: T
Returns Item[T][]
Parameters
- prop: string
Returns unknown[]

forEach

forEach(callback: ((item: Item, id: Id) => void), options?: DataInterfaceForEachOptions<Item>): void

Implementation of DataInterface.forEach

Execute a callback function for each item.

remarks
No guarantee is given about the order of iteration unless an ordering function is supplied.

Parameters
- callback: ((item: Item, id: Id) => void)
  
  Executed in similar fashion to Array.forEach callback, but instead of item, index, array receives item, id.
  - - (item: Item, id: Id): void
    - Parameters
      - item: Item
      - id: Id
      Returns void
- Optional options: DataInterfaceForEachOptions<Item>
  
  Options to specify iteration details.
Returns void

get

get(): FullItem<Item, IdProp>[]
get(options: DataInterfaceGetOptionsArray<Item>): FullItem<Item, IdProp>[]
get(options: DataInterfaceGetOptionsObject<Item>): Record<Id, FullItem<Item, IdProp>>
get(options: DataInterfaceGetOptions<Item>): FullItem<Item, IdProp>[] | Record<Id, FullItem<Item, IdProp>>
get(id: Id): null | FullItem<Item, IdProp>
get(id: Id, options: DataInterfaceGetOptionsArray<Item>): null | FullItem<Item, IdProp>
get(id: Id, options: DataInterfaceGetOptionsObject<Item>): Record<Id, FullItem<Item, IdProp>>
get(id: Id, options: DataInterfaceGetOptions<Item>): null | FullItem<Item, IdProp> | Record<Id, FullItem<Item, IdProp>>
get(ids: Id[]): FullItem<Item, IdProp>[]
get(ids: Id[], options: DataInterfaceGetOptionsArray<Item>): FullItem<Item, IdProp>[]
get(ids: Id[], options: DataInterfaceGetOptionsObject<Item>): Record<Id, FullItem<Item, IdProp>>
get(ids: Id[], options: DataInterfaceGetOptions<Item>): FullItem<Item, IdProp>[] | Record<Id, FullItem<Item, IdProp>>
get(ids: Id | Id[], options?: DataInterfaceGetOptions<Item>): null | FullItem<Item, IdProp> | FullItem<Item, IdProp>[] | Record<Id, FullItem<Item, IdProp>>

Implementation of DataInterface.get

Get all the items.

inheritdoc
Returns FullItem<Item, IdProp>[]
An array containing all the items.
Implementation of DataInterface.get

Get all the items.

inheritdoc
Parameters
- options: DataInterfaceGetOptionsArray<Item>
  
  Additional options.
Returns FullItem<Item, IdProp>[]
An array containing requested items.
Implementation of DataInterface.get

Get all the items.

inheritdoc
Parameters
- options: DataInterfaceGetOptionsObject<Item>
  
  Additional options.
Returns Record<Id, FullItem<Item, IdProp>>
An object map of items (may be an empty object if there are no items).
Implementation of DataInterface.get

Get all the items.

inheritdoc
Parameters
- options: DataInterfaceGetOptions<Item>
  
  Additional options.
Returns FullItem<Item, IdProp>[] | Record<Id, FullItem<Item, IdProp>>
An array containing requested items or if requested an object map of items (may be an empty object if there are no items).
Implementation of DataInterface.get

Get one item.

inheritdoc
Parameters
- id: Id
  
  The id of the item.
Returns null | FullItem<Item, IdProp>
The item or null if the id doesn't correspond to any item.
Implementation of DataInterface.get

Get one item.

inheritdoc
Parameters
- id: Id
  
  The id of the item.
- options: DataInterfaceGetOptionsArray<Item>
  
  Additional options.
Returns null | FullItem<Item, IdProp>
The item or null if the id doesn't correspond to any item.
Implementation of DataInterface.get

Get one item.

inheritdoc
Parameters
- id: Id
  
  The id of the item.
- options: DataInterfaceGetOptionsObject<Item>
  
  Additional options.
Returns Record<Id, FullItem<Item, IdProp>>
An object map of items (may be an empty object if no item was found).
Implementation of DataInterface.get

Get one item.

inheritdoc
Parameters
- id: Id
  
  The id of the item.
- options: DataInterfaceGetOptions<Item>
  
  Additional options.
Returns null | FullItem<Item, IdProp> | Record<Id, FullItem<Item, IdProp>>
The item if found or null otherwise. If requested an object map with 0 to 1 items.
Implementation of DataInterface.get

Get multiple items.

inheritdoc
Parameters
- ids: Id[]
  
  An array of requested ids.
Returns FullItem<Item, IdProp>[]
An array of found items (ids that do not correspond to any item are omitted).
Implementation of DataInterface.get

Get multiple items.

inheritdoc
Parameters
- ids: Id[]
  
  An array of requested ids.
- options: DataInterfaceGetOptionsArray<Item>
  
  Additional options.
Returns FullItem<Item, IdProp>[]
An array of found items (ids that do not correspond to any item are omitted).
Implementation of DataInterface.get

Get multiple items.

inheritdoc
Parameters
- ids: Id[]
  
  An array of requested ids.
- options: DataInterfaceGetOptionsObject<Item>
  
  Additional options.
Returns Record<Id, FullItem<Item, IdProp>>
An object map of items (may be an empty object if no item was found).
Implementation of DataInterface.get

Get multiple items.

inheritdoc
Parameters
- ids: Id[]
  
  An array of requested ids.
- options: DataInterfaceGetOptions<Item>
  
  Additional options.
Returns FullItem<Item, IdProp>[] | Record<Id, FullItem<Item, IdProp>>
An array of found items (ids that do not correspond to any item are omitted). If requested an object map of items (may be an empty object if no item was found).
Implementation of DataInterface.get

Get items.

inheritdoc
Parameters
- ids: Id | Id[]
  
  Id or ids to be returned.
- Optional options: DataInterfaceGetOptions<Item>
  
  Options to specify iteration details.
Returns null | FullItem<Item, IdProp> | FullItem<Item, IdProp>[] | Record<Id, FullItem<Item, IdProp>>
The items (format is determined by ids (single or array) and the options.

getDataSet

getDataSet(): DataSet<Item, IdProp>

Implementation of DataInterface.getDataSet

Get the DataSet to which the instance implementing this interface is connected. In case there is a chain of multiple DataViews, the root DataSet of this chain is returned.

Returns DataSet<Item, IdProp>
The data set that actually contains the data.

getIds

getIds(options?: DataInterfaceGetIdsOptions<Item>): Id[]

Implementation of DataInterface.getIds

Get ids of items.

remarks
No guarantee is given about the order of returned ids unless an ordering function is supplied.

Parameters
- Optional options: DataInterfaceGetIdsOptions<Item>
  
  Additional configuration.
Returns Id[]
An array of requested ids.

map

map<T>(callback: ((item: Item, id: Id) => T), options?: DataInterfaceMapOptions<Item, T>): T[]

Implementation of DataInterface.map

Map each item into different item and return them as an array.

remarks
No guarantee is given about the order of iteration even if ordering function is supplied (the items are sorted after the mapping).

Type Parameters
- T
Parameters
- callback: ((item: Item, id: Id) => T)
  
  Array.map-like callback, but only with the first two params.
  - - (item: Item, id: Id): T
    - Parameters
      - item: Item
      - id: Id
      Returns T
- Optional options: DataInterfaceMapOptions<Item, T>
  
  Options to specify iteration details.
Returns T[]
The mapped items.

max

max(field: keyof Item): null | Item

Find the item with maximum value of a specified field.

Parameters
- field: keyof Item
  
  Name of the property that should be searched for max value.
Returns null | Item
Item containing max value, or null if no items.

min

min(field: keyof Item): null | Item

Find the item with minimum value of a specified field.

Parameters
- field: keyof Item
  
  Name of the property that should be searched for min value.
Returns null | Item
Item containing min value, or null if no items.

off

off(event: "*", callback: (<N>(name: N, payload: EventPayloads<Item, IdProp>[N], senderId?: null | Id) => void)): void
off(event: "add", callback: ((name: "add", payload: null | AddEventPayload, senderId?: null | Id) => void)): void
off(event: "remove", callback: ((name: "remove", payload: null | RemoveEventPayload<Item, IdProp>, senderId?: null | Id) => void)): void
off(event: "update", callback: ((name: "update", payload: null | UpdateEventPayload<Item, IdProp>, senderId?: null | Id) => void)): void

Implementation of DataInterface.off
Inherited from DataSetPart.off

Remove a universal event listener.

inheritdoc
Parameters
- event: "*"
  
  Event name.
- callback: (<N>(name: N, payload: EventPayloads<Item, IdProp>[N], senderId?: null | Id) => void)
  
  Callback function.
  - - <N>(name: N, payload: EventPayloads<Item, IdProp>[N], senderId?: null | Id): void
    - Type Parameters
      - N extends keyof EventCallbacks<Item, IdProp>
      Parameters
      - name: N
        
        The name of the event (EventName).
      - payload: EventPayloads<Item, IdProp>[N]
        
        Data about the items affected by this event.
      - Optional senderId: null | Id
        
        A senderId, optionally provided by the application code which triggered the event. If senderId is not provided, the argument will be null.
      Returns void
Returns void
Implementation of DataInterface.off
Inherited from DataSetPart.off

Remove an add event listener.

inheritdoc
Parameters
- event: "add"
  
  Event name.
- callback: ((name: "add", payload: null | AddEventPayload, senderId?: null | Id) => void)
  
  Callback function.
  - - (name: "add", payload: null | AddEventPayload, senderId?: null | Id): void
    - Parameters
      - name: "add"
        
        The name of the event (EventName).
      - payload: null | AddEventPayload
        
        Data about the items affected by this event.
      - Optional senderId: null | Id
        
        A senderId, optionally provided by the application code which triggered the event. If senderId is not provided, the argument will be null.
      Returns void
Returns void
Implementation of DataInterface.off
Inherited from DataSetPart.off

Remove a remove event listener.

inheritdoc
Parameters
- event: "remove"
  
  Event name.
- callback: ((name: "remove", payload: null | RemoveEventPayload<Item, IdProp>, senderId?: null | Id) => void)
  
  Callback function.
  - - (name: "remove", payload: null | RemoveEventPayload<Item, IdProp>, senderId?: null | Id): void
    - Parameters
      - name: "remove"
        
        The name of the event (EventName).
      - payload: null | RemoveEventPayload<Item, IdProp>
        
        Data about the items affected by this event.
      - Optional senderId: null | Id
        
        A senderId, optionally provided by the application code which triggered the event. If senderId is not provided, the argument will be null.
      Returns void
Returns void
Implementation of DataInterface.off
Inherited from DataSetPart.off

Remove an update event listener.

inheritdoc
Parameters
- event: "update"
  
  Event name.
- callback: ((name: "update", payload: null | UpdateEventPayload<Item, IdProp>, senderId?: null | Id) => void)
  
  Callback function.
  - - (name: "update", payload: null | UpdateEventPayload<Item, IdProp>, senderId?: null | Id): void
    - Parameters
      - name: "update"
        
        The name of the event (EventName).
      - payload: null | UpdateEventPayload<Item, IdProp>
        
        Data about the items affected by this event.
      - Optional senderId: null | Id
        
        A senderId, optionally provided by the application code which triggered the event. If senderId is not provided, the argument will be null.
      Returns void
Returns void

on

on(event: "*", callback: (<N>(name: N, payload: EventPayloads<Item, IdProp>[N], senderId?: null | Id) => void)): void
on(event: "add", callback: ((name: "add", payload: null | AddEventPayload, senderId?: null | Id) => void)): void
on(event: "remove", callback: ((name: "remove", payload: null | RemoveEventPayload<Item, IdProp>, senderId?: null | Id) => void)): void
on(event: "update", callback: ((name: "update", payload: null | UpdateEventPayload<Item, IdProp>, senderId?: null | Id) => void)): void

Implementation of DataInterface.on
Inherited from DataSetPart.on

Add a universal event listener.

remarks
The * event is triggered when any of the events add, update, and remove occurs.

Parameters
- event: "*"
  
  Event name.
- callback: (<N>(name: N, payload: EventPayloads<Item, IdProp>[N], senderId?: null | Id) => void)
  
  Callback function.
  - - <N>(name: N, payload: EventPayloads<Item, IdProp>[N], senderId?: null | Id): void
    - Type Parameters
      - N extends keyof EventCallbacks<Item, IdProp>
      Parameters
      - name: N
        
        The name of the event (EventName).
      - payload: EventPayloads<Item, IdProp>[N]
        
        Data about the items affected by this event.
      - Optional senderId: null | Id
        
        A senderId, optionally provided by the application code which triggered the event. If senderId is not provided, the argument will be null.
      Returns void
Returns void
Implementation of DataInterface.on
Inherited from DataSetPart.on

Add an add event listener.

remarks
The add event is triggered when an item or a set of items is added, or when an item is updated while not yet existing.

Parameters
- event: "add"
  
  Event name.
- callback: ((name: "add", payload: null | AddEventPayload, senderId?: null | Id) => void)
  
  Callback function.
  - - (name: "add", payload: null | AddEventPayload, senderId?: null | Id): void
    - Parameters
      - name: "add"
        
        The name of the event (EventName).
      - payload: null | AddEventPayload
        
        Data about the items affected by this event.
      - Optional senderId: null | Id
        
        A senderId, optionally provided by the application code which triggered the event. If senderId is not provided, the argument will be null.
      Returns void
Returns void
Implementation of DataInterface.on
Inherited from DataSetPart.on

Add a remove event listener.

remarks
The remove event is triggered when an item or a set of items is removed.

Parameters
- event: "remove"
  
  Event name.
- callback: ((name: "remove", payload: null | RemoveEventPayload<Item, IdProp>, senderId?: null | Id) => void)
  
  Callback function.
  - - (name: "remove", payload: null | RemoveEventPayload<Item, IdProp>, senderId?: null | Id): void
    - Parameters
      - name: "remove"
        
        The name of the event (EventName).
      - payload: null | RemoveEventPayload<Item, IdProp>
        
        Data about the items affected by this event.
      - Optional senderId: null | Id
        
        A senderId, optionally provided by the application code which triggered the event. If senderId is not provided, the argument will be null.
      Returns void
Returns void
Implementation of DataInterface.on
Inherited from DataSetPart.on

Add an update event listener.

remarks
The update event is triggered when an existing item or a set of existing items is updated.

Parameters
- event: "update"
  
  Event name.
- callback: ((name: "update", payload: null | UpdateEventPayload<Item, IdProp>, senderId?: null | Id) => void)
  
  Callback function.
  - - (name: "update", payload: null | UpdateEventPayload<Item, IdProp>, senderId?: null | Id): void
    - Parameters
      - name: "update"
        
        The name of the event (EventName).
      - payload: null | UpdateEventPayload<Item, IdProp>
        
        Data about the items affected by this event.
      - Optional senderId: null | Id
        
        A senderId, optionally provided by the application code which triggered the event. If senderId is not provided, the argument will be null.
      Returns void
Returns void

remove

remove(id: Id | Item | (Id | Item)[], senderId?: null | Id): Id[]

Remove an item or multiple items by “reference” (only the id is used) or by id.
The method ignores removal of non-existing items, and returns an array containing the ids of the items which are actually removed from the DataSet.

After the items are removed, the DataSet will trigger an event remove for the removed items. When a senderId is provided, this id will be passed with the triggered event to all subscribers.

Example
```
// create a DataSet
const data = new vis.DataSet([
  { id: 1, text: 'item 1' },
  { id: 2, text: 'item 2' },
  { id: 3, text: 'item 3' }
])

// remove items
const ids = data.remove([2, { id: 3 }, 4])

console.log(ids) // [2, 3]
```
Parameters
- id: Id | Item | (Id | Item)[]
  
  One or more items or ids of items to be removed.
- Optional senderId: null | Id
  
  Sender id.
Returns Id[]
The ids of the removed items.

setOptions

setOptions(options?: DataSetOptions): void

Set new options.

Parameters
- Optional options: DataSetOptions
  
  The new options.
Returns void

stream

stream(ids?: Iterable<Id>): DataStream<Item>

Implementation of DataInterface.stream

Stream.

Parameters
- Optional ids: Iterable<Id>
  
  Ids of the items to be included in this stream (missing are ignored), all if omitted.
Returns DataStream<Item>
The data stream for this data set.

update

update(data: DeepPartial<Item> | DeepPartial<Item>[], senderId?: null | Id): Id[]

Update existing items. When an item does not exist, it will be created.
remarks
The provided properties will be merged in the existing item. When an item does not exist, it will be created.

After the items are updated, the DataSet will trigger an event add for the added items, and an event update. When a senderId is provided, this id will be passed with the triggered event to all subscribers.

Example
```
// create a DataSet
const data = new vis.DataSet([
  { id: 1, text: 'item 1' },
  { id: 2, text: 'item 2' },
  { id: 3, text: 'item 3' }
])

// update items
const ids = data.update([
  { id: 2, text: 'item 2 (updated)' },
  { id: 4, text: 'item 4 (new)' }
])

console.log(ids) // [2, 4]
```
Warning for TypeScript users

This method may introduce partial items into the data set. Use add or updateOnly instead for better type safety.
throws
When the supplied data is neither an item nor an array of items.
Parameters
- data: DeepPartial<Item> | DeepPartial<Item>[]
  
  Items to be updated (if the id is already present) or added (if the id is missing).
- Optional senderId: null | Id
  
  Sender id.
Returns Id[]
updatedIds - The ids of the added (these may be newly generated if there was no id in the item from the data) or updated items.

updateOnly

updateOnly(data: UpdateItem<Item, IdProp> | UpdateItem<Item, IdProp>[], senderId?: null | Id): Id[]

Update existing items. When an item does not exist, an error will be thrown.
remarks
The provided properties will be deeply merged into the existing item. When an item does not exist (id not present in the data set or absent), an error will be thrown and nothing will be changed.

After the items are updated, the DataSet will trigger an event update. When a senderId is provided, this id will be passed with the triggered event to all subscribers.

Example
```
// create a DataSet
const data = new vis.DataSet([
  { id: 1, text: 'item 1' },
  { id: 2, text: 'item 2' },
  { id: 3, text: 'item 3' },
])

// update items
const ids = data.update([
  { id: 2, text: 'item 2 (updated)' }, // works
  // { id: 4, text: 'item 4 (new)' }, // would throw
  // { text: 'item 4 (new)' }, // would also throw
])

console.log(ids) // [2]
```
throws
When the supplied data is neither an item nor an array of items, when the ids are missing.
Parameters
- data: UpdateItem<Item, IdProp> | UpdateItem<Item, IdProp>[]
  
  Updates (the id and optionally other props) to the items in this data set.
- Optional senderId: null | Id
  
  Sender id.
Returns Id[]
updatedIds - The ids of the updated items.

DataSet

Example

Type Parameters

Item extends PartItem<IdProp>

IdProp extends string = "id"

Hierarchy

Implements

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Type Parameters

Item extends Partial<Record<IdProp, OptId>>

IdProp extends string = "id"

Parameters

Optional options: DataSetInitialOptions<IdProp>

Returns DataSet<Item, IdProp>

Type Parameters

Item extends Partial<Record<IdProp, OptId>>

IdProp extends string = "id"

Parameters

data: Item[]

Optional options: DataSetInitialOptions<IdProp>

Returns DataSet<Item, IdProp>

Properties

Private _addItem

Private Readonly _data

Private _filterFields

Private Readonly _idProp

Private Readonly _options

Private _queue

Private _remove

Private _sort

Private _updateItem

Optional flush

Type declaration

Returns void

length

subscribe

Type declaration

Parameters

event: "*"

callback: (<N>(name: N, payload: EventPayloads<Item, IdProp>[N], senderId?: null | Id) => void)

Type Parameters

N extends keyof EventCallbacks<Item, IdProp>

Parameters

name: N

payload: EventPayloads<Item, IdProp>[N]

Optional senderId: null | Id

Returns void

Returns void

Parameters

event: "add"

callback: ((name: "add", payload: null | AddEventPayload, senderId?: null | Id) => void)

Parameters

name: "add"

payload: null | AddEventPayload

Optional senderId: null | Id

Returns void

Returns void

Parameters

event: "remove"

callback: ((name: "remove", payload: null | RemoveEventPayload<Item, IdProp>, senderId?: null | Id) => void)

Parameters

name: "remove"

payload: null | RemoveEventPayload<Item, IdProp>

Optional senderId: null | Id

Returns void

Returns void

Parameters

event: "update"

callback: ((name: "update", payload: null | UpdateEventPayload<Item, IdProp>, senderId?: null | Id) => void)

Parameters

name: "update"

payload: null | UpdateEventPayload<Item, IdProp>

Optional senderId: null | Id

Returns void