node-osc 11.2.0 → 11.2.2

package/dist/test/test-promises.js

@@ -2,29 +2,51 @@
 
 var node_events = require('node:events');
 var tap = require('tap');
-var util = require('./util.js');
 var nodeOsc = require('node-osc');
 
-tap.beforeEach(util.bootstrap);
-
 tap.test('client: send with promise - array', async (t) => {
-  const oscServer = new nodeOsc.Server(t.context.port, '127.0.0.1');
-  const client = new nodeOsc.Client('127.0.0.1', t.context.port);
+  const server = new nodeOsc.Server(0, '127.0.0.1');
+  await node_events.once(server, 'listening');
+  const client = new nodeOsc.Client('127.0.0.1', server.port);
 
   t.plan(1);
 
+  server.on('message', (msg) => {
+    server.close();
+    t.same(msg, ['/test', 0, 1, 'testing', true], 'We should receive expected payload');
+  });
+
+  await client.send(['/test', 0, 1, 'testing', true]);
+  await client.close();
+});
+
+tap.test('client: array is not mutated when sent with promise', async (t) => {
+  const oscServer = new nodeOsc.Server(0, '127.0.0.1');
+  await node_events.once(oscServer, 'listening');
+  const client = new nodeOsc.Client('127.0.0.1', oscServer.port);
+
+  t.plan(2);
+
+  const originalArray = ['/test', 0, 1, 'testing', true];
+  const expectedArray = ['/test', 0, 1, 'testing', true];
+
   oscServer.on('message', (msg) => {
     oscServer.close();
     t.same(msg, ['/test', 0, 1, 'testing', true], 'We should receive expected payload');
   });
 
-  await client.send(['/test', 0, 1, 'testing', true]);
+  await client.send(originalArray);
+  
+  // Verify the original array was not mutated
+  t.same(originalArray, expectedArray, 'Original array should not be mutated');
+  
   await client.close();
 });
 
 tap.test('client: send with promise - string', async (t) => {
-  const oscServer = new nodeOsc.Server(t.context.port, '127.0.0.1');
-  const client = new nodeOsc.Client('127.0.0.1', t.context.port);
+  const oscServer = new nodeOsc.Server(0, '127.0.0.1');
+  await node_events.once(oscServer, 'listening');
+  const client = new nodeOsc.Client('127.0.0.1', oscServer.port);
 
   t.plan(1);
 
@@ -38,8 +60,9 @@ tap.test('client: send with promise - string', async (t) => {
 });
 
 tap.test('client: send with promise - message object', async (t) => {
-  const oscServer = new nodeOsc.Server(t.context.port, '127.0.0.1');
-  const client = new nodeOsc.Client('127.0.0.1', t.context.port);
+  const oscServer = new nodeOsc.Server(0, '127.0.0.1');
+  await node_events.once(oscServer, 'listening');
+  const client = new nodeOsc.Client('127.0.0.1', oscServer.port);
 
   t.plan(1);
 
@@ -56,8 +79,9 @@ tap.test('client: send with promise - message object', async (t) => {
 });
 
 tap.test('client: send with promise - multiple args', async (t) => {
-  const oscServer = new nodeOsc.Server(t.context.port, '127.0.0.1');
-  const client = new nodeOsc.Client('127.0.0.1', t.context.port);
+  const oscServer = new nodeOsc.Server(0, '127.0.0.1');
+  await node_events.once(oscServer, 'listening');
+  const client = new nodeOsc.Client('127.0.0.1', oscServer.port);
 
   t.plan(1);
 
@@ -71,12 +95,15 @@ tap.test('client: send with promise - multiple args', async (t) => {
 });
 
 tap.test('client: send promise rejection on closed socket', async (t) => {
-  const client = new nodeOsc.Client('127.0.0.1', t.context.port);
+  const oscServer = new nodeOsc.Server(0, '127.0.0.1');
+  await node_events.once(oscServer, 'listening');
+  const client = new nodeOsc.Client('127.0.0.1', oscServer.port);
 
   t.plan(1);
 
   await client.close();
-  
+  await oscServer.close();
+
   try {
     await client.send('/boom');
     t.fail('Should have thrown an error');
@@ -86,8 +113,9 @@ tap.test('client: send promise rejection on closed socket', async (t) => {
 });
 
 tap.test('client: async/await usage', async (t) => {
-  const oscServer = new nodeOsc.Server(t.context.port, '127.0.0.1');
-  const client = new nodeOsc.Client('127.0.0.1', t.context.port);
+  const oscServer = new nodeOsc.Server(0, '127.0.0.1');
+  await node_events.once(oscServer, 'listening');
+  const client = new nodeOsc.Client('127.0.0.1', oscServer.port);
 
   t.plan(1);
 
@@ -103,7 +131,7 @@ tap.test('client: async/await usage', async (t) => {
 });
 
 tap.test('server: close with promise', async (t) => {
-  const oscServer = new nodeOsc.Server(t.context.port, '127.0.0.1');
+  const oscServer = new nodeOsc.Server(0, '127.0.0.1');
   
   t.plan(1);
 
@@ -114,7 +142,7 @@ tap.test('server: close with promise', async (t) => {
 });
 
 tap.test('server: no callback still emits listening event', async (t) => {
-  const oscServer = new nodeOsc.Server(t.context.port, '127.0.0.1');
+  const oscServer = new nodeOsc.Server(0, '127.0.0.1');
   
   t.plan(1);
 
@@ -125,15 +153,16 @@ tap.test('server: no callback still emits listening event', async (t) => {
 });
 
 tap.test('client and server: full async/await workflow', async (t) => {
-  const oscServer = new nodeOsc.Server(t.context.port, '127.0.0.1');
-  const client = new nodeOsc.Client('127.0.0.1', t.context.port);
-
-  t.plan(2);
+  t.plan(3);
+  const oscServer = new nodeOsc.Server(0, '127.0.0.1');
 
   // Wait for server to be ready
   await node_events.once(oscServer, 'listening');
   t.pass('Server started');
 
+  const client = new nodeOsc.Client('127.0.0.1', oscServer.port);
+  t.pass('Client created');
+
   // Set up message handler
   const messageReceived = node_events.once(oscServer, 'message');
 
@@ -148,9 +177,9 @@ tap.test('client and server: full async/await workflow', async (t) => {
 });
 
 tap.test('client: multiple sends with promises', async (t) => {
-  const oscServer = new nodeOsc.Server(t.context.port, '127.0.0.1');
-  const client = new nodeOsc.Client('127.0.0.1', t.context.port);
-
+  const oscServer = new nodeOsc.Server(0, '127.0.0.1');
+  await node_events.once(oscServer, 'listening');
+  const client = new nodeOsc.Client('127.0.0.1', oscServer.port);
   t.plan(3);
 
   const messages = [];
@@ -174,6 +203,8 @@ tap.test('client: multiple sends with promises', async (t) => {
 });
 
 tap.test('client: close promise rejection on error', async (t) => {
+  const oscServer = new nodeOsc.Server(0, '127.0.0.1');
+  await node_events.once(oscServer, 'listening');
   const client = new nodeOsc.Client('127.0.0.1', t.context.port);
 
   t.plan(1);
@@ -203,6 +234,7 @@ tap.test('client: close promise rejection on error', async (t) => {
   };
 
   try {
+    await oscServer.close();
     await client.close();
     t.fail('Should have thrown an error');
   } catch (err) {
@@ -211,7 +243,7 @@ tap.test('client: close promise rejection on error', async (t) => {
 });
 
 tap.test('server: close promise rejection on error', async (t) => {
-  const oscServer = new nodeOsc.Server(t.context.port, '127.0.0.1');
+  const oscServer = new nodeOsc.Server(0, '127.0.0.1');
 
   t.plan(1);
 
@@ -248,3 +280,35 @@ tap.test('server: close promise rejection on error', async (t) => {
     t.equal(err.code, 'MOCK_ERROR', 'Should reject with mock error');
   }
 });
+
+tap.test('client: send promise rejection on send error', async (t) => {
+  const oscServer = new nodeOsc.Server(0, '127.0.0.1');
+  await node_events.once(oscServer, 'listening');
+  const client = new nodeOsc.Client('127.0.0.1', oscServer.port);
+
+  t.plan(1);
+
+  // Mock the socket's send method to simulate an error
+  const originalSend = client._sock.send;
+  client._sock.send = function(msg, offset, length, port, address, callback) {
+    // Simulate an error being passed to callback
+    const err = new Error('Mock send error');
+    err.code = 'MOCK_SEND_ERROR';
+    if (callback) {
+      setImmediate(() => callback(err));
+    }
+  };
+
+  t.teardown(async () => {
+    client._sock.send = originalSend;
+    await client.close();
+    await oscServer.close();
+  });
+
+  try {
+    await client.send('/test', 'data');
+    t.fail('Should have thrown an error');
+  } catch (err) {
+    t.equal(err.code, 'MOCK_SEND_ERROR', 'Should reject with mock send error');
+  }
+});

package/dist/test/test-server.js

@@ -1,22 +1,22 @@
 'use strict';
 
+var node_events = require('node:events');
 var tap = require('tap');
-var util = require('./util.js');
 var nodeOsc = require('node-osc');
 
-tap.beforeEach(util.bootstrap);
-
-tap.test('server: create and close', (t) => {
+tap.test('server: create and close', async (t) => {
   t.plan(1);
-  const oscServer = new nodeOsc.Server(t.context.port, '127.0.0.1');
+  const oscServer = new nodeOsc.Server(0, '127.0.0.1');
+  await node_events.once(oscServer, 'listening');
   oscServer.close((err) => {
     t.error(err);
   });
 });
 
-tap.test('server: listen to message', (t) => {
-  const oscServer = new nodeOsc.Server(t.context.port);
-  const client = new nodeOsc.Client('127.0.0.1', t.context.port);
+tap.test('server: listen to message', async (t) => {
+  const oscServer = new nodeOsc.Server(0);
+  await node_events.once(oscServer, 'listening');
+  const client = new nodeOsc.Client('127.0.0.1', oscServer.port);
 
   t.plan(3);
 
@@ -38,9 +38,10 @@ tap.test('server: listen to message', (t) => {
   });
 });
 
-tap.test('server: no defined host', (t) => {
-  const oscServer = new nodeOsc.Server(t.context.port);
-  const client = new nodeOsc.Client('127.0.0.1', t.context.port);
+tap.test('server: no defined host', async (t) => {
+  const oscServer = new nodeOsc.Server(0);
+  await node_events.once(oscServer, 'listening');
+  const client = new nodeOsc.Client('127.0.0.1', oscServer.port);
 
   t.plan(3);
 
@@ -62,12 +63,13 @@ tap.test('server: no defined host', (t) => {
   });
 });
 
-tap.test('server: callback as second arg', (t) => {
+tap.test('server: callback as second arg', async (t) => {
   t.plan(4);
-  const oscServer = new nodeOsc.Server(t.context.port, () => {
+  const oscServer = new nodeOsc.Server(0, () => {
     t.ok('callback called');
   });
-  const client = new nodeOsc.Client('127.0.0.1', t.context.port);
+  await node_events.once(oscServer, 'listening');
+  const client = new nodeOsc.Client('127.0.0.1', oscServer.port);
 
   t.teardown(() => {
     oscServer.close();
@@ -87,9 +89,10 @@ tap.test('server: callback as second arg', (t) => {
   });
 });
 
-tap.test('server: bad message', (t) => {
+tap.test('server: bad message', async (t) => {
   t.plan(2);
-  const oscServer = new nodeOsc.Server(t.context.port, '127.0.0.1');
+  const oscServer = new nodeOsc.Server(0, '127.0.0.1');
+  await node_events.once(oscServer, 'listening');
   t.throws(() => {
     oscServer._sock.emit('message', 'whoops');
   }, /can't decode incoming message:/);

package/docs/README.md

@@ -0,0 +1,81 @@
+# node-osc Documentation
+
+Welcome to the node-osc documentation! This directory contains comprehensive documentation for the node-osc library.
+
+## Documentation Overview
+
+### 📚 [API Reference](./API.md)
+**Complete API documentation for all classes and functions**
+
+Auto-generated from JSDoc comments in the source code. This is your reference for:
+- All classes: `Server`, `Client`, `Message`, `Bundle`
+- All methods and their parameters
+- Low-level functions: `encode()` and `decode()`
+- Return types and error conditions
+- Code examples for each API
+
+> **Note:** This file is automatically generated. To update it, edit the JSDoc comments in the source code and run `npm run docs`.
+
+### 📘 [Usage Guide](./GUIDE.md)
+**Best practices, patterns, and troubleshooting**
+
+A comprehensive guide covering:
+- Event handling patterns
+- Error handling strategies
+- OSC type system details
+- Best practices for production use
+- Troubleshooting common issues
+- Advanced topics like custom transports and performance optimization
+
+## Quick Navigation
+
+**New to node-osc?**
+1. Start with the [main README](../README.md) for a quick introduction and installation
+2. Try the [examples](../examples/) to see working code
+3. Read the [Usage Guide](./GUIDE.md) to learn best practices
+4. Reference the [API documentation](./API.md) as needed
+
+**Looking for something specific?**
+- **How to send/receive messages** → [API Reference](./API.md) (Server and Client sections)
+- **How to handle errors** → [Usage Guide](./GUIDE.md#error-handling)
+- **Type system and data types** → [Usage Guide](./GUIDE.md#type-system)
+- **Working with bundles** → [API Reference](./API.md#bundle)
+- **Troubleshooting** → [Usage Guide](./GUIDE.md#troubleshooting)
+- **Code examples** → [Examples directory](../examples/)
+- **Advanced use cases** → [Usage Guide](./GUIDE.md#advanced-topics)
+
+## Additional Resources
+
+- **[Examples](../examples/)** - Working code examples for various use cases
+- **[Main README](../README.md)** - Quick start and project overview
+- **[OSC Specification](http://opensoundcontrol.org/spec-1_0)** - Official OSC protocol documentation
+
+## Contributing to Documentation
+
+### Updating API Documentation
+
+The API documentation is automatically generated from JSDoc comments:
+
+1. Edit JSDoc comments in the source files (`lib/**/*.mjs`)
+2. Run `npm run docs` to regenerate `API.md`
+3. Review the changes and commit
+
+### Updating the Usage Guide
+
+The Usage Guide (`GUIDE.md`) is manually maintained. When editing:
+
+- Keep it focused on patterns, best practices, and how-to content
+- Avoid duplicating API details (link to API.md instead)
+- Include practical code examples
+- Update the table of contents if adding new sections
+
+## Documentation Structure Philosophy
+
+Our documentation is organized to minimize duplication while maximizing usefulness:
+
+- **README.md** (main) → Quick start, basic examples, installation
+- **API.md** → Complete API reference with all technical details
+- **GUIDE.md** → How to use the library effectively, patterns, and troubleshooting
+- **examples/** → Working code you can run and learn from
+
+This structure ensures you can find what you need without reading through repeated content.

package/examples/README.md

@@ -115,5 +115,7 @@ Demonstrates:
 ## Further Reading
 
 - [Main README](../README.md) - Quick start guide
-- [API Documentation](../docs/API.md) - Complete API reference
+- [Documentation Hub](../docs/) - Complete documentation with navigation guide
+- [API Reference](../docs/API.md) - Complete API reference
+- [Usage Guide](../docs/GUIDE.md) - Best practices and troubleshooting
 - [OSC Specification](http://opensoundcontrol.org/spec-1_0) - Learn about the OSC protocol

package/lib/Client.mjs

@@ -154,7 +154,7 @@ class Client extends EventEmitter {
     if (message instanceof Array) {
       message = {
         address: message[0],
-        args: message.splice(1)
+        args: message.slice(1)
       };
     }
     

package/lib/Message.mjs

@@ -109,7 +109,9 @@ class Message {
     let argOut;
     switch (typeof arg) {
     case 'object':
-      if (arg instanceof Array) {
+      if (Buffer.isBuffer(arg)) {
+        this.args.push(arg);
+      } else if (arg instanceof Array) {
         arg.forEach(a => this.append(a));
       } else if (arg.type) {
         if (typeTags[arg.type]) arg.type = typeTags[arg.type];

package/lib/Server.mjs

@@ -90,18 +90,13 @@ class Server extends EventEmitter {
     });
     this._sock.bind(port, host);
     
-    // 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');
-      });
-    }
+    // Update port and emit listening event when socket is ready
+    this._sock.on('listening', () => {
+      // Update port with actual bound port (important when using port 0)
+      this.port = this._sock.address().port;
+      this.emit('listening');
+      if (cb) cb();
+    });
     
     this._sock.on('message', (msg, rinfo) => {
       try {

package/lib/internal/decode.mjs

@@ -3,7 +3,8 @@ import { decode } from '../osc.mjs';
 function sanitizeMessage(decoded) {
   const message = [];
   message.push(decoded.address);
-  decoded.args.forEach(arg => {
+  const args = decoded.args ?? [];
+  args.forEach(arg => {
     message.push(arg.value);
   });
   return message;
@@ -13,6 +14,7 @@ function sanitizeBundle(decoded) {
   decoded.elements = decoded.elements.map(element => {
     if (element.oscType === 'bundle') return sanitizeBundle(element);
     else if (element.oscType === 'message') return sanitizeMessage(element);
+    throw new Error('Malformed Packet');
   });
   return decoded;
 }

package/lib/osc.mjs

@@ -7,8 +7,9 @@ import { Buffer } from 'node:buffer';
 
 function padString(str) {
   const nullTerminated = str + '\0';
-  const padding = 4 - (nullTerminated.length % 4);
-  return nullTerminated + '\0'.repeat(padding === 4 ? 0 : padding);
+  const byteLength = Buffer.byteLength(nullTerminated);
+  const padding = (4 - (byteLength % 4)) % 4;
+  return nullTerminated + '\0'.repeat(padding);
 }
 
 function readString(buffer, offset) {
@@ -16,6 +17,9 @@ function readString(buffer, offset) {
   while (end < buffer.length && buffer[end] !== 0) {
     end++;
   }
+  if (end >= buffer.length) {
+    throw new Error('Malformed Packet: Missing null terminator for string');
+  }
   const str = buffer.subarray(offset, end).toString('utf8');
   // Find next 4-byte boundary
   const paddedLength = Math.ceil((end - offset + 1) / 4) * 4;
@@ -29,6 +33,9 @@ function writeInt32(value) {
 }
 
 function readInt32(buffer, offset) {
+  if (offset + 4 > buffer.length) {
+    throw new Error('Malformed Packet: Not enough bytes for int32');
+  }
   const value = buffer.readInt32BE(offset);
   return { value, offset: offset + 4 };
 }
@@ -40,6 +47,9 @@ function writeFloat32(value) {
 }
 
 function readFloat32(buffer, offset) {
+  if (offset + 4 > buffer.length) {
+    throw new Error('Malformed Packet: Not enough bytes for float32');
+  }
   const value = buffer.readFloatBE(offset);
   return { value, offset: offset + 4 };
 }
@@ -55,9 +65,18 @@ function writeBlob(value) {
 function readBlob(buffer, offset) {
   const lengthResult = readInt32(buffer, offset);
   const length = lengthResult.value;
+  if (length < 0) {
+    throw new Error('Malformed Packet: Invalid blob length');
+  }
+  if (lengthResult.offset + length > buffer.length) {
+    throw new Error('Malformed Packet: Not enough bytes for blob');
+  }
   const data = buffer.subarray(lengthResult.offset, lengthResult.offset + length);
   const padding = 4 - (length % 4);
   const nextOffset = lengthResult.offset + length + (padding === 4 ? 0 : padding);
+  if (nextOffset > buffer.length) {
+    throw new Error('Malformed Packet: Not enough bytes for blob padding');
+  }
   return { value: data, offset: nextOffset };
 }
 
@@ -65,7 +84,11 @@ 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);
-  if (typeof value === 'number') {
+  if (value === 0 || value === null || value === undefined) {
+    // Immediate execution
+    buffer.writeUInt32BE(0, 0);
+    buffer.writeUInt32BE(1, 4);
+  } else if (typeof value === 'number') {
     // Convert to OSC timetag format
     const seconds = Math.floor(value);
     const fraction = Math.floor((value - seconds) * 0x100000000);
@@ -80,6 +103,9 @@ function writeTimeTag(value) {
 }
 
 function readTimeTag(buffer, offset) {
+  if (offset + 8 > buffer.length) {
+    throw new Error('Malformed Packet: Not enough bytes for timetag');
+  }
   const seconds = buffer.readUInt32BE(offset);
   const fraction = buffer.readUInt32BE(offset + 4);
   
@@ -375,6 +401,9 @@ function decodeBundleFromBuffer(buffer) {
     const sizeResult = readInt32(buffer, offset);
     const size = sizeResult.value;
     offset = sizeResult.offset;
+    if (size <= 0 || offset + size > buffer.length) {
+      throw new Error('Malformed Packet');
+    }
     
     // Read element data
     const elementBuffer = buffer.subarray(offset, offset + size);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "node-osc",
   "description": "pyOSC inspired library for sending and receiving OSC messages",
-  "version": "11.2.0",
+  "version": "11.2.2",
   "exports": {
     "types": "./types/index.d.mts",
     "require": "./dist/lib/index.js",
@@ -28,7 +28,7 @@
     "build:types": "tsc",
     "docs": "node scripts/generate-docs.mjs",
     "prepublishOnly": "npm run build",
-    "lint": "eslint \"lib/**/*.mjs\" \"test/test-*.mjs\" test/util.mjs examples/*.js examples/*.mjs rollup.config.mjs",
+    "lint": "eslint \"lib/**/*.mjs\" \"test/test-*.mjs\" \"examples/*.js\" \"examples/*.mjs\" \"scripts/*.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"

package/rollup.config.mjs

@@ -69,6 +69,7 @@ function walkTest(config) {
       'node:fs',
       'node:path',
       'node:url',
+      'node:timers/promises',
       'node-osc',
       'tap',
       '#decode'

package/test/test-bundle.mjs

@@ -1,13 +1,12 @@
-import { beforeEach, test } from 'tap';
+import { once } from 'node:events';
+import { test } from 'tap';
 
 import { Client, Server, Bundle } from 'node-osc';
 
-import { bootstrap } from './util.mjs';
-beforeEach(bootstrap);
-
-test('bundle: verbose bundle', (t) => {
-  const server = new Server(t.context.port, '127.0.0.1');
-  const client = new Client('127.0.0.1', t.context.port);
+test('bundle: verbose bundle', async (t) => {
+  const server = new Server(0, '127.0.0.1');
+  await once(server, 'listening');
+  const client = new Client('127.0.0.1', server.port);
 
   t.plan(2);
 
@@ -34,9 +33,10 @@ test('bundle: verbose bundle', (t) => {
   }));
 });
 
-test('bundle: array syntax', (t) => {
-  const server = new Server(t.context.port, '127.0.0.1');
-  const client = new Client('127.0.0.1', t.context.port);
+test('bundle: array syntax', async (t) => {
+  const server = new Server(0, '127.0.0.1');
+  await once(server, 'listening');
+  const client = new Client('127.0.0.1', server.port);
 
   t.plan(2);
 
@@ -56,9 +56,10 @@ test('bundle: array syntax', (t) => {
   ));
 });
 
-test('bundle: nested bundle', (t) => {
-  const server = new Server(t.context.port, '127.0.0.1');
-  const client = new Client('127.0.0.1', t.context.port);
+test('bundle: nested bundle', async (t) => {
+  const server = new Server(0, '127.0.0.1');
+  await once(server, 'listening');
+  const client = new Client('127.0.0.1', server.port);
 
   t.plan(4);