node-osc 11.2.3 → 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.

package/lib/internal/send.mjs

@@ -0,0 +1,46 @@
+import { encode } from '../osc.mjs';
+import Message from '../Message.mjs';
+
+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 = 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 = 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);
+  }
+}
+
+export default performSend;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "node-osc",
   "description": "pyOSC inspired library for sending and receiving OSC messages",
-  "version": "11.2.3",
+  "version": "11.3.0",
   "exports": {
     "types": "./types/index.d.mts",
     "require": "./dist/lib/index.js",
@@ -47,9 +47,9 @@
     "url": "git+https://github.com/MylesBorins/node-osc.git"
   },
   "devDependencies": {
-    "@eslint/js": "^9.32.0",
-    "eslint": "^9.32.0",
-    "globals": "^16.3.0",
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.0.3",
+    "globals": "^17.4.0",
     "jsdoc": "^4.0.5",
     "rollup": "^4.46.2",
     "tap": "^21.1.0",

package/scripts/generate-docs.mjs

@@ -5,120 +5,89 @@
  * This script reads JSDoc JSON data and generates a formatted Markdown file.
  */
 
-import { writeFileSync } from 'node:fs';
 import { execSync } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
 
-// Generate JSDoc JSON
-let jsdocJson;
-try {
-  jsdocJson = execSync('npx jsdoc -X -c jsdoc.json', {
-    encoding: 'utf8',
-    maxBuffer: 10 * 1024 * 1024
-  });
-} catch (error) {
-  console.error('❌ Failed to run JSDoc:');
-  console.error(error.message);
-  process.exit(1);
-}
+const classOrder = ['Server', 'Client', 'Message', 'Bundle'];
+const functionOrder = ['encode', 'decode'];
 
-let docs;
-try {
-  docs = JSON.parse(jsdocJson);
-} catch (error) {
-  console.error('❌ Failed to parse JSDoc JSON output:');
-  console.error(error.message);
-  process.exit(1);
+function githubAnchor(text) {
+  return text
+    .trim()
+    .toLowerCase()
+    .replace(/[^\w\- ]+/g, '')
+    .replace(/\s+/g, '-');
 }
 
-// Filter and organize documentation
-const classes = {};
-const functions = {};
-
-docs.forEach(item => {
-  if (item.undocumented || item.ignore) return;
-  
-  if (item.kind === 'class' && item.classdesc) {
-    if (!classes[item.name]) {
-      classes[item.name] = {
-        desc: item.classdesc,
-        constructor: null,
-        methods: [],
-        examples: item.examples || [],
-        augments: item.augments || []
-      };
-    }
-    // Look for constructor params
-    if (item.params) {
-      classes[item.name].constructor = {
-        params: item.params,
-        examples: item.examples || []
-      };
-    }
-  } else if (item.kind === 'function' && item.memberof) {
-    // Method of a class
-    const className = item.memberof;
-    if (!classes[className]) {
-      classes[className] = {
-        desc: '',
-        constructor: null,
-        methods: [],
-        examples: []
-      };
-    }
-    classes[className].methods.push(item);
-  } else if (item.kind === 'function' && !item.memberof && item.scope === 'global') {
-    // Top-level function
-    functions[item.name] = item;
+function runJsdoc() {
+  try {
+    return execSync('npx jsdoc -X -c jsdoc.json', {
+      encoding: 'utf8',
+      maxBuffer: 10 * 1024 * 1024
+    });
+  } catch (error) {
+    throw new Error(`Failed to run JSDoc: ${error.message}`, { cause: error });
   }
-});
-
-// Generate Markdown
-let markdown = `<!-- Generated by JSDoc. Update this documentation by updating the source code. -->
-
-# API Reference
-
-> **⚠️ This file is auto-generated from JSDoc comments in the source code.**  
-> To update this documentation, edit the JSDoc comments in the source files and run \`npm run docs\`.
-
-This document provides detailed API reference for all classes, methods, and functions in node-osc.
+}
 
-For usage guides, best practices, and troubleshooting, see the **[Guide](./GUIDE.md)**.
+function parseJsdocJson(jsdocJson) {
+  try {
+    return JSON.parse(jsdocJson);
+  } catch (error) {
+    throw new Error(`Failed to parse JSDoc JSON output: ${error.message}`, { cause: error });
+  }
+}
 
-## Table of Contents
+function collectDocs(docs) {
+  const classes = {};
+  const functions = {};
 
-`;
+  docs.forEach(item => {
+    if (item.undocumented || item.ignore) return;
 
-// Define order: Server → Client → Message → Bundle → Low Level
-const classOrder = ['Server', 'Client', 'Message', 'Bundle'];
-const functionOrder = ['encode', 'decode'];
+    if (item.kind === 'class' && item.classdesc) {
+      const classInfo = classes[item.name] || {
+        desc: '',
+        constructor: null,
+        methods: [],
+        examples: [],
+        augments: []
+      };
 
-// Add classes to TOC
-classOrder.forEach(name => {
-  if (classes[name]) {
-    markdown += `- [${name}](#${name.toLowerCase()})\n`;
-    if (classes[name].constructor) {
-      markdown += `  - [Constructor](#${name.toLowerCase()}-constructor)\n`;
+      classInfo.desc = item.classdesc;
+      classInfo.examples = item.examples || [];
+      classInfo.augments = item.augments || [];
+      classes[item.name] = classInfo;
+
+      if (item.params) {
+        classes[item.name].constructor = {
+          params: item.params,
+          examples: item.examples || []
+        };
+      }
+    } else if (item.kind === 'function' && item.memberof) {
+      const className = item.memberof;
+      if (!classes[className]) {
+        classes[className] = {
+          desc: '',
+          constructor: null,
+          methods: [],
+          examples: [],
+          augments: []
+        };
+      }
+      classes[className].methods.push(item);
+    } else if (item.kind === 'function' && !item.memberof && item.scope === 'global') {
+      functions[item.name] = item;
     }
-    classes[name].methods.forEach(method => {
-      markdown += `  - [${method.name}()](#${name.toLowerCase()}-${method.name.toLowerCase()})\n`;
-    });
-  }
-});
-
-// Add functions to TOC
-markdown += `- [Low Level Functions](#low-level-functions)\n`;
-functionOrder.forEach(name => {
-  if (functions[name]) {
-    markdown += `  - [${name}()](#${name.toLowerCase()})\n`;
-  }
-});
+  });
 
-markdown += `\n---\n\n`;
+  return { classes, functions };
+}
 
-// Helper function to format parameters
 function formatParams(params) {
   if (!params || params.length === 0) return '';
-  
+
   let result = '\n**Parameters:**\n\n';
   params.forEach(param => {
     const optional = param.optional ? ' (optional)' : '';
@@ -129,10 +98,9 @@ function formatParams(params) {
   return result;
 }
 
-// Helper function to format examples
 function formatExamples(examples) {
   if (!examples || examples.length === 0) return '';
-  
+
   let result = '\n**Examples:**\n\n';
   examples.forEach(example => {
     result += '```javascript\n' + example + '\n```\n\n';
@@ -140,19 +108,17 @@ function formatExamples(examples) {
   return result;
 }
 
-// Helper function to format returns
 function formatReturns(returns) {
   if (!returns || returns.length === 0) return '';
-  
+
   const ret = returns[0];
   const types = ret.type ? ret.type.names.join(' | ') : 'any';
   return `\n**Returns:** *{${types}}* - ${ret.description || ''}\n`;
 }
 
-// Helper function to format throws
 function formatThrows(exceptions) {
   if (!exceptions || exceptions.length === 0) return '';
-  
+
   let result = '\n**Throws:**\n\n';
   exceptions.forEach(ex => {
     const types = ex.type ? ex.type.names.join(' | ') : 'Error';
@@ -161,69 +127,109 @@ function formatThrows(exceptions) {
   return result;
 }
 
-// Generate class documentation
-classOrder.forEach(className => {
-  const classInfo = classes[className];
-  if (!classInfo) return;
-  
-  markdown += `## ${className}\n\n`;
-  
-  // Add extends info
-  if (classInfo.augments && classInfo.augments.length > 0) {
-    markdown += `**Extends:** ${classInfo.augments.join(', ')}\n\n`;
-  }
-  
-  markdown += `${classInfo.desc}\n`;
-  
-  // Class-level examples
-  if (classInfo.examples.length > 0 && !classInfo.constructor) {
-    markdown += formatExamples(classInfo.examples);
-  }
-  
-  // Constructor
-  if (classInfo.constructor) {
-    markdown += `\n### ${className} Constructor\n\n`;
-    markdown += `Creates a new ${className} instance.\n`;
-    markdown += formatParams(classInfo.constructor.params);
-    markdown += formatExamples(classInfo.constructor.examples);
-  }
-  
-  // Methods
-  classInfo.methods.forEach(method => {
-    markdown += `\n### ${className}.${method.name}()\n\n`;
-    markdown += `${method.description || ''}\n`;
-    markdown += formatParams(method.params);
-    markdown += formatReturns(method.returns);
-    markdown += formatThrows(method.exceptions);
-    markdown += formatExamples(method.examples);
+function generateMarkdown(classes, functions) {
+  let markdown = `<!-- Generated by JSDoc. Update this documentation by updating the source code. -->
+
+# API Reference
+
+> **⚠️ This file is auto-generated from JSDoc comments in the source code.**  
+> To update this documentation, edit the JSDoc comments in the source files and run \`npm run docs\`.
+
+This document provides detailed API reference for all classes, methods, and functions in node-osc.
+
+For usage guides, best practices, and troubleshooting, see the **[Guide](./GUIDE.md)**.
+
+## Table of Contents
+
+`;
+
+  classOrder.forEach(name => {
+    if (classes[name]) {
+      markdown += `- [${name}](#${githubAnchor(name)})\n`;
+      if (classes[name].constructor) {
+        markdown += `  - [Constructor](#${githubAnchor(`${name} Constructor`)})\n`;
+      }
+      classes[name].methods.forEach(method => {
+        markdown += `  - [${method.name}()](#${githubAnchor(`${name}.${method.name}()`)})\n`;
+      });
+    }
+  });
+
+  markdown += `- [Low Level Functions](#${githubAnchor('Low Level Functions')})\n`;
+  functionOrder.forEach(name => {
+    if (functions[name]) {
+      markdown += `  - [${name}()](#${githubAnchor(`${name}()`)})\n`;
+    }
   });
-  
+
   markdown += `\n---\n\n`;
-});
-
-// Generate function documentation
-markdown += `## Low Level Functions\n\n`;
-markdown += `These functions provide low-level access to OSC encoding and decoding for advanced use cases.\n\n`;
-
-functionOrder.forEach(funcName => {
-  const func = functions[funcName];
-  if (!func) return;
-  
-  markdown += `### ${funcName}()\n\n`;
-  markdown += `${func.description || ''}\n`;
-  markdown += formatParams(func.params);
-  markdown += formatReturns(func.returns);
-  markdown += formatThrows(func.exceptions);
-  markdown += formatExamples(func.examples);
-  markdown += `\n`;
-});
-
-// Write output
-try {
-  writeFileSync('docs/API.md', markdown, 'utf8');
-  console.log('✅ API documentation generated: docs/API.md');
-} catch (error) {
-  console.error('❌ Failed to write API.md:');
-  console.error(error.message);
-  process.exit(1);
+
+  classOrder.forEach(className => {
+    const classInfo = classes[className];
+    if (!classInfo) return;
+
+    markdown += `## ${className}\n\n`;
+
+    if (classInfo.augments && classInfo.augments.length > 0) {
+      markdown += `**Extends:** ${classInfo.augments.join(', ')}\n\n`;
+    }
+
+    markdown += `${classInfo.desc}\n`;
+
+    if (classInfo.examples.length > 0 && !classInfo.constructor) {
+      markdown += formatExamples(classInfo.examples);
+    }
+
+    if (classInfo.constructor) {
+      markdown += `\n### ${className} Constructor\n\n`;
+      markdown += `Creates a new ${className} instance.\n`;
+      markdown += formatParams(classInfo.constructor.params);
+      markdown += formatExamples(classInfo.constructor.examples);
+    }
+
+    classInfo.methods.forEach(method => {
+      markdown += `\n### ${className}.${method.name}()\n\n`;
+      markdown += `${method.description || ''}\n`;
+      markdown += formatParams(method.params);
+      markdown += formatReturns(method.returns);
+      markdown += formatThrows(method.exceptions);
+      markdown += formatExamples(method.examples);
+    });
+
+    markdown += `\n---\n\n`;
+  });
+
+  markdown += `## Low Level Functions\n\n`;
+  markdown += 'These functions provide low-level access to OSC encoding and decoding for advanced use cases.\n\n';
+
+  functionOrder.forEach(funcName => {
+    const func = functions[funcName];
+    if (!func) return;
+
+    markdown += `### ${funcName}()\n\n`;
+    markdown += `${func.description || ''}\n`;
+    markdown += formatParams(func.params);
+    markdown += formatReturns(func.returns);
+    markdown += formatThrows(func.exceptions);
+    markdown += formatExamples(func.examples);
+    markdown += '\n';
+  });
+
+  return markdown;
 }
+
+function main() {
+  try {
+    const jsdocJson = runJsdoc();
+    const docs = parseJsdocJson(jsdocJson);
+    const { classes, functions } = collectDocs(docs);
+    const markdown = generateMarkdown(classes, functions);
+    writeFileSync('docs/API.md', markdown, 'utf8');
+    console.log('✅ API documentation generated: docs/API.md');
+  } catch (error) {
+    console.error(`❌ ${error.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/test/fixtures/types/test-cjs-types.ts

@@ -4,6 +4,7 @@ const osc = require('node-osc');
 
 // Create server first (typical usage pattern)
 const server: Server = new osc.Server(3333, '0.0.0.0');
+server.send(['/server-test', 1], 3334, '127.0.0.1', () => {});
 
 // Create client after server
 const client: Client = new osc.Client('127.0.0.1', 3333);

package/test/fixtures/types/test-esm-types.ts

@@ -7,6 +7,7 @@ const server: Server = new Server(3333, '0.0.0.0');
 
 // Wait for server to be ready (pattern from examples)
 await once(server, 'listening');
+await server.send(['/server-test', 1], 3334, '127.0.0.1');
 
 server.on('message', (msg) => {
   console.log('Received message:', msg);

package/test/test-promises.mjs

@@ -140,6 +140,22 @@ test('server: close with promise', async (t) => {
   t.pass('Server closed successfully with promise');
 });
 
+test('server: send promise rejection on closed socket', async (t) => {
+  const oscServer = new Server(0, '127.0.0.1');
+
+  t.plan(1);
+
+  await 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');
+  }
+});
+
 test('server: no callback still emits listening event', async (t) => {
   const oscServer = new Server(0, '127.0.0.1');
   

package/test/test-server.mjs

@@ -88,6 +88,67 @@ test('server: callback as second arg', async (t) => {
   });
 });
 
+test('server: send to remote port', async (t) => {
+  const sender = new Server(0, '127.0.0.1');
+  const receiver = new Server(0, '127.0.0.1');
+  await Promise.all([once(sender, 'listening'), once(receiver, 'listening')]);
+
+  t.plan(1);
+
+  t.teardown(async () => {
+    await Promise.all([sender.close(), receiver.close()]);
+  });
+
+  const receivedMessage = 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');
+});
+
+test('server: can receive and reply from within message handler', async (t) => {
+  const requester = new Server(0, '127.0.0.1');
+  const responder = new Server(0, '127.0.0.1');
+  await Promise.all([once(requester, 'listening'), 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 = 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');
+});
+
+test('server: send before listening returns a clear error', async (t) => {
+  t.plan(3);
+
+  const server = new 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 once(server, 'listening');
+  await server.close();
+});
+
 test('server: bad message', async (t) => {
   t.plan(2);
   const oscServer = new Server(0, '127.0.0.1');

package/types/Client.d.mts

@@ -56,7 +56,6 @@ declare class Client extends EventEmitter<any> {
      * await client.close();
      */
     close(cb?: Function): Promise<void> | undefined;
-    _performSend(message: any, args: any, callback: any): void;
     /**
      * Send an OSC message or bundle to the server.
      *

package/types/Client.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"Client.d.mts","sourceRoot":"","sources":["../lib/Client.mjs"],"names":[],"mappings":";AAKA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IACE;;;;;;;;OAQG;IACH,kBANW,MAAM,QACN,MAAM,EAiBhB;IAVC,aAAgB;IAChB,aAAgB;IAChB,mCAGE;IAMJ;;;;;;;;;;;;;;;;;OAiBG;IACH,sBAZa,OAAO,CAAC,IAAI,CAAC,GAAC,SAAS,CAuBnC;IACD,2DA2BC;IACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH,cA7Bc,GAAC,EAAA,GAIF,OAAO,CAAC,IAAI,CAAC,GAAC,SAAS,CAmDnC;CACF;6BA9K4B,aAAa"}
+{"version":3,"file":"Client.d.mts","sourceRoot":"","sources":["../lib/Client.mjs"],"names":[],"mappings":";AAIA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IACE;;;;;;;;OAQG;IACH,kBANW,MAAM,QACN,MAAM,EAiBhB;IAVC,aAAgB;IAChB,aAAgB;IAChB,mCAGE;IAMJ;;;;;;;;;;;;;;;;;OAiBG;IACH,sBAZa,OAAO,CAAC,IAAI,CAAC,GAAC,SAAS,CAuBnC;IACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH,cA7Bc,GAAC,EAAA,GAIF,OAAO,CAAC,IAAI,CAAC,GAAC,SAAS,CA2CnC;CACF;6BAzI4B,aAAa"}

package/types/Server.d.mts

@@ -73,7 +73,35 @@ declare class Server extends EventEmitter<any> {
     constructor(port: number, host?: string, cb?: Function);
     port: number;
     host: string;
+    _isListening: boolean;
+    _isClosed: boolean;
     _sock: import("node:dgram").Socket;
+    /**
+     * 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: import("./Message.mjs").default | import("./Bundle.mjs").default | any[] | string, port: number, host: string, cb?: Function): Promise<void> | undefined;
     /**
      * Close the server socket.
      *

package/types/Server.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"Server.d.mts","sourceRoot":"","sources":["../lib/Server.mjs"],"names":[],"mappings":";AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH;IACE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,kBApBW,MAAM,SACN,MAAM,iBAgEhB;IArCC,aAAgB;IAChB,aAAgB;IAChB,mCAGE;IAiCJ;;;;;;;;;;;;;;;;;OAiBG;IACH,sBAZa,OAAO,CAAC,IAAI,CAAC,GAAC,SAAS,CAuBnC;CACF;6BAvJ4B,aAAa"}
+{"version":3,"file":"Server.d.mts","sourceRoot":"","sources":["../lib/Server.mjs"],"names":[],"mappings":";AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH;IACE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,kBApBW,MAAM,SACN,MAAM,iBAyEhB;IA9CC,aAAgB;IAChB,aAAgB;IAChB,sBAAyB;IACzB,mBAAsB;IACtB,mCAGE;IAwCJ;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,cApBW,OAAO,eAAe,EAAE,OAAO,GAAC,OAAO,cAAc,EAAE,OAAO,WAAO,MAAM,QAC3E,MAAM,QACN,MAAM,kBAEJ,OAAO,CAAC,IAAI,CAAC,GAAC,SAAS,CAyCnC;IACD;;;;;;;;;;;;;;;;;OAiBG;IACH,sBAZa,OAAO,CAAC,IAAI,CAAC,GAAC,SAAS,CAuBnC;CACF;6BAxN4B,aAAa"}

package/types/internal/send.d.mts

@@ -0,0 +1,3 @@
+export default performSend;
+declare function performSend(sock: any, message: any, args: any, port: any, host: any, callback: any): void;
+//# sourceMappingURL=send.d.mts.map

package/types/internal/send.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"send.d.mts","sourceRoot":"","sources":["../../lib/internal/send.mjs"],"names":[],"mappings":";AAcA,4GA6BC"}