Source: client/spine.js

  1. /*
  2.  * Copyright 2023, TeamDev. All rights reserved.
  3.  *
  4.  * Licensed under the Apache License, Version 2.0 (the "License");
  5.  * you may not use this file except in compliance with the License.
  6.  * You may obtain a copy of the License at
  7.  *
  8.  * http://www.apache.org/licenses/LICENSE-2.0
  9.  *
  10.  * Redistribution and use in source and/or binary forms, with or without
  11.  * modification, must retain the above copyright notice and the following
  12.  * disclaimer.
  13.  *
  14.  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  15.  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  16.  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  17.  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  18.  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  19.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  20.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21.  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22.  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23.  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  24.  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25.  */
  27. "use strict";
  29. import {FirebaseClientFactory} from './firebase-client';
  30. import {CustomClientFactory} from './client-factory';
  31. import {DirectClientFactory} from "./direct-client";
  32. import {CompositeClient} from "./composite-client";
  33. import KnownTypes from "./known-types";
  34. import TypeParsers from "./parser/type-parsers";
  36. /**
  37.  * @typedef {Object} CompositeClientOptions is a configuration of a composite client, which allows
  38.  * different client implementations to be used for different client requests.
  39.  *
  40.  * @property {!Array<Object>} protoIndexFiles
  41.  *  the list of the `index.js` files generated by {@link https://github.com/SpineEventEngine/base/tree/master/tools/proto-js-plugin the Protobuf plugin for JS}
  42.  * @property {ClientOptions} forQueries
  43.  *  options of the client used for queries
  44.  * @property {ClientOptions} forSubscriptions
  45.  *  options of the client used for subscriptions
  46.  * @property {ClientOptions} forCommands
  47.  *  options of the client used for commands
  48.  */
  50. /**
  51.  * The main entry point of the `spine-web` JS library. Serves for initialization
  52.  * of the `Client` instances to interact with Spine-based backend.
  53.  *
  54.  * To initialize a new instance of client that uses Firebase as a storage do the following:
  55.  * ```
  56.  *  import * as protobufs from './proto/index.js';
  57.  *  import * as spineWeb from 'spine-web';
  58.  *
  59.  *  const firebaseApp = Firebase.initializeApp({...Firebase options});
  60.  *
  61.  *  // The backend client will receive updates of the current actor through this instance
  62.  *  const actorProvider = new ActorProvider();
  63.  *
  64.  *  const client = spineWeb.init({
  65.  *      protoIndexFiles: [protobufs],
  66.  *      endpointUrl: 'http://example.appspot.com',
  67.  *      firebaseDatabase: firebaseApp.database(),
  68.  *      actorProvider: actorProvider
  69.  *  });
  70.  * ```
  71.  *
  72.  * To substitute a custom implementation of `Client` for tests do the following:
  73.  * ```
  74.  *  // An instance of class extending `spineWeb.Client`
  75.  *  const mockClientImpl = new MockClient();
  76.  *
  77.  *  const mockClient = spineWeb.init({
  78.  *      protoIndexFiles: [protobufs],
  79.  *      implementation: mockClientImpl
  80.  *  });
  81.  * ```
  82.  * Note, when using of custom `Client` implementation protobuf index files
  83.  * registration is still required.
  84.  *
  85.  * @param {ClientOptions|CompositeClientOptions} options
  86.  * @return {Client}
  87.  */
  88. export function init(options) {
  89.   _registerTypes(...options.protoIndexFiles);
  90.   const compositeClient = _initCompositeClient(options);
  91.   return compositeClient !== null ? compositeClient : _initSimpleClient(options);
  92. }
  94. function _initCompositeClient(options) {
  95.   const forQueries = options.forQueries;
  96.   const forSubscriptions = options.forSubscriptions;
  97.   const forCommands = options.forCommands;
  99.   if (!!forQueries || !!forSubscriptions || !!forCommands) {
  100.     if (!(!!forQueries && !!forSubscriptions && !!forCommands)) {
  101.       throw Error("All of `forQueries`, `forSubscriptions`, and `forCommands` must be defined.");
  102.     }
  103.   } else {
  104.     return null;
  105.   }
  107.   const querying = _selectFactory(forQueries).createQuerying(forQueries);
  108.   const subscribing = _selectFactory(forSubscriptions).createSubscribing(forSubscriptions);
  109.   const commanding = _selectFactory(forCommands).createCommanding(forCommands);
  110.   return new CompositeClient(querying, subscribing, commanding);
  111. }
  113. function _initSimpleClient(options) {
  114.   const factory = _selectFactory(options);
  115.   return factory.createClient(options);
  116. }
  118. function _selectFactory(options) {
  119.   let clientFactory;
  120.   if (!!options.firebaseDatabase) {
  121.     clientFactory = FirebaseClientFactory;
  122.   } else if (!!options.implementation) {
  123.     clientFactory = CustomClientFactory;
  124.   } else {
  125.     clientFactory = DirectClientFactory;
  126.   }
  127.   return clientFactory;
  128. }
  130. /**
  131.  * Registers all Protobuf types provided by the specified modules.
  132.  *
  133.  * After the registration, the types can be used and parsed correctly.
  134.  *
  135.  * @param protoIndexFiles the index.js files generated by
  136.  * {@link https://github.com/SpineEventEngine/base/tree/master/tools/proto-js-plugin the Protobuf plugin for JS}
  137.  * @private
  138.  */
  139. function _registerTypes(...protoIndexFiles) {
  140.   for (let indexFile of protoIndexFiles) {
  141.     for (let [typeUrl, type] of indexFile.types) {
  142.       KnownTypes.register(type, typeUrl);
  143.     }
  144.     for (let [typeUrl, parserType] of indexFile.parsers) {
  145.       TypeParsers.register(new parserType(), typeUrl);
  146.     }
  147.   }
  148. }