@soundworks/core 3.7.0 → 4.0.0-alpha.1
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.
- package/.eslintrc +16 -0
- package/LICENSE +1 -1
- package/README.md +32 -30
- package/package.json +48 -28
- package/src/client/Client.js +391 -0
- package/src/client/Context.js +225 -0
- package/src/client/ContextManager.js +111 -0
- package/src/client/Plugin.js +66 -0
- package/src/client/PluginManager.js +123 -0
- package/src/client/SharedState.js +84 -0
- package/src/client/Socket.js +389 -0
- package/src/client/StateManager.js +67 -0
- package/src/client/index.js +77 -0
- package/src/common/BasePlugin.js +163 -0
- package/src/common/BasePluginManager.js +227 -0
- package/{common/SharedState.js → src/common/BaseSharedState.js} +198 -234
- package/src/common/BaseStateManager.js +200 -0
- package/{common → src/common}/ParameterBag.js +74 -112
- package/{common → src/common}/SharedStatePrivate.js +56 -62
- package/src/common/constants.js +51 -0
- package/src/common/logger.js +154 -0
- package/src/common/promise-store.js +25 -0
- package/src/common/sockets-utils.js +73 -0
- package/src/common/utils.js +22 -0
- package/src/server/Client.js +50 -0
- package/src/server/Context.js +99 -0
- package/src/server/ContextManager.js +266 -0
- package/src/server/Plugin.js +77 -0
- package/src/server/PluginManager.js +150 -0
- package/src/server/Server.js +849 -0
- package/src/server/SharedState.js +86 -0
- package/{server → src/server}/Socket.js +114 -88
- package/{server → src/server}/Sockets.js +73 -60
- package/{common/SharedStateManagerServer.js → src/server/StateManager.js} +181 -129
- package/src/server/audit-network-latency.worker.js +57 -0
- package/src/server/audit-schema.js +42 -0
- package/src/server/index.js +45 -0
- package/tsconfig.json +21 -0
- package/types/client/Client.d.ts +194 -0
- package/types/client/Client.d.ts.map +1 -0
- package/types/client/Context.d.ts +139 -0
- package/types/client/Context.d.ts.map +1 -0
- package/types/client/ContextManager.d.ts +45 -0
- package/types/client/ContextManager.d.ts.map +1 -0
- package/types/client/Plugin.d.ts +53 -0
- package/types/client/Plugin.d.ts.map +1 -0
- package/types/client/PluginManager.d.ts +96 -0
- package/types/client/PluginManager.d.ts.map +1 -0
- package/types/client/SharedState.d.ts +85 -0
- package/types/client/SharedState.d.ts.map +1 -0
- package/types/client/Socket.d.ts +138 -0
- package/types/client/Socket.d.ts.map +1 -0
- package/types/client/StateManager.d.ts +72 -0
- package/types/client/StateManager.d.ts.map +1 -0
- package/types/client/index.d.ts +11 -0
- package/types/client/index.d.ts.map +1 -0
- package/types/common/BasePlugin.d.ts +145 -0
- package/types/common/BasePlugin.d.ts.map +1 -0
- package/types/common/BasePluginManager.d.ts +88 -0
- package/types/common/BasePluginManager.d.ts.map +1 -0
- package/types/common/BaseSharedState.d.ts +173 -0
- package/types/common/BaseSharedState.d.ts.map +1 -0
- package/types/common/BaseStateManager.d.ts +70 -0
- package/types/common/BaseStateManager.d.ts.map +1 -0
- package/types/common/ParameterBag.d.ts +143 -0
- package/types/common/ParameterBag.d.ts.map +1 -0
- package/types/common/SharedStatePrivate.d.ts +20 -0
- package/types/common/SharedStatePrivate.d.ts.map +1 -0
- package/types/common/constants.d.ts +35 -0
- package/types/common/constants.d.ts.map +1 -0
- package/types/common/logger.d.ts +16 -0
- package/types/common/logger.d.ts.map +1 -0
- package/types/common/promise-store.d.ts +4 -0
- package/types/common/promise-store.d.ts.map +1 -0
- package/types/common/sockets-utils.d.ts +9 -0
- package/types/common/sockets-utils.d.ts.map +1 -0
- package/types/common/utils.d.ts +5 -0
- package/types/common/utils.d.ts.map +1 -0
- package/types/server/Client.d.ts +40 -0
- package/types/server/Client.d.ts.map +1 -0
- package/types/server/Context.d.ts +59 -0
- package/types/server/Context.d.ts.map +1 -0
- package/types/server/ContextManager.d.ts +69 -0
- package/types/server/ContextManager.d.ts.map +1 -0
- package/types/server/Plugin.d.ts +70 -0
- package/types/server/Plugin.d.ts.map +1 -0
- package/types/server/PluginManager.d.ts +91 -0
- package/types/server/PluginManager.d.ts.map +1 -0
- package/types/server/Server.d.ts +223 -0
- package/types/server/Server.d.ts.map +1 -0
- package/types/server/SharedState.d.ts +86 -0
- package/types/server/SharedState.d.ts.map +1 -0
- package/types/server/Socket.d.ts +128 -0
- package/types/server/Socket.d.ts.map +1 -0
- package/types/server/Sockets.d.ts +73 -0
- package/types/server/Sockets.d.ts.map +1 -0
- package/types/server/StateManager.d.ts +190 -0
- package/types/server/StateManager.d.ts.map +1 -0
- package/types/server/audit-network-latency.worker.d.ts +2 -0
- package/types/server/audit-network-latency.worker.d.ts.map +1 -0
- package/types/server/audit-schema.d.ts +27 -0
- package/types/server/audit-schema.d.ts.map +1 -0
- package/types/server/index.d.ts +7 -0
- package/types/server/index.d.ts.map +1 -0
- package/client/AbstractExperience.js +0 -54
- package/client/AbstractPlugin.js +0 -230
- package/client/Client.js +0 -193
- package/client/PluginManager.js +0 -279
- package/client/Socket.js +0 -346
- package/client/index.js +0 -48
- package/client.js +0 -28
- package/common/SharedStateManagerClient.js +0 -194
- package/common/Signal.js +0 -40
- package/common/SignalAll.js +0 -44
- package/common/logger.js +0 -162
- package/common/shared-state-utils.js +0 -89
- package/common/sockets-encoder-decoder.js +0 -73
- package/server/AbstractExperience.js +0 -126
- package/server/AbstractPlugin.js +0 -214
- package/server/Client.js +0 -70
- package/server/PluginManager.js +0 -273
- package/server/Server.js +0 -785
- package/server/index.js +0 -49
- 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"}
|