node-osc 11.1.0 → 11.2.0

package/lib/Client.mjs

@@ -1,42 +1,92 @@
 import { createSocket } from 'node:dgram';
-import { toBuffer } from '#osc';
+import { EventEmitter } from 'node:events';
+import { encode } from './osc.mjs';
 import Message from './Message.mjs';
 
-class Client {
+/**
+ * OSC Client for sending messages and bundles over UDP.
+ * 
+ * Extends EventEmitter and emits the following events:
+ * - 'error': Emitted when a socket error occurs
+ * 
+ * @class
+ * @extends EventEmitter
+ * @example
+ * // Create a client
+ * const client = new Client('127.0.0.1', 3333);
+ * 
+ * // Send a message with callback
+ * client.send('/oscAddress', 200, (err) => {
+ *   if (err) console.error(err);
+ *   client.close();
+ * });
+ * 
+ * @example
+ * // Send a message with async/await
+ * const client = new Client('127.0.0.1', 3333);
+ * await client.send('/oscAddress', 200);
+ * await client.close();
+ */
+class Client extends EventEmitter {
+  /**
+   * Create an OSC Client.
+   * 
+   * @param {string} host - The hostname or IP address of the OSC server.
+   * @param {number} port - The port number of the OSC server.
+   * 
+   * @example
+   * const client = new Client('127.0.0.1', 3333);
+   */
   constructor(host, port) {
+    super();
     this.host = host;
     this.port = port;
     this._sock = createSocket({
       type: 'udp4',
       reuseAddr: true
     });
+    
+    this._sock.on('error', (err) => {
+      this.emit('error', err);
+    });
   }
+  /**
+   * Close the client socket.
+   * 
+   * This method can be used with either a callback or as a Promise.
+   * 
+   * @param {Function} [cb] - Optional callback function called when socket is closed.
+   * @returns {Promise<void>|undefined} Returns a Promise if no callback is provided.
+   * 
+   * @example
+   * // With callback
+   * client.close((err) => {
+   *   if (err) console.error(err);
+   * });
+   * 
+   * @example
+   * // With async/await
+   * await client.close();
+   */
   close(cb) {
-    this._sock.close(cb);
-  }
-  send(...args) {
-    let message = args[0];
-    let callback;
-    if (typeof args[args.length - 1] === 'function') {
-      callback = args.pop();
-    }
-    else {
-      callback = () => {};
+    if (cb) {
+      this._sock.close(cb);
+    } else {
+      return new Promise((resolve, reject) => {
+        this._sock.close((err) => {
+          if (err) reject(err);
+          else resolve();
+        });
+      });
     }
-
-    if (message instanceof Array) {
-      message = {
-        address: message[0],
-        args: message.splice(1)
-      };
-    }
-    
+  }
+  _performSend(message, args, callback) {
     let mes;
     let buf;
     try {
       switch (typeof message) {
         case 'object':
-          buf = toBuffer(message);
+          buf = encode(message);
           this._sock.send(buf, 0, buf.length, this.port, this.host, callback);
           break;
         case 'string':
@@ -44,7 +94,7 @@ class Client {
           for (let i = 1; i < args.length; i++) {
             mes.append(args[i]);
           }
-          buf = toBuffer(mes);
+          buf = encode(mes);
           this._sock.send(buf, 0, buf.length, this.port, this.host, callback);
           break;
         default:
@@ -58,6 +108,71 @@ class Client {
       callback(error);
     }
   }
+  /**
+   * Send an OSC message or bundle to the server.
+   * 
+   * This method can be used with either a callback or as a Promise.
+   * Messages can be sent in several formats:
+   * - As separate arguments: address followed by values
+   * - As a Message or Bundle object
+   * - As an array: [address, ...values]
+   * 
+   * @param {...*} args - The message to send. Can be:
+   *   - (address: string, ...values: any[], callback?: Function)
+   *   - (message: Message|Bundle, callback?: Function)
+   *   - (array: Array, callback?: Function)
+   * @returns {Promise<void>|undefined} Returns a Promise if no callback is provided.
+   * 
+   * @throws {TypeError} If the message format is invalid.
+   * @throws {ReferenceError} If attempting to send on a closed socket.
+   * 
+   * @example
+   * // Send with address and arguments
+   * client.send('/oscAddress', 200, 'hello', (err) => {
+   *   if (err) console.error(err);
+   * });
+   * 
+   * @example
+   * // Send with async/await
+   * await client.send('/oscAddress', 200, 'hello');
+   * 
+   * @example
+   * // Send a Message object
+   * const msg = new Message('/test', 1, 2, 3);
+   * await client.send(msg);
+   * 
+   * @example
+   * // Send a Bundle object
+   * const bundle = new Bundle(['/one', 1], ['/two', 2]);
+   * await client.send(bundle);
+   */
+  send(...args) {
+    let message = args[0];
+    let callback;
+    
+    // Convert array syntax to message object
+    if (message instanceof Array) {
+      message = {
+        address: message[0],
+        args: message.splice(1)
+      };
+    }
+    
+    if (typeof args[args.length - 1] === 'function') {
+      callback = args.pop();
+      this._performSend(message, args, callback);
+    }
+    else {
+      // No callback provided, return a Promise
+      return new Promise((resolve, reject) => {
+        callback = (err) => {
+          if (err) reject(err);
+          else resolve();
+        };
+        this._performSend(message, args, callback);
+      });
+    }
+  }
 }
 
 export default Client;

package/lib/Message.mjs

@@ -2,23 +2,109 @@ const typeTags = {
   s: 'string',
   f: 'float',
   i: 'integer',
-  b: 'blob'
+  b: 'blob',
+  m: 'midi'
 };
 
+/**
+ * Represents a typed argument for an OSC message.
+ * 
+ * @class
+ * @private
+ */
 class Argument {
+  /**
+   * @param {string} type - The type of the argument (string, float, integer, blob, boolean).
+   * @param {*} value - The value of the argument.
+   */
   constructor(type, value) {
     this.type = type;
     this.value = value;
   }
 }
 
+/**
+ * Represents an OSC message with an address and arguments.
+ * 
+ * OSC messages consist of an address pattern (string starting with '/')
+ * and zero or more arguments of various types.
+ * 
+ * @class
+ * 
+ * @example
+ * // Create a message with constructor arguments
+ * const msg = new Message('/test', 1, 2, 'hello');
+ * 
+ * @example
+ * // Create a message and append arguments
+ * const msg = new Message('/test');
+ * msg.append(1);
+ * msg.append('hello');
+ * msg.append(3.14);
+ */
 class Message {
+  /**
+   * Create an OSC Message.
+   * 
+   * @param {string} address - The OSC address pattern (e.g., '/oscillator/frequency').
+   * @param {...*} args - Optional arguments to include in the message.
+   * 
+   * @example
+   * const msg = new Message('/test');
+   * 
+   * @example
+   * const msg = new Message('/test', 1, 2, 3);
+   * 
+   * @example
+   * const msg = new Message('/synth', 'note', 60, 0.5);
+   */
   constructor(address, ...args) {
     this.oscType = 'message';
     this.address = address;
     this.args = args;
   }
   
+  /**
+   * Append an argument to the message.
+   * 
+   * Automatically detects the type based on the JavaScript type:
+   * - Integers are encoded as OSC integers
+   * - Floats are encoded as OSC floats
+   * - Strings are encoded as OSC strings
+   * - Booleans are encoded as OSC booleans
+   * - Buffers are encoded as OSC blobs
+   * - Arrays are recursively appended
+   * - Objects with a 'type' property are used as-is
+   * 
+   * @param {*} arg - The argument to append. Can be:
+   *   - A primitive value (number, string, boolean)
+   *   - A Buffer (encoded as blob)
+   *   - An array of values (will be recursively appended)
+   *   - An object with 'type' and 'value' properties for explicit type control
+   * 
+   * @throws {Error} If the argument type cannot be encoded.
+   * 
+   * @example
+   * const msg = new Message('/test');
+   * msg.append(42);           // Integer
+   * msg.append(3.14);         // Float
+   * msg.append('hello');      // String
+   * msg.append(true);         // Boolean
+   * 
+   * @example
+   * // Append multiple values at once
+   * msg.append([1, 2, 3]);
+   * 
+   * @example
+   * // Explicitly specify type
+   * msg.append({ type: 'float', value: 42 });
+   * msg.append({ type: 'blob', value: Buffer.from('data') });
+   * 
+   * @example
+   * // MIDI messages (4 bytes: port, status, data1, data2)
+   * msg.append({ type: 'midi', value: { port: 0, status: 144, data1: 60, data2: 127 } });
+   * msg.append({ type: 'm', value: Buffer.from([0, 144, 60, 127]) });
+   */
   append(arg) {
     let argOut;
     switch (typeof arg) {

package/lib/Server.mjs

@@ -3,14 +3,84 @@ import { EventEmitter } from 'node:events';
 
 import decode from '#decode';
 
+/**
+ * OSC Server for receiving messages and bundles over UDP.
+ * 
+ * Emits the following events:
+ * - 'listening': Emitted when the server starts listening
+ * - 'message': Emitted when an OSC message is received (receives msg array and rinfo object)
+ * - 'bundle': Emitted when an OSC bundle is received (receives bundle object and rinfo object)
+ * - 'error': Emitted when a socket error or decoding error occurs (receives error and rinfo)
+ * - Address-specific events: Emitted for each message address (e.g., '/test')
+ * 
+ * @class
+ * @extends EventEmitter
+ * 
+ * @fires Server#listening
+ * @fires Server#message
+ * @fires Server#bundle
+ * @fires Server#error
+ * 
+ * @example
+ * // Create and listen for messages
+ * const server = new Server(3333, '0.0.0.0', () => {
+ *   console.log('Server is listening');
+ * });
+ * 
+ * server.on('message', (msg, rinfo) => {
+ *   console.log('Message:', msg);
+ *   console.log('From:', rinfo.address, rinfo.port);
+ * });
+ * 
+ * @example
+ * // Using async/await with events.once
+ * import { once } from 'node:events';
+ * 
+ * const server = new Server(3333, '0.0.0.0');
+ * await once(server, 'listening');
+ * 
+ * server.on('message', (msg) => {
+ *   console.log('Message:', msg);
+ * });
+ * 
+ * @example
+ * // Listen for specific OSC addresses
+ * server.on('/note', (msg) => {
+ *   const [address, pitch, velocity] = msg;
+ *   console.log(`Note: ${pitch}, Velocity: ${velocity}`);
+ * });
+ */
 class Server extends EventEmitter {
+  /**
+   * Create an OSC Server.
+   * 
+   * @param {number} port - The port to listen on.
+   * @param {string} [host='127.0.0.1'] - The host address to bind to. Use '0.0.0.0' to listen on all interfaces.
+   * @param {Function} [cb] - Optional callback function called when server starts listening.
+   * 
+   * @example
+   * // Basic server
+   * const server = new Server(3333);
+   * 
+   * @example
+   * // Server on all interfaces with callback
+   * const server = new Server(3333, '0.0.0.0', () => {
+   *   console.log('Server started');
+   * });
+   * 
+   * @example
+   * // Host parameter can be omitted, callback as second parameter
+   * const server = new Server(3333, () => {
+   *   console.log('Server started on 127.0.0.1');
+   * });
+   */
   constructor(port, host='127.0.0.1', cb) {
     super();
     if (typeof host === 'function') {
       cb = host;
       host = '127.0.0.1';
     }
-    if (!cb) cb = () => {};
+    
     let decoded;
     this.port = port;
     this.host = host;
@@ -19,10 +89,20 @@ class Server extends EventEmitter {
       reuseAddr: true
     });
     this._sock.bind(port, host);
-    this._sock.on('listening', () => {
-      this.emit('listening');
-      cb();
-    });
+    
+    // Support both callback and promise-based listening
+    if (cb) {
+      this._sock.on('listening', () => {
+        this.emit('listening');
+        cb();
+      });
+    } else {
+      // For promise support, still emit the event but don't require a callback
+      this._sock.on('listening', () => {
+        this.emit('listening');
+      });
+    }
+    
     this._sock.on('message', (msg, rinfo) => {
       try {
         decoded = decode(msg);
@@ -40,9 +120,40 @@ class Server extends EventEmitter {
         this.emit(decoded[0], decoded, rinfo);
       }
     });
+    
+    this._sock.on('error', (err) => {
+      this.emit('error', err);
+    });
   }
+  /**
+   * Close the server socket.
+   * 
+   * This method can be used with either a callback or as a Promise.
+   * 
+   * @param {Function} [cb] - Optional callback function called when socket is closed.
+   * @returns {Promise<void>|undefined} Returns a Promise if no callback is provided.
+   * 
+   * @example
+   * // With callback
+   * server.close((err) => {
+   *   if (err) console.error(err);
+   * });
+   * 
+   * @example
+   * // With async/await
+   * await server.close();
+   */
   close(cb) {
-    this._sock.close(cb);
+    if (cb) {
+      this._sock.close(cb);
+    } else {
+      return new Promise((resolve, reject) => {
+        this._sock.close((err) => {
+          if (err) reject(err);
+          else resolve();
+        });
+      });
+    }
   }
 }
 

package/lib/index.mjs

@@ -2,3 +2,4 @@ export { default as Message } from './Message.mjs';
 export { default as Bundle } from './Bundle.mjs';
 export { default as Server } from './Server.mjs';
 export { default as Client } from './Client.mjs';
+export { encode, decode } from './osc.mjs';

package/lib/internal/decode.mjs

@@ -1,4 +1,4 @@
-import { fromBuffer } from '#osc';
+import { decode } from '../osc.mjs';
 
 function sanitizeMessage(decoded) {
   const message = [];
@@ -17,8 +17,8 @@ function sanitizeBundle(decoded) {
   return decoded;
 }
 
-function decode(data, customFromBuffer = fromBuffer) {
-  const decoded = customFromBuffer(data);
+function decodeAndSanitize(data, customDecode = decode) {
+  const decoded = customDecode(data);
   if (decoded.oscType === 'bundle') {
     return sanitizeBundle(decoded);
   }
@@ -30,4 +30,4 @@ function decode(data, customFromBuffer = fromBuffer) {
   }
 }
 
-export default decode;
+export default decodeAndSanitize;

package/{dist/lib/internal/osc.js → lib/osc.mjs}

@@ -1,10 +1,10 @@
-'use strict';
-
 // OSC 1.0 Protocol Implementation
 // Based on http://opensoundcontrol.org/spec-1_0
 
 // Helper functions for OSC encoding/decoding
 
+import { Buffer } from 'node:buffer';
+
 function padString(str) {
   const nullTerminated = str + '\0';
   const padding = 4 - (nullTerminated.length % 4);
@@ -149,6 +149,9 @@ function encodeArgument(arg) {
         // For doubles, use float for now (OSC 1.0 doesn't have double)
         return { tag: 'f', data: writeFloat32(arg.value) };
       case 'T':
+        return { tag: 'T', data: Buffer.alloc(0) };
+      case 'F':
+        return { tag: 'F', data: Buffer.alloc(0) };
       case 'boolean':
         return arg.value ? { tag: 'T', data: Buffer.alloc(0) } : { tag: 'F', data: Buffer.alloc(0) };
       case 'm':
@@ -202,7 +205,37 @@ function decodeArgument(tag, buffer, offset) {
   }
 }
 
-function toBuffer(message) {
+/**
+ * Encode an OSC message or bundle to a Buffer.
+ * 
+ * This low-level function converts OSC messages and bundles into binary format
+ * for transmission or storage. Useful for sending OSC over custom transports
+ * (WebSocket, TCP, HTTP), storing to files, or implementing custom OSC routers.
+ * 
+ * @param {Object} message - OSC message or bundle object with oscType property
+ * @returns {Buffer} The encoded OSC data ready for transmission
+ * 
+ * @example
+ * // Encode a message
+ * import { Message, encode } from 'node-osc';
+ * 
+ * const message = new Message('/oscillator/frequency', 440);
+ * const buffer = encode(message);
+ * console.log('Encoded bytes:', buffer.length);
+ * 
+ * @example
+ * // Encode a bundle
+ * import { Bundle, encode } from 'node-osc';
+ * 
+ * const bundle = new Bundle(['/one', 1], ['/two', 2]);
+ * const buffer = encode(bundle);
+ * 
+ * @example
+ * // Send over WebSocket
+ * const buffer = encode(message);
+ * websocket.send(buffer);
+ */
+function encode(message) {
   if (message.oscType === 'bundle') {
     return encodeBundleToBuffer(message);
   } else {
@@ -253,7 +286,39 @@ function encodeBundleToBuffer(bundle) {
   return Buffer.concat([bundleStringBuffer, timetagBuffer, ...elementBuffers]);
 }
 
-function fromBuffer(buffer) {
+/**
+ * Decode a Buffer containing OSC data into a message or bundle object.
+ * 
+ * This low-level function parses binary OSC data back into JavaScript objects.
+ * Useful for receiving OSC over custom transports, reading from files,
+ * or implementing custom OSC routers.
+ * 
+ * @param {Buffer} buffer - The Buffer containing OSC data
+ * @returns {Object} The decoded OSC message or bundle. Messages have
+ *   {oscType: 'message', address: string, args: Array}, bundles have
+ *   {oscType: 'bundle', timetag: number, elements: Array}
+ * @throws {Error} If the buffer contains malformed OSC data
+ * 
+ * @example
+ * // Decode received data
+ * import { decode } from 'node-osc';
+ * 
+ * const decoded = decode(buffer);
+ * if (decoded.oscType === 'message') {
+ *   console.log('Address:', decoded.address);
+ *   console.log('Arguments:', decoded.args);
+ * }
+ * 
+ * @example
+ * // Round-trip encode/decode
+ * import { Message, encode, decode } from 'node-osc';
+ * 
+ * const original = new Message('/test', 42, 'hello');
+ * const buffer = encode(original);
+ * const decoded = decode(buffer);
+ * console.log(decoded.address); // '/test'
+ */
+function decode(buffer) {
   // Check if it's a bundle or message
   if (buffer.length >= 8 && buffer.subarray(0, 8).toString() === '#bundle\0') {
     return decodeBundleFromBuffer(buffer);
@@ -313,7 +378,7 @@ function decodeBundleFromBuffer(buffer) {
     
     // Read element data
     const elementBuffer = buffer.subarray(offset, offset + size);
-    const element = fromBuffer(elementBuffer);
+    const element = decode(elementBuffer);
     elements.push(element);
     offset += size;
   }
@@ -325,5 +390,4 @@ function decodeBundleFromBuffer(buffer) {
   };
 }
 
-exports.fromBuffer = fromBuffer;
-exports.toBuffer = toBuffer;
+export { encode, decode };

package/package.json

@@ -1,19 +1,17 @@
 {
   "name": "node-osc",
   "description": "pyOSC inspired library for sending and receiving OSC messages",
-  "version": "11.1.0",
+  "version": "11.2.0",
   "exports": {
+    "types": "./types/index.d.mts",
     "require": "./dist/lib/index.js",
+    "import": "./lib/index.mjs",
     "default": "./lib/index.mjs"
   },
   "imports": {
     "#decode": {
       "require": "./dist/lib/internal/decode.js",
       "default": "./lib/internal/decode.mjs"
-    },
-    "#osc": {
-      "require": "./dist/lib/internal/osc.js",
-      "default": "./lib/internal/osc.mjs"
     }
   },
   "author": {
@@ -23,12 +21,14 @@
   "engines": {
     "node": "^20.9.0 || ^22.11.0 || >=24.0.0"
   },
-  "license": "LGPL-3.0-or-later",
+  "license": "Apache-2.0",
   "scripts": {
-    "clean": "rm -rf dist/",
-    "build": "npm run clean && rollup --config rollup.config.mjs",
+    "clean": "rm -rf dist/ types/",
+    "build": "npm run clean && rollup --config rollup.config.mjs && npm run build:types",
+    "build:types": "tsc",
+    "docs": "node scripts/generate-docs.mjs",
     "prepublishOnly": "npm run build",
-    "lint": "eslint \"lib/**/*.mjs\" test/* examples/* rollup.config.mjs",
+    "lint": "eslint \"lib/**/*.mjs\" \"test/test-*.mjs\" test/util.mjs examples/*.js examples/*.mjs rollup.config.mjs",
     "test": "npm run lint && npm run build && npm run test:esm && npm run test:cjs",
     "test:esm": "tap test/test-*.mjs",
     "test:cjs": "tap dist/test/test-*.js"
@@ -50,7 +50,9 @@
     "@eslint/js": "^9.32.0",
     "eslint": "^9.32.0",
     "globals": "^16.3.0",
+    "jsdoc": "^4.0.5",
     "rollup": "^4.46.2",
-    "tap": "^21.1.0"
+    "tap": "^21.1.0",
+    "typescript": "^5.9.3"
   }
 }