node-osc 11.2.2 → 11.3.0

package/.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "08:00"
+      timezone: "UTC"
+    open-pull-requests-limit: 10
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "08:30"
+      timezone: "UTC"
+    open-pull-requests-limit: 10

package/.node-version

@@ -0,0 +1 @@
+24

package/{agent.md → AGENTS.md}

@@ -12,7 +12,7 @@ This document provides context and instructions for AI agents (GitHub Copilot, C
 - Both callback and async/await APIs
 - TypeScript type definitions generated from JSDoc
 - Well-tested with comprehensive test coverage
-- Supports Node.js 20, 22, and 24
+- Supports Node.js 20, 22, and 24+
 
 ## Architecture
 
@@ -43,9 +43,9 @@ This document provides context and instructions for AI agents (GitHub Copilot, C
 The project uses **ESM as the source format** but provides **dual ESM/CommonJS support**:
 - Source files: `lib/**/*.mjs` (ESM)
 - Built CommonJS files: `dist/lib/**/*.js` (transpiled via Rollup)
-- TypeScript definitions: `types/index.d.mts` (generated from JSDoc)
+- Generated TypeScript definitions: `types/*.d.mts` (with `types/index.d.mts` as the package entry point)
 
-**Important:** The single `.d.mts` type definition file works for both ESM and CommonJS consumers.
+**Important:** `types/index.d.mts` is the exported type entry point for both ESM and CommonJS consumers, and the supporting `.d.mts` files in `types/` are generated artifacts.
 
 ### Package Exports
 
@@ -95,7 +95,7 @@ npm run clean
 - Tests are written in ESM format in `test/test-*.mjs`
 - Tests are run against both ESM source (`lib/`) and transpiled CJS (`dist/`)
 - Uses `tap` test framework
-- Test utilities in `test/util.mjs` provide helpers like `getPort()` for getting available ports
+- Tests typically use ephemeral ports via `new Server(0, ...)` and wait for readiness with `once(server, 'listening')`
 - Always run `npm run build` before running CJS tests
 - **100% test coverage is required** - All lines, branches, functions, and statements must be covered
 
@@ -122,7 +122,7 @@ The build is automatically run before publishing (`prepublishOnly` script).
 - **JSDoc comments**: All public APIs must have JSDoc comments
 - **Type annotations**: Use JSDoc types for TypeScript generation
 - **Examples**: Include code examples in JSDoc comments
-- **Auto-generated docs**: Run `npm run docs` after changing JSDoc comments
+- **Auto-generated docs**: Run `npm run docs` after changing JSDoc comments; update `scripts/generate-docs.mjs` if the API doc layout or anchor generation needs to change
 
 Example JSDoc pattern:
 ```javascript
@@ -181,21 +181,24 @@ When writing code that needs to work in both ESM and CJS:
 
 ### Tests
 - `test/test-*.mjs` - Test files using tap framework
-- `test/util.mjs` - Test utilities and helpers
 - `test/fixtures/` - Test data and fixtures
 
 ### Documentation
 - `README.md` - Main documentation with quick start guide
 - `docs/API.md` - Auto-generated API reference (do not edit manually)
 - `docs/GUIDE.md` - Best practices, error handling, troubleshooting
+- `docs/README.md` - Documentation hub and maintenance notes
 - `examples/` - Working example code for various use cases
 
 ### Configuration
+- `.github/workflows/` - CI, release, and automation workflows
+- `.github/dependabot.yml` - Dependabot configuration for npm and GitHub Actions updates
 - `package.json` - Package configuration, scripts, exports
 - `eslint.config.mjs` - ESLint configuration
 - `rollup.config.mjs` - Rollup build configuration (ESM to CJS)
 - `tsconfig.json` - TypeScript compiler options for type generation
 - `jsdoc.json` - JSDoc configuration for documentation generation
+- `scripts/generate-docs.mjs` - Regenerates API documentation and handles API doc anchor/link formatting logic
 
 ## Making Changes
 
@@ -206,7 +209,7 @@ When writing code that needs to work in both ESM and CJS:
 3. **Export** from `lib/index.mjs` if it's a public API
 4. **Write tests** in `test/test-*.mjs` - **must achieve 100% coverage** (lines, branches, functions, statements)
 5. **Run tests**: `npm test` (tests both ESM and CJS)
-6. **Update docs**: `npm run docs` to regenerate API.md
+6. **Update docs**: `npm run docs` to regenerate `docs/API.md`
 7. **Update README.md** if adding user-facing functionality
 
 ### Fixing a Bug
@@ -273,7 +276,7 @@ const decoded = decode(buffer);
 
 ### Test Issues
 
-- **Port conflicts**: Tests use dynamic port allocation via `getPort()` utility
+- **Port conflicts**: Tests usually avoid conflicts by binding servers to port `0` and reading back the assigned port after the `'listening'` event
 - **Timing issues**: Use async/await and proper event handling
 - **ESM/CJS differences**: Ensure code works in both environments
 

package/README.md

@@ -52,11 +52,13 @@ server.on('message', (msg) => {
 - 📘 **[Usage Guide](./docs/GUIDE.md)** - Best practices, error handling, and troubleshooting
 - 📖 **[Examples](./examples/)** - Working examples for various use cases
 
+The API reference is generated from the source JSDoc comments. If you change a public API or its JSDoc, run `npm run docs` and review `docs/API.md`.
+
 ## Compatibility
 
-Written using ESM, supports CJS.
+Written as ESM and published with both ESM and CommonJS entry points.
 
-Supports the latest versions of Node.js 20, 22, and 24 in both ESM + CJS.
+Supports Node.js 20, 22, and 24+ in both ESM and CJS environments.
 
 ## TypeScript
 

package/dist/lib/Client.js

@@ -2,8 +2,7 @@
 
 var node_dgram = require('node:dgram');
 var node_events = require('node:events');
-var osc = require('./osc.js');
-var Message = require('./Message.js');
+var send = require('./internal/send.js');
 
 /**
  * OSC Client for sending messages and bundles over UDP.
@@ -82,34 +81,6 @@ class Client extends node_events.EventEmitter {
       });
     }
   }
-  _performSend(message, args, callback) {
-    let mes;
-    let buf;
-    try {
-      switch (typeof message) {
-        case 'object':
-          buf = osc.encode(message);
-          this._sock.send(buf, 0, buf.length, this.port, this.host, callback);
-          break;
-        case 'string':
-          mes = new Message(args[0]);
-          for (let i = 1; i < args.length; i++) {
-            mes.append(args[i]);
-          }
-          buf = osc.encode(mes);
-          this._sock.send(buf, 0, buf.length, this.port, this.host, callback);
-          break;
-        default:
-          throw new TypeError('That Message Just Doesn\'t Seem Right');
-      }
-    }
-    catch (e) {
-      if (e.code !== 'ERR_SOCKET_DGRAM_NOT_RUNNING') throw e;
-      const error = new ReferenceError('Cannot send message on closed socket.');
-      error.code = e.code;
-      callback(error);
-    }
-  }
   /**
    * Send an OSC message or bundle to the server.
    * 
@@ -149,20 +120,12 @@ class Client extends node_events.EventEmitter {
    * 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.slice(1)
-      };
-    }
+    const message = args.shift();
     
     if (typeof args[args.length - 1] === 'function') {
       callback = args.pop();
-      this._performSend(message, args, callback);
+      send(this._sock, message, args, this.port, this.host, callback);
     }
     else {
       // No callback provided, return a Promise
@@ -171,7 +134,7 @@ class Client extends node_events.EventEmitter {
           if (err) reject(err);
           else resolve();
         };
-        this._performSend(message, args, callback);
+        send(this._sock, message, args, this.port, this.host, callback);
       });
     }
   }

package/dist/lib/Server.js

@@ -2,8 +2,13 @@
 
 var node_dgram = require('node:dgram');
 var node_events = require('node:events');
+var send = require('./internal/send.js');
 var decode = require('#decode');
 
+function createSocketNotReadyError() {
+  return new Error('Cannot send message before server is listening. Wait for the "listening" event.');
+}
+
 /**
  * OSC Server for receiving messages and bundles over UDP.
  * 
@@ -85,6 +90,8 @@ class Server extends node_events.EventEmitter {
     let decoded;
     this.port = port;
     this.host = host;
+    this._isListening = false;
+    this._isClosed = false;
     this._sock = node_dgram.createSocket({
       type: 'udp4',
       reuseAddr: true
@@ -94,6 +101,8 @@ class Server extends node_events.EventEmitter {
     // 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._isListening = true;
+      this._isClosed = false;
       this.port = this._sock.address().port;
       this.emit('listening');
       if (cb) cb();
@@ -120,6 +129,62 @@ class Server extends node_events.EventEmitter {
     this._sock.on('error', (err) => {
       this.emit('error', err);
     });
+
+    this._sock.on('close', () => {
+      this._isListening = false;
+      this._isClosed = true;
+    });
+  }
+  /**
+   * Send an OSC message or bundle from the server's bound socket.
+   * 
+   * This method can be used with either a callback or as a Promise.
+   * 
+   * @param {import('./Message.mjs').default|import('./Bundle.mjs').default|Array|string} message - The message, bundle, address, or array to send.
+   * @param {number} port - The remote port to send to.
+   * @param {string} host - The remote host to send to.
+   * @param {Function} [cb] - Optional callback function called when send completes.
+   * @returns {Promise<void>|undefined} Returns a Promise if no callback is provided.
+   * 
+   * @throws {Error} If the server socket is not yet listening.
+   * @throws {TypeError} If the message format is invalid.
+   * @throws {ReferenceError} If attempting to send on a closed socket.
+   * 
+   * @example
+   * // Send an address-only message
+   * await server.send('/ping', 9000, '127.0.0.1');
+   * 
+   * @example
+   * // Send an array message
+   * server.send(['/ack', 1], 9000, '192.168.1.42', (err) => {
+   *   if (err) console.error(err);
+   * });
+   */
+  send(message, port, host, cb) {
+    if (!this._isListening && !this._isClosed) {
+      const error = createSocketNotReadyError();
+
+      if (cb) {
+        cb(error);
+        return;
+      }
+
+      throw error;
+    }
+
+    if (cb) {
+      send(this._sock, message, [], port, host, cb);
+    }
+    else {
+      return new Promise((resolve, reject) => {
+        const callback = (err) => {
+          if (err) reject(err);
+          else resolve();
+        };
+
+        send(this._sock, message, [], port, host, callback);
+      });
+    }
   }
   /**
    * Close the server socket.

package/dist/lib/internal/send.js

@@ -0,0 +1,48 @@
+'use strict';
+
+var osc = require('../osc.js');
+var Message = require('../Message.js');
+
+function normalizeMessage(message) {
+  if (message instanceof Array) {
+    return {
+      address: message[0],
+      args: message.slice(1)
+    };
+  }
+
+  return message;
+}
+
+function performSend(sock, message, args, port, host, callback) {
+  let mes;
+  let buf;
+  const normalizedMessage = normalizeMessage(message);
+
+  try {
+    switch (typeof normalizedMessage) {
+      case 'object':
+        buf = osc.encode(normalizedMessage);
+        sock.send(buf, 0, buf.length, port, host, callback);
+        break;
+      case 'string':
+        mes = new Message(normalizedMessage);
+        for (const arg of args) {
+          mes.append(arg);
+        }
+        buf = osc.encode(mes);
+        sock.send(buf, 0, buf.length, port, host, callback);
+        break;
+      default:
+        throw new TypeError('That Message Just Doesn\'t Seem Right');
+    }
+  }
+  catch (e) {
+    if (e.code !== 'ERR_SOCKET_DGRAM_NOT_RUNNING') throw e;
+    const error = new ReferenceError('Cannot send message on closed socket.');
+    error.code = e.code;
+    callback(error);
+  }
+}
+
+module.exports = performSend;

package/dist/test/test-promises.js

@@ -141,6 +141,22 @@ tap.test('server: close with promise', async (t) => {
   t.pass('Server closed successfully with promise');
 });
 
+tap.test('server: send promise rejection on closed socket', async (t) => {
+  const oscServer = new nodeOsc.Server(0, '127.0.0.1');
+
+  t.plan(1);
+
+  await node_events.once(oscServer, 'listening');
+  await oscServer.close();
+
+  try {
+    await oscServer.send('/boom', 3333, '127.0.0.1');
+    t.fail('Should have thrown an error');
+  } catch (err) {
+    t.equal(err.code, 'ERR_SOCKET_DGRAM_NOT_RUNNING', 'Should reject with correct error code');
+  }
+});
+
 tap.test('server: no callback still emits listening event', async (t) => {
   const oscServer = new nodeOsc.Server(0, '127.0.0.1');
   

package/dist/test/test-server.js

@@ -89,6 +89,67 @@ tap.test('server: callback as second arg', async (t) => {
   });
 });
 
+tap.test('server: send to remote port', async (t) => {
+  const sender = new nodeOsc.Server(0, '127.0.0.1');
+  const receiver = new nodeOsc.Server(0, '127.0.0.1');
+  await Promise.all([node_events.once(sender, 'listening'), node_events.once(receiver, 'listening')]);
+
+  t.plan(1);
+
+  t.teardown(async () => {
+    await Promise.all([sender.close(), receiver.close()]);
+  });
+
+  const receivedMessage = node_events.once(receiver, 'message');
+  await sender.send(['/test', 1], receiver.port, '127.0.0.1');
+  const [msg] = await receivedMessage;
+
+  t.same(msg, ['/test', 1], 'server should send a message from its bound socket');
+});
+
+tap.test('server: can receive and reply from within message handler', async (t) => {
+  const requester = new nodeOsc.Server(0, '127.0.0.1');
+  const responder = new nodeOsc.Server(0, '127.0.0.1');
+  await Promise.all([node_events.once(requester, 'listening'), node_events.once(responder, 'listening')]);
+
+  t.plan(3);
+
+  t.teardown(async () => {
+    await Promise.all([requester.close(), responder.close()]);
+  });
+
+  responder.on('message', (msg, rinfo) => {
+    t.same(msg, ['/ping', 1], 'responder should receive the incoming message');
+    responder.send(['/ack', 1], rinfo.port, rinfo.address, (err) => {
+      t.error(err, 'responder should reply without error');
+    });
+  });
+
+  const receivedReply = node_events.once(requester, 'message');
+  await requester.send(['/ping', 1], responder.port, '127.0.0.1');
+  const [reply] = await receivedReply;
+
+  t.same(reply, ['/ack', 1], 'requester should receive the reply on the same socket');
+});
+
+tap.test('server: send before listening returns a clear error', async (t) => {
+  t.plan(3);
+
+  const server = new nodeOsc.Server(0, '127.0.0.1');
+
+  t.throws(() => {
+    server.send('/test', 3333, '127.0.0.1');
+  }, /before server is listening/i, 'send without callback should throw before listening');
+
+  server.send('/test', 3333, '127.0.0.1', (err) => {
+    t.ok(err instanceof Error, 'send should fail with an Error before listening');
+    t.match(err.message, /before server is listening/i, 'error message should explain the socket is not ready');
+  });
+
+  await node_events.once(server, 'listening');
+  await server.close();
+});
+
 tap.test('server: bad message', async (t) => {
   t.plan(2);
   const oscServer = new nodeOsc.Server(0, '127.0.0.1');

package/docs/API.md

@@ -13,17 +13,17 @@ For usage guides, best practices, and troubleshooting, see the **[Guide](./GUIDE
 
 - [Server](#server)
   - [Constructor](#server-constructor)
-  - [close()](#server-close)
+  - [close()](#serverclose)
 - [Client](#client)
   - [Constructor](#client-constructor)
-  - [close()](#client-close)
-  - [send()](#client-send)
+  - [close()](#clientclose)
+  - [send()](#clientsend)
 - [Message](#message)
   - [Constructor](#message-constructor)
-  - [append()](#message-append)
+  - [append()](#messageappend)
 - [Bundle](#bundle)
   - [Constructor](#bundle-constructor)
-  - [append()](#bundle-append)
+  - [append()](#bundleappend)
 - [Low Level Functions](#low-level-functions)
   - [encode()](#encode)
   - [decode()](#decode)

package/docs/GUIDE.md

@@ -9,6 +9,8 @@ This guide provides best practices, patterns, and detailed information for using
 - [Type System](#type-system)
 - [Best Practices](#best-practices)
 - [Troubleshooting](#troubleshooting)
+- [Advanced Topics](#advanced-topics)
+- [Further Reading](#further-reading)
 
 ## Events
 
@@ -483,10 +485,12 @@ await client.close();
 Ensure you wait for the server to start before sending messages:
 
 ```javascript
+import { once } from 'node:events';
+
 const server = new Server(3333, '0.0.0.0');
 
 // Wait for server to be ready
-await new Promise(resolve => server.on('listening', resolve));
+await once(server, 'listening');
 
 // Now safe to send messages
 console.log('Server ready!');

package/docs/README.md

@@ -56,7 +56,7 @@ A comprehensive guide covering:
 
 The API documentation is automatically generated from JSDoc comments:
 
-1. Edit JSDoc comments in the source files (`lib/**/*.mjs`)
+1. Edit JSDoc comments in the source files (`lib/**/*.mjs`). If the docs layout or anchor generation needs to change, update `scripts/generate-docs.mjs`.
 2. Run `npm run docs` to regenerate `API.md`
 3. Review the changes and commit
 

package/lib/Client.mjs

@@ -1,7 +1,6 @@
 import { createSocket } from 'node:dgram';
 import { EventEmitter } from 'node:events';
-import { encode } from './osc.mjs';
-import Message from './Message.mjs';
+import performSend from './internal/send.mjs';
 
 /**
  * OSC Client for sending messages and bundles over UDP.
@@ -80,34 +79,6 @@ class Client extends EventEmitter {
       });
     }
   }
-  _performSend(message, args, callback) {
-    let mes;
-    let buf;
-    try {
-      switch (typeof message) {
-        case 'object':
-          buf = encode(message);
-          this._sock.send(buf, 0, buf.length, this.port, this.host, callback);
-          break;
-        case 'string':
-          mes = new Message(args[0]);
-          for (let i = 1; i < args.length; i++) {
-            mes.append(args[i]);
-          }
-          buf = encode(mes);
-          this._sock.send(buf, 0, buf.length, this.port, this.host, callback);
-          break;
-        default:
-          throw new TypeError('That Message Just Doesn\'t Seem Right');
-      }
-    }
-    catch (e) {
-      if (e.code !== 'ERR_SOCKET_DGRAM_NOT_RUNNING') throw e;
-      const error = new ReferenceError('Cannot send message on closed socket.');
-      error.code = e.code;
-      callback(error);
-    }
-  }
   /**
    * Send an OSC message or bundle to the server.
    * 
@@ -147,20 +118,12 @@ class Client extends EventEmitter {
    * 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.slice(1)
-      };
-    }
+    const message = args.shift();
     
     if (typeof args[args.length - 1] === 'function') {
       callback = args.pop();
-      this._performSend(message, args, callback);
+      performSend(this._sock, message, args, this.port, this.host, callback);
     }
     else {
       // No callback provided, return a Promise
@@ -169,7 +132,7 @@ class Client extends EventEmitter {
           if (err) reject(err);
           else resolve();
         };
-        this._performSend(message, args, callback);
+        performSend(this._sock, message, args, this.port, this.host, callback);
       });
     }
   }

package/lib/Server.mjs

@@ -1,8 +1,13 @@
 import { createSocket } from 'node:dgram';
 import { EventEmitter } from 'node:events';
+import performSend from './internal/send.mjs';
 
 import decode from '#decode';
 
+function createSocketNotReadyError() {
+  return new Error('Cannot send message before server is listening. Wait for the "listening" event.');
+}
+
 /**
  * OSC Server for receiving messages and bundles over UDP.
  * 
@@ -84,6 +89,8 @@ class Server extends EventEmitter {
     let decoded;
     this.port = port;
     this.host = host;
+    this._isListening = false;
+    this._isClosed = false;
     this._sock = createSocket({
       type: 'udp4',
       reuseAddr: true
@@ -93,6 +100,8 @@ class Server extends EventEmitter {
     // 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._isListening = true;
+      this._isClosed = false;
       this.port = this._sock.address().port;
       this.emit('listening');
       if (cb) cb();
@@ -119,6 +128,62 @@ class Server extends EventEmitter {
     this._sock.on('error', (err) => {
       this.emit('error', err);
     });
+
+    this._sock.on('close', () => {
+      this._isListening = false;
+      this._isClosed = true;
+    });
+  }
+  /**
+   * Send an OSC message or bundle from the server's bound socket.
+   * 
+   * This method can be used with either a callback or as a Promise.
+   * 
+   * @param {import('./Message.mjs').default|import('./Bundle.mjs').default|Array|string} message - The message, bundle, address, or array to send.
+   * @param {number} port - The remote port to send to.
+   * @param {string} host - The remote host to send to.
+   * @param {Function} [cb] - Optional callback function called when send completes.
+   * @returns {Promise<void>|undefined} Returns a Promise if no callback is provided.
+   * 
+   * @throws {Error} If the server socket is not yet listening.
+   * @throws {TypeError} If the message format is invalid.
+   * @throws {ReferenceError} If attempting to send on a closed socket.
+   * 
+   * @example
+   * // Send an address-only message
+   * await server.send('/ping', 9000, '127.0.0.1');
+   * 
+   * @example
+   * // Send an array message
+   * server.send(['/ack', 1], 9000, '192.168.1.42', (err) => {
+   *   if (err) console.error(err);
+   * });
+   */
+  send(message, port, host, cb) {
+    if (!this._isListening && !this._isClosed) {
+      const error = createSocketNotReadyError();
+
+      if (cb) {
+        cb(error);
+        return;
+      }
+
+      throw error;
+    }
+
+    if (cb) {
+      performSend(this._sock, message, [], port, host, cb);
+    }
+    else {
+      return new Promise((resolve, reject) => {
+        const callback = (err) => {
+          if (err) reject(err);
+          else resolve();
+        };
+
+        performSend(this._sock, message, [], port, host, callback);
+      });
+    }
   }
   /**
    * Close the server socket.