node-osc 11.2.1 → 11.2.2

package/.github/workflows/nodejs.yml

@@ -26,7 +26,7 @@ jobs:
       uses: actions/setup-node@v6
       with:
         node-version: ${{ matrix.node-version }}
-        cache: 'npm'
+        cache: ${{ runner.os != 'Windows' && 'npm' || '' }}
 
     - name: Install Dependencies
       run: npm ci

package/README.md

@@ -47,8 +47,9 @@ server.on('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
+- 📂 **[Documentation Hub](./docs/)** - Complete documentation with navigation guide
+- 📚 **[API Reference](./docs/API.md)** - Complete API reference generated from source code
+- 📘 **[Usage Guide](./docs/GUIDE.md)** - Best practices, error handling, and troubleshooting
 - 📖 **[Examples](./examples/)** - Working examples for various use cases
 
 ## Compatibility

package/agent.md

@@ -0,0 +1,330 @@
+# Agent Instructions for node-osc
+
+This document provides context and instructions for AI agents (GitHub Copilot, Cursor, and other agentic platforms) working on the node-osc project.
+
+## Project Overview
+
+**node-osc** is a Node.js library for sending and receiving [Open Sound Control (OSC)](http://opensoundcontrol.org) messages over UDP. It provides a simple, no-frills API inspired by pyOSC.
+
+### Key Features
+- Send and receive OSC messages and bundles
+- Dual module support (ESM and CommonJS)
+- 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
+
+## Architecture
+
+### Core Components
+
+1. **Server** (`lib/Server.mjs`) - EventEmitter-based OSC server for receiving messages
+   - Listens on UDP socket
+   - Emits events: `listening`, `message`, `bundle`, `error`, and address-specific events
+
+2. **Client** (`lib/Client.mjs`) - OSC client for sending messages
+   - Sends messages over UDP
+   - Supports both callbacks and async/await
+
+3. **Message** (`lib/Message.mjs`) - Represents a single OSC message
+   - Contains address (string) and arguments (array)
+   - Can append additional arguments
+
+4. **Bundle** (`lib/Bundle.mjs`) - Represents a collection of OSC messages
+   - Contains timetag and array of elements (messages or nested bundles)
+   - Used for sending multiple messages together
+
+5. **Low-level encoding/decoding** (`lib/osc.mjs`, `lib/internal/`) - Binary OSC protocol implementation
+   - `encode()` - Converts Message/Bundle objects to binary Buffer
+   - `decode()` - Parses binary Buffer into Message/Bundle objects
+
+### Module System
+
+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)
+
+**Important:** The single `.d.mts` type definition file works for both ESM and CommonJS consumers.
+
+### Package Exports
+
+```json
+{
+  "exports": {
+    "types": "./types/index.d.mts",
+    "require": "./dist/lib/index.js",
+    "import": "./lib/index.mjs",
+    "default": "./lib/index.mjs"
+  }
+}
+```
+
+## Development Workflow
+
+### Essential Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Run linter (ESLint)
+npm run lint
+
+# Build the project (clean, transpile to CJS, generate types)
+npm run build
+
+# Run all tests (lint + build + ESM tests + CJS tests)
+npm test
+
+# Run only ESM tests
+npm run test:esm
+
+# Run only CJS tests
+npm run test:cjs
+
+# Generate API documentation from JSDoc
+npm run docs
+
+# Clean build artifacts
+npm run clean
+```
+
+### Testing Strategy
+
+- 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
+- Always run `npm run build` before running CJS tests
+- **100% test coverage is required** - All lines, branches, functions, and statements must be covered
+
+### Build Process
+
+1. **Clean**: Removes `dist/` and `types/` directories
+2. **Rollup**: Transpiles ESM to CommonJS in `dist/` directory
+3. **TypeScript**: Generates type definitions from JSDoc in `types/` directory
+
+The build is automatically run before publishing (`prepublishOnly` script).
+
+## Coding Standards
+
+### JavaScript Style
+
+- **ES Modules**: Use ESM syntax (`import`/`export`)
+- **File extension**: Use `.mjs` for ESM files
+- **Linting**: Follow ESLint rules in `eslint.config.mjs`
+- **Modern JavaScript**: Use async/await, arrow functions, destructuring
+- **Error handling**: Always handle errors in async operations
+
+### Documentation
+
+- **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
+
+Example JSDoc pattern:
+```javascript
+/**
+ * Sends an OSC message or bundle.
+ * 
+ * @param {Message|Bundle|string} msg - The message, bundle, or address to send.
+ * @param {...*} args - Additional arguments (used when first param is a string address).
+ * @returns {Promise<void>}
+ * 
+ * @example
+ * await client.send('/test', 123);
+ * 
+ * @example
+ * const message = new Message('/test', 123);
+ * await client.send(message);
+ */
+async send(msg, ...args) { ... }
+```
+
+### Type System
+
+- TypeScript definitions are **generated** from JSDoc comments
+- Do not manually edit `types/*.d.mts` files
+- Update JSDoc comments in source files instead
+- Run `npm run build:types` to regenerate types
+
+### Naming Conventions
+
+- **Classes**: PascalCase (e.g., `Client`, `Server`, `Message`, `Bundle`)
+- **Functions**: camelCase (e.g., `encode`, `decode`, `toBuffer`)
+- **Private functions**: Prefix with underscore (e.g., `_oscType`)
+- **Constants**: UPPER_SNAKE_CASE for true constants
+- **Files**: Match class names or use descriptive kebab-case
+
+### Dual Module Support Patterns
+
+When writing code that needs to work in both ESM and CJS:
+
+1. **Imports**: Use ESM imports in source (Rollup handles conversion)
+2. **Exports**: Use named exports for all public APIs
+3. **Testing**: Test both ESM and CJS builds
+4. **Package imports**: Use `#decode` subpath import for internal modules (defined in `package.json` imports field)
+
+## Important Files and Directories
+
+### Source Files
+- `lib/` - ESM source code (the canonical source)
+- `lib/index.mjs` - Main entry point, exports all public APIs
+- `lib/internal/` - Internal utilities (decode, encode, helpers)
+- `lib/osc.mjs` - Low-level encode/decode functions
+
+### Build Artifacts
+- `dist/` - Transpiled CommonJS files (generated, do not edit)
+- `types/` - TypeScript type definitions (generated, do not edit)
+
+### 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
+- `examples/` - Working example code for various use cases
+
+### Configuration
+- `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
+
+## Making Changes
+
+### Adding a New Feature
+
+1. **Write ESM source** in `lib/`
+2. **Add JSDoc comments** with types and examples
+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
+7. **Update README.md** if adding user-facing functionality
+
+### Fixing a Bug
+
+1. **Write a failing test** that demonstrates the bug
+2. **Fix the bug** in the ESM source files
+3. **Run tests**: `npm test` to verify fix works in both ESM and CJS
+4. **Verify coverage**: Ensure 100% test coverage is maintained
+5. **Check no regressions**: Ensure all tests pass
+
+### Modifying the API
+
+1. **Update JSDoc** in source files
+2. **Regenerate types**: `npm run build:types`
+3. **Update tests** to cover new behavior - **must maintain 100% coverage**
+4. **Regenerate docs**: `npm run docs`
+5. **Update README.md** and `docs/GUIDE.md` as appropriate
+
+## Common Patterns
+
+### Creating a Server
+```javascript
+import { Server } from 'node-osc';
+
+const server = new Server(3333, '0.0.0.0');
+server.on('message', (msg, rinfo) => {
+  console.log('Message:', msg);
+});
+```
+
+### Creating a Client
+```javascript
+import { Client } from 'node-osc';
+
+const client = new Client('127.0.0.1', 3333);
+await client.send('/test', 123);
+await client.close();
+```
+
+### Working with Bundles
+```javascript
+import { Bundle } from 'node-osc';
+
+const bundle = new Bundle(['/one', 1], ['/two', 2]);
+await client.send(bundle);
+```
+
+### Low-level Encoding/Decoding
+```javascript
+import { Message, encode, decode } from 'node-osc';
+
+const message = new Message('/test', 123);
+const buffer = encode(message);
+const decoded = decode(buffer);
+```
+
+## Troubleshooting
+
+### Build Issues
+
+- **"Cannot find module"**: Run `npm install` to install dependencies
+- **Type generation fails**: Check JSDoc syntax in source files
+- **CJS tests fail but ESM pass**: Run `npm run build` before testing
+
+### Test Issues
+
+- **Port conflicts**: Tests use dynamic port allocation via `getPort()` utility
+- **Timing issues**: Use async/await and proper event handling
+- **ESM/CJS differences**: Ensure code works in both environments
+
+### Module Resolution
+
+- **Dual package hazard**: The package exports both ESM and CJS - don't mix them
+- **Type imports**: TypeScript consumers get types automatically from `types/index.d.mts`
+- **Internal imports**: Use `#decode` subpath for internal modules
+
+## Dependencies
+
+### Runtime Dependencies
+- **None** - This is a zero-dependency library for production use
+
+### Development Dependencies
+- **eslint** - Code linting
+- **tap** - Test framework
+- **rollup** - Module bundler for ESM → CJS transpilation
+- **typescript** - Type definition generation from JSDoc
+- **jsdoc** - Documentation generation
+- **globals** - ESLint globals configuration
+
+## OSC Protocol Knowledge
+
+When working with OSC message encoding/decoding:
+
+- OSC addresses start with `/` (e.g., `/oscillator/frequency`)
+- OSC types: integer (i), float (f), string (s), blob (b), time tag (t)
+- Messages are null-padded to 4-byte boundaries
+- Bundles have time tags (when to execute) and can contain nested bundles
+- See [OSC Specification](http://opensoundcontrol.org/spec-1_0) for protocol details
+
+## Security Considerations
+
+- Always validate input data when decoding OSC messages
+- Be careful with buffer operations to avoid out-of-bounds access
+- Limit message and bundle sizes to prevent DoS attacks
+- Sanitize OSC addresses before using them as event names
+- Handle malformed OSC data gracefully (emit errors, don't crash)
+
+## License
+
+This project uses the Apache-2.0 license. When contributing code:
+- Ensure all new code is compatible with Apache-2.0
+- Do not introduce dependencies with incompatible licenses
+- Include proper attribution for any third-party code
+
+## Getting Help
+
+- **API Documentation**: See `docs/API.md`
+- **Usage Guide**: See `docs/GUIDE.md`
+- **Examples**: See `examples/` directory
+- **Issues**: Check existing GitHub issues for similar problems
+- **OSC Protocol**: Refer to http://opensoundcontrol.org for protocol details

package/dist/lib/Server.js

@@ -91,18 +91,13 @@ class Server extends node_events.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/dist/lib/internal/decode.js

@@ -5,7 +5,8 @@ var osc = require('../osc.js');
 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;
@@ -15,6 +16,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/dist/lib/osc.js

@@ -18,6 +18,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;
@@ -31,6 +34,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 };
 }
@@ -42,6 +48,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 };
 }
@@ -57,9 +66,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 };
 }
 
@@ -67,7 +85,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 = node_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);
@@ -82,6 +104,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);
   
@@ -377,6 +402,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/dist/test/lib/osc.js

@@ -18,6 +18,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;
@@ -31,6 +34,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 };
 }
@@ -42,6 +48,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 };
 }
@@ -57,9 +66,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 };
 }
 
@@ -67,7 +85,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 = node_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);
@@ -82,6 +104,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);
   
@@ -377,6 +402,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/dist/test/test-bundle.js

@@ -1,14 +1,13 @@
 'use strict';
 
+var node_events = require('node:events');
 var tap = require('tap');
 var nodeOsc = require('node-osc');
-var util = require('./util.js');
 
-tap.beforeEach(util.bootstrap);
-
-tap.test('bundle: verbose bundle', (t) => {
-  const server = new nodeOsc.Server(t.context.port, '127.0.0.1');
-  const client = new nodeOsc.Client('127.0.0.1', t.context.port);
+tap.test('bundle: verbose bundle', async (t) => {
+  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(2);
 
@@ -35,9 +34,10 @@ tap.test('bundle: verbose bundle', (t) => {
   }));
 });
 
-tap.test('bundle: array syntax', (t) => {
-  const server = new nodeOsc.Server(t.context.port, '127.0.0.1');
-  const client = new nodeOsc.Client('127.0.0.1', t.context.port);
+tap.test('bundle: array syntax', async (t) => {
+  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(2);
 
@@ -57,9 +57,10 @@ tap.test('bundle: array syntax', (t) => {
   ));
 });
 
-tap.test('bundle: nested bundle', (t) => {
-  const server = new nodeOsc.Server(t.context.port, '127.0.0.1');
-  const client = new nodeOsc.Client('127.0.0.1', t.context.port);
+tap.test('bundle: nested bundle', async (t) => {
+  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(4);