@soundworks/core 3.7.0 → 4.0.0-alpha.1

package/client/Client.js

@@ -1,193 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
-
-var _PluginManager = _interopRequireDefault(require("./PluginManager.js"));
-
-var _SharedStateManagerClient = _interopRequireDefault(require("../common/SharedStateManagerClient.js"));
-
-var _Socket = _interopRequireDefault(require("./Socket.js"));
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
-
-/**
- * Create a new client of a *soundworks* application.
- *
- * The `Client` is the main entry point to access *soundworks* components
- * such as {@link client.Socket}, {@link client.PluginManager} or
- * {@link client.SharedStateManagerClient}. It is also responsible for the
- * initialization lifecycle.
- *
- * @memberof client
- *
- * @example
- * import soundworks from '@soundworks/core/client';
- *
- * // create a new `soundworks.Client` instance
- * const client = new soundworks.Client();
- * // initialize the client (mainly connect and initialize WebSockets)
- * await client.init(config);
- * // create application specific experience (extends `client.AbstractExperience`
- * const playerExperience = new PlayerExperience(client);
- * // start the client
- * await client.start();
- * // when everything is ready, the experience can be safely started
- * playerExperience.start();
- */
-class Client {
-  constructor() {
-    /**
-     * Type of the client, this can generally be considered as the role of the
-     * client in the application.
-     * @type {String}
-     */
-    this.type = null;
-    /**
-     * Session id of the client (incremeted positive number),
-     * generated and retrieved by the server on start.
-     * The counter is reset when the server restarts.
-     * @type {Number}
-     */
-
-    this.id = null;
-    /**
-     * Unique session uuid of the client (uuidv4), generated and retrieved by
-     * the server on start.
-     * @type {String}
-     */
-
-    this.uuid = null;
-    /**
-     * Configuration object, typically contains the configuration sent by the
-     * server (cf. {@link server.Server#init}).
-     * @see {@link server.Server#init}.
-     * @type {Object}
-     */
-
-    this.config = {};
-    /**
-     * Instance of the `Socket` class that handle communications with the server.
-     * @see {@link client.Socket}
-     * @type {client.Socket}
-     */
-
-    this.socket = new _Socket.default();
-    /**
-     * Instance of the `PluginManager` class.
-     * @see {@link client.PluginManager}
-     * @type {client.PluginManager}
-     */
-
-    this.pluginManager = new _PluginManager.default(this);
-    /**
-     * Instance of the `SharedStateManagerClient` class.
-     * @see {@link client.SharedStateManagerClient}
-     * @type {client.SharedStateManagerClient}
-     */
-
-    this.stateManager = null;
-  }
-  /**
-   * Method to be called before {@link client.Client#start} in the
-   * initialization lifecycle of the soundworks client.
-   *
-   * Basically waits for the socket to be connected.
-   * @see {@link server.Server#init}
-   *
-   * @param {Object} config - Configuration object (cf. {@link server.Server#init})
-   */
-
-
-  async init(config) {
-    if (!(Object.prototype.toString.call(config) === '[object Object]')) {
-      throw new Error('[soundworks.init] must receive a config object as argument`');
-    }
-
-    if (!('clientType' in config)) {
-      throw new Error('[soundworks.init] config object "must" define a `clientType`');
-    } // handle config
-
-
-    this.type = config.clientType;
-    this.config = config; // @todo - review that to adapt to ws options
-
-    this.config.env.websockets = Object.assign({
-      // url: '',
-      path: 'socket' // pingInterval: 5 * 1000,
-
-    }, config.env.websockets); // init socket communications (string and binary)
-
-    await this.socket.init(this.type, this.config);
-    return Promise.resolve();
-  }
-  /**
-   * Method to be called when {@link client.Client#init} has finished in the
-   * initialization lifecycle of the soundworks client.
-   *
-   * Initilialize the {@link client.SharedStateManagerClient} and all required
-   * plugins. When done, the {@link client.AbstractExperience#start} method
-   * should be consider as being safely called.
-   *
-   * @see {@link server.Server#start}
-   */
-
-
-  async start() {
-    this._ready = new Promise((resolve, reject) => {
-      const payload = {
-        requiredPlugins: this.pluginManager.getRequiredPlugins()
-      }; // wait for handshake response to mark client as `ready`
-
-      this.socket.addListener('s:client:start', ({
-        id,
-        uuid
-      }) => {
-        this.id = id;
-        this.uuid = uuid; // mimic eventEmitter API
-
-        const transport = {
-          emit: this.socket.send.bind(this.socket),
-          addListener: this.socket.addListener.bind(this.socket),
-          // removeListener: this.socket.removeListener.bind(this.socket),
-          removeAllListeners: this.socket.removeAllListeners.bind(this.socket)
-        };
-        this.stateManager = new _SharedStateManagerClient.default(this.id, transport); // everything is ready start plugin manager
-
-        this.pluginManager.start().then(() => resolve());
-      });
-      this.socket.addListener('s:client:error', err => {
-        let msg = ``;
-
-        switch (err.type) {
-          case 'plugins':
-            msg = `"${err.data.join(', ')}" required client-side but not server-side`;
-            break;
-
-          case 'no-activity':
-            msg = `[soundworks:core] No activity registered server-side for "${this.type}", make sure an Experience has been created for this client`;
-            break;
-
-          default:
-            msg = `Unknown error`;
-            break;
-        }
-
-        this.socket.terminate();
-        reject(msg);
-      });
-      this.socket.send('s:client:handshake', payload);
-    });
-    return this._ready;
-  }
-
-  async stop() {
-    this.socket.terminate();
-  }
-
-}
-
-var _default = Client;
-exports.default = _default;

package/client/PluginManager.js

@@ -1,279 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
-
-var _debug = _interopRequireDefault(require("debug"));
-
-var _AbstractPlugin = _interopRequireDefault(require("./AbstractPlugin.js"));
-
-var _Signal = _interopRequireDefault(require("../common/Signal.js"));
-
-var _SignalAll = _interopRequireDefault(require("../common/SignalAll.js"));
-
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
-
-const log = (0, _debug.default)('soundworks:lifecycle');
-/**
- * Component dedicated at registering, instantiating and initializing plugins.
- *
- * An instance of the `PluginManager` is automatically created by the
- * `soundworks.Client`.
- * @see {@link client.Client#pluginManager}
- *
- * @memberof client
- *
- * @example
- * import soundworks from '@soundworks/core/client';
- *
- * // create a new `soundworks.Client` instance
- * const client = new soundworks.Client();
- * client.pluginManager.register('my-plugin', myPluginFactory, {}, []);
- */
-
-class PluginManager {
-  constructor(client) {
-    /** @private */
-    this._instances = {};
-    /** @private */
-
-    this._registeredPlugins = {};
-    /** @private */
-
-    this._observers = new Set();
-    /** @private */
-
-    this._pluginsStatuses = {};
-    /** @private */
-
-    this._client = client;
-    log('> pluginManager init');
-    this.signals = {
-      start: new _Signal.default(),
-      ready: new _SignalAll.default()
-    };
-    this.ready = new Promise(resolve => {
-      this._resolveReadyPromise = resolve;
-    });
-  }
-  /**
-   * Sends the signal required by all plugins to start.
-   * @private
-   */
-
-
-  start() {
-    log('> pluginManager start');
-    this.signals.ready.addObserver(() => {
-      log('> pluginManager ready');
-
-      this._resolveReadyPromise();
-    });
-
-    this._propagateStatusChange(); // start before ready, even if no deps
-
-
-    this.signals.start.value = true;
-
-    if (!this.signals.ready.length) {
-      this.signals.ready.value = true;
-    }
-
-    return this.ready;
-  }
-  /** @private */
-
-
-  _propagateStatusChange(name = null, status = null) {
-    if (name != null && status != null) {
-      this._pluginsStatuses[name] = status;
-      const statuses = this.getStatuses();
-
-      this._observers.forEach(observer => observer(statuses, {
-        [name]: status
-      }));
-    } else {
-      const statuses = this.getStatuses();
-
-      this._observers.forEach(observer => observer(statuses, {}));
-    }
-  }
-  /** @private */
-
-
-  observe(observer) {
-    this._observers.add(observer);
-
-    return () => {
-      this._observers.delete(observer);
-    };
-  }
-  /** @private */
-  // @todo rename to `getStatuses`
-
-
-  getStatuses() {
-    return Object.assign({}, this._pluginsStatuses);
-  }
-  /**
-   * Register the client-side part of a plugin into soundworks instance.
-   *
-   * Notes:
-   *    - A plugin must always be registered (and required) both client-side
-   *    and server-side
-   *    - A plugin factory can be used several times with different names to
-   *    create several instances of the plugin
-   *
-   *
-   * @see {@link server.PluginManager#register}
-   * @see {@link client.AbstractExperience#require}
-   * @see {@link client.AbstractPlugin#start}
-   * @see {@link client.AbstractPlugin#ready}
-   *
-   * @param {String} name - Name of the plugin
-   * @param {Function} factory - Factory function that return the plugin class
-   * @param {Object} [options={}] - Options to configure the plugin
-   * @param {Array} [deps=[]] - List of plugins' names the plugin depends on, aka
-   *   the plugins that the plugin should wait for being `ready` before `start`
-   *
-   * @example
-   * ```js
-   * client.pluginManager.register('user-defined-name', pluginFactory);
-   * ```
-   */
-
-
-  register(name, factory, options = {}, deps = []) {
-    if (this._registeredPlugins[name]) {
-      const ctor = factory(_AbstractPlugin.default);
-      throw new Error(`[soundworks:core] Plugin "${name}" of type "${ctor.name}" already registered`);
-    }
-
-    const ctor = factory(_AbstractPlugin.default);
-    this._registeredPlugins[name] = {
-      ctor,
-      options,
-      deps
-    };
-  }
-  /**
-   * Returns an instance of a plugin with options to be applied to its constructor.
-   * Warning: using this method do not attach any client to the plugin (as does
-   * {@link client.AbstractExperience#require}, use this method only if you know
-   * what you are doing.
-   *
-   * @see {client.AbstractExperience#require}
-   * @param {String} name - Name of the plugin.
-   */
-
-
-  get(name, _experienceRequired = false) {
-    if (!this._registeredPlugins[name]) {
-      throw new Error(`[soundworks:core] Cannot get or require plugin "${name}", plugin is not registered
-> registered plugins are:
-${Object.keys(this._registeredPlugins).map(n => `> - ${n}\n`).join('')}
-`);
-    } // throw an error if manager already started
-
-
-    if (_experienceRequired && this.signals.start.value === true) {
-      throw new Error(`[soundworks:core] Plugin "${name}" required after pluginManager start`);
-    }
-
-    if (!this._instances[name]) {
-      const {
-        ctor,
-        options,
-        deps
-      } = this._registeredPlugins[name];
-      const instance = new ctor(this._client, name, options); // wait, at least,  for the plugin manager start signal
-
-      instance.signals.start.add(this.signals.start); // handle dependency tree
-
-      this.signals.ready.add(instance.signals.ready);
-
-      if (deps.length > 0) {
-        deps.forEach(dependencyName => {
-          if (!this._instances[dependencyName]) {
-            this.get(dependencyName, _experienceRequired);
-          }
-
-          const dependency = this._instances[dependencyName];
-          instance.signals.start.add(dependency.signals.ready);
-        });
-      } // handle plugin status for reporting
-
-
-      this._pluginsStatuses[name] = 'idle';
-      let unsubscribe;
-
-      const onPluginStarted = () => {
-        this._pluginsStatuses[name] = 'started';
-        /**
-         * @FIXME
-         * relying on `instance.state` is very weak...
-         * we should find a better solution, to declare that we want the
-         * pluginManager to watch and propagate initialization steps.
-         *
-         * This is probably a dirty hack to make the init views working...
-         */
-
-        if (instance.state) {
-          unsubscribe = instance.state.subscribe(() => {
-            this._propagateStatusChange();
-          });
-        }
-
-        this._propagateStatusChange();
-      };
-
-      const onPluginErrored = () => {
-        this._pluginsStatuses[name] = 'errored';
-
-        this._propagateStatusChange();
-
-        if (unsubscribe) {
-          unsubscribe();
-        }
-
-        instance.signals.started.removeObserver(onPluginStarted);
-        instance.signals.ready.removeObserver(onPluginReady);
-        instance.signals.errored.removeObserver(onPluginErrored);
-      };
-
-      const onPluginReady = () => {
-        this._pluginsStatuses[name] = 'ready';
-
-        this._propagateStatusChange();
-
-        if (unsubscribe) {
-          unsubscribe();
-        }
-
-        instance.signals.started.removeObserver(onPluginStarted);
-        instance.signals.ready.removeObserver(onPluginReady);
-        instance.signals.errored.removeObserver(onPluginErrored);
-      };
-
-      instance.signals.started.addObserver(onPluginStarted);
-      instance.signals.ready.addObserver(onPluginReady);
-      instance.signals.errored.addObserver(onPluginErrored); // store instance
-
-      this._instances[name] = instance;
-    } // if instance exists and no other argument given, `get` acts a a pure getter
-
-
-    const instance = this._instances[name];
-    return instance;
-  }
-
-  getRequiredPlugins() {
-    return Object.keys(this._pluginsStatuses);
-  }
-
-}
-
-var _default = PluginManager;
-exports.default = _default;