@soundworks/core 3.7.0 → 4.0.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (124) hide show
  1. package/.eslintrc +16 -0
  2. package/LICENSE +1 -1
  3. package/README.md +32 -30
  4. package/package.json +48 -28
  5. package/src/client/Client.js +391 -0
  6. package/src/client/Context.js +225 -0
  7. package/src/client/ContextManager.js +111 -0
  8. package/src/client/Plugin.js +66 -0
  9. package/src/client/PluginManager.js +123 -0
  10. package/src/client/SharedState.js +84 -0
  11. package/src/client/Socket.js +389 -0
  12. package/src/client/StateManager.js +67 -0
  13. package/src/client/index.js +77 -0
  14. package/src/common/BasePlugin.js +163 -0
  15. package/src/common/BasePluginManager.js +227 -0
  16. package/{common/SharedState.js → src/common/BaseSharedState.js} +198 -234
  17. package/src/common/BaseStateManager.js +200 -0
  18. package/{common → src/common}/ParameterBag.js +74 -112
  19. package/{common → src/common}/SharedStatePrivate.js +56 -62
  20. package/src/common/constants.js +51 -0
  21. package/src/common/logger.js +154 -0
  22. package/src/common/promise-store.js +25 -0
  23. package/src/common/sockets-utils.js +73 -0
  24. package/src/common/utils.js +22 -0
  25. package/src/server/Client.js +50 -0
  26. package/src/server/Context.js +99 -0
  27. package/src/server/ContextManager.js +266 -0
  28. package/src/server/Plugin.js +77 -0
  29. package/src/server/PluginManager.js +150 -0
  30. package/src/server/Server.js +849 -0
  31. package/src/server/SharedState.js +86 -0
  32. package/{server → src/server}/Socket.js +114 -88
  33. package/{server → src/server}/Sockets.js +73 -60
  34. package/{common/SharedStateManagerServer.js → src/server/StateManager.js} +181 -129
  35. package/src/server/audit-network-latency.worker.js +57 -0
  36. package/src/server/audit-schema.js +42 -0
  37. package/src/server/index.js +45 -0
  38. package/tsconfig.json +21 -0
  39. package/types/client/Client.d.ts +194 -0
  40. package/types/client/Client.d.ts.map +1 -0
  41. package/types/client/Context.d.ts +139 -0
  42. package/types/client/Context.d.ts.map +1 -0
  43. package/types/client/ContextManager.d.ts +45 -0
  44. package/types/client/ContextManager.d.ts.map +1 -0
  45. package/types/client/Plugin.d.ts +53 -0
  46. package/types/client/Plugin.d.ts.map +1 -0
  47. package/types/client/PluginManager.d.ts +96 -0
  48. package/types/client/PluginManager.d.ts.map +1 -0
  49. package/types/client/SharedState.d.ts +85 -0
  50. package/types/client/SharedState.d.ts.map +1 -0
  51. package/types/client/Socket.d.ts +138 -0
  52. package/types/client/Socket.d.ts.map +1 -0
  53. package/types/client/StateManager.d.ts +72 -0
  54. package/types/client/StateManager.d.ts.map +1 -0
  55. package/types/client/index.d.ts +11 -0
  56. package/types/client/index.d.ts.map +1 -0
  57. package/types/common/BasePlugin.d.ts +145 -0
  58. package/types/common/BasePlugin.d.ts.map +1 -0
  59. package/types/common/BasePluginManager.d.ts +88 -0
  60. package/types/common/BasePluginManager.d.ts.map +1 -0
  61. package/types/common/BaseSharedState.d.ts +173 -0
  62. package/types/common/BaseSharedState.d.ts.map +1 -0
  63. package/types/common/BaseStateManager.d.ts +70 -0
  64. package/types/common/BaseStateManager.d.ts.map +1 -0
  65. package/types/common/ParameterBag.d.ts +143 -0
  66. package/types/common/ParameterBag.d.ts.map +1 -0
  67. package/types/common/SharedStatePrivate.d.ts +20 -0
  68. package/types/common/SharedStatePrivate.d.ts.map +1 -0
  69. package/types/common/constants.d.ts +35 -0
  70. package/types/common/constants.d.ts.map +1 -0
  71. package/types/common/logger.d.ts +16 -0
  72. package/types/common/logger.d.ts.map +1 -0
  73. package/types/common/promise-store.d.ts +4 -0
  74. package/types/common/promise-store.d.ts.map +1 -0
  75. package/types/common/sockets-utils.d.ts +9 -0
  76. package/types/common/sockets-utils.d.ts.map +1 -0
  77. package/types/common/utils.d.ts +5 -0
  78. package/types/common/utils.d.ts.map +1 -0
  79. package/types/server/Client.d.ts +40 -0
  80. package/types/server/Client.d.ts.map +1 -0
  81. package/types/server/Context.d.ts +59 -0
  82. package/types/server/Context.d.ts.map +1 -0
  83. package/types/server/ContextManager.d.ts +69 -0
  84. package/types/server/ContextManager.d.ts.map +1 -0
  85. package/types/server/Plugin.d.ts +70 -0
  86. package/types/server/Plugin.d.ts.map +1 -0
  87. package/types/server/PluginManager.d.ts +91 -0
  88. package/types/server/PluginManager.d.ts.map +1 -0
  89. package/types/server/Server.d.ts +223 -0
  90. package/types/server/Server.d.ts.map +1 -0
  91. package/types/server/SharedState.d.ts +86 -0
  92. package/types/server/SharedState.d.ts.map +1 -0
  93. package/types/server/Socket.d.ts +128 -0
  94. package/types/server/Socket.d.ts.map +1 -0
  95. package/types/server/Sockets.d.ts +73 -0
  96. package/types/server/Sockets.d.ts.map +1 -0
  97. package/types/server/StateManager.d.ts +190 -0
  98. package/types/server/StateManager.d.ts.map +1 -0
  99. package/types/server/audit-network-latency.worker.d.ts +2 -0
  100. package/types/server/audit-network-latency.worker.d.ts.map +1 -0
  101. package/types/server/audit-schema.d.ts +27 -0
  102. package/types/server/audit-schema.d.ts.map +1 -0
  103. package/types/server/index.d.ts +7 -0
  104. package/types/server/index.d.ts.map +1 -0
  105. package/client/AbstractExperience.js +0 -54
  106. package/client/AbstractPlugin.js +0 -230
  107. package/client/Client.js +0 -193
  108. package/client/PluginManager.js +0 -279
  109. package/client/Socket.js +0 -346
  110. package/client/index.js +0 -48
  111. package/client.js +0 -28
  112. package/common/SharedStateManagerClient.js +0 -194
  113. package/common/Signal.js +0 -40
  114. package/common/SignalAll.js +0 -44
  115. package/common/logger.js +0 -162
  116. package/common/shared-state-utils.js +0 -89
  117. package/common/sockets-encoder-decoder.js +0 -73
  118. package/server/AbstractExperience.js +0 -126
  119. package/server/AbstractPlugin.js +0 -214
  120. package/server/Client.js +0 -70
  121. package/server/PluginManager.js +0 -273
  122. package/server/Server.js +0 -785
  123. package/server/index.js +0 -49
  124. package/server.js +0 -28
@@ -0,0 +1,194 @@
1
+ export default Client;
2
+ /**
3
+ * The `Client` class is the main entry point for the client-side of soundworks
4
+ * application.
5
+ *
6
+ * A `Client` instance allows to access soundworks components such as {@link client.StateManager},
7
+ * {@link client.PluginManager},{@link client.Socket} or {@link client.ContextManager}.
8
+ * Its is also responsible for handling the initialization lifecycles of the different
9
+ * soundworks components.
10
+ *
11
+ * ```
12
+ * import { Client } from '@soundworks/core/client.js';
13
+ * // create a new soundworks `Client` instance
14
+ * const client = new Client({ role: 'player' });
15
+ * // init and start the client
16
+ * await client.start();
17
+ * ```
18
+ *
19
+ * @memberof client
20
+ */
21
+ declare class Client {
22
+ /**
23
+ * @param {client.BrowserClientConfig|client.NodeClientConfig} config -
24
+ * Configuration of the soundworks client.
25
+ * @throws Will throw if the given config object is invalid.
26
+ */
27
+ constructor(config: client.BrowserClientConfig | client.NodeClientConfig);
28
+ /**
29
+ * Role of the client in the application.
30
+ *
31
+ * @type {string}
32
+ */
33
+ role: string;
34
+ /**
35
+ * Configuration object.
36
+ *
37
+ * @type {client.BrowserClientConfig|client.NodeClientConfig}
38
+ */
39
+ config: client.BrowserClientConfig | client.NodeClientConfig;
40
+ /**
41
+ * Session id of the client (incremeted positive number), generated and
42
+ * retrieved by the server during `client.init`. The counter is reset when
43
+ * the server restarts.
44
+ *
45
+ * @type {number}
46
+ */
47
+ id: number;
48
+ /**
49
+ * Unique session uuid of the client (uuidv4), generated and retrieved by
50
+ * the server during {@link client.Client#init}.
51
+ *
52
+ * @type {string}
53
+ */
54
+ uuid: string;
55
+ /**
56
+ * Instance of the {@link client.Socket} class that handle websockets communications with
57
+ * the server.
58
+ *
59
+ * @see {@link client.Socket}
60
+ * @type {client.Socket}
61
+ */
62
+ socket: client.Socket;
63
+ /**
64
+ * Runtime platform on which the client is executed, i.e. 'browser' or 'node'.
65
+ *
66
+ * @type {string}
67
+ */
68
+ target: string;
69
+ /**
70
+ * Instance of the {@link client.ContextManager} class.
71
+ *
72
+ * The context manager can be safely used after `client.init()` has been fulfilled.
73
+ *
74
+ * @see {@link client.ContextManager}
75
+ * @type {client.ContextManager}
76
+ */
77
+ contextManager: client.ContextManager;
78
+ /**
79
+ * Instance of the {@link client.PluginManager} class.
80
+ *
81
+ * The context manager can be safely used after `client.init()` has been fulfilled.
82
+ *
83
+ * @see {@link client.PluginManager}
84
+ * @type {client.PluginManager}
85
+ */
86
+ pluginManager: client.PluginManager;
87
+ /**
88
+ * Instance of the {@link client.StateManager} class.
89
+ *
90
+ * The context manager can be safely used after `client.init()` has been fulfilled.
91
+ *
92
+ * @see {@link client.StateManager}
93
+ * @type {client.StateManager}
94
+ */
95
+ stateManager: client.StateManager;
96
+ /**
97
+ * Status of the client, 'idle', 'inited', 'started' or 'errored'.
98
+ *
99
+ * @type {string}
100
+ */
101
+ status: string;
102
+ /** @private */
103
+ private _onStatusChangeCallbacks;
104
+ /** @private */
105
+ private _auditState;
106
+ /**
107
+ * The `init` method is part of the initialization lifecycle of the `soundworks`
108
+ * client. Most of the time, the `init` method will be implicitly called by the
109
+ * {@link client.Client#start} method.
110
+ *
111
+ * In some situations you might want to call this method manually, in such cases
112
+ * the method should be called before the {@link client.Client#start} method.
113
+ *
114
+ * What it does:
115
+ * - connect the sockets to be server
116
+ * - perform the handshake with soundworks server (retrieve id, etc.)
117
+ * - launch the state manager
118
+ * - initialize all registered plugin
119
+ *
120
+ * After `await client.init()` is fulfilled, the {@link client.Client#stateManager},
121
+ * the {@link client.Client#pluginManager} and the {@link client.Client#socket}
122
+ * can be safely used.
123
+ *
124
+ * @example
125
+ * import { Client } from '@soundworks/core/client.js'
126
+ *
127
+ * const client = new Client(config);
128
+ * // optionnal explicit call of `init` before `start`
129
+ * await client.init();
130
+ * await client.start();
131
+ */
132
+ init(): Promise<void>;
133
+ /**
134
+ * The `start` method is part of the initialization lifecycle of the `soundworks`
135
+ * client. The `start` method will implicitly call the {@link client.Client#init}
136
+ * method if it has not been called manually.
137
+ *
138
+ * What it does:
139
+ * - optionnaly call {@link client.Client#init}
140
+ * - starts all the already created contexts (see {@link client.Context})
141
+ *
142
+ * @example
143
+ * import { Client } from '@soundworks/core/client.js'
144
+ *
145
+ * const client = new Client(config);
146
+ * await client.start();
147
+ */
148
+ start(): Promise<void>;
149
+ /**
150
+ * Stops all started contexts, plugins and terminates the socket connections.
151
+ *
152
+ * In most situations, you might not need to call this method. However, it can
153
+ * be usefull for unit testing or similar situations where you want to create
154
+ * and delete several clients in the same process.
155
+ *
156
+ * @example
157
+ * import { Client } from '@soundworks/core/client.js'
158
+ *
159
+ * const client = new Client(config);
160
+ * await client.start();
161
+ *
162
+ * await new Promise(resolve => setTimeout(resolve, 1000));
163
+ * await client.stop();
164
+ */
165
+ stop(): Promise<void>;
166
+ /**
167
+ * Attach and retrieve the global audit state of the application.
168
+ *
169
+ * The audit state is a {@link client.SharedState} instance that keeps track of
170
+ * global informations about the application such as, the number of connected
171
+ * clients, network latency estimation, etc. It is usefull for controller client
172
+ * roles to give the user an overview about the state of the application.
173
+ *
174
+ * The audit state is lazily attached to the client only if this method is called.
175
+ *
176
+ * @returns {Promise<client.SharedState>}
177
+ * @throws Will throw if called before `client.init()`
178
+ * @see {@link client.SharedState}
179
+ * @example
180
+ * const auditState = await client.getAuditState();
181
+ * auditState.onUpdate(() => console.log(auditState.getValues()), true);
182
+ */
183
+ getAuditState(): Promise<client.SharedState>;
184
+ /**
185
+ * Listen for the status change ('inited', 'started', 'stopped') of the client.
186
+ *
187
+ * @param {Function} callback - Listener to the status change.
188
+ * @returns {Function} Delete the listener.
189
+ */
190
+ onStatusChange(callback: Function): Function;
191
+ /** @private */
192
+ private _dispatchStatus;
193
+ }
194
+ //# sourceMappingURL=Client.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"Client.d.ts","sourceRoot":"","sources":["../../src/client/Client.js"],"names":[],"mappings":";AAeA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IACE;;;;OAIG;IACH,oBAJW,oDAAkD,EA0I5D;IApGC;;;;OAIG;IACH,MAFU,MAAM,CAEO;IAEvB;;;;OAIG;IACH,QAFU,oDAAkD,CAExC;IAYpB;;;;;;OAMG;IACH,IAFU,MAAM,CAEF;IAEd;;;;;OAKG;IACH,MAFU,MAAM,CAEA;IAEhB;;;;;;OAMG;IACH,sBAA0B;IAE1B;;;;OAIG;IACH,QAFU,MAAM,CAE8B;IAE9C;;;;;;;OAOG;IACH,sCAA0C;IAE1C;;;;;;;OAOG;IACH,oCAA4C;IAE5C;;;;;;;OAOG;IACH,kCAAwB;IAExB;;;;OAIG;IACH,QAFU,MAAM,CAEI;IAEpB,eAAe;IACf,iCAAyC;IACzC,eAAe;IACf,oBAAuB;IAKzB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,sBA6DC;IAED;;;;;;;;;;;;;;OAcG;IACH,uBAmBC;IAED;;;;;;;;;;;;;;;OAeG;IACH,sBAUC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,iBAPa,2BAA2B,CAiBvC;IAED;;;;;OAKG;IACH,6CAIC;IAED,eAAe;IACf,wBAgBC;CACF"}
@@ -0,0 +1,139 @@
1
+ export default Context;
2
+ /**
3
+ * Base class to extend in order to implement a new Context.
4
+ *
5
+ * In the `soundworks` paradigm, a client has a "role" (e.g. _player_, _controller_)
6
+ * see {@link client.Client#role}) and can be in different "contexts" (e.g. different
7
+ * part of the experience such as sections of a music piece, etc.). This class
8
+ * provides a simple and unified way to model these reccuring aspects of an application.
9
+ *
10
+ * You can also think of a `Context` as a state of a state machine from which a
11
+ * client can `enter()` or `exit()` (be aware that `soundworks` does not provide
12
+ * an implementation for the state machine).
13
+ *
14
+ * Optionally, a `Context` can also have a server-side counterpart to perform
15
+ * some logic (e.g. updating some global shared state) when a client enters or exits
16
+ * the context. In such case, `soundworks` guarantees that the server-side
17
+ * logic is executed before the `enter()` and `exit()` promises are fulfilled.
18
+ *
19
+ * ```
20
+ * import { Client, Context } from '@soundworks/core/index.js'
21
+ *
22
+ * const client = new Client(config);
23
+ *
24
+ * class MyContext extends Context {
25
+ * async enter() {
26
+ * await super.enter();
27
+ * console.log(`client ${this.client.id} entered my context`);
28
+ * }
29
+ *
30
+ * async exit() {
31
+ * await super.exit();
32
+ * console.log(`client ${this.client.id} exited my context`);
33
+ * }
34
+ * }
35
+ * const myContext = new MyContext(client);
36
+ *
37
+ * await client.start();
38
+ * await myContext.enter();
39
+ *
40
+ * await new Promise(resolve => setTimeout(resolve, 2000));
41
+ * await myContext.exit();
42
+ * ```
43
+ *
44
+ * @memberof client
45
+ */
46
+ declare class Context {
47
+ /**
48
+ * @param {client.Client} client - The soundworks client instance.
49
+ * @throws Will throw if the first argument is not a soundworks client instance.
50
+ */
51
+ constructor(client: client.Client);
52
+ /**
53
+ * The soundworks client instance.
54
+ */
55
+ client: Client;
56
+ /**
57
+ * Status of the context, i.e. 'idle', 'inited', 'started', 'errored'
58
+ */
59
+ status: string;
60
+ /**
61
+ * Name of the context. Defaults to the class name, override to use a user-defined name.
62
+ *
63
+ * @returns {string} - Name of the context.
64
+ * @example
65
+ * class MyContext extends Context {
66
+ * get name() {
67
+ * return 'my-user-defined-context-name';
68
+ * }
69
+ * }
70
+ */
71
+ get name(): string;
72
+ /**
73
+ * Start the context. This method is automatically called when `await client.start()`
74
+ * is called, or lazilly called when entering the context (i.e. `context.enter()`)
75
+ * if the context has been created after `client.start()`.
76
+ *
77
+ * In some situation, you might want to implement this method to handle application
78
+ * wise behavior regardeless the client enters or exists the context.
79
+ */
80
+ start(): Promise<void>;
81
+ /**
82
+ * Stop the context. This method is automatically called when `await client.stop()`
83
+ * is called.
84
+ *
85
+ * In some situation, you might want to implement this method to handle application
86
+ * wise behavior regardeless the client enters or exists the context.
87
+ */
88
+ stop(): Promise<void>;
89
+ /**
90
+ * Enter the context. Implement this method to define the logic that should be
91
+ * done (e.g. creating a shared state, etc.) when the context is entered.
92
+ *
93
+ * If a server-side part of the context is defined (i.e. a context with the same
94
+ * {@link client.Context#name}), the corresponding server-side `enter()` method
95
+ * will be executed before the returned Promise is fulfilled.
96
+ *
97
+ * If the context has not been started yet, the `start` method is implicitely executed.
98
+ *
99
+ * @returns {Promise} - Promise that resolves when the context is entered.
100
+ * @example
101
+ * class MyContext extends Context {
102
+ * async enter() {
103
+ * await super.enter();
104
+ * this.state = await this.client.stateManager.create('my-context-state');
105
+ * }
106
+ *
107
+ * async exit() {
108
+ * await super.exit();
109
+ * await this.state.delete();
110
+ * }
111
+ * }
112
+ */
113
+ enter(): Promise<any>;
114
+ /**
115
+ * Exit the context. Implement this method to define the logic that should be
116
+ * done (e.g. delete a shared state, etc.) when the context is exited.
117
+ *
118
+ * If a server-side part of the context is defined (i.e. a context with the same
119
+ * {@link client.Context#name}), the corresponding server-side `exit()` method
120
+ * will be executed before the returned Promise is fulfilled.
121
+ *
122
+ * @returns {Promise} - Promise that resolves when the context is exited.
123
+ * @example
124
+ * class MyContext extends Context {
125
+ * async enter() {
126
+ * await super.enter();
127
+ * this.state = await this.client.stateManager.create('my-context-state');
128
+ * }
129
+ *
130
+ * async exit() {
131
+ * await super.exit();
132
+ * await this.state.delete();
133
+ * }
134
+ * }
135
+ */
136
+ exit(): Promise<any>;
137
+ }
138
+ import Client from "./Client.js";
139
+ //# sourceMappingURL=Context.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"Context.d.ts","sourceRoot":"","sources":["../../src/client/Context.js"],"names":[],"mappings":";AAeA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH;IACE;;;OAGG;IACH,mCAgDC;IA3CC;;OAEG;IACH,eAAoB;IAEpB;;OAEG;IACH,eAAoB;IAqCtB;;;;;;;;;;OAUG;IACH,mBAEC;IAED;;;;;;;OAOG;IACH,uBAAgB;IAEhB;;;;;;OAMG;IACH,sBAAe;IAEf;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,sBAeC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,qBAUC;CACF"}
@@ -0,0 +1,45 @@
1
+ export default ContextManager;
2
+ /**
3
+ * Manage the different contexts and their lifecycle.
4
+ *
5
+ * See {@link client.Client#contextManager}
6
+ *
7
+ * _WARNING: In most cases, you should not have to manipulate the context manager directly._
8
+ *
9
+ * @memberof client
10
+ * @hideconstructor
11
+ */
12
+ declare class ContextManager {
13
+ /** @private */
14
+ private _contexts;
15
+ /** @private */
16
+ private _contextStartPromises;
17
+ /**
18
+ * Register the context into the manager. Is called in context constructor.
19
+ *
20
+ * @param {client.Context} context - The context to be registered.
21
+ * @private
22
+ */
23
+ private register;
24
+ /**
25
+ * Retrieve a started context from its name.
26
+ *
27
+ * _WARNING: Most of the time, you should not have to call this method manually._
28
+ *
29
+ * @param {client.Context#name} contextName - Name of the context.
30
+ */
31
+ get(contextName: any): Promise<any>;
32
+ /**
33
+ * Start all registered contexts. Called during `client.start()`
34
+ *
35
+ * @private
36
+ */
37
+ private start;
38
+ /**
39
+ * Stop all registered contexts. Called during `client.stop()`
40
+ *
41
+ * @private
42
+ */
43
+ private stop;
44
+ }
45
+ //# sourceMappingURL=ContextManager.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ContextManager.d.ts","sourceRoot":"","sources":["../../src/client/ContextManager.js"],"names":[],"mappings":";AAuBA;;;;;;;;;GASG;AACH;IAEI,eAAe;IACf,kBAAwC;IACxC,eAAe;IACf,8BAAsC;IAGxC;;;;;OAKG;IACH,iBAMC;IAED;;;;;;OAMG;IACH,oCAyBC;IAED;;;;OAIG;IACH,cAGC;IAED;;;;OAIG;IACH,aAGC;CACF"}
@@ -0,0 +1,53 @@
1
+ export default Plugin;
2
+ export namespace client {
3
+ /**
4
+ * ~onStateChangeCallback
5
+ */
6
+ export type Plugin = (#state: client.Plugin) => any;
7
+ /**
8
+ * Callback executed when the plugin state is updated.
9
+ *
10
+ * @callback client.Plugin~onStateChangeCallback
11
+ * @param {client.Plugin#state} state - Current state of the plugin.
12
+ */
13
+ /**
14
+ * Delete the registered {@link client.Plugin~onStateChangeCallback}.
15
+ *
16
+ * @callback client.Plugin~deleteOnStateChangeCallback
17
+ */
18
+ /**
19
+ * Base class to extend in order to create new `soundworks` plugins.
20
+ *
21
+ * In the `soundworks` paradigm, a plugin is a component that allows to extend
22
+ * the framework capabilities by encapsulating common and reusable logic in
23
+ * an application wise perspective. For example, plugins are available to handle
24
+ * clock synchronization, to deal with the file system, etc. Plugin should always
25
+ * have both a client-side and a server-side part.
26
+ *
27
+ * See [https://soundworks.dev/guide/ecosystem](https://soundworks.dev/guide/ecosystem)
28
+ * for more informations on the available plugins.
29
+ *
30
+ * _Creating new plugins should be considered an advanced usage._
31
+ *
32
+ * @memberof client
33
+ * @extends BasePlugin
34
+ * @inheritdoc
35
+ */
36
+ class Plugin extends BasePlugin {
37
+ /**
38
+ * @param {client.Client} client - The soundworks client instance.
39
+ * @param {string} id - User defined id of the plugin as defined in
40
+ * {@link client.PluginManager#register}.
41
+ */
42
+ constructor(client: client.Client, id: string);
43
+ /**
44
+ * Instance of soundworks client.
45
+ *
46
+ * @type {client.Client}
47
+ * @see {@link client.Client}
48
+ */
49
+ client: client.Client;
50
+ }
51
+ }
52
+ import BasePlugin from "../common/BasePlugin.js";
53
+ //# sourceMappingURL=Plugin.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"Plugin.d.ts","sourceRoot":"","sources":["../../src/client/Plugin.js"],"names":[],"mappings":";;;;;kCAMW,aAAa;IAJxB;;;;;OAKG;IAEH;;;;OAIG;IAEH;;;;;;;;;;;;;;;;;OAiBG;IACH;QACE;;;;WAIG;QACH,uCAHW,MAAM,EAahB;QAPC;;;;;WAKG;QACH,sBAAoB;KAevB"}
@@ -0,0 +1,96 @@
1
+ export default PluginManager;
2
+ export namespace client {
3
+ /**
4
+ * ~onStateChangeCallback
5
+ */
6
+ type PluginManager = (: object, initiator: client.Plugin | null) => any;
7
+ }
8
+ /**
9
+ * Callback executed when a plugin internal state is updated.
10
+ *
11
+ * @callback client.PluginManager~onStateChangeCallback
12
+ * @param {object<client.Plugin#id, client.Plugin>} fullState - List of all plugins.
13
+ * @param {client.Plugin|null} initiator - Plugin that initiated the update or `null`
14
+ * if the change was initiated by the state manager (i.e. when the initialization
15
+ * of the plugins starts).
16
+ */
17
+ /**
18
+ * Delete the registered {@link client.PluginManager~onStateChangeCallback}.
19
+ *
20
+ * @callback client.PluginManager~deleteOnStateChangeCallback
21
+ */
22
+ /**
23
+ * The `PluginManager` allows to register and retrieve `soundworks` plugins.
24
+ *
25
+ * Plugins should always be registered both client-side and server-side,
26
+ * and before {@link client.Client#start} or {@link server.Server#start}
27
+ * are called for proper initialization.
28
+ *
29
+ * In some sitautions, you might want to register the same plugin factory several times
30
+ * using different ids (e.g. for watching several parts of the file system, etc.).
31
+ *
32
+ * Refer to the plugins' documentation for more precise examples, and the specific API
33
+ * they expose. See [https://soundworks.dev/guide/ecosystem](https://soundworks.dev/guide/ecosystem)
34
+ * for more informations on the available plugins.
35
+ *
36
+ * See {@link client.Client#pluginManager}
37
+ *
38
+ * ```
39
+ * import { Client } from '@soundworks/core/client.js';
40
+ * import platformPlugin from '@soundworks/plugin-sync/client.js';
41
+ *
42
+ * const client = new Client(config);
43
+ * // register the plugin before `client.start()`
44
+ * client.pluginManager.register('sync', pluginSync);
45
+ *
46
+ * await client.start();
47
+ *
48
+ * const sync = await client.pluginManager.get('sync');
49
+ *
50
+ * setInterval(() => {
51
+ * // log the estimated global synced clock alongside the local clock.
52
+ * console.log(sync.getSyncTime(), sync.getLocalTime());
53
+ * }, 1000);
54
+ * ```
55
+ *
56
+ * @memberof client
57
+ * @extends BasePluginManager
58
+ * @inheritdoc
59
+ * @hideconstructor
60
+ */
61
+ declare class PluginManager extends BasePluginManager {
62
+ /**
63
+ * @param {client.Client} client - The soundworks client instance.
64
+ */
65
+ constructor(client: client.Client);
66
+ register(id: any, factory: any, options?: {}, deps?: any[]): void;
67
+ /**
68
+ * Retrieve an fully started instance of a registered plugin.
69
+ *
70
+ * Be aware that the `get` method resolves only when the plugin is fully 'started',
71
+ * which is what we want 99.99% of the time. As such, and to prevent the application
72
+ * to be stuck in some kind of Promise dead lock, this method will throw if
73
+ * used before `client.init()` (or `client.start()`).
74
+ *
75
+ * To handle the remaining 0.01% cases and access plugin instances during their
76
+ * initialization (e.g. to display initialization screen, etc.), you should rely
77
+ * on the `onStateChange` method.
78
+ *
79
+ * _Note: the async API is designed to enable the dynamic creation of plugins (hopefully
80
+ * without brealing changes) in a future release._
81
+ *
82
+ * @param {client.Plugin#id} id - Id of the plugin as defined when registered.
83
+ * @returns {client.Plugin}
84
+ * @see {@link client.PluginManager#onStateChange}
85
+ *
86
+ * @private
87
+ */
88
+ private get;
89
+ /**
90
+ * @protected
91
+ * @ignore
92
+ */
93
+ protected getRegisteredPlugins(): any[];
94
+ }
95
+ import BasePluginManager from "../common/BasePluginManager.js";
96
+ //# sourceMappingURL=PluginManager.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"PluginManager.d.ts","sourceRoot":"","sources":["../../src/client/PluginManager.js"],"names":[],"mappings":";;;;;4BAQW,MAAM,aACN,gBAAc,IAAI;;AAL7B;;;;;;;;GAQG;AAEH;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH;IACE;;OAEG;IACH,mCAMC;IAED,kEAQC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAMC;IAKD;;;OAGG;IACH,wCAEC;CACF"}
@@ -0,0 +1,85 @@
1
+ export default SharedState;
2
+ export namespace client {
3
+ /**
4
+ * ~onUpdateCallback
5
+ */
6
+ type SharedState = (newValues: any, oldValues: any, context?: Mixed) => any;
7
+ }
8
+ /**
9
+ * @callback client.SharedState~onUpdateCallback
10
+ * @param {Object} newValues - Key / value pairs of the updates that have been
11
+ * applied to the state.
12
+ * @param {Object} oldValues - Key / value pairs of the updated params before
13
+ * the updates has been applied to the state.
14
+ * @param {Mixed} [context=null] - Optionnal context object that has been passed
15
+ * with the values updates in the `set` call.
16
+ */
17
+ /**
18
+ * Delete the registered {@link client.SharedState~onUpdateCallback}.
19
+ *
20
+ * @callback client.SharedState~deleteOnUpdateCallback
21
+ */
22
+ /**
23
+ * The `SharedState` is one of the most important and versatile abstraction provided
24
+ * by `soundworks`. It represents a set of parameters that are synchronized accross
25
+ * every nodes of the application (clients and server) that declared some interest
26
+ * to the shared state.
27
+ *
28
+ * A `SharedState` is created according to a "schema" (in the sense of a database
29
+ * schema) that must be declared and registered server-side. Any number of `SharedState`s
30
+ * can be created from a single schema.
31
+ *
32
+ * A shared state can be created both by the clients or by the server (in which case
33
+ * it is generally considered as a global state of the application). Similarly any
34
+ * node of the application (clients or server) can declare interest and "attach" to
35
+ * a state created by another node. All node attached to a state can modify its values
36
+ * and/or react to the modifications applied by other nodes.
37
+ *
38
+ * Tutorial: {@link https://soundworks.dev/guide/state-manager.html}
39
+ *
40
+ * ```
41
+ * // server-side
42
+ * import { Server } from '@soundworks/server/index.js';
43
+ *
44
+ * const server = new Server(config);
45
+ * // declare and register the schema of a shared state.
46
+ * server.stateManager.registerSchema('some-global-state', {
47
+ * myRandom: {
48
+ * type: 'float',
49
+ * default: 0,
50
+ * }
51
+ * });
52
+ *
53
+ * await server.start();
54
+ *
55
+ * // create a global state server-side
56
+ * const globalState = await server.stateManager.create('some-global-state');
57
+ * // listen and react to the changes made by the clients
58
+ * globalState.onUpdate(updates => console.log(updates));
59
+ * ```
60
+ *
61
+ * ```
62
+ * // client-side
63
+ * import { Client } from '@soundworks/client.index.js';
64
+ *
65
+ * const client = new Client(config);
66
+ * await client.start();
67
+ *
68
+ * // attach to the global state created by the server
69
+ * const globalState = await client.stateManager.attach('some-global-state');
70
+ *
71
+ * // update the value of a `myRandom` parameter every seconds
72
+ * setInterval(() => {
73
+ * globalState.set({ myRandom: Math.random() });
74
+ * }, 1000);
75
+ * ```
76
+ *
77
+ * @memberof client
78
+ * @extends BaseSharedState
79
+ * @inheritdoc
80
+ * @hideconstructor
81
+ */
82
+ declare class SharedState extends BaseSharedState {
83
+ }
84
+ import BaseSharedState from "../common/BaseSharedState.js";
85
+ //# sourceMappingURL=SharedState.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"SharedState.d.ts","sourceRoot":"","sources":["../../src/client/SharedState.js"],"names":[],"mappings":";;;;;;;AAIA;;;;;;;;GAQG;AAEH;;;;GAIG;AAGH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH;CAA4C"}