cap:children - access child things

This capability is used when a thing has children. Children are used to map when a thing is a bridge or when a physical thing has several virtual children. An example of such use is for power strips that support control or monitoring of their indivudal outlets.

if(thing.matches('cap:children')) {
        // Get all children
        const children = thing.children();

        // Get a single child
        const child = thing.child('usb');
}

API

children()

Get the children of the thing as an iterable.

Example:

for(const child of thing.children) {
        console.log('Child:', child);
}
child(id)

Get a child based on its identifier. The identifier can either be a full identifier or a partial one.

Arguments:
  • id (string) – The identifier to get thing for.
Returns:

The thing if found or null.

Example:

const child = thing.child(fullIdOrPartial);

Partial identifiers

Partial identifiers are identifiers that make it easier to find a child. The are constructed in such a way that the full identifier is a combination of the parent id with a short logical id for the child.

For a thing with id example:thing a child with the partial identifier usb would have the full id example:thing:usb.

Events

thing:available

A new child is available for this thing. Emitted whenver a child is added.

Example:

thing.on('thing:available', child => console.log('Added child:', child));
thing:unavailable

A child is no longer available. Emitted when a child is no longer available.

Example:

thing.on('thing:unavailable', child => console.log('Removed child:', child));

Protected methods

addChild(thing)

Add a child to this thing. This will add the thing and emit the thing:available event.

Arguments:
  • thing – The thing to add as a child.

Example:

this.addChild(new ChildThing(...));
removeChild(thingOrId)

Remove a child from this thing. This will remove the thing and emit the thing:unavailable event.

Arguments:
  • thingOrId – The thing instance or identifier that should be removed.

Example:

this.removeChild(existingChild);
this.removeChild('id-of-thing');
findChild(filter)

Find the first child that matches the given filter function.

Arguments:
  • filter (function) – Filter function to apply, should return true when a thing matches.
Returns:

Thing if found, otherwise null.

Example:

// Get the first power outlet
this.findChild(thing => thing.matches('type:power-outlet'));

Implementing capability

When implementing this capability children need to be managed. This can either be done manually or via a method such as ChildSyncer.

Manual management is recommended if only a few known children exist:

const { Thing, Children } = require('abstract-things');

class Example extends Thing.with(Children) {

        constructor() {
                super();

                this.addChild(new ChildThing(this, ...));
        }

}

Using ChildSyncer, commonly for things such as bridges:

const { ChildSyncer } = require('abstract-things/children');

class Example extends Thing.with(Children) {

        constructor() {
                super();

                this.syncer = new ChildSyncer(this, (def, thing) => {

                });
        }

        async initCallback() {
                await super.initCallback();

                await this.loadChildren();
        }

        async loadChildren() {
                /*
                 * Load the children, should be an array with objects that contain
                 * at least an `id` property.
                 */
                const defs = await loadChildrenSomehow();

                await syncer.update(defs);
        }
}