node-osc 11.1.1 → 11.2.0

package/docs/GUIDE.md

@@ -0,0 +1,605 @@
+# node-osc Guide
+
+This guide provides best practices, patterns, and detailed information for using node-osc effectively.
+
+## Table of Contents
+
+- [Events](#events)
+- [Error Handling](#error-handling)
+- [Type System](#type-system)
+- [Best Practices](#best-practices)
+- [Troubleshooting](#troubleshooting)
+
+## Events
+
+The `Server` class extends `EventEmitter` and emits several events for different scenarios.
+
+### Server Events
+
+#### `listening`
+
+Emitted when the server starts listening for messages.
+
+```javascript
+server.on('listening', () => {
+  console.log('Server is ready to receive messages');
+});
+```
+
+#### `message`
+
+Emitted when an OSC message is received.
+
+**Parameters:**
+- `msg` (Array): The message as an array where the first element is the address and subsequent elements are arguments
+- `rinfo` (Object): Remote address information
+  - `address` (string): The sender's IP address
+  - `port` (number): The sender's port number
+
+```javascript
+server.on('message', (msg, rinfo) => {
+  const [address, ...args] = msg;
+  console.log(`Received ${address} from ${rinfo.address}:${rinfo.port}`);
+  console.log('Arguments:', args);
+});
+```
+
+#### `bundle`
+
+Emitted when an OSC bundle is received.
+
+**Parameters:**
+- `bundle` (Object): The bundle object
+  - `timetag` (number): The bundle's timetag
+  - `elements` (Array): Array of messages or nested bundles
+- `rinfo` (Object): Remote address information
+
+```javascript
+server.on('bundle', (bundle, rinfo) => {
+  console.log(`Received bundle with timetag ${bundle.timetag}`);
+  bundle.elements.forEach((element) => {
+    console.log('Element:', element);
+  });
+});
+```
+
+#### Address-Specific Events
+
+The server also emits events for each message address received. This allows you to listen for specific OSC addresses without filtering in your code.
+
+```javascript
+// Listen specifically for messages to /note
+server.on('/note', (msg, rinfo) => {
+  const [address, pitch, velocity] = msg;
+  console.log(`Note: ${pitch}, Velocity: ${velocity}`);
+});
+
+// Listen for /oscillator/frequency
+server.on('/oscillator/frequency', (msg) => {
+  const [address, freq] = msg;
+  console.log(`Frequency set to ${freq} Hz`);
+});
+```
+
+#### `error`
+
+Emitted when there's an error decoding an incoming message or a socket error.
+
+**Parameters:**
+- `error` (Error): The error object
+- `rinfo` (Object): Remote address information (for decode errors)
+
+```javascript
+server.on('error', (error, rinfo) => {
+  if (rinfo) {
+    console.error(`Error from ${rinfo.address}:${rinfo.port}: ${error.message}`);
+  } else {
+    console.error('Socket error:', error.message);
+  }
+});
+```
+
+### Client Events
+
+#### `error`
+
+Emitted when a socket error occurs.
+
+```javascript
+client.on('error', (error) => {
+  console.error('Client error:', error.message);
+});
+```
+
+## Error Handling
+
+Proper error handling is essential for robust OSC applications.
+
+### Client Errors
+
+#### Sending on Closed Socket
+
+If you try to send a message after closing the client, a `ReferenceError` will be thrown:
+
+```javascript
+const client = new Client('127.0.0.1', 3333);
+await client.close();
+
+try {
+  await client.send('/test', 123);
+} catch (err) {
+  console.error(err.message); // "Cannot send message on closed socket."
+  console.error(err.code);    // "ERR_SOCKET_DGRAM_NOT_RUNNING"
+}
+```
+
+**Prevention:** Always ensure the client is open before sending:
+
+```javascript
+const client = new Client('127.0.0.1', 3333);
+try {
+  await client.send('/test', 123);
+} finally {
+  await client.close(); // Close after sending
+}
+```
+
+#### Invalid Message Format
+
+Passing an invalid message format will throw a `TypeError`:
+
+```javascript
+try {
+  await client.send(12345); // Not a valid message format
+} catch (err) {
+  console.error(err.message); // "That Message Just Doesn't Seem Right"
+}
+```
+
+### Server Errors
+
+#### Decoding Errors
+
+When the server receives malformed OSC data, it emits an `'error'` event rather than throwing:
+
+```javascript
+server.on('error', (err, rinfo) => {
+  console.error(`Decode error from ${rinfo.address}: ${err.message}`);
+});
+```
+
+### Error Handling Patterns
+
+#### With Callbacks
+
+```javascript
+client.send('/test', 123, (err) => {
+  if (err) {
+    console.error('Send failed:', err);
+    return;
+  }
+  console.log('Message sent successfully');
+});
+```
+
+#### With Async/Await
+
+```javascript
+try {
+  await client.send('/test', 123);
+  console.log('Message sent successfully');
+} catch (err) {
+  console.error('Send failed:', err);
+}
+```
+
+#### Always Close Resources
+
+Use try/finally to ensure resources are cleaned up even if errors occur:
+
+```javascript
+const client = new Client('127.0.0.1', 3333);
+try {
+  await client.send('/test', 123);
+  await client.send('/test', 456);
+} catch (err) {
+  console.error('Error sending:', err);
+} finally {
+  await client.close(); // Always executes
+}
+```
+
+## Type System
+
+OSC supports several data types. node-osc automatically detects types for common JavaScript values:
+
+| JavaScript Type | OSC Type | Description |
+|----------------|----------|-------------|
+| Integer number | `integer` | Whole numbers (e.g., 42, -10, 0) |
+| Float number | `float` | Decimal numbers (e.g., 3.14, -0.5) |
+| String | `string` | Text values (e.g., "hello") |
+| Boolean | `boolean` | true or false |
+| Buffer | `blob` | Binary data |
+| MIDI object/Buffer | `midi` | MIDI messages (4 bytes: port, status, data1, data2) |
+
+### Automatic Type Detection
+
+```javascript
+const msg = new Message('/test');
+msg.append(42);      // → integer
+msg.append(3.14);    // → float
+msg.append('hello'); // → string
+msg.append(true);    // → boolean
+```
+
+### Explicit Type Control
+
+For advanced use cases, you can explicitly specify types:
+
+```javascript
+const msg = new Message('/test');
+
+// Force a whole number to be sent as float
+msg.append({ type: 'float', value: 42 });
+
+// Use shorthand type notation
+msg.append({ type: 'f', value: 42 });  // 'f' = float
+msg.append({ type: 'i', value: 3.14 }); // 'i' = integer (truncates)
+msg.append({ type: 's', value: 'text' }); // 's' = string
+msg.append({ type: 'b', value: Buffer.from('data') }); // 'b' = blob
+msg.append({ type: 'm', value: { port: 0, status: 144, data1: 60, data2: 127 } }); // 'm' = MIDI
+```
+
+### Supported Type Tags
+
+- `'i'` or `'integer'` - 32-bit integer
+- `'f'` or `'float'` - 32-bit float
+- `'s'` or `'string'` - OSC string
+- `'b'` or `'blob'` - Binary blob
+- `'m'` or `'midi'` - MIDI message (4 bytes)
+- `'boolean'` - Boolean value (true/false)
+- `'T'` - True
+- `'F'` - False
+
+## Best Practices
+
+### 1. Use Async/Await for Cleaner Code
+
+Prefer async/await over callbacks for more readable code:
+
+```javascript
+// ✅ Good - Clean and readable
+async function sendMessages() {
+  const client = new Client('127.0.0.1', 3333);
+  try {
+    await client.send('/test', 1);
+    await client.send('/test', 2);
+    await client.send('/test', 3);
+  } finally {
+    await client.close();
+  }
+}
+
+// ❌ Less ideal - Callback pyramid
+function sendMessages() {
+  const client = new Client('127.0.0.1', 3333);
+  client.send('/test', 1, (err) => {
+    if (err) return console.error(err);
+    client.send('/test', 2, (err) => {
+      if (err) return console.error(err);
+      client.send('/test', 3, (err) => {
+        if (err) return console.error(err);
+        client.close();
+      });
+    });
+  });
+}
+```
+
+### 2. Always Close Resources
+
+Always close clients and servers when done to prevent resource leaks:
+
+```javascript
+const client = new Client('127.0.0.1', 3333);
+try {
+  await client.send('/test', 123);
+} finally {
+  await client.close(); // Always close
+}
+```
+
+### 3. Use Address-Specific Event Listeners
+
+For better code organization, use address-specific event listeners:
+
+```javascript
+// ✅ Good - Clear and organized
+server.on('/note', (msg) => {
+  handleNote(msg);
+});
+
+server.on('/control', (msg) => {
+  handleControl(msg);
+});
+
+// ❌ Less ideal - Manual routing
+server.on('message', (msg) => {
+  const [address] = msg;
+  if (address === '/note') handleNote(msg);
+  else if (address === '/control') handleControl(msg);
+});
+```
+
+### 4. Handle Errors Gracefully
+
+Always implement error handling for both clients and servers:
+
+```javascript
+// Client
+try {
+  await client.send('/test', 123);
+} catch (err) {
+  console.error('Failed to send:', err.message);
+}
+
+// Server
+server.on('error', (err, rinfo) => {
+  console.error(`Server error from ${rinfo?.address}:`, err.message);
+});
+```
+
+### 5. Use Bundles for Related Messages
+
+When sending multiple related messages, use bundles for atomic operations:
+
+```javascript
+// ✅ Good - Atomic operation
+const bundle = new Bundle(
+  ['/synth/freq', 440],
+  ['/synth/amp', 0.5],
+  ['/synth/gate', 1]
+);
+await client.send(bundle);
+
+// ❌ Less ideal - Separate messages (not atomic)
+await client.send('/synth/freq', 440);
+await client.send('/synth/amp', 0.5);
+await client.send('/synth/gate', 1);
+```
+
+### 6. Listen on All Interfaces for Network Access
+
+If you need to receive messages from other machines:
+
+```javascript
+// Listen on all interfaces (accessible from network)
+const server = new Server(3333, '0.0.0.0');
+
+// Only localhost (default, more secure)
+const server = new Server(3333, '127.0.0.1');
+```
+
+### 7. Use Descriptive OSC Addresses
+
+Follow OSC naming conventions with hierarchical addresses:
+
+```javascript
+// ✅ Good - Hierarchical and descriptive
+await client.send('/synth/oscillator/1/frequency', 440);
+await client.send('/mixer/channel/3/volume', 0.8);
+
+// ❌ Less ideal - Flat and unclear
+await client.send('/freq1', 440);
+await client.send('/vol3', 0.8);
+```
+
+### 8. Validate Input Data
+
+Validate data before sending to avoid runtime errors:
+
+```javascript
+function sendNote(pitch, velocity) {
+  if (typeof pitch !== 'number' || pitch < 0 || pitch > 127) {
+    throw new Error('Invalid pitch: must be 0-127');
+  }
+  if (typeof velocity !== 'number' || velocity < 0 || velocity > 127) {
+    throw new Error('Invalid velocity: must be 0-127');
+  }
+  return client.send('/note', pitch, velocity);
+}
+```
+
+### 9. Wait for Server Ready
+
+Always wait for the server to be listening 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 once(server, 'listening');
+
+// Now safe to send messages
+console.log('Server ready!');
+```
+
+### 10. Use Parallel Sends When Appropriate
+
+When sending multiple independent messages, use `Promise.all` for better performance:
+
+```javascript
+// Send multiple messages in parallel
+await Promise.all([
+  client.send('/track/1/volume', 0.8),
+  client.send('/track/2/volume', 0.6),
+  client.send('/track/3/volume', 0.9)
+]);
+```
+
+## Troubleshooting
+
+### Messages Not Being Received
+
+**Possible causes and solutions:**
+
+1. **Firewall blocking UDP traffic**
+   - Check your firewall settings
+   - Ensure the UDP port is open
+   - Try with localhost first (`127.0.0.1`)
+
+2. **Wrong host binding**
+   - Server: Use `'0.0.0.0'` to listen on all interfaces
+   - Server: Use `'127.0.0.1'` for localhost only
+   - Client: Match the server's IP address
+
+3. **Port mismatch**
+   - Ensure client and server use the same port number
+   - Check if another process is using the port
+
+4. **Network connectivity**
+   - Test with localhost first (`127.0.0.1`)
+   - Verify network connectivity between machines
+   - Check if devices are on the same network
+
+### "Cannot send message on closed socket"
+
+This error occurs when trying to send after closing the client:
+
+```javascript
+// ❌ Wrong - Sending after close
+await client.close();
+await client.send('/test', 123); // Error!
+
+// ✅ Correct - Send before close
+await client.send('/test', 123);
+await client.close();
+```
+
+### Server Not Listening
+
+Ensure you wait for the server to start before sending messages:
+
+```javascript
+const server = new Server(3333, '0.0.0.0');
+
+// Wait for server to be ready
+await new Promise(resolve => server.on('listening', resolve));
+
+// Now safe to send messages
+console.log('Server ready!');
+```
+
+### Messages Lost or Dropped
+
+UDP is unreliable by design and messages can be lost:
+
+**Solutions:**
+1. Use TCP-based OSC if reliability is critical (requires custom implementation)
+2. Implement acknowledgment messages
+3. Add retry logic for critical messages
+4. Use bundles to ensure related messages arrive together
+
+### High CPU Usage
+
+If you're seeing high CPU usage:
+
+1. **Check for infinite loops** in event handlers
+2. **Rate limit** message sending if sending many messages
+3. **Use bundles** instead of many individual messages
+4. **Close unused connections** to free resources
+
+### Memory Leaks
+
+To prevent memory leaks:
+
+1. **Always close** clients and servers when done
+2. **Remove event listeners** when no longer needed
+3. **Avoid** creating new clients/servers in loops
+4. **Reuse** client/server instances when possible
+
+```javascript
+// ✅ Good - Proper cleanup
+const server = new Server(3333);
+const handler = (msg) => console.log(msg);
+server.on('message', handler);
+
+// Later, clean up
+server.removeListener('message', handler);
+await server.close();
+```
+
+## Advanced Topics
+
+### Custom Transports
+
+The `encode` and `decode` functions allow you to use OSC over custom transports:
+
+```javascript
+import { encode, decode, Message } from 'node-osc';
+import WebSocket from 'ws';
+
+// WebSocket server
+const wss = new WebSocket.Server({ port: 8080 });
+wss.on('connection', (ws) => {
+  ws.on('message', (data) => {
+    const oscMsg = decode(data);
+    console.log('Received:', oscMsg);
+  });
+});
+
+// WebSocket client
+const ws = new WebSocket('ws://localhost:8080');
+const message = new Message('/test', 123);
+ws.send(encode(message));
+```
+
+### Timetags in Bundles
+
+OSC bundles support timetags for scheduling:
+
+```javascript
+// Immediate execution (timetag = 0)
+const bundle = new Bundle(['/test', 1], ['/test', 2]);
+
+// Scheduled execution (timetag in OSC time)
+const futureTime = Date.now() / 1000 + 5; // 5 seconds from now
+const scheduledBundle = new Bundle(futureTime, ['/test', 1]);
+```
+
+**Note:** The server receives the timetag but does not automatically schedule execution. You must implement scheduling logic if needed.
+
+### Performance Optimization
+
+For high-throughput applications:
+
+1. **Reuse client instances** instead of creating new ones
+2. **Use bundles** to send multiple messages together
+3. **Batch messages** and send periodically rather than immediately
+4. **Use binary blobs** for large data instead of many arguments
+5. **Profile your code** to identify bottlenecks
+
+```javascript
+// ✅ Good - Reuse client
+const client = new Client('127.0.0.1', 3333);
+for (let i = 0; i < 1000; i++) {
+  await client.send('/test', i);
+}
+await client.close();
+
+// ❌ Bad - Creating many clients
+for (let i = 0; i < 1000; i++) {
+  const client = new Client('127.0.0.1', 3333);
+  await client.send('/test', i);
+  await client.close();
+}
+```
+
+## Further Reading
+
+- [API Documentation](./API.md) - Complete API reference
+- [OSC Specification](http://opensoundcontrol.org/spec-1_0) - Official OSC 1.0 specification
+- [Examples](../examples/) - Working code examples
+- [Main README](../README.md) - Quick start guide

package/examples/README.md

@@ -0,0 +1,119 @@
+# node-osc Examples
+
+This directory contains working examples demonstrating various ways to use the node-osc library.
+
+## Running the Examples
+
+All examples can be run directly with Node.js. Some examples require a server and client running simultaneously.
+
+### Server/Client Examples
+
+Run the server in one terminal:
+```bash
+node examples/server.js
+```
+
+Run the client in another terminal:
+```bash
+node examples/client.js
+```
+
+### Standalone Examples
+
+These examples run both client and server in the same process:
+
+```bash
+# Callback-based example
+node examples/esm.mjs
+
+# Async/await example (recommended)
+node examples/async-await.mjs
+
+# Bundle example
+node examples/bundle-example.mjs
+
+# Error handling example
+node examples/error-handling.mjs
+```
+
+## Example Files
+
+### [server.js](./server.js)
+**CommonJS Server Example**
+
+Demonstrates:
+- Creating an OSC server with CommonJS
+- Listening for messages
+- Displaying remote client information
+- Closing the server after receiving a message
+
+### [client.js](./client.js)
+**CommonJS Client Example**
+
+Demonstrates:
+- Creating an OSC client with CommonJS
+- Building messages with the Message class
+- Sending messages with callbacks
+
+### [esm.mjs](./esm.mjs)
+**ESM with Callbacks Example**
+
+Demonstrates:
+- Using node-osc with ES modules
+- Callback-based API
+- Server event listeners
+- Client sending with callbacks
+
+### [async-await.mjs](./async-await.mjs)
+**ESM with Async/Await Example** (Recommended Pattern)
+
+Demonstrates:
+- Modern async/await patterns
+- Using `node:events.once()` to wait for server ready
+- Sending multiple messages in parallel with `Promise.all()`
+- Clean shutdown of both client and server
+- Complete end-to-end workflow
+
+Expected output:
+```
+OSC server listening on port 3333
+Sent /hello
+Sent counters
+Received: /hello [ 'world' ]
+Received: /counter [ 1 ]
+Received: /counter [ 2 ]
+Received: /counter [ 3 ]
+Client and server closed
+```
+
+### [bundle-example.mjs](./bundle-example.mjs)
+**OSC Bundles Example**
+
+Demonstrates:
+- Creating OSC bundles with multiple messages
+- Sending bundles atomically
+- Receiving and processing bundles
+- Using timetags
+
+### [error-handling.mjs](./error-handling.mjs)
+**Error Handling Example**
+
+Demonstrates:
+- Proper error handling with try/catch
+- Server error events
+- Resource cleanup with finally blocks
+- Handling closed socket errors
+
+## Tips
+
+1. **Always close resources**: Use try/finally or ensure you call `.close()` on clients and servers
+2. **Wait for server ready**: Use the 'listening' event before sending messages
+3. **Use async/await**: The async/await pattern is cleaner than callbacks for most use cases
+4. **Handle errors**: Always implement error handling in production code
+5. **Test locally first**: Start with `127.0.0.1` before trying network communication
+
+## Further Reading
+
+- [Main README](../README.md) - Quick start guide
+- [API Documentation](../docs/API.md) - Complete API reference
+- [OSC Specification](http://opensoundcontrol.org/spec-1_0) - Learn about the OSC protocol