Initial commit of my folder

backend/node_modules/node-osc/examples/README.md

@@ -0,0 +1,121 @@
+# 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
+- [Documentation Hub](../docs/) - Complete documentation with navigation guide
+- [API Reference](../docs/API.md) - Complete API reference
+- [Usage Guide](../docs/GUIDE.md) - Best practices and troubleshooting
+- [OSC Specification](http://opensoundcontrol.org/spec-1_0) - Learn about the OSC protocol

backend/node_modules/node-osc/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");

backend/node_modules/node-osc/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!");

backend/node_modules/node-osc/examples/client.js

@@ -0,0 +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');  // 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();
+});
+
+// Alternative ways to send messages:
+
+// Method 1: Send address and arguments directly
+// client.send('/address', 'testing', 'testing', 123);
+
+// Method 2: Create message with constructor arguments
+// const msg = new Message('/address', 1, 2, 3);
+// client.send(msg);

backend/node_modules/node-osc/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");

backend/node_modules/node-osc/examples/esm.mjs

@@ -0,0 +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();
+});

backend/node_modules/node-osc/examples/server.js

@@ -0,0 +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();
+});