Cue Collection

Introduction

Cue Collection specifies an interface for a collection of (key, cue) pairs, extended with events.

Cue collection emulates the Javascript Map API by defining methods has(), get(), keys(), values() and entries(). Also, the number of (key,cue) pairs managed by the cue collection is exposed by the property size.

Cue collection also defines three events: batch, change and remove. Events allow modifications of the cue collection to be detected by subscribers. Events are implemented as defined in Events.

Note

The Cue Collection interface is only read-only and does not specify any mechanisms for modifying the collection of (key, value) pairs. Methods for modification are left for specific implementations of the interface, such as Dataset and Sequencer.

Events

Modification Types

Cue collection supports two types of modifications: membership-modifications and cue-modifications:

membership-modifications
Cues inserted into or deleted from the cue collection.
cue-modifications
Modification of cues in cue collection.

Change and Remove

Cue collection defines events change and remove. Each event report modifications concerning an single (key, cue) pair.

change
  • inserted cues (membership-modification)
  • modified cues (cue-modification)
remove
  • deleted cues (membership-modification)
// cue collection
let cc;

cc.on("change", function(eArg) {
    console.log("change")
});

cc.on("remove", function(eArg) {
    console.log("remove")
});

Note

It would also have been possible to expose three events (insert, modify, delete) instead of two events (change, remove). However, the latter is often more convenient, as insert and modify events are frequently handled the same way. On the other hand, if the distincion matters the event argument of the change event may be used to tell them apart. See Event Argument.

Batch Event

Cue collection additionally defines a batch event which delivers multiple change and remove together. This is relevant for implementations supporting modification of multiple cues in one (atomic) operation. If so, the batch event makes it possible to process concurrent events in one operation, and making decisions based on the whole batch, as opposed to single events.

The event argument eArg of the batch event is simply a list of event arguments for individual change and remove events.

// cue collection
let cc;

cc.on("update", function (eArgList) {
    eArgList.forEach(function(eArg) {
        if (eArg.new != undefined) {
            if (eArg.old != undefined) {
                console.log("modify");
            } else {
                console.log("insert");
            }
        } else {
            if (eArg.old != undefined) {
                console.log("delete");
            } else {
                console.log("noop");
            }
        }
    });
});

Note

Cue collection may emit a batch event including event arguments where both eArg.new and eArg.old are undefined, i.e. noop events.

Event Argument

Cue collection events provide an event argument eArg describing the modification of a single cue. The event argument is a simple object with properties key, new and old:

// Event Argument
let eArg = {key: ..., new: {...}, old: {...}}
key
key (unique in cue collection)
old
cue before modification, or undefined if cue was inserted.
new
cue after modification, or undefined if cue was deleted.

This table show values eArg.old and eArg.new may assume for different events and modification types.

modification event eArg.old eArg.new
insert change undefined cue
modify change cue cue
delete remove cue undefined
noop   undefined undefined

Distinguishing between modification types is easy:

// cue collection
let cc;

cc.on("change", function(eArg) {
    if (eArg.old == undefined) {
        console.log("insert");
    } else {
        console.log("modify");
    }
});

cc.on("remove", function(eArg) {
    console.log("delete")
});

Cue Ordering

By default cue collections do not enforce a particular ordering for its (key, cue) pairs. If needed, order may be specified on the constructor. The cues() method will then returne an ordered list of cues. In addition, cue events will be delivered in the correct order. Ordering options may also be supplied directly to the CueCollection.cues() and will take precedence over constructor options. This applies for both Dataset and Sequencer, which are both cue collactions.

// order by keys
function cmp(cue_a, cue_b) {
    return cue_a.key < cue_b.key;
}

let cc = new CueCollection({order:cmp})

// unordered iterator of cues
let cues_iterator = cc.values()

// ordered list of cues
let cues_list = cc.cues();