node-osc 11.1.0 → 11.2.0

package/test/test-promises.mjs

@@ -0,0 +1,249 @@
+import { once } from 'node:events';
+import { beforeEach, test } from 'tap';
+import { bootstrap } from './util.mjs';
+
+import { Server, Client } from 'node-osc';
+
+beforeEach(bootstrap);
+
+test('client: send with promise - array', async (t) => {
+  const oscServer = new Server(t.context.port, '127.0.0.1');
+  const client = new Client('127.0.0.1', t.context.port);
+
+  t.plan(1);
+
+  oscServer.on('message', (msg) => {
+    oscServer.close();
+    t.same(msg, ['/test', 0, 1, 'testing', true], 'We should receive expected payload');
+  });
+
+  await client.send(['/test', 0, 1, 'testing', true]);
+  await client.close();
+});
+
+test('client: send with promise - string', async (t) => {
+  const oscServer = new Server(t.context.port, '127.0.0.1');
+  const client = new Client('127.0.0.1', t.context.port);
+
+  t.plan(1);
+
+  oscServer.on('message', (msg) => {
+    oscServer.close();
+    t.same(msg, ['/test'], 'We should receive expected payload');
+  });
+
+  await client.send('/test');
+  await client.close();
+});
+
+test('client: send with promise - message object', async (t) => {
+  const oscServer = new Server(t.context.port, '127.0.0.1');
+  const client = new Client('127.0.0.1', t.context.port);
+
+  t.plan(1);
+
+  oscServer.on('message', (msg) => {
+    oscServer.close();
+    t.same(msg, ['/test', 1, 2, 3, 'lol', false], 'we received the payload');
+  });
+
+  await client.send({
+    address: '/test',
+    args: [1, 2, 3, 'lol', false]
+  });
+  await client.close();
+});
+
+test('client: send with promise - multiple args', async (t) => {
+  const oscServer = new Server(t.context.port, '127.0.0.1');
+  const client = new Client('127.0.0.1', t.context.port);
+
+  t.plan(1);
+
+  oscServer.on('message', (msg) => {
+    oscServer.close();
+    t.same(msg, ['/test', 1, 2, 'testing'], 'We should receive expected payload');
+  });
+
+  await client.send('/test', 1, 2, 'testing');
+  await client.close();
+});
+
+test('client: send promise rejection on closed socket', async (t) => {
+  const client = new Client('127.0.0.1', t.context.port);
+
+  t.plan(1);
+
+  await client.close();
+  
+  try {
+    await client.send('/boom');
+    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('client: async/await usage', async (t) => {
+  const oscServer = new Server(t.context.port, '127.0.0.1');
+  const client = new Client('127.0.0.1', t.context.port);
+
+  t.plan(1);
+
+  const messagePromise = once(oscServer, 'message');
+
+  await client.send('/async-test', 42, 'hello');
+  const [receivedMessage] = await messagePromise;
+  
+  t.same(receivedMessage, ['/async-test', 42, 'hello'], 'Message received via async/await');
+
+  await client.close();
+  await oscServer.close();
+});
+
+test('server: close with promise', async (t) => {
+  const oscServer = new Server(t.context.port, '127.0.0.1');
+  
+  t.plan(1);
+
+  await once(oscServer, 'listening');
+
+  await oscServer.close();
+  t.pass('Server closed successfully with promise');
+});
+
+test('server: no callback still emits listening event', async (t) => {
+  const oscServer = new Server(t.context.port, '127.0.0.1');
+  
+  t.plan(1);
+
+  await once(oscServer, 'listening');
+  t.pass('listening event emitted');
+
+  await oscServer.close();
+});
+
+test('client and server: full async/await workflow', async (t) => {
+  const oscServer = new Server(t.context.port, '127.0.0.1');
+  const client = new Client('127.0.0.1', t.context.port);
+
+  t.plan(2);
+
+  // Wait for server to be ready
+  await once(oscServer, 'listening');
+  t.pass('Server started');
+
+  // Set up message handler
+  const messageReceived = once(oscServer, 'message');
+
+  // Send message and wait for it to be received
+  await client.send('/workflow', 'test', 123);
+  const [msg] = await messageReceived;
+  t.same(msg, ['/workflow', 'test', 123], 'Message received correctly');
+
+  // Clean up
+  await client.close();
+  await oscServer.close();
+});
+
+test('client: multiple sends with promises', async (t) => {
+  const oscServer = new Server(t.context.port, '127.0.0.1');
+  const client = new Client('127.0.0.1', t.context.port);
+
+  t.plan(3);
+
+  const messages = [];
+  oscServer.on('message', (msg) => {
+    messages.push(msg);
+  });
+
+  await client.send('/msg1', 1);
+  await client.send('/msg2', 2);
+  await client.send('/msg3', 3);
+
+  // Give a little time for all messages to be received
+  await new Promise((resolve) => setTimeout(resolve, 100));
+
+  t.equal(messages.length, 3, 'Received all three messages');
+  t.same(messages[0], ['/msg1', 1], 'First message correct');
+  t.same(messages[2], ['/msg3', 3], 'Last message correct');
+
+  await client.close();
+  await oscServer.close();
+});
+
+test('client: close promise rejection on error', async (t) => {
+  const client = new Client('127.0.0.1', t.context.port);
+
+  t.plan(1);
+
+  // Mock the socket's close method to simulate an error
+  const originalClose = client._sock.close.bind(client._sock);
+  
+  // Set up teardown to ensure socket is properly closed
+  t.teardown(() => {
+    // Restore original close method first
+    client._sock.close = originalClose;
+    // Then close the socket
+    try {
+      client._sock.close(() => {});
+    } catch {
+      // Socket might already be closed, that's ok
+    }
+  });
+  
+  client._sock.close = function(cb) {
+    // Simulate an error being passed to callback
+    if (cb) {
+      const err = new Error('Mock close error');
+      err.code = 'MOCK_ERROR';
+      setImmediate(() => cb(err));
+    }
+  };
+
+  try {
+    await client.close();
+    t.fail('Should have thrown an error');
+  } catch (err) {
+    t.equal(err.code, 'MOCK_ERROR', 'Should reject with mock error');
+  }
+});
+
+test('server: close promise rejection on error', async (t) => {
+  const oscServer = new Server(t.context.port, '127.0.0.1');
+
+  t.plan(1);
+
+  await once(oscServer, 'listening');
+
+  // Mock the socket's close method to simulate an error
+  const originalClose = oscServer._sock.close.bind(oscServer._sock);
+  
+  // Set up teardown to ensure socket is properly closed
+  t.teardown(() => {
+    // Restore original close method first
+    oscServer._sock.close = originalClose;
+    // Then close the socket
+    try {
+      oscServer._sock.close(() => {});
+    } catch {
+      // Socket might already be closed, that's ok
+    }
+  });
+  
+  oscServer._sock.close = function(cb) {
+    // Simulate an error being passed to callback
+    if (cb) {
+      const err = new Error('Mock close error');
+      err.code = 'MOCK_ERROR';
+      setImmediate(() => cb(err));
+    }
+  };
+
+  try {
+    await oscServer.close();
+    t.fail('Should have thrown an error');
+  } catch (err) {
+    t.equal(err.code, 'MOCK_ERROR', 'Should reject with mock error');
+  }
+});

package/test/test-types.mjs

@@ -0,0 +1,39 @@
+import { test } from 'tap';
+import { execSync } from 'node:child_process';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+// Only run in ESM mode (not when transpiled to CJS in dist/)
+// Normalize path separators for cross-platform compatibility
+const normalizedPath = __dirname.replace(/\\/g, '/');
+const isESM = !normalizedPath.includes('/dist/');
+
+test('types: TypeScript compilation', (t) => {
+  let tsconfigPath;
+  const testRoot = resolve(__dirname, isESM ? '.': '../../test');
+  if (isESM) {
+    tsconfigPath = join(testRoot, 'fixtures', 'types', 'tsconfig-esm.test.json');
+  }
+  else {
+    tsconfigPath = join(testRoot, 'fixtures', 'types', 'tsconfig-cjs.test.json');
+  }
+  
+  try {
+    // Run TypeScript compiler
+    const cmd = 'npx tsc --project "' + tsconfigPath + '"';
+    execSync(cmd, { 
+      encoding: 'utf-8',
+      stdio: 'pipe',
+      cwd: join(testRoot, 'fixtures', 'types')
+    });
+    t.pass('TypeScript types compile successfully');
+  } catch (error) {
+    t.fail('TypeScript compilation failed: ' + error.message);
+    if (error.stdout) console.log('STDOUT:', error.stdout);
+    if (error.stderr) console.log('STDERR:', error.stderr);
+  }
+
+  t.end();
+});

package/test/util.mjs

@@ -1,4 +1,5 @@
 import { createServer } from 'node:net';
+import { setImmediate } from 'node:timers/promises';
 
 async function bootstrap(t) {
   const port = await getPort();
@@ -7,18 +8,24 @@ async function bootstrap(t) {
   };
 }
 
-function getPort() {
-  return new Promise((resolve, reject) => {
-    const server = createServer();
-    server.unref();
+async function getPort() {
+  const server = createServer();
+  server.unref();
+  
+  const port = await new Promise((resolve, reject) => {
     server.on('error', reject);
     server.listen(() => {
-      const { port } = server.address();
-      server.close(() => {
-        resolve(port);
-      });
+      resolve(server.address().port);
     });
   });
+  
+  await server.close();
+  
+  // Allow the event loop to process and ensure port is fully released
+  // This prevents EACCES errors when immediately rebinding to the same port
+  await setImmediate();
+  
+  return port;
 }
 
 export {

package/tsconfig.json

@@ -0,0 +1,45 @@
+{
+  "compilerOptions": {
+    // Enable JSDoc type checking
+    "allowJs": true,
+    "checkJs": false,
+    
+    // Generate declaration files only
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "declarationMap": true,
+    
+    // Output directory for declarations
+    "outDir": "./types",
+    
+    // Module settings for ESM (will generate .d.mts files)
+    "module": "ES2022",
+    "moduleResolution": "node",
+    "target": "ES2022",
+    
+    // Allow default imports from modules with no default export
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    
+    // Strict options for better type inference
+    "strict": false,
+    "skipLibCheck": true,
+    
+    // Resolve JSON modules
+    "resolveJsonModule": true,
+    
+    // Base URL for paths
+    "baseUrl": ".",
+    "paths": {
+      "#decode": ["./lib/internal/decode.mjs"]
+    }
+  },
+  "include": [
+    "lib/**/*.mjs"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "test"
+  ]
+}

package/types/Bundle.d.mts

@@ -0,0 +1,70 @@
+export default Bundle;
+/**
+ * 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);
+ */
+declare 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: any, ...elements: (Message | Bundle | any[])[]);
+    oscType: string;
+    timetag: any;
+    elements: (Message | Bundle)[];
+    /**
+     * 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: Message | Bundle | any[]): void;
+}
+import Message from './Message.mjs';
+//# sourceMappingURL=Bundle.d.mts.map

package/types/Bundle.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Bundle.d.mts","sourceRoot":"","sources":["../lib/Bundle.mjs"],"names":[],"mappings":";AAaA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IACE;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,uCAjBc,CAAC,OAAO,GAAC,MAAM,QAAM,CAAC,EAAA,EAyBnC;IAHC,gBAAuB;IACvB,aAAsB;IACtB,+BAAsC;IAGxC;;;;;;;;;;;;;;;;OAgBG;IACH,gBAdW,OAAO,GAAC,MAAM,QAAM,QAgB9B;CACF;oBAvFmB,eAAe"}

package/types/Client.d.mts

@@ -0,0 +1,101 @@
+export default Client;
+/**
+ * OSC Client for sending messages and bundles over UDP.
+ *
+ * Extends EventEmitter and emits the following events:
+ * - 'error': Emitted when a socket error occurs
+ *
+ * @class
+ * @extends EventEmitter
+ * @example
+ * // Create a client
+ * const client = new Client('127.0.0.1', 3333);
+ *
+ * // Send a message with callback
+ * client.send('/oscAddress', 200, (err) => {
+ *   if (err) console.error(err);
+ *   client.close();
+ * });
+ *
+ * @example
+ * // Send a message with async/await
+ * const client = new Client('127.0.0.1', 3333);
+ * await client.send('/oscAddress', 200);
+ * await client.close();
+ */
+declare class Client extends EventEmitter<[never]> {
+    /**
+     * Create an OSC Client.
+     *
+     * @param {string} host - The hostname or IP address of the OSC server.
+     * @param {number} port - The port number of the OSC server.
+     *
+     * @example
+     * const client = new Client('127.0.0.1', 3333);
+     */
+    constructor(host: string, port: number);
+    host: string;
+    port: number;
+    _sock: import("dgram").Socket;
+    /**
+     * Close the client socket.
+     *
+     * This method can be used with either a callback or as a Promise.
+     *
+     * @param {Function} [cb] - Optional callback function called when socket is closed.
+     * @returns {Promise<void>|undefined} Returns a Promise if no callback is provided.
+     *
+     * @example
+     * // With callback
+     * client.close((err) => {
+     *   if (err) console.error(err);
+     * });
+     *
+     * @example
+     * // With async/await
+     * 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.
+     *
+     * This method can be used with either a callback or as a Promise.
+     * Messages can be sent in several formats:
+     * - As separate arguments: address followed by values
+     * - As a Message or Bundle object
+     * - As an array: [address, ...values]
+     *
+     * @param {...*} args - The message to send. Can be:
+     *   - (address: string, ...values: any[], callback?: Function)
+     *   - (message: Message|Bundle, callback?: Function)
+     *   - (array: Array, callback?: Function)
+     * @returns {Promise<void>|undefined} Returns a Promise if no callback is provided.
+     *
+     * @throws {TypeError} If the message format is invalid.
+     * @throws {ReferenceError} If attempting to send on a closed socket.
+     *
+     * @example
+     * // Send with address and arguments
+     * client.send('/oscAddress', 200, 'hello', (err) => {
+     *   if (err) console.error(err);
+     * });
+     *
+     * @example
+     * // Send with async/await
+     * await client.send('/oscAddress', 200, 'hello');
+     *
+     * @example
+     * // Send a Message object
+     * const msg = new Message('/test', 1, 2, 3);
+     * await client.send(msg);
+     *
+     * @example
+     * // Send a Bundle object
+     * const bundle = new Bundle(['/one', 1], ['/two', 2]);
+     * await client.send(bundle);
+     */
+    send(...args: any[]): Promise<void> | undefined;
+}
+import { EventEmitter } from 'node:events';
+//# sourceMappingURL=Client.d.mts.map

package/types/Client.d.mts.map

@@ -0,0 +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,8BAGE;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"}

package/types/Message.d.mts

@@ -0,0 +1,84 @@
+export default Message;
+/**
+ * Represents an OSC message with an address and arguments.
+ *
+ * OSC messages consist of an address pattern (string starting with '/')
+ * and zero or more arguments of various types.
+ *
+ * @class
+ *
+ * @example
+ * // Create a message with constructor arguments
+ * const msg = new Message('/test', 1, 2, 'hello');
+ *
+ * @example
+ * // Create a message and append arguments
+ * const msg = new Message('/test');
+ * msg.append(1);
+ * msg.append('hello');
+ * msg.append(3.14);
+ */
+declare class Message {
+    /**
+     * Create an OSC Message.
+     *
+     * @param {string} address - The OSC address pattern (e.g., '/oscillator/frequency').
+     * @param {...*} args - Optional arguments to include in the message.
+     *
+     * @example
+     * const msg = new Message('/test');
+     *
+     * @example
+     * const msg = new Message('/test', 1, 2, 3);
+     *
+     * @example
+     * const msg = new Message('/synth', 'note', 60, 0.5);
+     */
+    constructor(address: string, ...args: any[]);
+    oscType: string;
+    address: string;
+    args: any[];
+    /**
+     * Append an argument to the message.
+     *
+     * Automatically detects the type based on the JavaScript type:
+     * - Integers are encoded as OSC integers
+     * - Floats are encoded as OSC floats
+     * - Strings are encoded as OSC strings
+     * - Booleans are encoded as OSC booleans
+     * - Buffers are encoded as OSC blobs
+     * - Arrays are recursively appended
+     * - Objects with a 'type' property are used as-is
+     *
+     * @param {*} arg - The argument to append. Can be:
+     *   - A primitive value (number, string, boolean)
+     *   - A Buffer (encoded as blob)
+     *   - An array of values (will be recursively appended)
+     *   - An object with 'type' and 'value' properties for explicit type control
+     *
+     * @throws {Error} If the argument type cannot be encoded.
+     *
+     * @example
+     * const msg = new Message('/test');
+     * msg.append(42);           // Integer
+     * msg.append(3.14);         // Float
+     * msg.append('hello');      // String
+     * msg.append(true);         // Boolean
+     *
+     * @example
+     * // Append multiple values at once
+     * msg.append([1, 2, 3]);
+     *
+     * @example
+     * // Explicitly specify type
+     * msg.append({ type: 'float', value: 42 });
+     * msg.append({ type: 'blob', value: Buffer.from('data') });
+     *
+     * @example
+     * // MIDI messages (4 bytes: port, status, data1, data2)
+     * msg.append({ type: 'midi', value: { port: 0, status: 144, data1: 60, data2: 127 } });
+     * msg.append({ type: 'm', value: Buffer.from([0, 144, 60, 127]) });
+     */
+    append(arg: any): void;
+}
+//# sourceMappingURL=Message.d.mts.map

package/types/Message.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Message.d.mts","sourceRoot":"","sources":["../lib/Message.mjs"],"names":[],"mappings":";AAyBA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IACE;;;;;;;;;;;;;;OAcG;IACH,qBAZW,MAAM,WACH,GAAC,EAAA,EAed;IAHC,gBAAwB;IACxB,gBAAsB;IACtB,YAAgB;IAGlB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACH,YA7BW,GAAC,QA2DX;CACF"}