Nice Parakeet Marriage


    0.5.0 • Public • Published


    Package Version License PackagePhobia Node compatibility

    Generic in-memory collection with events


    Installation of the npm package:

    > npm install --save xo-collection


    var { Collection } = require('xo-collection')


    // Creates a new collection.
    var col = new Collection()


    Inserting a new item

    col.add('foo', true)
    • Throws DuplicateItem if the item is already in the collection.

    Updating an existing item

    col.update('foo', false)
    • Throws NoSuchItem if the item is not in the collection.

    Inserting or updating an item

    col.set('bar', true)

    Notifying an external update

    If an item is an object, it can be updated directly without using the set/update methods.

    To make sure the collection stays in sync and the correct events are sent, the touch method can be used to notify the change.

    var baz = {}
    col.add('baz', baz)
    baz.prop = true

    Because this is a much used pattern, touch returns the item to allow its direct modification.

    col.touch('baz').prop = false
    • Throws NoSuchItem if the item is not in the collection.
    • Throws IllegalTouch if the item is not an object.

    Removing an existing item

    • Throws NoSuchItem if the item is not in the collection.

    Removing an item without error

    This is the symmetric method of set(): it removes the item if it exists otherwise does nothing.


    Removing all items



    Checking the existence of an item

    var hasBar = col.has('bar')

    Getting an existing item

    var foo = col.get('foo')
    // The second parameter can be used to specify a fallback in case the
    // item does not exist.
    var bar = col.get('bar', 6.28)
    • Throws NoSuchItem if the item is not in the collection and no fallback has been passed.

    Getting a read-only view of the collection

    This property is useful for example to iterate over the collection or to make advanced queries with the help of utility libraries such as lodash.

    var _ = require('lodash')
    // Prints all the items.
    _.forEach(col.all, function (value, key) {
      console.log('- %s: %j', key, value)
    // Finds all the items which are objects and have a property
    // `active` which equals `true`.
    var results = _.where(col.all, { active: true })

    Getting the number of items

    var size = col.size


    The events are emitted asynchronously (at the next turn/tick of the event loop) and are deduplicated which means, for instance, that an addition followed by an update will result only in a single addition.

    New items

    col.on('add', added => {
      forEach(added, (value, key) => {
        console.log('+ %s: %j', key, value)

    Updated items

    col.on('update', updated => {
      forEach(updated, (value, key) => {
        console.log('± %s: %j', key, value)

    Removed items

    col.on('remove', removed => {
      // For consistency, `removed` is also a map but contrary to `added`
      // and `updated`, the values associated to the keys are not
      // significant since the items have already be removed.
      forEach(removed, (value, key) => {
        console.log('- %s', key)

    End of update

    Emitted when all the update process is finished and all the update events has been emitted.

    col.on('finish', () => {
      console.log('the collection has been updated')


    for (const [key, value] of col) {
      console.log('- %s: %j', key, value)
    for (const key of col.keys()) {
      console.log('- %s', key)
    for (const value of col.values()) {
      console.log('- %j', value)


    const { View } = require('xo-collection/view')

    A view is a read-only collection which contains only the items of a parent collection which satisfy a predicate.

    It is updated at most once per turn of the event loop and therefore can be briefly invalid.

    const myView = new View(parentCollection, function predicate(value, key) {
      // This function should return a boolean indicating whether the
      // current item should be in this view.


    Contributions are very welcomed, either on the documentation or on the code.

    You may:

    • report any issue you've encountered;
    • fork and create a pull request.


    AGPL-3.0-or-later © Vates SAS




    npm i xo-collection

    DownloadsWeekly Downloads






    Unpacked Size

    97.5 kB

    Total Files


    Last publish


    • olivierlambert
    • julien-f
    • marsaud
    • pdonias
    • rajaa_b