Client API update

[dmitrykuzmin]

This PR updates the API of Spine web client.

Now, the API is a bit more flexible and tries to mimic the new Java API where appropriate.

In general, the new API looks as follows:

// Query.
client.select(Customer.class)
      .byId(westCoastCustomerIds())
      .withMask("name", "address", "email")
      .where([Filters.eq("type", "permanent"),
              Filters.eq("discount_percent", 10),
              Filters.eq("company_size", Company.Size.SMALL)])
      .orderBy("name", OrderBy.Direction.ASCENDING)
      .limit(20)
      .run(); // The returned type is `Promise<Customer[]>`.

// Subscription to entities.
client.subscribeTo(Task.class)
      .where(Filters.eq("status", Task.Status.ACTIVE))
      // Additional filtering can be done here.
      .post()
      .then(({itemAdded, itemChanged, itemRemoved, unsubscribe}) => {
          itemAdded.subscribe(_addDisplayedTask);
          itemChanged.subscribe(_changeDisplayedTask);
          itemRemoved.subscribe(_removeDisplayedTask);
      });

// Subscription to events.
client.subscribeToEvent(TaskCreated.class)
      .where([Filters.eq("task_priority", Task.Priority.HIGH),
              Filters.eq("context.past_message.actor_context.actor", userId)])
      .post()
      .then(({eventEmitted, unsubscribe}) => {
          eventEmitted.subscribe(_logEvent);
      });

// Command.
client.command(logInUser)
      .onOk(_logOk)
      .onError(_logError)
      .observe(UserLoggedIn.class, ({subscribe, unsubscribe}) => {
          subscribe(event => _logAndUnsubscribe(event, unsubscribe));
          setTimeout(unsubscribe, EVENT_WAIT_TIMEOUT);
      })
      .observe(UserAlreadyLoggedIn.class, (({subscribe, unsubscribe}) => {
          subscribe(event => _warnAboutAndUnsubscribe(event, unsubscribe));
          setTimeout(unsubscribe, EVENT_WAIT_TIMEOUT);
      })
      .post();

Notable changes

• The client now allows to observe the events that are the immediate result of handling the posted command. This can be done using the observe method, in a similar way to the example above. Note, that in the example we make sure the event subscriptions are always cancelled, even if the event of the corresponding type is never received. This can be done in some other way but all the subscriptions created with observe should be cleaned up manually.

• The event subscriptions will now always write spine.core.Event instances to the Firebase database and always receive spine.core.Event instances instead of event messages on the client, in the subscription objects.

• A service which keeps the active subscriptions "alive", will no longer ignore the erroneous response received from the server. If the subscriptions can't be "kept-up", it will be removed from the list of active subscriptions and the "keep-up" requests will no longer be sent for it.

• The entity subscription will now be notified about the no-longer-matching objects with the help of itemRemoved callback. Previously, it was done with the itemChanged callback with null body, which raised some problems when it was necessary to identify the object which stopped matching the subscription.

Changes to the old API

Removed

• Client.fetch(...) - please use Client.select(...).byId(...).run() instead;
• Client.subscribe(...) - please use Client.subscribeTo[Event](...).byId(...).post() instead.

Renamed

• Client.subscribeTo(Topic) -> Client.subscribe(Topic).

Deprecated

• Client.execute(Query) - please use Client.read(Query) instead;
• Client.sendCommand(...) - please use Client.command(...).onOk(...) ... .post() instead.

All other API remains intact.

Other

Spine version advances to 1.2.9.

[dmitrykuzmin]

@dmdashenkov PTAL.

The coverage is low because the changes are mostly covered by the integration tests which do not count towards coverage.

[dmdashenkov]

@dmitrykuzmin, as discussed, let's

• keep the old API operational at least for some time;
• move subscription callbacks to observe.

[dmdashenkov]

Please fix the indent.

[dmdashenkov]

Can this be reverted? Is there a performance issue?

[dmdashenkov]

Please check if this still fails.

[dmitrykuzmin]

@dmdashenkov PTAL again.

[dmdashenkov]

Could you split this file up? It's LoC count is at 600 already. GitHub even considers it too large to display.

[dmdashenkov]

Same here, please split up this file into 2 or 3. I'd say that one class per file would be an adequate strategy.

[dmitrykuzmin]

@dmdashenkov PTAL again.

[dmdashenkov]

@dmitrykuzmin, LGTM with a single minor comment.