@gama-platform/gama-client 1.0.2

package/dist/gama_client.js

@@ -0,0 +1,532 @@
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+
+// src/gama_client.ts
+import WebSocket from "ws";
+
+// src/constants.ts
+var GAMA_ERROR_MESSAGES = [
+  "SimulationStatusError",
+  "SimulationErrorDialog",
+  "SimulationError",
+  "RuntimeError",
+  "GamaServerError",
+  "MalformedRequest",
+  "UnableToExecuteRequest"
+];
+
+// src/gama_client.ts
+import { getLogger } from "@logtape/logtape";
+var logger = getLogger(["GAMA-library", "GAMA-client"]);
+var GamaClient = class {
+  //websocket of the client. needs to be initialized by using the asynchronous connectGama() to be used               
+  /**
+   * 
+   * @param port port of gama server you want to reach
+   * @param host host of the gama server you want to reach
+   */
+  constructor(port, host) {
+    // json object detailing the state of the gama server, including: if connected, experiment details, errors from the server, and loading status
+    this.port = 1e3;
+    //default port number pointing to the gama server. can be redefined when using the constructor
+    this.host = "localhost";
+    this.jsonGamaState = {
+      connected: false,
+      model_path: "",
+      experiment_state: "NONE",
+      loading: false,
+      content_error: "",
+      experiment_id: "",
+      experiment_name: ""
+    };
+    this.port = port || 1e3;
+    this.host = host || "localhost";
+  }
+  //? GETTERS
+  isConnected() {
+    return this.jsonGamaState.connected;
+  }
+  getExperimentState() {
+    return this.jsonGamaState.experiment_state;
+  }
+  isLoading() {
+    return this.jsonGamaState.loading;
+  }
+  getContentError() {
+    return this.jsonGamaState.content_error;
+  }
+  getExperimentId() {
+    return this.jsonGamaState.experiment_id;
+  }
+  getModelPath() {
+    return this.jsonGamaState.model_path;
+  }
+  getExperimentName() {
+    return this.jsonGamaState.experiment_name;
+  }
+  getReadyState() {
+    return this.gama_socket.readyState;
+  }
+  getPort() {
+    return this.port;
+  }
+  getHost() {
+    return this.host;
+  }
+  getSocket() {
+    return this.gama_socket;
+  }
+  //? SETTERS --------------------------------------------------------------------------------------------------------------------------------------
+  setConnected(connected) {
+    this.jsonGamaState.connected = connected;
+  }
+  setExperimentState(state) {
+    this.jsonGamaState.experiment_state = state;
+  }
+  setLoading(loading) {
+    this.jsonGamaState.loading = loading;
+  }
+  setContentError(content_error) {
+    this.jsonGamaState.content_error = content_error;
+  }
+  setExperimentId(experiment_id) {
+    this.jsonGamaState.experiment_id = experiment_id;
+  }
+  setExperimentName(experiment_name) {
+    this.jsonGamaState.experiment_name = experiment_name;
+  }
+  setModelPath(model_path) {
+    this.jsonGamaState.model_path = model_path;
+  }
+  //? INTERNAL UTILITIES ---------------------------------------------------------------------------------------------------------------------------
+  /**
+   * internal function to avoid unecessary boilerplate code,
+   * checks if gamasocket exists, and if it's ready to accept a new message
+   */
+  socketCheck() {
+    if (!this.gama_socket) {
+      throw new Error("No socket connected to GAMA Server found");
+    } else if (!this.jsonGamaState.connected) {
+      throw new Error("Gama is not connected");
+    } else if (!(this.getReadyState() === WebSocket.OPEN || this.getReadyState() === WebSocket.CONNECTING)) {
+      throw new Error("socket not in the OPEN state");
+    } else {
+      logger.trace("Websocket is connected and open");
+      this.setConnected(true);
+    }
+  }
+  /**
+   * internal function that contains a simple try catch and stringifies a json payload to send it to the websocket
+   * @param payload json payload to be sent
+   */
+  sendPayload(payload) {
+    try {
+      this.gama_socket.send(JSON.stringify(payload));
+      logger.debug("sent message to websocket:{payload}", { payload });
+    } catch (error) {
+      throw new Error(`couldn't send the message to the websocket:${error}`);
+    }
+  }
+  /**
+   * internal function that returns the string of an experiment to run
+   * it represents the last used experiment or the new one if any specified
+   * @param new_exp_id id of the experiment passed by  the user in parameter. used by default, sets the current experience to itself
+   * @returns the string of the Id of the last used experiment. Used if no new_exp_id is given
+   */
+  getId(new_exp_id) {
+    if (new_exp_id) {
+      this.setExperimentId(new_exp_id);
+      return new_exp_id;
+    } else {
+      if (this.getExperimentId() === "") throw new Error("no current experiment to be called");
+      return this.getExperimentId();
+    }
+  }
+  /**
+   * async function that closes the websocket connection, and runs the callback function passed in parameter if any.
+   * When called, creates a promise that either rejects after 15 seconds to avoid timeout lockdowns,
+   * or resolves after the close internalListener fires. 
+   * @param optional callback Function to be called after the websocket's connection is closed
+   */
+  async closeConnection(callback) {
+    if (!this.gama_socket || this.getReadyState() === WebSocket.CLOSED) {
+      logger.warn("Websocket already closed, running the callback function");
+      if (callback) callback();
+      return;
+    }
+    if (this.getReadyState() === WebSocket.OPEN || this.getReadyState() === WebSocket.CONNECTING) {
+      await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          this.gama_socket.removeEventListener("close", internalListener);
+          reject(new Error("Websocket timed out"));
+        }, 15e3);
+        const internalListener = () => {
+          clearTimeout(timer);
+          this.gama_socket.removeEventListener("close", internalListener);
+          resolve();
+        };
+        this.gama_socket.addEventListener("close", internalListener);
+        this.gama_socket.close();
+      });
+      if (callback) callback();
+    }
+  }
+  /**
+  * Connects the websocket client with gama server and manage the messages received
+  * this function is asynchronous, it needs to be called with await. This is because
+  * other functions need the websocket to be created and in the state "OPEN" to start
+  * sending messages, which is not done when the function has finished it's execution
+  * @returns WebSocket properly initialised at the end of the asynchronous execution
+  */
+  async connectGama() {
+    return new Promise((resolve, reject) => {
+      if (this.gama_socket && (this.getReadyState() === WebSocket.OPEN || this.getReadyState() === WebSocket.CONNECTING)) {
+        this.setConnected(true);
+        logger.info("Already connected or connecting. Skipping. status:{status}", { status: this.getReadyState() });
+        return resolve();
+      }
+      try {
+        this.gama_socket = new WebSocket(`ws://${this.host}:${this.port}`);
+        this.gama_socket.onopen = () => {
+          this.setConnected(true);
+          logger.info("created new connection to {host}:{port}", { host: this.host, port: this.port });
+          this.gama_socket.onclose = () => {
+            this.setConnected(false);
+            this.setExperimentState("NONE");
+            logger.info("successfully closed the websocket.");
+          };
+          const simulationStatus = (event) => {
+            const message = JSON.parse(event.data);
+            if (message.type === "SimulationStatus") {
+              this.setExperimentState(message.content);
+              this.setExperimentId(message.exp_id);
+            }
+            logger.info("JsonGamaState:{state}", { state: this.getExperimentName() });
+          };
+          this.gama_socket.addEventListener("message", simulationStatus);
+          return resolve();
+        };
+        this.gama_socket.onerror = (error) => {
+          this.setConnected(false);
+          if (error.error.code == "ECONNREFUSED") {
+            logger.trace(`full stack trace for Error CONNREFUSED {error}`, { error });
+            logger.error("The platform can't connect to GAMA at address {host}:{port}", { host: this.host, port: this.port });
+            reject(new Error(`Failed to connect to GAMA at ${this.host}:${this.port} with error code ECONNREFUSED`));
+          } else {
+            logger.error(`An error happened within the Gama Server WebSocket
+{error}`, { error });
+            reject(new Error(`Failed to connect to GAMA at ${this.host}:${this.port}`));
+          }
+        };
+      } catch (e) {
+        const err = e;
+        logger.error("Synchronous error when creating the websocket:{error}", { error: err.message });
+        reject(e);
+      }
+    });
+  }
+  /**
+  * This function is used to watch on messages stream and look for a response to the command initiated.
+  * it resolves if the message received is of the same type specified in the parameter
+  * and throws an error if it's of any type specified in the GAMA_ERROR_MESSAGES specified in the constants file
+  * @returns returns a promise containing the response's message's content
+  */
+  async success(successMessage) {
+    return new Promise((resolve, reject) => {
+      const onMessage = (event) => {
+        const message = JSON.parse(event.data);
+        const type = message.type;
+        if (type === successMessage) {
+          this.gama_socket.removeEventListener("message", onMessage);
+          resolve(message);
+        } else if (GAMA_ERROR_MESSAGES.includes(type)) {
+          this.gama_socket.removeEventListener("message", onMessage);
+          this.setContentError(message.content);
+          reject(`Couldn't execute command on the Gama Server. ${type}: ${JSON.stringify(message.content)}`);
+        }
+      };
+      this.gama_socket.addEventListener("message", onMessage);
+    });
+  }
+  /**
+   * function used to check for a specific message on the websocket.
+   * returns a resolved boolean promise once the provided message is found
+   * @param messageType the basic type of the message you want to analyse
+   * @param field what part of the message to analyse 
+   * @param expectedValue what you expect the field value to be
+   * @returns a resolved promise containing a boolean
+   */
+  //Voir pour retourner le message au lieu de juste retourner un booléen ? 
+  async listenFor(messageType, field, expectedValue) {
+    if (!this.gama_socket) {
+      throw new Error("couldn't find an active gama socket when creating a listener:");
+    }
+    return new Promise((resolve, reject) => {
+      const listener = (event) => {
+        const message = JSON.parse(event.data);
+        logger.debug("message:  {message}", { message });
+        const type = message.type;
+        if (type === messageType && message[field] === expectedValue) {
+          clearTimeout(timer);
+          resolve(true);
+          this.gama_socket.removeEventListener("message", listener);
+        }
+      };
+      const timer = setTimeout(() => {
+        this.gama_socket.removeEventListener("message", listener);
+        reject(new Error("Websocket timed out"));
+      }, 15e3);
+      this.gama_socket.addEventListener("message", listener);
+      logger.debug("added an event listener to the gama_socket");
+    });
+  }
+  async readyCheck() {
+    const isReady = new Promise(async (resolve, reject) => {
+      if (this.getExperimentState() === "PAUSED" || "RUNNING") {
+        resolve(true);
+      } else {
+        return await this.listenFor("SimulationStatus", "content", "PAUSED");
+      }
+    });
+  }
+  //? GAMA FUNCTIONS ---------------------------------------------------------------------------------------------------------------------------
+  /**
+   * loads and launches an experiment using the absolute path of it's model and
+   * the identifier of the experiment. Resolves when the server answers with a SimulationStatus of type "PAUSED"
+   * @param model_path absolute path pointing to the model cointaining the experiment
+   * @param experiment id of the experiment to load
+   */
+  async loadExperiment(model_path, experiment) {
+    this.socketCheck();
+    const payload = {
+      "type": "load",
+      "model": model_path,
+      "experiment": experiment
+    };
+    this.sendPayload(payload);
+    this.setModelPath(model_path);
+    this.setExperimentName(experiment);
+    this.setExperimentId(experiment);
+    await this.success("CommandExecutedSuccessfully");
+    return await this.readyCheck();
+  }
+  /**
+   * Starts or resumes the experiment specified.
+   * @param exp_id string name of the experiment to pause or resume
+   * @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
+   * when starting the experiment
+   */
+  async play(exp_id, sync) {
+    this.socketCheck();
+    if (this.getExperimentState() === "NOTREADY") {
+      logger.warn("Simulation not ready yet, waiting for PAUSED simulationstatus");
+      await this.listenFor("Simulationstatus", "content", "PAUSED");
+    } else if (this.getExperimentState() === "PAUSED") {
+      const payload = __spreadValues({
+        "type": "play",
+        "exp_id": this.getId()
+      }, sync && { "sync": sync });
+      this.sendPayload(payload);
+      return await this.success("CommandExecutedSuccessfully");
+    } else if (this.getExperimentState() === "RUNNING") {
+      logger.warn("cannot unpause a running simulation");
+    }
+  }
+  /**
+   * Pauses the experiment specified.
+   * @param exp_id optionnal parameter, will default to last used experiment
+   */
+  async pause(exp_id) {
+    this.socketCheck();
+    const payload = {
+      "type": "pause",
+      "exp_id": this.getId(exp_id)
+    };
+    this.sendPayload(payload);
+    return await this.success("CommandExecutedSuccessfully");
+  }
+  async reload(exp_id, parameters, until) {
+    this.socketCheck();
+    if (this.getExperimentState() === "NOTREADY") {
+      await this.listenFor("Simulationstatus", "content", "PAUSED");
+    }
+    const payload = __spreadValues(__spreadValues({
+      "type": "reload",
+      "exp_id": this.getId(exp_id)
+    }, parameters && { "parameters": parameters }), until && { "until": until });
+    this.sendPayload(payload);
+    return await this.success("CommandExecutedSuccessfully");
+  }
+  /**
+   * Sends a message to gama to order it to process a specified number of steps.
+   * Can only be used after the simulation has already been loaded
+   * @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
+   * @param nb_step the number of steps you want to simulate. if none is specified, it will default to one step
+   */
+  async step(nb_step, sync, exp_id) {
+    this.socketCheck();
+    if (this.getExperimentState() === "NOTREADY") {
+      logger.warn("The experiment is not yet ready:{state}", { state: this.getExperimentState() });
+      await this.listenFor("Simulationstatus", "content", "PAUSED");
+    }
+    const exp_id_payload = exp_id ? exp_id : this.getExperimentId();
+    if (exp_id_payload === "") throw new Error("no experience_id specified, and no experiment in the jsongamastate");
+    const payload = __spreadProps(__spreadValues({
+      "type": "step",
+      "exp_id": exp_id_payload
+    }, nb_step && { "nb_step": nb_step }), {
+      "sync": true
+    });
+    this.sendPayload(payload);
+    return await this.success("CommandExecutedSuccessfully");
+  }
+  /** 
+   * ! you must be sure that the type of the experiment is compatible (record) before using this
+   * This command is used to rollback a specific amount of steps.
+   * Can only be used if the experiment is of type "record"
+   * @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
+   * @param nb_step  the number of steps you want to simulate. if none is specified, it will default to one step
+   */
+  async stepback(nb_step, exp_id) {
+    this.socketCheck();
+    const payload = __spreadProps(__spreadValues({
+      "type": "stepBack",
+      "exp_id": this.getId(exp_id)
+    }, nb_step && { "nb_step": nb_step }), {
+      "sync": true
+    });
+    this.sendPayload(payload);
+    return await this.success("CommandExecutedSuccessfully");
+  }
+  /**
+   * stops the specified experiment or the current experiment if not specified
+   * @param exp_id optionnal parameter, leave empty to use the last used exp_id
+   */
+  async stop(exp_id) {
+    this.socketCheck();
+    if (this.getExperimentState() !== "NONE") {
+      try {
+        const payload = {
+          "type": "stop",
+          "exp_id": this.getId(exp_id)
+        };
+        this.sendPayload(payload);
+        return await this.success("CommandExecutedSuccessfully");
+      } catch (error) {
+        throw new Error(`couldn't stop the experiment:${error}`);
+      }
+    } else {
+      logger.warn(`couldn't stop the experiment, no experiment running`);
+      return new Promise((resolve) => {
+        resolve("couldn't stop experiment");
+      });
+    }
+  }
+  /**
+   * used to specify a fonction to be called on any message received by the websocket from the gama server
+   * you can only have one onMessage per client.
+   * @param callback the function you want to call upon receiving data through the javascript client
+   */
+  onMessage(callback) {
+    if (!this.gama_socket) {
+      throw new Error("WebSocket is not initialized");
+    }
+    this.gama_socket.on("message", (data) => {
+      try {
+        const parsed = JSON.parse(data.toString());
+        callback(parsed);
+      } catch (err) {
+        logger.warn("Received non-JSON message:{data}", { data });
+        callback(data);
+      }
+    });
+  }
+  /**
+   * kills the gama server.
+   * used to exit the gama server, closes the websocket connection and closes the gama instance 
+   */
+  async killGamaServer() {
+    this.socketCheck();
+    const payload = { "type": "exit" };
+    this.sendPayload(payload);
+  }
+  /**
+   * used to run execute an action defined in an agent in an experiment.
+   * @param action gaml code to be run from an agent
+   * @param args arguments of the action
+   * @param agent what agent this code applies to
+   * @param escaped optional parameter, if true will escape the action and args before sending them to gama
+   * @param exp_id optionnal parameter to specify the experiment. if none is given it will instead default to the last used experiment
+   * @returns a stringified response containing the result of the execution of the command
+   */
+  async ask(action, args, agent, escaped, exp_id) {
+    this.socketCheck();
+    var payload = __spreadValues({
+      "type": "ask",
+      "exp_id": this.getId(exp_id),
+      "action": action,
+      "args": args,
+      "agent": agent
+    }, escaped && { "escaped": escaped });
+    this.sendPayload(payload);
+    return await this.success("CommandExecutedSuccessfully");
+  }
+  /**
+   * Compiles the code given in parameter and returns a message if any errors are detected.
+   * @param expr gaml expression to test
+   * @param syntax optionnal boolean, if true will only check the syntax. false will check for both syntactical and semantic errors
+   * @param escaped optionnal boolean, dictates if the expression is escaped or not
+   * @returns stringified json containing errors in the code if any
+   */
+  async validate(expr, syntax, escaped) {
+    this.socketCheck();
+    const payload = __spreadValues(__spreadValues({
+      "type": "validate",
+      "expr": expr
+    }, syntax && { "syntax": syntax }), escaped && { "escaped": escaped });
+    this.sendPayload(payload);
+    try {
+      return await this.success("CommandExecutedSuccessfully");
+    } catch (err) {
+      throw err;
+    }
+  }
+  /**
+   * This command is used to ask the server more information on a given model. When received, 
+   * the server will compile the model and return the different components found, depending on the option picked by the client.
+   * @param model_path path to the model to evaluate
+   * @param experimentsNames optional boolean that returns the name of all the experiments of the model
+   * @param speciesNames optional boolean that returns all of the species' names
+   * @param speciesVariables optional boolean that returns all variables of the species
+   * @param speciesActions optional boolean that returns all actions in the species
+   */
+  async describe(model_path, experimentsNames, speciesNames, speciesVariables, speciesActions) {
+    this.socketCheck();
+    const payload = __spreadValues(__spreadValues(__spreadValues(__spreadValues({
+      "type": "describe",
+      "model": model_path
+    }, experimentsNames && { "experiments": experimentsNames }), speciesNames && { "speciesNames": speciesNames }), speciesActions && { "speciesActions": speciesActions }), speciesVariables && { "speciesVariables": speciesVariables });
+    this.sendPayload(payload);
+    return await this.success("CommandExecutedSuccessfully");
+  }
+};
+export {
+  GamaClient as default
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+    "name": "@gama-platform/gama-client",
+    "version": "1.0.2",
+    "type": "module",
+    "description": "library to control simulations from a js client",
+    "main": "./dist/gama_client.cjs",
+    "module": "./dist/gama_client.js",
+    "types": "./dist/gama_client.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/gama_client.js",
+            "require": "./dist/gama_client.cjs",
+            "types": "./dist/gama_client.d.ts"
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "dependencies": {
+        "@logtape/logtape": "^2.0.4",
+        "path": "^0.12.7",
+        "react": "^18.3.1",
+        "ws": "^8.17.1"
+    },
+    "devDependencies": {
+        "@babel/preset-typescript": "^7.27.1",
+        "@tsconfig/node20": "^20.1.5",
+        "@types/jest": "^29.5.14",
+        "@types/ws": "^8.18.1",
+        "jest": "^29.7.0",
+        "ts-jest": "^29.3.3",
+        "ts-node": "^10.9.2",
+        "tsx": "^4.19.4",
+        "tsup": "^8.4.0",
+        "typescript": "^5.8.3"
+    },
+    "scripts": {
+        "build": "tsup src/gama_client.ts --format esm,cjs --dts --out-dir dist",
+        "test": "npx jest --detectOpenHandles"
+    }
+}