@soundworks/core 4.0.0-alpha.21 → 4.0.0-alpha.23

package/types/server/Client.d.ts

@@ -36,5 +36,10 @@ declare class Client {
      * @type {server.Socket}
      */
     socket: server.Socket;
+    /**
+     * Is set in server._onSocketConnection
+     * @private
+     */
+    private token;
 }
 //# sourceMappingURL=Client.d.ts.map

package/types/server/Client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Client.d.ts","sourceRoot":"","sources":["../../src/server/Client.js"],"names":[],"mappings":";AAMA;;;;;;GAMG;AACH;IACE;;;OAGG;IACH,iDA4BC;IA3BC;;;;OAIG;IACH,aAAgB;IAEhB;;;;OAIG;IACH,WAAiC;IAEjC;;;;OAIG;IACH,aAAkB;IAElB;;;;OAIG;IACH,sBAAoB;CAEvB"}
+{"version":3,"file":"Client.d.ts","sourceRoot":"","sources":["../../src/server/Client.js"],"names":[],"mappings":";AAKA;;;;;;GAMG;AACH;IACE;;;OAGG;IACH,iDAkCC;IAjCC;;;;OAIG;IACH,aAAgB;IAEhB;;;;OAIG;IACH,WAAiC;IAEjC;;;;OAIG;IACH,aAAkB;IAElB;;;;OAIG;IACH,sBAAoB;IAEpB;;;OAGG;IACH,cAAiB;CAEpB"}

package/types/server/Context.d.ts

@@ -1,59 +1,199 @@
 export default Context;
 /**
- * Base class to extend in order to create the server-side counterpart of
- * a {@link client.Context}. If not defined, a default context will be created
+ * Base class to extend in order to implment the optionnal server-side counterpart
+ * of a {@link client.Context}. If not defined, a default context will be created
  * and used by the server.
  *
+ * In the `soundworks` paradigm, a client has a "role" (e.g. _player_, _controller_)
+ * see {@link client.Client#role}) and can be in different "contexts" (e.g. different
+ * part of the experience such as sections of a music piece, etc.). The
+ * {@link client.Context} and optionnal {@link serverContext} abstractions provide
+ * a simple and unified way to model these reccuring aspects of an application.
+ *
+ * If a `server.Context` is recognized as the server-side counterpart of a
+ * {@link client.Context}, based on their respective `name` (see {@link client.Context#name}
+ * and {@link server.Context#name}), `soundworks` will ensure the logic defined
+ * by the server-side Context will be executed at the beginning of the
+ * {@link client.Client#enter} and {@link client.Client#exit} methods. The example
+ * show how soundwords handles (and guarantees) the order of the `enter()` steps
+ * between the client-side and the server-side parts of the context. The same goes
+ * for the `exit()` method.
+ *
+ * ```
+ * // client-side
+ * import { Context } from '@soundworks/core/client.js';
+ *
+ * class MyContext extends Context {
+ *   async enter() {
+ *     // 1. client side context enter() starts
+ *     //    server-side logic is triggered first
+ *     await super.enter();
+ *     // 4. server-side context enter() is fully done
+ *     // some async job can be done here
+ *     await new Promise(resolve => setTimeout(resolve, 1000));
+ *     // 5. client-side context enter() ends
+ *   }
+ * }
+ *
+ * // Instanciate the context (assuming the `client.role` is 'test')
+ * const myContext = new MyContext(client);
+ *
+ * // At some point in the application, the client enters the context trigerring
+ * // the steps 1 to 5 described in the client-side and server-side `enter()`
+ * // implementations. Note that the server-side `enter()` is never called manually.
+ * await myContext.enter();
+ * ```
+ *
+ * ```
+ * // server-side
+ * import { Context } from '@soundworks/core/server.js';
+ *
+ * class MyContext extends Context {
+ *   async enter(client) {
+ *     // 2. server-side context enter() starts
+ *     await super.enter(client);
+ *     // some async job can be done here
+ *     await new Promise(resolve => setTimeout(resolve, 1000));
+ *     // 3. server-side context enter() ends
+ *   }
+ * }
+ *
+ * // Instantiate the context
+ * const myContext = new Context(server);
+ * ```
+ *
  * @memberof server
  */
 declare class Context {
-    constructor(server: any, roles?: any[]);
+    /**
+     * @param {client.Client} client - The soundworks client instance.
+     * @param {string|string[]} [roles=[]] - Optionnal list of client roles that can
+     *  use this context. In large applications, this may be usefull to guarantee
+     *  that a context can be consumed only by specific client roles, throwing an
+     *  error if any other client role tries to use it. If empty, no access policy
+     *  will be used.
+     * @throws Will throw if the first argument is not a soundworks server instance.
+     */
+    constructor(server: any, roles?: string | string[]);
     /**
      * soundworks server
      * @type {server.Server}
+     * @readonly
      */
-    server: server.Server;
+    readonly server: server.Server;
     /**
      * List of clients that are currently in this context
-     * @type {Client[]}
+     * @type {server.Client[]}
      */
-    clients: Client[];
+    clients: server.Client[];
     /**
      * Status of the context ('idle', 'inited', 'started' or 'errored')
-     * @type {String}
+     * @type {string}
+     * @readonly
      */
-    status: string;
-    roles: Set<any>;
+    readonly status: string;
+    roles: Set<string>;
     /**
-     * Name of the context, default to the class name.
-     * Override the `get name()` getter to use a user-defined context name.
+     * Optionnal user-defined name of the context (defaults to the class name).
+     *
+     * The context manager will match the client-side and server-side contexts based
+     * on this name. If the {@link server.ContextManager} don't find a corresponding
+     * user-defined context with the same name, it will use a default (noop) context.
+     *
+     * @readonly
+     * @type {string}
+     * @example
+     * // server-side and client-side contexts are matched based on their respective `name`
+     * class MyContext extends Context {
+     *   get name() {
+     *     return 'my-user-defined-context-name';
+     *   }
+     * }
      */
-    get name(): string;
+    readonly get name(): string;
     /**
-     * Method automatically called when the server starts, or lazilly called if
-     * the context is created after `server.start()`
+     * Start the context. This method is lazilly called when a client enters the
+     * context for the first time (cf. ${server.Context#enter}). If you know some
+     * some heavy and/or potentially long job has to be done  when starting the context
+     * (e.g. connect to a database, parsing a long file) it may be a good practice
+     * to call it explicitely.
      *
-     * _WARNING: this method should never be called manually._
+     * This method should be implemented to perform operations that are valid for the
+     * whole lifetime of the context, regardless a client enters or exits the context.
+     *
+     * @example
+     * import { Context } from '@soundworks/core/server.js';
+     *
+     * class MyContext extends Context {
+     *   async start() {
+     *     await super.start();
+     *     await this.doSomeLongJob();
+     *   }
+     * }
+     *
+     * // Instantiate the context
+     * const myContext = new Context(server, ['test']);
+     * // manually start the context to perform the long operation before the first
+     * // client enters the context
+     * await myContext.start();
+     * ```
      */
     start(): Promise<void>;
     /**
-     * Method automatically called when the server stops.
+     * Stop the context. The method that is automatically called when the server
+     * stops. It should be used to cleanup context wise operations made in `start()`
+     * (e.g. disconnect from a database, release a file handle).
      *
      * _WARNING: this method should never be called manually._
      */
     stop(): Promise<void>;
     /**
-     * Method automatically called when the client enters the context.
+     * Enter the context. Implement this method to define the logic that should be
+     * done (e.g. creating a shared state, etc.) when a client enters the context.
+     *
+     * If the context has not been started yet, the `start` method is implicitely executed.
      *
      * _WARNING: this method should never be called manually._
+     *
+     * @param {server.Client} client - Server-side representation of the client
+     *  that enters the context.
+     * @returns {Promise} - Promise that resolves when the context is entered.
+     * @example
+     * class MyContext extends Context {
+     *   async enter(client) {
+     *     await super.enter(client);
+     *     registerTheClientSomewhere(client);
+     *   }
+     *
+     *   async exit(client) {
+     *     await super.exit(client);
+     *     unregisterTheClientSomewhere(client);
+     *   }
+     * }
      */
-    enter(client: any): Promise<void>;
+    enter(client: server.Client): Promise<any>;
     /**
-     * Method automatically called when the client exits the context.
+     * Exit the context. Implement this method to define the logic that should be
+     * done (e.g. delete a shared state, etc.) when a client exits the context.
      *
-     * _WARNING: this method should never be called manually._
+     * * _WARNING: this method should never be called manually._
+     *
+     * @param {server.Client} client - Server-side representation of the client
+     *  that exits the context.
+     * @returns {Promise} - Promise that resolves when the context is exited.
+     * @example
+     * class MyContext extends Context {
+     *   async enter(client) {
+     *     await super.enter(client);
+     *     this.state = await this.client.stateManager.create('my-context-state');
+     *   }
+     *
+     *   async exit(client) {
+     *     await super.exit(client);
+     *     await this.state.delete();
+     *   }
+     * }
      */
-    exit(client: any): Promise<void>;
+    exit(client: server.Client): Promise<any>;
 }
-import Client from "./Client.js";
 //# sourceMappingURL=Context.d.ts.map

package/types/server/Context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Context.d.ts","sourceRoot":"","sources":["../../src/server/Context.js"],"names":[],"mappings":";AAGA;;;;;;GAMG;AACH;IACE,wCAmCC;IA1BC;;;OAGG;IACH,sBAAoB;IAEpB;;;OAGG;IACH,SAFU,MAAM,EAAE,CAEM;IAExB;;;OAGG;IACH,eAAoB;IAMpB,gBAA2B;IAM7B;;;OAGG;IACH,mBAEC;IAED;;;;;OAKG;IACH,uBAAgB;IAEhB;;;;OAIG;IACH,sBAAe;IAEf;;;;OAIG;IACH,kCAMC;IAED;;;;OAIG;IACH,iCAMC;CACF"}
+{"version":3,"file":"Context.d.ts","sourceRoot":"","sources":["../../src/server/Context.js"],"names":[],"mappings":";AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH;IACE;;;;;;;;OAQG;IACH,iCAPW,MAAM,GAAC,MAAM,EAAE,EA+CzB;IAnCC;;;;OAIG;IACH,+BAAoB;IAEpB;;;OAGG;IACH,SAFU,eAAe,CAED;IAExB;;;;OAIG;IACH,iBAHU,MAAM,CAGI;IAapB,mBAA2B;IAM7B;;;;;;;;;;;;;;;;OAgBG;IACH,4BAEC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,uBAAgB;IAEhB;;;;;;OAMG;IACH,sBAAe;IAEf;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,2CAMC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,0CAMC;CACF"}

package/types/server/ContextManager.d.ts

@@ -6,6 +6,7 @@ export default ContextManager;
  * _WARNING: Most of the time, you should not have to manipulate the context manager directly._
  *
  * @memberof server
+ * @hideconstructor
  */
 declare class ContextManager {
     /**
@@ -30,12 +31,11 @@ declare class ContextManager {
     /**
      * Retrieve a started context from its name.
      *
-     * @see {server.Context#name}
-     * @param {String} contextName - Name of the context.
+     * _WARNING: Most of the time, you should not have to call this method manually._
      *
-     * @private
+     * @param {server.Context#name} contextName - Name of the context.
      */
-    private get;
+    get(contextName: any): Promise<any>;
     /**
      * Called when a client connects to the server (websocket handshake)
      *

package/types/server/ContextManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ContextManager.d.ts","sourceRoot":"","sources":["../../src/server/ContextManager.js"],"names":[],"mappings":";AAoDA;;;;;;;GAOG;AACH;IACE;;OAEG;IACH,mCAOC;IANC,eAAe;IACf,eAAoB;IACpB,eAAe;IACf,kBAAwC;IACxC,eAAe;IACf,8BAAsC;IAGxC;;;;;;;OAOG;IACH,iBAOC;IAED;;;;;;;OAOG;IACH,YAyBC;IAED;;;;;;OAMG;IACH,kBA0FC;IAED;;;;;;OAMG;IACH,qBAUC;IAED;;;;;OAKG;IACH,cAGC;IAED;;;;OAIG;IACH,aAGC;CACF"}
+{"version":3,"file":"ContextManager.d.ts","sourceRoot":"","sources":["../../src/server/ContextManager.js"],"names":[],"mappings":";AAoDA;;;;;;;;GAQG;AACH;IACE;;OAEG;IACH,mCAOC;IANC,eAAe;IACf,eAAoB;IACpB,eAAe;IACf,kBAAwC;IACxC,eAAe;IACf,8BAAsC;IAGxC;;;;;;;OAOG;IACH,iBAOC;IAED;;;;;;OAMG;IACH,oCAyBC;IAED;;;;;;OAMG;IACH,kBAyFC;IAED;;;;;;OAMG;IACH,qBAUC;IAED;;;;;OAKG;IACH,cAGC;IAED;;;;OAIG;IACH,aAGC;CACF"}

package/types/server/Plugin.d.ts

@@ -3,68 +3,69 @@ export namespace server {
     /**
      * ~onStateChangeCallback
      */
-    export type Plugin = (#state: server.Plugin) => any;
+    type Plugin = (#state: server.Plugin) => any;
+}
+/**
+ * Callback executed when the plugin state is updated.
+ *
+ * @callback server.Plugin~onStateChangeCallback
+ * @param {server.Plugin#state} state - Current state of the plugin.
+ */
+/**
+ * Delete the registered {@link server.Plugin~onStateChangeCallback}.
+ *
+ * @callback server.Plugin~deleteOnStateChangeCallback
+ */
+/**
+ * Base class to extend in order to create the server-side counterpart of a
+ * `soundworks` plugin.
+ *
+ * In the `soundworks` paradigm, a plugin is a component that allows to extend
+ * the framework capabilities by encapsulating common and reusable logic in
+ * an application wise perspective. For example, plugins are available to handle
+ * clock synchronization, to deal with the file system, etc. Plugin should always
+ * have both a client-side and a server-side part.
+ *
+ * See [https://soundworks.dev/guide/ecosystem](https://soundworks.dev/guide/ecosystem)
+ * for more informations on the available plugins.
+ *
+ * _Creating new plugins should be considered an advanced usage._
+ *
+ * @memberof server
+ * @extends BasePlugin
+ * @inheritdoc
+ */
+declare class Plugin extends BasePlugin {
     /**
-     * Callback executed when the plugin state is updated.
-     *
-     * @callback server.Plugin~onStateChangeCallback
-     * @param {server.Plugin#state} state - Current state of the plugin.
+     * @param {server.Server} server - The soundworks server instance.
+     * @param {string} id - User defined id of the plugin as defined in
+     *  {@link server.PluginManager#register}.
      */
+    constructor(server: server.Server, id: string);
     /**
-     * Delete the registered {@link server.Plugin~onStateChangeCallback}.
-     *
-     * @callback server.Plugin~deleteOnStateChangeCallback
+     * Instance of soundworks server.
+     * @type {server.Server}
+     * @see {@link server.Server}
      */
+    server: server.Server;
+    /** @private */
+    private clients;
     /**
-     * Base class to extend in order to create new `soundworks` plugins.
-     *
-     * In the `soundworks` paradigm, a plugin is a component that allows to extend
-     * the framework capabilities by encapsulating common and reusable logic in
-     * an application wise perspective. For example, plugins are available to handle
-     * clock synchronization, to deal with the file system, etc. Plugin should always
-     * have both a client-side and a server-side part.
+     * Method called when a client (which registered the client-side plugin),
+     * connects to the application. Override this method if you need to perform
+     * some particular logic (e.g. creating a shared state) for each clients.
      *
-     * See [https://soundworks.dev/guide/ecosystem](https://soundworks.dev/guide/ecosystem)
-     * for more informations on the available plugins.
-     *
-     * _Creating new plugins should be considered an advanced usage._
+     * @param {server.Client} client
+     */
+    addClient(client: server.Client): Promise<void>;
+    /**
+     * Method called when a client (which registered the client-side plugin),
+     * disconnects from the application. Override this method if you need to perform
+     * some particular logic (e.g. creating a shared state) for each clients.
      *
-     * @memberof server
-     * @extends BasePlugin
-     * @inheritdoc
+     * @param {server.Client} client
      */
-    class Plugin extends BasePlugin {
-        /**
-         * @param {server.Server} server - The soundworks server instance.
-         * @param {string} id - User defined id of the plugin as defined in
-         *  {@link server.PluginManager#register}.
-         */
-        constructor(server: server.Server, id: string);
-        /**
-         * Instance of soundworks server.
-         * @type {server.Server}
-         * @see {@link server.Server}
-         */
-        server: server.Server;
-        /** @private */
-        private clients;
-        /**
-         * Method called when a client (which registered the client-side plugin),
-         * connects to the application. Override this method if you need to perform
-         * some particular logic (e.g. creating a shared state) for each clients.
-         *
-         * @param {server.Client} client
-         */
-        addClient(client: server.Client): Promise<void>;
-        /**
-         * Method called when a client (which registered the client-side plugin),
-         * disconnects from the application. Override this method if you need to perform
-         * some particular logic (e.g. creating a shared state) for each clients.
-         *
-         * @param {server.Client} client
-         */
-        removeClient(client: server.Client): Promise<void>;
-    }
+    removeClient(client: server.Client): Promise<void>;
 }
-import BasePlugin from "../common/BasePlugin.js";
+import BasePlugin from '../common/BasePlugin.js';
 //# sourceMappingURL=Plugin.d.ts.map

package/types/server/Plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Plugin.d.ts","sourceRoot":"","sources":["../../src/server/Plugin.js"],"names":[],"mappings":";;;;;kCAMW,aAAa;IAJxB;;;;;OAKG;IAEH;;;;OAIG;IAEH;;;;;;;;;;;;;;;;;OAiBG;IACH;QACE;;;;WAIG;QACH,uCAHW,MAAM,EAehB;QATC;;;;WAIG;QACH,sBAAoB;QAEpB,eAAe;QACf,gBAAwB;QAG1B;;;;;;WAMG;QACH,gDAEC;QAED;;;;;;WAMG;QACH,mDAEC;KACF"}
+{"version":3,"file":"Plugin.d.ts","sourceRoot":"","sources":["../../src/server/Plugin.js"],"names":[],"mappings":";;;;;2BAMW,aAAa;;AAJxB;;;;;GAKG;AAEH;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH;IACE;;;;OAIG;IACH,uCAHW,MAAM,EAehB;IATC;;;;OAIG;IACH,sBAAoB;IAEpB,eAAe;IACf,gBAAwB;IAG1B;;;;;;OAMG;IACH,gDAEC;IAED;;;;;;OAMG;IACH,mDAEC;CACF;uBA3EsB,yBAAyB"}

package/types/server/PluginManager.d.ts

@@ -24,7 +24,7 @@ export namespace server {
  *
  * Plugins should always be registered both client-side and server-side,
  * and before {@link client.Client#start} or {@link server.Server#start}
- * are called for proper initialization.
+ * to be properly initialized.
  *
  * In some sitautions, you might want to register the same plugin factory several times
  * using different ids (e.g. for watching several parts of the file system, etc.).
@@ -34,12 +34,32 @@ export namespace server {
  * for more informations on the available plugins.
  *
  * ```
+ * // client-side
+ * import { Client } from '@soundworks/core/client.js';
+ * import syncPlugin from '@soundworks/plugin-sync/client.js';
+ *
+ * const client = new Client(config);
+ * // register the plugin before `client.start()`
+ * client.pluginManager.register('sync', syncPlugin);
+ *
+ * await client.start();
+ *
+ * const sync = await client.pluginManager.get('sync');
+ *
+ * setInterval(() => {
+ *   // log the estimated global synced clock alongside the local clock.
+ *   console.log(sync.getSyncTime(), sync.getLocalTime());
+ * }, 1000);
+ * ```
+ *
+ * ```
+ * // server-side
  * import { Server } from '@soundworks/core/server.js';
- * import platformPlugin from '@soundworks/plugin-sync/server.js';
+ * import syncPlugin from '@soundworks/plugin-sync/server.js';
  *
  * const server = new Server(config);
  * // register the plugin before `server.start()`
- * server.pluginManager.register('sync', pluginSync);
+ * server.pluginManager.register('sync', syncPlugin);
  *
  * await server.start();
  *
@@ -70,8 +90,8 @@ declare class PluginManager extends BasePluginManager {
      * initialization (e.g. to display initialization screen, etc.), you should rely
      * on the `onStateChange` method.
      *
-     * _Note: the async API is designed to enable the dynamic creation of plugins (hopefully
-     * without brealing changes) in a future release._
+     * _Note: the async API is designed to enable the dynamic creation of plugins
+     * (hopefully without brealing changes) in a future release._
      *
      * @param {server.Plugin#id} id - Id of the plugin as defined when registered.
      * @returns {server.Plugin}
@@ -87,5 +107,5 @@ declare class PluginManager extends BasePluginManager {
     /** @private */
     private removeClient;
 }
-import BasePluginManager from "../common/BasePluginManager.js";
+import BasePluginManager from '../common/BasePluginManager.js';
 //# sourceMappingURL=PluginManager.d.ts.map

package/types/server/PluginManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PluginManager.d.ts","sourceRoot":"","sources":["../../src/server/PluginManager.js"],"names":[],"mappings":";;;;;4BAQW,MAAM,aACN,gBAAc,IAAI;;AAL7B;;;;;;;;GAQG;AAEH;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH;IASE,mEAQC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAMC;IAID,cAAc;IACd,qDAYC;IAED,eAAe;IACf,kBAUC;IAED,eAAe;IACf,qBAUC;CACF"}
+{"version":3,"file":"PluginManager.d.ts","sourceRoot":"","sources":["../../src/server/PluginManager.js"],"names":[],"mappings":";;;;;4BAQW,MAAM,aACN,gBAAc,IAAI;;AAL7B;;;;;;;;GAQG;AAEH;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH;IASE,mEAQC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAMC;IAID,cAAc;IACd,qDAYC;IAED,eAAe;IACf,kBAUC;IAED,eAAe;IACf,qBAUC;CACF;8BAvK6B,gCAAgC"}