Coaty JS Migration Guide

The jump to a new major release of Coaty involves breaking changes to the Coaty JS framework API. This guide describes what they are and how to upgrade your Coaty JS application to a new release.

Coaty 1 -> Coaty 2

Coaty 2 incorporates experience and feedback gathered with Coaty 1. It pursues the main goal to streamline and simplify the framework API, to get rid of unused and deprecated functionality, and to prepare for future extensions.

Among other refactorings, Coaty JS 2 carries breaking changes regarding package naming and import declarations, object types, distributed lifecycle management, IO routing, and the communication protocol while keeping the essential set of communication event patterns. Therefore, Coaty 2 applications are no longer backward-compatible and interoperable with Coaty 1 applications.

Coaty JS 1 is still available on npm package coaty@1.x.y. Coaty JS 2 is deployed separately on scoped npm package @coaty/core@2.x.y.

To update to Coaty JS 2, follow the migration steps described next.

Before migrating

To update the build infrastructure of your application, follow these steps:

Changes to package naming and import declarations

Coaty 2 introduces a common npm package scope named @coaty for current and future framework projects of the Coaty JS platform. The Coaty 2 framework is published in the npm package @coaty/core.

Rewrite all import and require declarations coaty/<modulename> to use this scoped package as follows:

Refactor import declarations of the following type references:

Deprecated functionality

All features marked as deprecated in Coaty 1 have been removed:

Changes in util module

Changes in runtime-node module

Refactor the following definitions:

Changes in Configuration options

Changes in Container

Changes in Coaty object types

Changes in subscription management

In Coaty 2, you no longer need to care about unsubscribing RxJS subscriptions of Observables returned by CommunicationManager.observe...() and CommunicationManager.publish...() methods when the communication manager is stopped. These subscriptions are now automatically disposed, in order to release system resources and to avoid memory leaks.

Changes in distributed lifecycle management

To realize distributed lifecycle management for Coaty agents in Coaty 1, individual identity objects were assigned to the communication manager as well as to each controller, in order to be advertised and to be discoverable by other agents. The identity objects were also used to provide event source IDs for communication events to realize echo suppression on the controller level so that events published by a controller could never be observed by itself.

In Coaty 2, distributed lifecycle management has been simplified and made more efficient:

Upgrade to the new approach as follows:

If echo suppression of communication events is required for your custom controller, place it into its own container and filter out observed events whose event source ID equals the object ID of the container’s identity, like this:

this.communicationManager.observeDiscover()
    .pipe(filter(event => event.sourceId !== this.container.identity.objectId))
    .subscribe(event => {
        // Handle non-echo events only.
    });

Changes in communication

Changes in Update event

We abandon partial Update events in favor of full Update events where you can choose to observe Update events for a specific core type or object type, analogous to Advertise events. This reduces messaging traffic because Update events are no longer submitted to all Update event observers but only to the ones interested in a specific type of object.

Changes in Call event

When observing Call events by CommunicationManager.observeCall() with a context argument specified, the logic of matching the context filter of an incoming Call event to the given context object has changed: A Call event is no longer emitted by the observable if context filter is not supplied and context object is specified.

Changes in Raw event

Changes in Sensor Things

Changes in IO routing

In Coaty 1, the scope of IO routing is restricted to a single user and its devices that define IO sources and actors. IO value events are only routed between the IO sources and actors of these devices.

Coaty 2 redesigns IO routing by generalizing and broadening the scope of routing. User and Device objects are no longer used for IO routing. They are replaced by IoContext and IoNode objects, respectively:

To migrate to the new concept, read the updated section on IO routing in the Developer Guide and follow these steps:

Copyright (c) 2020 Siemens AG. This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.