node-osc 11.1.0 → 11.2.0

package/README.md

@@ -3,19 +3,84 @@
 A no frills [Open Sound Control](http://opensoundcontrol.org) client and server.
 Heavily inspired by [pyOSC](https://trac.v2.nl/wiki/pyOSC).
 
+## Installation
+
 Install using npm
 
-```
+```bash
 npm install node-osc
 ```
 
-## Written using ESM supports CJS
+## Features
+
+- 🚀 Simple and intuitive API
+- 🔄 Both callback and async/await support
+- 📦 Send and receive OSC messages and bundles
+- 🌐 Works with both ESM and CommonJS
+- 📘 TypeScript type definitions included (generated from JSDoc)
+- 📝 Comprehensive documentation and examples
+- ✅ Well tested and actively maintained
+
+## Quick Start
+
+### Sending Messages
+
+```js
+import { Client } from 'node-osc';
+
+const client = new Client('127.0.0.1', 3333);
+await client.send('/oscAddress', 200);
+await client.close();
+```
+
+### Receiving Messages
+
+```js
+import { Server } from 'node-osc';
+
+const server = new Server(3333, '0.0.0.0');
+
+server.on('message', (msg) => {
+  console.log(`Message: ${msg}`);
+});
+```
+
+## Documentation
+
+- 📚 **[API Documentation](./docs/API.md)** - Complete API reference generated from source code
+- 📘 **[Guide](./docs/GUIDE.md)** - Best practices, error handling, and troubleshooting
+- 📖 **[Examples](./examples/)** - Working examples for various use cases
 
-Supports the latest versions of Node.js 20, 22, and 24 in both ESM + CJS
+## Compatibility
+
+Written using ESM, supports CJS.
+
+Supports the latest versions of Node.js 20, 22, and 24 in both ESM + CJS.
+
+## TypeScript
+
+TypeScript type definitions are included! No need to install `@types/node-osc`.
+
+The types are automatically generated from JSDoc comments during the build process and included with the package. A single `.d.mts` type definition format is provided that works for both ESM and CommonJS consumers.
+
+**Note:** If you previously installed `@types/node-osc`, you should uninstall it to avoid conflicts:
+```bash
+npm uninstall @types/node-osc
+```
 
-## Example
+## More Examples
 
-### Sending OSC messages:
+### Sending with async/await
+
+```js
+import { Client } from 'node-osc';
+
+const client = new Client('127.0.0.1', 3333);
+await client.send('/oscAddress', 200);
+await client.close();
+```
+
+### Sending with callbacks
 
 ```js
 import { Client } from 'node-osc';
@@ -25,89 +90,117 @@ client.send('/oscAddress', 200, () => {
   client.close();
 });
 ```
-  
-### Listening for OSC messages:
+
+### Listening for OSC messages
 
 ```js
 import { Server } from 'node-osc';
 
-var oscServer = new Server(3333, '0.0.0.0', () => {
+const oscServer = new Server(3333, '0.0.0.0', () => {
   console.log('OSC Server is listening');
 });
 
 oscServer.on('message', function (msg) {
   console.log(`Message: ${msg}`);
-  oscServer.close();
 });
 ```
 
-### Sending OSC bundles:
+### Sending OSC bundles
 
 ```js
 import { Bundle, Client } from 'node-osc';
 
-// a bundle without an explicit time tag
 const bundle = new Bundle(['/one', 1], ['/two', 2], ['/three', 3]);
-
-// a bundle with a timetag of 10
-bundle.append(new Bundle(10, ['/four', 4]));
-
 const client = new Client('127.0.0.1', 3333);
-client.send(bundle));
+await client.send(bundle);
+await client.close();
 ```
 
-### Listening for OSC bundles:
+### Listening for OSC bundles
 
 ```js
 import { Server } from 'node-osc';
 
-var oscServer = new Server(3333, '0.0.0.0', () => {
+const oscServer = new Server(3333, '0.0.0.0', () => {
   console.log('OSC Server is listening');
 });
 
 oscServer.on('bundle', function (bundle) {
-  bundle.elements.forEach((element, i) => {
-    console.log(`Timestamp: ${bundle.timetag[i]}`);
+  bundle.elements.forEach((element) => {
+    console.log(`Timestamp: ${bundle.timetag}`);
     console.log(`Message: ${element}`);
   });
-  oscServer.close();
 });
 ```
 
-### CJS API
+### Low-Level Encoding and Decoding
 
-This just works due to conditional exports, isn't that cool!
+For advanced use cases, you can directly encode and decode OSC messages:
+
+```js
+import { Message, encode, decode } from 'node-osc';
+
+// Encode a message to binary
+const message = new Message('/oscillator/frequency', 440);
+const buffer = encode(message);
+
+// Decode binary data back to a message
+const decoded = decode(buffer);
+console.log('Address:', decoded.address);
+console.log('Value:', decoded.args[0].value);
+```
+
+This is useful for:
+- Sending OSC over non-UDP transports (WebSocket, TCP, HTTP)
+- Storing OSC messages to files or databases
+- Testing and debugging OSC implementations
+- Building custom OSC routers or processors
+
+See the **[API Documentation](./docs/API.md)** for complete details.
+
+## CommonJS
+
+Both callback and promise-based APIs work with CommonJS!
 
 ```js
 const { Client, Server } = require('node-osc');
 
-const client = new Client('127.0.0.1', 3333);
-var server = new Server(3333, '0.0.0.0');
+async function main() {
+  const server = new Server(3333, '0.0.0.0');
+  const client = new Client('127.0.0.1', 3333);
 
-server.on('listening', () => {
-  console.log('OSC Server is listening.');
-})
+  await new Promise((resolve) => {
+    server.on('listening', resolve);
+  });
 
-server.on('message', (msg) => {
-  console.log(`Message: ${msg}`);
-  server.close();
-});
+  server.on('message', (msg) => {
+    console.log(`Message: ${msg}`);
+  });
 
-client.send('/hello', 'world', (err) => {
-  if (err) console.error(err);
-  client.close();
-});
+  await client.send('/hello', 'world');
+  await client.close();
+  await server.close();
+}
+
+main();
 ```
 
-## Typescript 
+## Examples
 
-To install type definitions for node-osc:  
-   
-`npm install --save @types/node-osc`  or  `yarn add @types/node-osc`  
+See the [examples](./examples/) directory for more usage examples:
+- [client.js](./examples/client.js) - CommonJS client example
+- [server.js](./examples/server.js) - CommonJS server example
+- [esm.mjs](./examples/esm.mjs) - ESM example with callbacks
+- [async-await.mjs](./examples/async-await.mjs) - ESM example with async/await
+- [bundle-example.mjs](./examples/bundle-example.mjs) - Working with bundles
+- [error-handling.mjs](./examples/error-handling.mjs) - Error handling patterns
 
-The types should then be automatically included by the compiler.  
+## Contributing
 
+Contributions are welcome! Please feel free to submit a Pull Request.
 
 ## License
 
-LGPL.  Please see the file lesser.txt for details.
+Apache-2.0
+
+**Note:** This project was relicensed from LGPL-3.0-or-later to Apache-2.0 in December 2025.

package/dist/lib/Bundle.js

@@ -2,12 +2,61 @@
 
 var Message = require('./Message.js');
 
+/**
+ * Convert array notation to Message object.
+ * @private
+ * @param {Array|Message|Bundle} element - The element to sanitize.
+ * @returns {Message|Bundle} The sanitized element.
+ */
 function sanitize(element) {
   if (element instanceof Array) element = new Message(element[0], ...element.slice(1));
   return element;
 }
 
+/**
+ * Represents an OSC bundle containing multiple messages or nested bundles.
+ * 
+ * OSC bundles allow multiple messages to be sent together, optionally with
+ * a timetag indicating when the bundle should be processed.
+ * 
+ * @class
+ * 
+ * @example
+ * // Create a bundle without a timetag
+ * const bundle = new Bundle(['/one', 1], ['/two', 2]);
+ * 
+ * @example
+ * // Create a bundle with a timetag
+ * const bundle = new Bundle(10, ['/one', 1], ['/two', 2]);
+ * 
+ * @example
+ * // Nest bundles
+ * const bundle1 = new Bundle(['/one', 1]);
+ * const bundle2 = new Bundle(['/two', 2]);
+ * bundle1.append(bundle2);
+ */
 class Bundle {
+  /**
+   * Create an OSC Bundle.
+   * 
+   * @param {number|Message|Bundle|Array} [timetagOrElement=0] - Timetag, or if not a number, the first element and timetag will default to 0.
+   * @param {...(Message|Bundle|Array)} elements - Messages or bundles to include.
+   *   Arrays will be automatically converted to Message objects.
+   * 
+   * @example
+   * // Bundle without timetag
+   * const bundle = new Bundle(['/test', 1], ['/test2', 2]);
+   * 
+   * @example
+   * // Bundle with timetag of 10
+   * const bundle = new Bundle(10, ['/test', 1]);
+   * 
+   * @example
+   * // Bundle with Message objects
+   * const msg1 = new Message('/one', 1);
+   * const msg2 = new Message('/two', 2);
+   * const bundle = new Bundle(msg1, msg2);
+   */
   constructor(timetag, ...elements) {
     if (!(typeof timetag === 'number')) {
       elements.unshift(timetag);
@@ -18,6 +67,23 @@ class Bundle {
     this.elements = elements.map(sanitize);
   }
 
+  /**
+   * Append a message or bundle to this bundle.
+   * 
+   * @param {Message|Bundle|Array} element - The message or bundle to append.
+   *   Arrays will be automatically converted to Message objects.
+   * 
+   * @example
+   * const bundle = new Bundle();
+   * bundle.append(['/test', 1]);
+   * bundle.append(new Message('/test2', 2));
+   * 
+   * @example
+   * // Append a nested bundle
+   * const bundle1 = new Bundle(['/one', 1]);
+   * const bundle2 = new Bundle(['/two', 2]);
+   * bundle1.append(bundle2);
+   */
   append(element) {
     this.elements.push(sanitize(element));
   }

package/dist/lib/Client.js

@@ -1,44 +1,94 @@
 'use strict';
 
 var node_dgram = require('node:dgram');
-var _osc = require('#osc');
+var node_events = require('node:events');
+var osc = require('./osc.js');
 var Message = require('./Message.js');
 
-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 node_events.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 = node_dgram.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 = _osc.toBuffer(message);
+          buf = osc.encode(message);
           this._sock.send(buf, 0, buf.length, this.port, this.host, callback);
           break;
         case 'string':
@@ -46,7 +96,7 @@ class Client {
           for (let i = 1; i < args.length; i++) {
             mes.append(args[i]);
           }
-          buf = _osc.toBuffer(mes);
+          buf = osc.encode(mes);
           this._sock.send(buf, 0, buf.length, this.port, this.host, callback);
           break;
         default:
@@ -60,6 +110,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);
+      });
+    }
+  }
 }
 
 module.exports = Client;

package/dist/lib/Message.js

@@ -4,23 +4,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) {