node-osc 11.1.0 → 11.2.0

package/dist/lib/Server.js

@@ -4,14 +4,84 @@ var node_dgram = require('node:dgram');
 var node_events = require('node:events');
 var decode = require('#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 node_events.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;
@@ -20,10 +90,20 @@ class Server extends node_events.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);
@@ -41,9 +121,40 @@ class Server extends node_events.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/dist/lib/index.js

@@ -4,6 +4,7 @@ var Message = require('./Message.js');
 var Bundle = require('./Bundle.js');
 var Server = require('./Server.js');
 var Client = require('./Client.js');
+var osc = require('./osc.js');
 
 
 
@@ -11,3 +12,5 @@ exports.Message = Message;
 exports.Bundle = Bundle;
 exports.Server = Server;
 exports.Client = Client;
+exports.decode = osc.decode;
+exports.encode = osc.encode;

package/dist/lib/internal/decode.js

@@ -1,6 +1,6 @@
 'use strict';
 
-var _osc = require('#osc');
+var osc = require('../osc.js');
 
 function sanitizeMessage(decoded) {
   const message = [];
@@ -19,8 +19,8 @@ function sanitizeBundle(decoded) {
   return decoded;
 }
 
-function decode(data, customFromBuffer = _osc.fromBuffer) {
-  const decoded = customFromBuffer(data);
+function decodeAndSanitize(data, customDecode = osc.decode) {
+  const decoded = customDecode(data);
   if (decoded.oscType === 'bundle') {
     return sanitizeBundle(decoded);
   }
@@ -32,4 +32,4 @@ function decode(data, customFromBuffer = _osc.fromBuffer) {
   }
 }
 
-module.exports = decode;
+module.exports = decodeAndSanitize;

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

@@ -1,7 +1,10 @@
+'use strict';
+
+var node_buffer = require('node:buffer');
+
 // OSC 1.0 Protocol Implementation
 // Based on http://opensoundcontrol.org/spec-1_0
 
-// Helper functions for OSC encoding/decoding
 
 function padString(str) {
   const nullTerminated = str + '\0';
@@ -21,7 +24,7 @@ function readString(buffer, offset) {
 }
 
 function writeInt32(value) {
-  const buffer = Buffer.alloc(4);
+  const buffer = node_buffer.Buffer.alloc(4);
   buffer.writeInt32BE(value, 0);
   return buffer;
 }
@@ -32,7 +35,7 @@ function readInt32(buffer, offset) {
 }
 
 function writeFloat32(value) {
-  const buffer = Buffer.alloc(4);
+  const buffer = node_buffer.Buffer.alloc(4);
   buffer.writeFloatBE(value, 0);
   return buffer;
 }
@@ -46,8 +49,8 @@ function writeBlob(value) {
   const length = value.length;
   const lengthBuffer = writeInt32(length);
   const padding = 4 - (length % 4);
-  const paddingBuffer = Buffer.alloc(padding === 4 ? 0 : padding);
-  return Buffer.concat([lengthBuffer, value, paddingBuffer]);
+  const paddingBuffer = node_buffer.Buffer.alloc(padding === 4 ? 0 : padding);
+  return node_buffer.Buffer.concat([lengthBuffer, value, paddingBuffer]);
 }
 
 function readBlob(buffer, offset) {
@@ -62,7 +65,7 @@ function readBlob(buffer, offset) {
 function writeTimeTag(value) {
   // For now, treat timetag as a double (8 bytes)
   // OSC timetag is 64-bit: 32-bit seconds since 1900, 32-bit fractional
-  const buffer = Buffer.alloc(8);
+  const buffer = node_buffer.Buffer.alloc(8);
   if (typeof value === 'number') {
     // Convert to OSC timetag format
     const seconds = Math.floor(value);
@@ -97,9 +100,9 @@ function readTimeTag(buffer, offset) {
 
 function writeMidi(value) {
   // MIDI message is 4 bytes: port id, status byte, data1, data2
-  const buffer = Buffer.alloc(4);
+  const buffer = node_buffer.Buffer.alloc(4);
   
-  if (Buffer.isBuffer(value)) {
+  if (node_buffer.Buffer.isBuffer(value)) {
     if (value.length !== 4) {
       throw new Error('MIDI message must be exactly 4 bytes');
     }
@@ -138,7 +141,7 @@ function encodeArgument(arg) {
         return { tag: 'f', data: writeFloat32(arg.value) };
       case 's':
       case 'string':
-        return { tag: 's', data: Buffer.from(padString(arg.value)) };
+        return { tag: 's', data: node_buffer.Buffer.from(padString(arg.value)) };
       case 'b':
       case 'blob':
         return { tag: 'b', data: writeBlob(arg.value) };
@@ -147,8 +150,11 @@ 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: node_buffer.Buffer.alloc(0) };
+      case 'F':
+        return { tag: 'F', data: node_buffer.Buffer.alloc(0) };
       case 'boolean':
-        return arg.value ? { tag: 'T', data: Buffer.alloc(0) } : { tag: 'F', data: Buffer.alloc(0) };
+        return arg.value ? { tag: 'T', data: node_buffer.Buffer.alloc(0) } : { tag: 'F', data: node_buffer.Buffer.alloc(0) };
       case 'm':
       case 'midi':
         return { tag: 'm', data: writeMidi(arg.value) };
@@ -166,11 +172,11 @@ function encodeArgument(arg) {
         return { tag: 'f', data: writeFloat32(arg) };
       }
     case 'string':
-      return { tag: 's', data: Buffer.from(padString(arg)) };
+      return { tag: 's', data: node_buffer.Buffer.from(padString(arg)) };
     case 'boolean':
-      return arg ? { tag: 'T', data: Buffer.alloc(0) } : { tag: 'F', data: Buffer.alloc(0) };
+      return arg ? { tag: 'T', data: node_buffer.Buffer.alloc(0) } : { tag: 'F', data: node_buffer.Buffer.alloc(0) };
     default:
-      if (Buffer.isBuffer(arg)) {
+      if (node_buffer.Buffer.isBuffer(arg)) {
         return { tag: 'b', data: writeBlob(arg) };
       }
       throw new Error(`Don't know how to encode argument: ${arg}`);
@@ -200,7 +206,37 @@ function decodeArgument(tag, buffer, offset) {
   }
 }
 
-export 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 {
@@ -215,15 +251,15 @@ function encodeMessageToBuffer(message) {
   // Arguments (encoded according to type tags)
   
   const address = padString(message.address);
-  const addressBuffer = Buffer.from(address);
+  const addressBuffer = node_buffer.Buffer.from(address);
   
   const encodedArgs = message.args.map(encodeArgument);
   const typeTags = ',' + encodedArgs.map(arg => arg.tag).join('');
-  const typeTagsBuffer = Buffer.from(padString(typeTags));
+  const typeTagsBuffer = node_buffer.Buffer.from(padString(typeTags));
   
   const argumentBuffers = encodedArgs.map(arg => arg.data);
   
-  return Buffer.concat([addressBuffer, typeTagsBuffer, ...argumentBuffers]);
+  return node_buffer.Buffer.concat([addressBuffer, typeTagsBuffer, ...argumentBuffers]);
 }
 
 function encodeBundleToBuffer(bundle) {
@@ -233,7 +269,7 @@ function encodeBundleToBuffer(bundle) {
   // Elements (each prefixed with size)
   
   const bundleString = padString('#bundle');
-  const bundleStringBuffer = Buffer.from(bundleString);
+  const bundleStringBuffer = node_buffer.Buffer.from(bundleString);
   
   const timetagBuffer = writeTimeTag(bundle.timetag);
   
@@ -245,13 +281,45 @@ function encodeBundleToBuffer(bundle) {
       elementBuffer = encodeMessageToBuffer(element);
     }
     const sizeBuffer = writeInt32(elementBuffer.length);
-    return Buffer.concat([sizeBuffer, elementBuffer]);
+    return node_buffer.Buffer.concat([sizeBuffer, elementBuffer]);
   });
   
-  return Buffer.concat([bundleStringBuffer, timetagBuffer, ...elementBuffers]);
+  return node_buffer.Buffer.concat([bundleStringBuffer, timetagBuffer, ...elementBuffers]);
 }
 
-export 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);
@@ -311,7 +379,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;
   }
@@ -321,4 +389,7 @@ function decodeBundleFromBuffer(buffer) {
     timetag,
     elements
   };
-}
+}
+
+exports.decode = decode;
+exports.encode = encode;