@unitn-asa/deliveroo-js-sdk 1.3.3 → 1.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unitn-asa/deliveroo-js-sdk",
-  "version": "1.3.3",
+  "version": "1.3.4",
   "description": "Software development kit for Deliveroo.js",
   "author": "Marco Robol <marco.robol@unitn.it>",
   "type": "module",
@@ -31,6 +31,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "devDependencies": {},
-  "dependencies": {}
+  "devDependencies": {
+    "@types/node": "^25.6.0"
+  }
 }

package/src/client/DjsClientSocket.js

@@ -30,12 +30,12 @@ export class DjsClientSocket extends Socket {
     
     /** @type { Promise < IOAgent > } */
     me = new Promise( (res) => {
-        this.once( 'you', (agent, info) => {
+        this.once( 'you', (agent) => {
             res( agent );
         } );
     } );
     
-    /** @type { Promise } */
+    /** @type { Promise < IOConfig > } */
     config = new Promise( (res) => {
         this.once( 'config', (config) => {
             res( config );
@@ -129,7 +129,7 @@ export class DjsClientSocket extends Socket {
      * @param { string } id
      * @param { string } name
      * @param { {} } msg
-     * @param { function( any ) : void } replyAcknowledgmentCallback ( reply )
+     * @param { function( Object ) : void = } replyAcknowledgmentCallback ( reply )
      */
     /**
      * Listen to 'msg' events
@@ -187,6 +187,10 @@ export class DjsClientSocket extends Socket {
         } );
     }
 
+    /**ì
+     * @param {any} msg 
+     * @returns { Promise < { any } > } reply
+     */
     async emitShout ( msg ) {
         return new Promise( (success) => {
             this.emit( 'shout', msg, async ( status ) =>  {
@@ -219,10 +223,10 @@ export class DjsClientSocket extends Socket {
      * - if array of ids is provided: putdown only specified parcels
      * - if no list is provided: put down all parcels
      * When completed, resolves to the list of dropped parcels
-     * @param { string [] } selected array of parcels id to drop
+     * @param { string [] = } selected array of parcels id to drop
      * @returns { Promise < { id:string } [] >}
      */
-    async emitPutdown ( selected = null ) {
+    async emitPutdown ( selected = [] ) {
         return this.emitAndResolveOnAck( 'putdown', selected );
     }
 
@@ -235,7 +239,7 @@ export class DjsClientSocket extends Socket {
     
     /**
      * Listen to 'log' events from server and those redirected here from others client
-     * @param { function ( { src:'server'|'client', ms:number, frame: number, socket:string, id:string, name:string }, ...any) : void } callback ( { src, ms, frame, socket, id, name }, ...msgArgs )
+     * @param { function ( 'server' | { socket:string, id:string, name:string }, ...any) : void } callback ( { src, ms, frame, socket, id, name }, ...msgArgs )
      */
     onLog ( callback ) {
         this.on( "log", callback )
@@ -252,12 +256,15 @@ export class DjsClientSocket extends Socket {
 
         /**
          * Mixin function to copy methods from a class prototype to an object
+         * @param { any } target the object to enhance
+         * @param { any } MixinClass the class whose methods will be copied to the target
          */
         function applyMixin(target, MixinClass) {
             
             let proto = MixinClass.prototype;
 
             const descriptors = Object.getOwnPropertyDescriptors(proto);
+            // @ts-expect-error
             delete descriptors.constructor;
             
             Object.defineProperties(target, descriptors);

package/src/client/DjsConnect.js

@@ -25,15 +25,28 @@ export function DjsConnect ( host = process.env.HOST || 'http://localhost:8080',
     console.log( `Connecting to ${host} ${ token ? 'with token '+ (token).substring(0,5)+'...'+(token).substring(token.length-5) : name ? 'as '+name : 'with no token and no name' }` );
     
     enhancedClientSocket.onConnect( () => {
-        console.log( `Connected` )
+        console.log( `Connected` );
     });
 
     enhancedClientSocket.onceYou( me => {
-        console.log( `Authenticated as ${me.name}(${me.id}) in team ${me.teamName}(${me.teamId})` )
+        console.log( `Authenticated as ${me.name}(${me.id}) in team ${me.teamName}(${me.teamId})` );
     });
+
+    // Handle ping events to measure latency. The server will send a 'ping' event with a timestamp, and the client responds with a 'clientTimestamp' to allow the server to calculate round-trip time and network latency.
+    try {
+        enhancedClientSocket.on( "ping", ( pingData, callback ) => {
+            try {
+                callback( { clientTimestamp: performance.now() } );
+            } catch (error) {
+                console.warn("Error handling ping event");
+            }
+        } );
+    } catch (error) {
+        console.error("Error setting up ping event:", error);
+    }
     
     enhancedClientSocket.on( 'disconnect', (reason) => {
-        console.log( `Disconnected from ${host} because ${reason}` )
+        console.log( `Disconnected from ${host} because ${reason}` );
     });
 
     enhancedClientSocket.io.on("error", (error) => {

package/src/global.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Global type declarations for Node.js environment
+ */
+
+declare const process: {
+  env: {
+    HOST?: string;
+    TOKEN?: string;
+    NAME?: string;
+    [key: string]: string | undefined;
+  };
+};

package/src/types/IOAgent.json

@@ -0,0 +1,62 @@
+[
+  {
+    "type": "object",
+    "title": "IOAgent",
+    "required": [
+      "id",
+      "name",
+      "teamId",
+      "teamName",
+      "x",
+      "y",
+      "score",
+      "penalty"
+    ],
+    "properties": {
+      "id": {
+        "type": "string"
+      },
+      "name": {
+        "type": "string"
+      },
+      "teamId": {
+        "type": "string"
+      },
+      "teamName": {
+        "type": "string"
+      },
+      "x": {
+        "type": "object",
+        "anyOf": [
+          {
+            "classRelation": "is-a",
+            "$ref": "#/$defs/number"
+          },
+          {
+            "classRelation": "is-a",
+            "$ref": "#/$defs/undefined"
+          }
+        ]
+      },
+      "y": {
+        "type": "object",
+        "anyOf": [
+          {
+            "classRelation": "is-a",
+            "$ref": "#/$defs/number"
+          },
+          {
+            "classRelation": "is-a",
+            "$ref": "#/$defs/undefined"
+          }
+        ]
+      },
+      "score": {
+        "type": "number"
+      },
+      "penalty": {
+        "type": "number"
+      }
+    }
+  }
+]

package/src/types/IOGameOptions.js

@@ -26,9 +26,8 @@
  * @typedef IONpcsOptions
  * NPC configuration object
  * @property {IOClockEvent} moving_event                Event whenever the NPC moves
- * @property {string} type                              NPC type (random, collector, etc.)
+ * @property {'random'|'intelligent'} type                              NPC type (random, collector, etc.)
  * @property {number} count                             Number of NPCs of this type
- * @property {number} capacity                          Capacity (for collector NPCs)
 */
 
 /**

package/src/types/IOSocketEvents.js

@@ -4,6 +4,24 @@
 /** @typedef {import('./IOInfo.js').IOInfo} IOInfo */
 /** @typedef {import('./IOSensing.js').IOSensing} IOSensing */
 
+/**
+ * @typedef {Object} IOLatency
+ * @property {number} roundTrip - Total round trip time in milliseconds
+ * @property {number} clientProcessing - Time spent processing on the client side in milliseconds
+ * @property {number} serverProcessing - Time spent processing on the server side in milliseconds
+ * @property {number} networkLag - Estimated network latency in milliseconds
+ * @property {number} timestamp - Timestamp when the latency was measured (in milliseconds since epoch)
+ */
+
+/**
+ * @typedef {Object} IOMetrics
+ * @property { {ms: number, frame: number, fps: number, uptime: number} } timing
+ * @property { {heapUsed: number, heapTotal: number, rss: number, external: number} } memory
+ * @property { {current: number, samples: number[]} } cpu
+ * @property { {currentLag: number, maxLag: number, avgLag: number} } eventLoop
+ * @property { {count: number, avg: number, min: number, max: number, samples: IOLatency[], byAgent: Object.<string, {id: string, name: string, teamId: string, teamName: string, sockets: []}>} } latency
+ */
+
 /**
  * Client -> Server events. Emitted by the client and listened by the server.
  * @typedef {{
@@ -35,6 +53,8 @@
  *      'you':              function ( IOAgent ) : void,
  *      'sensing':          function ( IOSensing ) : void,
  *      'info':             function ( IOInfo ) : void,
+ *      'ping':             function ( { timestamp: number }, function ( { clientTimestamp: number } ) : void ) : void,
+ *      'metrics':          function ( IOMetrics ) : void,
  *      'msg':              function ( string, string, Object, function ( Object ) : void = ) : Object,
  *      'log':              function ( 'server' | { socket:string, id:string, name:string }, ...any ) : void
  * }} IOServerEvents