@gama-platform/gama-client 1.0.2

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 (5) hide show
  1. package/dist/gama_client.cjs +560 -0
  2. package/dist/gama_client.d.cts +166 -0
  3. package/dist/gama_client.d.ts +166 -0
  4. package/dist/gama_client.js +532 -0
  5. package/package.json +41 -0
package/dist/gama_client.d.cts ADDED
@@ -0,0 +1,166 @@
1
+ import WebSocket from 'ws';
2
+
3
+ /**
4
+ * This class creates a websocket client for Gama Server.
5
+ * uses port 1000 and host localhost unless specified otherwise.
6
+ */
7
+ declare class GamaClient {
8
+ private jsonGamaState;
9
+ private port;
10
+ private host;
11
+ private gama_socket;
12
+ /**
13
+ *
14
+ * @param port port of gama server you want to reach
15
+ * @param host host of the gama server you want to reach
16
+ */
17
+ constructor(port?: number, host?: string);
18
+ isConnected(): boolean;
19
+ getExperimentState(): string;
20
+ isLoading(): boolean;
21
+ getContentError(): string;
22
+ getExperimentId(): string;
23
+ getModelPath(): string;
24
+ getExperimentName(): string;
25
+ getReadyState(): number;
26
+ getPort(): number;
27
+ getHost(): string;
28
+ getSocket(): WebSocket;
29
+ private setConnected;
30
+ private setExperimentState;
31
+ private setLoading;
32
+ private setContentError;
33
+ private setExperimentId;
34
+ private setExperimentName;
35
+ private setModelPath;
36
+ /**
37
+ * internal function to avoid unecessary boilerplate code,
38
+ * checks if gamasocket exists, and if it's ready to accept a new message
39
+ */
40
+ private socketCheck;
41
+ /**
42
+ * internal function that contains a simple try catch and stringifies a json payload to send it to the websocket
43
+ * @param payload json payload to be sent
44
+ */
45
+ private sendPayload;
46
+ /**
47
+ * internal function that returns the string of an experiment to run
48
+ * it represents the last used experiment or the new one if any specified
49
+ * @param new_exp_id id of the experiment passed by the user in parameter. used by default, sets the current experience to itself
50
+ * @returns the string of the Id of the last used experiment. Used if no new_exp_id is given
51
+ */
52
+ getId(new_exp_id?: string): string;
53
+ /**
54
+ * async function that closes the websocket connection, and runs the callback function passed in parameter if any.
55
+ * When called, creates a promise that either rejects after 15 seconds to avoid timeout lockdowns,
56
+ * or resolves after the close internalListener fires.
57
+ * @param optional callback Function to be called after the websocket's connection is closed
58
+ */
59
+ closeConnection(callback?: () => void): Promise<void>;
60
+ /**
61
+ * Connects the websocket client with gama server and manage the messages received
62
+ * this function is asynchronous, it needs to be called with await. This is because
63
+ * other functions need the websocket to be created and in the state "OPEN" to start
64
+ * sending messages, which is not done when the function has finished it's execution
65
+ * @returns WebSocket properly initialised at the end of the asynchronous execution
66
+ */
67
+ connectGama(): Promise<void>;
68
+ /**
69
+ * This function is used to watch on messages stream and look for a response to the command initiated.
70
+ * it resolves if the message received is of the same type specified in the parameter
71
+ * and throws an error if it's of any type specified in the GAMA_ERROR_MESSAGES specified in the constants file
72
+ * @returns returns a promise containing the response's message's content
73
+ */
74
+ success(successMessage: string): Promise<string>;
75
+ /**
76
+ * function used to check for a specific message on the websocket.
77
+ * returns a resolved boolean promise once the provided message is found
78
+ * @param messageType the basic type of the message you want to analyse
79
+ * @param field what part of the message to analyse
80
+ * @param expectedValue what you expect the field value to be
81
+ * @returns a resolved promise containing a boolean
82
+ */
83
+ listenFor(messageType: string, field: string, expectedValue: any): Promise<boolean>;
84
+ readyCheck(): Promise<void>;
85
+ /**
86
+ * loads and launches an experiment using the absolute path of it's model and
87
+ * the identifier of the experiment. Resolves when the server answers with a SimulationStatus of type "PAUSED"
88
+ * @param model_path absolute path pointing to the model cointaining the experiment
89
+ * @param experiment id of the experiment to load
90
+ */
91
+ loadExperiment(model_path: string, experiment: string): Promise<void>;
92
+ /**
93
+ * Starts or resumes the experiment specified.
94
+ * @param exp_id string name of the experiment to pause or resume
95
+ * @param sync boolean used if an end condition was specified when loading a simulation. the command will return only the SimulationEnded message if true, and both a response and a SimulationEnded message if false
96
+ * when starting the experiment
97
+ */
98
+ play(exp_id?: string, sync?: boolean): Promise<string | undefined>;
99
+ /**
100
+ * Pauses the experiment specified.
101
+ * @param exp_id optionnal parameter, will default to last used experiment
102
+ */
103
+ pause(exp_id?: string): Promise<string>;
104
+ reload(exp_id?: string, parameters?: string, until?: string): Promise<string>;
105
+ /**
106
+ * Sends a message to gama to order it to process a specified number of steps.
107
+ * Can only be used after the simulation has already been loaded
108
+ * @param exp_id the name of the experiment you want to step to. if not used, then the last used experiment Id will be used
109
+ * @param nb_step the number of steps you want to simulate. if none is specified, it will default to one step
110
+ */
111
+ step(nb_step?: number, sync?: boolean, exp_id?: string): Promise<string>;
112
+ /**
113
+ * ! you must be sure that the type of the experiment is compatible (record) before using this
114
+ * This command is used to rollback a specific amount of steps.
115
+ * Can only be used if the experiment is of type "record"
116
+ * @param exp_id the name of the experiment you want to step to. if not used, then the last used experiment Id will be used
117
+ * @param nb_step the number of steps you want to simulate. if none is specified, it will default to one step
118
+ */
119
+ stepback(nb_step?: number, exp_id?: string): Promise<string>;
120
+ /**
121
+ * stops the specified experiment or the current experiment if not specified
122
+ * @param exp_id optionnal parameter, leave empty to use the last used exp_id
123
+ */
124
+ stop(exp_id?: string): Promise<unknown>;
125
+ /**
126
+ * used to specify a fonction to be called on any message received by the websocket from the gama server
127
+ * you can only have one onMessage per client.
128
+ * @param callback the function you want to call upon receiving data through the javascript client
129
+ */
130
+ onMessage(callback: (data: any) => void): void;
131
+ /**
132
+ * kills the gama server.
133
+ * used to exit the gama server, closes the websocket connection and closes the gama instance
134
+ */
135
+ killGamaServer(): Promise<void>;
136
+ /**
137
+ * used to run execute an action defined in an agent in an experiment.
138
+ * @param action gaml code to be run from an agent
139
+ * @param args arguments of the action
140
+ * @param agent what agent this code applies to
141
+ * @param escaped optional parameter, if true will escape the action and args before sending them to gama
142
+ * @param exp_id optionnal parameter to specify the experiment. if none is given it will instead default to the last used experiment
143
+ * @returns a stringified response containing the result of the execution of the command
144
+ */
145
+ ask(action: string, args: string, agent: string, escaped?: boolean, exp_id?: string): Promise<string>;
146
+ /**
147
+ * Compiles the code given in parameter and returns a message if any errors are detected.
148
+ * @param expr gaml expression to test
149
+ * @param syntax optionnal boolean, if true will only check the syntax. false will check for both syntactical and semantic errors
150
+ * @param escaped optionnal boolean, dictates if the expression is escaped or not
151
+ * @returns stringified json containing errors in the code if any
152
+ */
153
+ validate(expr: string, syntax?: boolean, escaped?: boolean): Promise<string>;
154
+ /**
155
+ * This command is used to ask the server more information on a given model. When received,
156
+ * the server will compile the model and return the different components found, depending on the option picked by the client.
157
+ * @param model_path path to the model to evaluate
158
+ * @param experimentsNames optional boolean that returns the name of all the experiments of the model
159
+ * @param speciesNames optional boolean that returns all of the species' names
160
+ * @param speciesVariables optional boolean that returns all variables of the species
161
+ * @param speciesActions optional boolean that returns all actions in the species
162
+ */
163
+ describe(model_path: string, experimentsNames?: boolean, speciesNames?: boolean, speciesVariables?: boolean, speciesActions?: boolean): Promise<string>;
164
+ }
165
+
166
+ export { GamaClient as default };
package/dist/gama_client.d.ts ADDED
@@ -0,0 +1,166 @@
1
+ import WebSocket from 'ws';
2
+
3
+ /**
4
+ * This class creates a websocket client for Gama Server.
5
+ * uses port 1000 and host localhost unless specified otherwise.
6
+ */
7
+ declare class GamaClient {
8
+ private jsonGamaState;
9
+ private port;
10
+ private host;
11
+ private gama_socket;
12
+ /**
13
+ *
14
+ * @param port port of gama server you want to reach
15
+ * @param host host of the gama server you want to reach
16
+ */
17
+ constructor(port?: number, host?: string);
18
+ isConnected(): boolean;
19
+ getExperimentState(): string;
20
+ isLoading(): boolean;
21
+ getContentError(): string;
22
+ getExperimentId(): string;
23
+ getModelPath(): string;
24
+ getExperimentName(): string;
25
+ getReadyState(): number;
26
+ getPort(): number;
27
+ getHost(): string;
28
+ getSocket(): WebSocket;
29
+ private setConnected;
30
+ private setExperimentState;
31
+ private setLoading;
32
+ private setContentError;
33
+ private setExperimentId;
34
+ private setExperimentName;
35
+ private setModelPath;
36
+ /**
37
+ * internal function to avoid unecessary boilerplate code,
38
+ * checks if gamasocket exists, and if it's ready to accept a new message
39
+ */
40
+ private socketCheck;
41
+ /**
42
+ * internal function that contains a simple try catch and stringifies a json payload to send it to the websocket
43
+ * @param payload json payload to be sent
44
+ */
45
+ private sendPayload;
46
+ /**
47
+ * internal function that returns the string of an experiment to run
48
+ * it represents the last used experiment or the new one if any specified
49
+ * @param new_exp_id id of the experiment passed by the user in parameter. used by default, sets the current experience to itself
50
+ * @returns the string of the Id of the last used experiment. Used if no new_exp_id is given
51
+ */
52
+ getId(new_exp_id?: string): string;
53
+ /**
54
+ * async function that closes the websocket connection, and runs the callback function passed in parameter if any.
55
+ * When called, creates a promise that either rejects after 15 seconds to avoid timeout lockdowns,
56
+ * or resolves after the close internalListener fires.
57
+ * @param optional callback Function to be called after the websocket's connection is closed
58
+ */
59
+ closeConnection(callback?: () => void): Promise<void>;
60
+ /**
61
+ * Connects the websocket client with gama server and manage the messages received
62
+ * this function is asynchronous, it needs to be called with await. This is because
63
+ * other functions need the websocket to be created and in the state "OPEN" to start
64
+ * sending messages, which is not done when the function has finished it's execution
65
+ * @returns WebSocket properly initialised at the end of the asynchronous execution
66
+ */
67
+ connectGama(): Promise<void>;
68
+ /**
69
+ * This function is used to watch on messages stream and look for a response to the command initiated.
70
+ * it resolves if the message received is of the same type specified in the parameter
71
+ * and throws an error if it's of any type specified in the GAMA_ERROR_MESSAGES specified in the constants file
72
+ * @returns returns a promise containing the response's message's content
73
+ */
74
+ success(successMessage: string): Promise<string>;
75
+ /**
76
+ * function used to check for a specific message on the websocket.
77
+ * returns a resolved boolean promise once the provided message is found
78
+ * @param messageType the basic type of the message you want to analyse
79
+ * @param field what part of the message to analyse
80
+ * @param expectedValue what you expect the field value to be
81
+ * @returns a resolved promise containing a boolean
82
+ */
83
+ listenFor(messageType: string, field: string, expectedValue: any): Promise<boolean>;
84
+ readyCheck(): Promise<void>;
85
+ /**
86
+ * loads and launches an experiment using the absolute path of it's model and
87
+ * the identifier of the experiment. Resolves when the server answers with a SimulationStatus of type "PAUSED"
88
+ * @param model_path absolute path pointing to the model cointaining the experiment
89
+ * @param experiment id of the experiment to load
90
+ */
91
+ loadExperiment(model_path: string, experiment: string): Promise<void>;
92
+ /**
93
+ * Starts or resumes the experiment specified.
94
+ * @param exp_id string name of the experiment to pause or resume
95
+ * @param sync boolean used if an end condition was specified when loading a simulation. the command will return only the SimulationEnded message if true, and both a response and a SimulationEnded message if false
96
+ * when starting the experiment
97
+ */
98
+ play(exp_id?: string, sync?: boolean): Promise<string | undefined>;
99
+ /**
100
+ * Pauses the experiment specified.
101
+ * @param exp_id optionnal parameter, will default to last used experiment
102
+ */
103
+ pause(exp_id?: string): Promise<string>;
104
+ reload(exp_id?: string, parameters?: string, until?: string): Promise<string>;
105
+ /**
106
+ * Sends a message to gama to order it to process a specified number of steps.
107
+ * Can only be used after the simulation has already been loaded
108
+ * @param exp_id the name of the experiment you want to step to. if not used, then the last used experiment Id will be used
109
+ * @param nb_step the number of steps you want to simulate. if none is specified, it will default to one step
110
+ */
111
+ step(nb_step?: number, sync?: boolean, exp_id?: string): Promise<string>;
112
+ /**
113
+ * ! you must be sure that the type of the experiment is compatible (record) before using this
114
+ * This command is used to rollback a specific amount of steps.
115
+ * Can only be used if the experiment is of type "record"
116
+ * @param exp_id the name of the experiment you want to step to. if not used, then the last used experiment Id will be used
117
+ * @param nb_step the number of steps you want to simulate. if none is specified, it will default to one step
118
+ */
119
+ stepback(nb_step?: number, exp_id?: string): Promise<string>;
120
+ /**
121
+ * stops the specified experiment or the current experiment if not specified
122
+ * @param exp_id optionnal parameter, leave empty to use the last used exp_id
123
+ */
124
+ stop(exp_id?: string): Promise<unknown>;
125
+ /**
126
+ * used to specify a fonction to be called on any message received by the websocket from the gama server
127
+ * you can only have one onMessage per client.
128
+ * @param callback the function you want to call upon receiving data through the javascript client
129
+ */
130
+ onMessage(callback: (data: any) => void): void;
131
+ /**
132
+ * kills the gama server.
133
+ * used to exit the gama server, closes the websocket connection and closes the gama instance
134
+ */
135
+ killGamaServer(): Promise<void>;
136
+ /**
137
+ * used to run execute an action defined in an agent in an experiment.
138
+ * @param action gaml code to be run from an agent
139
+ * @param args arguments of the action
140
+ * @param agent what agent this code applies to
141
+ * @param escaped optional parameter, if true will escape the action and args before sending them to gama
142
+ * @param exp_id optionnal parameter to specify the experiment. if none is given it will instead default to the last used experiment
143
+ * @returns a stringified response containing the result of the execution of the command
144
+ */
145
+ ask(action: string, args: string, agent: string, escaped?: boolean, exp_id?: string): Promise<string>;
146
+ /**
147
+ * Compiles the code given in parameter and returns a message if any errors are detected.
148
+ * @param expr gaml expression to test
149
+ * @param syntax optionnal boolean, if true will only check the syntax. false will check for both syntactical and semantic errors
150
+ * @param escaped optionnal boolean, dictates if the expression is escaped or not
151
+ * @returns stringified json containing errors in the code if any
152
+ */
153
+ validate(expr: string, syntax?: boolean, escaped?: boolean): Promise<string>;
154
+ /**
155
+ * This command is used to ask the server more information on a given model. When received,
156
+ * the server will compile the model and return the different components found, depending on the option picked by the client.
157
+ * @param model_path path to the model to evaluate
158
+ * @param experimentsNames optional boolean that returns the name of all the experiments of the model
159
+ * @param speciesNames optional boolean that returns all of the species' names
160
+ * @param speciesVariables optional boolean that returns all variables of the species
161
+ * @param speciesActions optional boolean that returns all actions in the species
162
+ */
163
+ describe(model_path: string, experimentsNames?: boolean, speciesNames?: boolean, speciesVariables?: boolean, speciesActions?: boolean): Promise<string>;
164
+ }
165
+
166
+ export { GamaClient as default };