node-osc 11.1.0 → 11.2.0

package/examples/async-await.mjs

@@ -0,0 +1,57 @@
+/**
+ * OSC Client and Server Example (ESM with Async/Await)
+ * 
+ * This is the recommended pattern for modern Node.js applications.
+ * It demonstrates:
+ * - Using async/await for cleaner async code
+ * - Properly waiting for server to be ready
+ * - Sending multiple messages in parallel
+ * - Clean shutdown of resources
+ * 
+ * To run this example:
+ * node examples/async-await.mjs
+ */
+
+// Example: Using async/await with node-osc Client and Server (ESM)
+import { once } from "node:events";
+import { setImmediate } from "node:timers/promises";
+import { Client, Server } from "node-osc";
+
+// Create server on all interfaces, port 3333
+const server = new Server(3333, "0.0.0.0");
+
+// Wait for server to be ready using once() - cleaner than event listeners
+await once(server, "listening");
+
+console.log("OSC server listening on port 3333");
+
+// Set up message handler
+// Messages arrive as arrays: [address, ...arguments]
+server.on("message", (msg) => {
+  const [address, ...args] = msg;
+  console.log("Received:", address, args);
+});
+
+// Create client pointing to localhost
+const client = new Client("127.0.0.1", 3333);
+
+// Send a simple message
+await client.send("/hello", "world");
+console.log("Sent /hello");
+
+// Send multiple messages in parallel using Promise.all()
+await Promise.all([
+  client.send("/counter", 1),
+  client.send("/counter", 2),
+  client.send("/counter", 3),
+]);
+console.log("Sent counters");
+
+// Allow socket I/O to be processed before shutting down
+await setImmediate();
+
+// Clean shutdown - always close resources
+await client.close();
+await server.close();
+
+console.log("Client and server closed");

package/examples/bundle-example.mjs

@@ -0,0 +1,92 @@
+/**
+ * OSC Bundle Example
+ * 
+ * This example demonstrates how to create and send OSC bundles.
+ * Bundles allow you to group multiple messages together, optionally
+ * with a timetag for synchronized processing.
+ * 
+ * To run this example:
+ * node examples/bundle-example.mjs
+ */
+
+import { once } from "node:events";
+import { setImmediate } from "node:timers/promises";
+import { Bundle, Client, Message, Server } from "node-osc";
+
+// Start server
+const server = new Server(3333, "0.0.0.0");
+await once(server, "listening");
+console.log("Server listening on port 3333\n");
+
+// Handle bundles specifically
+server.on("bundle", (bundle, rinfo) => {
+  console.log(`📦 Received bundle from ${rinfo.address}:${rinfo.port}`);
+  console.log(`   Timetag: ${bundle.timetag}`);
+  console.log(`   Elements: ${bundle.elements.length}`);
+  
+  // Process each element in the bundle
+  bundle.elements.forEach((element, i) => {
+    if (element.oscType === 'message') {
+      const [address, ...args] = element;
+      console.log(`   ${i + 1}. ${address}: ${args.join(', ')}`);
+    } else if (element.oscType === 'bundle') {
+      console.log(`   ${i + 1}. [Nested Bundle]`);
+    }
+  });
+  console.log();
+});
+
+// Create client
+const client = new Client("127.0.0.1", 3333);
+
+// Example 1: Bundle without timetag (array notation)
+console.log("Sending bundle without timetag...");
+const bundle1 = new Bundle(
+  ["/synth/freq", 440],
+  ["/synth/amp", 0.5],
+  ["/synth/gate", 1]
+);
+await client.send(bundle1);
+await setImmediate();
+
+// Example 2: Bundle with timetag
+console.log("Sending bundle with timetag...");
+const bundle2 = new Bundle(
+  10,  // timetag
+  ["/oscillator/1/freq", 220],
+  ["/oscillator/2/freq", 330]
+);
+await client.send(bundle2);
+await setImmediate();
+
+// Example 3: Bundle with Message objects
+console.log("Sending bundle with Message objects...");
+const msg1 = new Message("/note", 60, 127);
+const msg2 = new Message("/note", 64, 127);
+const msg3 = new Message("/note", 67, 127);
+const bundle3 = new Bundle(msg1, msg2, msg3);
+await client.send(bundle3);
+await setImmediate();
+
+// Example 4: Nested bundles
+console.log("Sending nested bundles...");
+const innerBundle = new Bundle(["/inner/message", 123]);
+const outerBundle = new Bundle(["/outer/message", 456]);
+outerBundle.append(innerBundle);
+await client.send(outerBundle);
+await setImmediate();
+
+// Example 5: Building a bundle incrementally
+console.log("Sending incrementally built bundle...");
+// Create bundle with initial element, then append more
+const bundle5 = new Bundle(["/initial", 0]);
+bundle5.append(["/control/1", 10]);
+bundle5.append(["/control/2", 20]);
+bundle5.append(["/control/3", 30]);
+await client.send(bundle5);
+await setImmediate();
+
+// Clean shutdown
+await client.close();
+await server.close();
+console.log("Done!");

package/examples/client.js

@@ -1,23 +1,40 @@
+/**
+ * OSC Client Example (CommonJS)
+ * 
+ * This example demonstrates how to create an OSC client and send messages
+ * using the Message class with callbacks.
+ * 
+ * To run this example:
+ * 1. Start the server: node examples/server.js
+ * 2. Run this client: node examples/client.js
+ */
+
 'use strict';
 const { Client, Message } = require('node-osc');
 
+// Create a client connected to localhost on port 3333
 const client = new Client('127.0.0.1', 3333);
 
+// Create a message using the Message class
 const message = new Message('/address');
-message.append('testing');
-message.append('testing');
-message.append(123);
+message.append('testing');  // Append a string
+message.append('testing');  // Append the same string again (for demonstration)
+message.append(123);        // Append an integer
 
+// Send the message with a callback
 client.send(message, (err) => {
   if (err) {
     console.error(new Error(err));
   }
+  // Always close the client when done
   client.close();
 });
 
-// or
+// Alternative ways to send messages:
+
+// Method 1: Send address and arguments directly
 // client.send('/address', 'testing', 'testing', 123);
 
-// or
+// Method 2: Create message with constructor arguments
 // const msg = new Message('/address', 1, 2, 3);
 // client.send(msg);

package/examples/error-handling.mjs

@@ -0,0 +1,152 @@
+/**
+ * OSC Error Handling Example
+ * 
+ * This example demonstrates proper error handling patterns with node-osc,
+ * including handling server errors, client errors, and ensuring cleanup.
+ * 
+ * To run this example:
+ * node examples/error-handling.mjs
+ */
+
+import { once } from "node:events";
+import { Client, Server } from "node-osc";
+
+console.log("=== OSC Error Handling Examples ===\n");
+
+// Example 1: Server decode errors
+console.log("1. Testing server decode error handling...");
+const server = new Server(3333, "0.0.0.0");
+
+// Set up error handler for server
+server.on("error", (err, rinfo) => {
+  console.error(`❌ Server error from ${rinfo.address}:${rinfo.port}`);
+  console.error(`   ${err.message}`);
+});
+
+await once(server, "listening");
+console.log("✅ Server started successfully\n");
+
+// Example 2: Try/catch with async/await
+console.log("2. Testing client send with try/catch...");
+const client = new Client("127.0.0.1", 3333);
+
+try {
+  await client.send("/test", 123, "hello", true);
+  console.log("✅ Message sent successfully\n");
+} catch (err) {
+  console.error(`❌ Failed to send message: ${err.message}\n`);
+}
+
+// Example 3: Error when sending on closed socket
+console.log("3. Testing send on closed socket...");
+await client.close();
+console.log("   Client closed");
+
+try {
+  await client.send("/test", 456);
+  console.log("✅ Message sent (this shouldn't happen)\n");
+} catch (err) {
+  console.log(`✅ Caught expected error: ${err.message}`);
+  console.log(`   Error code: ${err.code}\n`);
+}
+
+// Example 4: Try/finally for cleanup
+console.log("4. Testing try/finally for guaranteed cleanup...");
+const client2 = new Client("127.0.0.1", 3333);
+
+try {
+  await client2.send("/cleanup/test", 789);
+  console.log("✅ Message sent");
+  
+  // Simulate an error
+  throw new Error("Simulated error");
+} catch (err) {
+  console.log(`⚠️  Caught error: ${err.message}`);
+} finally {
+  // This always runs, even if there was an error
+  await client2.close();
+  console.log("✅ Client closed in finally block\n");
+}
+
+// Example 5: Callback-based error handling
+console.log("5. Testing callback-based error handling...");
+const client3 = new Client("127.0.0.1", 3333);
+
+await new Promise((resolve) => {
+  client3.send("/callback/test", 999, (err) => {
+    if (err) {
+      console.error(`❌ Send error: ${err}`);
+    } else {
+      console.log("✅ Message sent via callback");
+    }
+    
+    client3.close((err) => {
+      if (err) {
+        console.error(`❌ Close error: ${err}`);
+      } else {
+        console.log("✅ Client closed via callback\n");
+      }
+      resolve();
+    });
+  });
+});
+
+// Example 6: Multiple operations with proper error handling
+console.log("6. Testing multiple operations with error handling...");
+const client4 = new Client("127.0.0.1", 3333);
+
+try {
+  // Send multiple messages
+  const results = await Promise.allSettled([
+    client4.send("/multi/1", 1),
+    client4.send("/multi/2", 2),
+    client4.send("/multi/3", 3),
+  ]);
+  
+  // Check results
+  results.forEach((result, i) => {
+    if (result.status === "fulfilled") {
+      console.log(`✅ Message ${i + 1} sent successfully`);
+    } else {
+      console.error(`❌ Message ${i + 1} failed: ${result.reason}`);
+    }
+  });
+} catch (err) {
+  console.error(`❌ Unexpected error: ${err.message}`);
+} finally {
+  await client4.close();
+  console.log("✅ Client closed\n");
+}
+
+// Example 7: Server error event
+console.log("7. Testing server message handling with error check...");
+let messageReceived = false;
+
+server.on("message", (msg) => {
+  messageReceived = true;
+  const [address, ...args] = msg;
+  console.log(`✅ Received: ${address} with args: ${args.join(", ")}`);
+});
+
+const client5 = new Client("127.0.0.1", 3333);
+await client5.send("/final/test", "done");
+await client5.close();
+
+// Wait a bit for message to be received
+await new Promise(resolve => setTimeout(resolve, 100));
+
+if (!messageReceived) {
+  console.log("⚠️  Warning: Message was not received");
+}
+
+// Clean shutdown
+await server.close();
+console.log("\n✅ All tests complete, server closed");
+
+console.log("\n=== Key Takeaways ===");
+console.log("1. Always use try/catch with async/await");
+console.log("2. Use try/finally to ensure cleanup");
+console.log("3. Listen for 'error' events on servers");
+console.log("4. Check for errors in callbacks");
+console.log("5. Don't send on closed sockets");
+console.log("6. Use Promise.allSettled for multiple operations");

package/examples/esm.mjs

@@ -1,18 +1,39 @@
+/**
+ * OSC Client and Server Example (ESM with Callbacks)
+ * 
+ * This example demonstrates using node-osc with ES modules and callback-based API.
+ * It shows how to create both a client and server, send messages, and handle events.
+ * 
+ * To run this example:
+ * node examples/esm.mjs
+ */
+
 import { Client, Server } from 'node-osc';
 
+// Create a client connected to localhost on port 3333
 const client = new Client('127.0.0.1', 3333);
+
+// Create a server listening on port 3333, bound to all interfaces
 var server = new Server(3333, '0.0.0.0');
 
+// Listen for when the server is ready
 server.on('listening', () => {
   console.log('OSC Server is Listening');
 });
 
+// Listen for incoming messages
 server.on('message', (msg, rinfo) => {
+  // msg is an array: [address, ...arguments]
   console.log(`Message: ${msg}\nReceived from: ${rinfo.address}:${rinfo.port}`);
+  
+  // Close the server after receiving a message
   server.close();
 });
 
+// Send a message with callback-based API
 client.send('/hello', 'world', (err) => {
   if (err) console.error(err);
+  
+  // Close the client after sending
   client.close();
 });

package/examples/server.js

@@ -1,9 +1,25 @@
+/**
+ * OSC Server Example (CommonJS)
+ * 
+ * This example demonstrates how to create an OSC server that listens for
+ * incoming messages and displays them along with sender information.
+ * 
+ * To run this example:
+ * 1. Start this server: node examples/server.js
+ * 2. Send messages from client: node examples/client.js
+ */
+
 'use strict';
 var { Server } = require('node-osc');
 
+// Create a server listening on port 3333, bound to all interfaces
 var oscServer = new Server(3333, '0.0.0.0');
 
+// Listen for incoming OSC messages
 oscServer.on('message', function (msg, rinfo) {
+  // msg is an array: [address, ...arguments]
   console.log(`Message: ${msg}\nReceived from: ${rinfo.address}:${rinfo.port}`);
+  
+  // Close the server after receiving one message (for demo purposes)
   oscServer.close();
 });

package/jsdoc.json

@@ -0,0 +1,16 @@
+{
+  "source": {
+    "include": [
+      "lib/Server.mjs",
+      "lib/Client.mjs",
+      "lib/Bundle.mjs",
+      "lib/Message.mjs",
+      "lib/osc.mjs"
+    ],
+    "includePattern": ".+\\.mjs$"
+  },
+  "opts": {
+    "encoding": "utf8",
+    "recurse": false
+  }
+}

package/lib/Bundle.mjs

@@ -1,11 +1,60 @@
 import Message from './Message.mjs';
 
+/**
+ * Convert array notation to Message object.
+ * @private
+ * @param {Array|Message|Bundle} element - The element to sanitize.
+ * @returns {Message|Bundle} The sanitized element.
+ */
 function sanitize(element) {
   if (element instanceof Array) element = new Message(element[0], ...element.slice(1));
   return element;
 }
 
+/**
+ * Represents an OSC bundle containing multiple messages or nested bundles.
+ * 
+ * OSC bundles allow multiple messages to be sent together, optionally with
+ * a timetag indicating when the bundle should be processed.
+ * 
+ * @class
+ * 
+ * @example
+ * // Create a bundle without a timetag
+ * const bundle = new Bundle(['/one', 1], ['/two', 2]);
+ * 
+ * @example
+ * // Create a bundle with a timetag
+ * const bundle = new Bundle(10, ['/one', 1], ['/two', 2]);
+ * 
+ * @example
+ * // Nest bundles
+ * const bundle1 = new Bundle(['/one', 1]);
+ * const bundle2 = new Bundle(['/two', 2]);
+ * bundle1.append(bundle2);
+ */
 class Bundle {
+  /**
+   * Create an OSC Bundle.
+   * 
+   * @param {number|Message|Bundle|Array} [timetagOrElement=0] - Timetag, or if not a number, the first element and timetag will default to 0.
+   * @param {...(Message|Bundle|Array)} elements - Messages or bundles to include.
+   *   Arrays will be automatically converted to Message objects.
+   * 
+   * @example
+   * // Bundle without timetag
+   * const bundle = new Bundle(['/test', 1], ['/test2', 2]);
+   * 
+   * @example
+   * // Bundle with timetag of 10
+   * const bundle = new Bundle(10, ['/test', 1]);
+   * 
+   * @example
+   * // Bundle with Message objects
+   * const msg1 = new Message('/one', 1);
+   * const msg2 = new Message('/two', 2);
+   * const bundle = new Bundle(msg1, msg2);
+   */
   constructor(timetag, ...elements) {
     if (!(typeof timetag === 'number')) {
       elements.unshift(timetag);
@@ -16,6 +65,23 @@ class Bundle {
     this.elements = elements.map(sanitize);
   }
 
+  /**
+   * Append a message or bundle to this bundle.
+   * 
+   * @param {Message|Bundle|Array} element - The message or bundle to append.
+   *   Arrays will be automatically converted to Message objects.
+   * 
+   * @example
+   * const bundle = new Bundle();
+   * bundle.append(['/test', 1]);
+   * bundle.append(new Message('/test2', 2));
+   * 
+   * @example
+   * // Append a nested bundle
+   * const bundle1 = new Bundle(['/one', 1]);
+   * const bundle2 = new Bundle(['/two', 2]);
+   * bundle1.append(bundle2);
+   */
   append(element) {
     this.elements.push(sanitize(element));
   }