node-osc 11.1.0 → 11.2.0

package/rollup.config.mjs

@@ -20,48 +20,59 @@ function walk(root, result=[]) {
 }
 
 function walkLib(config) {
+  // Build all lib files in a single pass
   const files = walk('./lib/');
-  files.forEach(({input, dir}) => {
-    config.push({
-      input,
-      output: {
-        entryFileNames: '[name].js',
-        dir,
-        format: 'cjs',
-        preserveModules: true,
-        exports: 'auto'
-      },
-      external: [
-        'node:dgram',
-        'node:events',
-        'jspack',
-        '#decode'
-      ]
-    });
+  config.push({
+    input: files.map(f => f.input),
+    output: {
+      entryFileNames: '[name].js',
+      dir: 'dist/lib',
+      format: 'cjs',
+      preserveModules: true,
+      preserveModulesRoot: 'lib',
+      exports: 'auto'
+    },
+    external: [
+      'node:dgram',
+      'node:events',
+      'node:buffer',
+      'jspack',
+      '#decode'
+    ]
   });
 }
 
 function walkTest(config) {
-  const tests = walk('./test/');
-  tests.forEach(({input, dir}) => {
-    config.push({
-      input,
-      plugins: [],
-      output: {
-        entryFileNames: '[name].js',
-        dir,
-        format: 'cjs',
-        exports: 'auto',
-        preserveModules: true
-      },
-      external: [
-        'node:dgram',
-        'node:net',
-        'node-osc',
-        'tap',
-        '#decode'
-      ]
-    });
+  // Build all test files in a single pass, excluding fixtures
+  const tests = walk('./test/').filter(t => {
+    // Normalize path separators to work on both Unix and Windows
+    const normalizedPath = t.input.replace(/\\/g, '/');
+    return !normalizedPath.includes('/fixtures/');
+  });
+  config.push({
+    input: tests.map(t => t.input),
+    plugins: [],
+    output: {
+      entryFileNames: '[name].js',
+      dir: 'dist/test',
+      format: 'cjs',
+      exports: 'auto',
+      preserveModules: true,
+      preserveModulesRoot: 'test'
+    },
+    external: [
+      'node:dgram',
+      'node:net',
+      'node:buffer',
+      'node:events',
+      'node:child_process',
+      'node:fs',
+      'node:path',
+      'node:url',
+      'node-osc',
+      'tap',
+      '#decode'
+    ]
   });
 }
 

package/scripts/generate-docs.mjs

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+
+/**
+ * Converts JSDoc JSON output to Markdown documentation.
+ * This script reads JSDoc JSON data and generates a formatted Markdown file.
+ */
+
+import { writeFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+
+// Generate JSDoc JSON
+let jsdocJson;
+try {
+  jsdocJson = execSync('npx jsdoc -X -c jsdoc.json', {
+    encoding: 'utf8',
+    maxBuffer: 10 * 1024 * 1024
+  });
+} catch (error) {
+  console.error('❌ Failed to run JSDoc:');
+  console.error(error.message);
+  process.exit(1);
+}
+
+let docs;
+try {
+  docs = JSON.parse(jsdocJson);
+} catch (error) {
+  console.error('❌ Failed to parse JSDoc JSON output:');
+  console.error(error.message);
+  process.exit(1);
+}
+
+// Filter and organize documentation
+const classes = {};
+const functions = {};
+
+docs.forEach(item => {
+  if (item.undocumented || item.ignore) return;
+  
+  if (item.kind === 'class' && item.classdesc) {
+    if (!classes[item.name]) {
+      classes[item.name] = {
+        desc: item.classdesc,
+        constructor: null,
+        methods: [],
+        examples: item.examples || [],
+        augments: item.augments || []
+      };
+    }
+    // Look for constructor params
+    if (item.params) {
+      classes[item.name].constructor = {
+        params: item.params,
+        examples: item.examples || []
+      };
+    }
+  } else if (item.kind === 'function' && item.memberof) {
+    // Method of a class
+    const className = item.memberof;
+    if (!classes[className]) {
+      classes[className] = {
+        desc: '',
+        constructor: null,
+        methods: [],
+        examples: []
+      };
+    }
+    classes[className].methods.push(item);
+  } else if (item.kind === 'function' && !item.memberof && item.scope === 'global') {
+    // Top-level function
+    functions[item.name] = item;
+  }
+});
+
+// Generate Markdown
+let markdown = `<!-- Generated by JSDoc. Update this documentation by updating the source code. -->
+
+# API Reference
+
+> **⚠️ This file is auto-generated from JSDoc comments in the source code.**  
+> To update this documentation, edit the JSDoc comments in the source files and run \`npm run docs\`.
+
+This document provides detailed API reference for all classes, methods, and functions in node-osc.
+
+For usage guides, best practices, and troubleshooting, see the **[Guide](./GUIDE.md)**.
+
+## Table of Contents
+
+`;
+
+// Define order: Server → Client → Message → Bundle → Low Level
+const classOrder = ['Server', 'Client', 'Message', 'Bundle'];
+const functionOrder = ['encode', 'decode'];
+
+// Add classes to TOC
+classOrder.forEach(name => {
+  if (classes[name]) {
+    markdown += `- [${name}](#${name.toLowerCase()})\n`;
+    if (classes[name].constructor) {
+      markdown += `  - [Constructor](#${name.toLowerCase()}-constructor)\n`;
+    }
+    classes[name].methods.forEach(method => {
+      markdown += `  - [${method.name}()](#${name.toLowerCase()}-${method.name.toLowerCase()})\n`;
+    });
+  }
+});
+
+// Add functions to TOC
+markdown += `- [Low Level Functions](#low-level-functions)\n`;
+functionOrder.forEach(name => {
+  if (functions[name]) {
+    markdown += `  - [${name}()](#${name.toLowerCase()})\n`;
+  }
+});
+
+markdown += `\n---\n\n`;
+
+// Helper function to format parameters
+function formatParams(params) {
+  if (!params || params.length === 0) return '';
+  
+  let result = '\n**Parameters:**\n\n';
+  params.forEach(param => {
+    const optional = param.optional ? ' (optional)' : '';
+    const defaultVal = param.defaultvalue ? ` - Default: \`${param.defaultvalue}\`` : '';
+    const types = param.type ? param.type.names.join(' | ') : 'any';
+    result += `- \`${param.name}\` *{${types}}*${optional}${defaultVal} - ${param.description || ''}\n`;
+  });
+  return result;
+}
+
+// Helper function to format examples
+function formatExamples(examples) {
+  if (!examples || examples.length === 0) return '';
+  
+  let result = '\n**Examples:**\n\n';
+  examples.forEach(example => {
+    result += '```javascript\n' + example + '\n```\n\n';
+  });
+  return result;
+}
+
+// Helper function to format returns
+function formatReturns(returns) {
+  if (!returns || returns.length === 0) return '';
+  
+  const ret = returns[0];
+  const types = ret.type ? ret.type.names.join(' | ') : 'any';
+  return `\n**Returns:** *{${types}}* - ${ret.description || ''}\n`;
+}
+
+// Helper function to format throws
+function formatThrows(exceptions) {
+  if (!exceptions || exceptions.length === 0) return '';
+  
+  let result = '\n**Throws:**\n\n';
+  exceptions.forEach(ex => {
+    const types = ex.type ? ex.type.names.join(' | ') : 'Error';
+    result += `- *{${types}}* - ${ex.description || ''}\n`;
+  });
+  return result;
+}
+
+// Generate class documentation
+classOrder.forEach(className => {
+  const classInfo = classes[className];
+  if (!classInfo) return;
+  
+  markdown += `## ${className}\n\n`;
+  
+  // Add extends info
+  if (classInfo.augments && classInfo.augments.length > 0) {
+    markdown += `**Extends:** ${classInfo.augments.join(', ')}\n\n`;
+  }
+  
+  markdown += `${classInfo.desc}\n`;
+  
+  // Class-level examples
+  if (classInfo.examples.length > 0 && !classInfo.constructor) {
+    markdown += formatExamples(classInfo.examples);
+  }
+  
+  // Constructor
+  if (classInfo.constructor) {
+    markdown += `\n### ${className} Constructor\n\n`;
+    markdown += `Creates a new ${className} instance.\n`;
+    markdown += formatParams(classInfo.constructor.params);
+    markdown += formatExamples(classInfo.constructor.examples);
+  }
+  
+  // Methods
+  classInfo.methods.forEach(method => {
+    markdown += `\n### ${className}.${method.name}()\n\n`;
+    markdown += `${method.description || ''}\n`;
+    markdown += formatParams(method.params);
+    markdown += formatReturns(method.returns);
+    markdown += formatThrows(method.exceptions);
+    markdown += formatExamples(method.examples);
+  });
+  
+  markdown += `\n---\n\n`;
+});
+
+// Generate function documentation
+markdown += `## Low Level Functions\n\n`;
+markdown += `These functions provide low-level access to OSC encoding and decoding for advanced use cases.\n\n`;
+
+functionOrder.forEach(funcName => {
+  const func = functions[funcName];
+  if (!func) return;
+  
+  markdown += `### ${funcName}()\n\n`;
+  markdown += `${func.description || ''}\n`;
+  markdown += formatParams(func.params);
+  markdown += formatReturns(func.returns);
+  markdown += formatThrows(func.exceptions);
+  markdown += formatExamples(func.examples);
+  markdown += `\n`;
+});
+
+// Write output
+try {
+  writeFileSync('docs/API.md', markdown, 'utf8');
+  console.log('✅ API documentation generated: docs/API.md');
+} catch (error) {
+  console.error('❌ Failed to write API.md:');
+  console.error(error.message);
+  process.exit(1);
+}

package/test/fixtures/types/test-cjs-types.ts

@@ -0,0 +1,19 @@
+// Test CJS-style TypeScript imports
+import type { Client, Server, Message, Bundle } from 'node-osc';
+const osc = require('node-osc');
+
+// Create server first (typical usage pattern)
+const server: Server = new osc.Server(3333, '0.0.0.0');
+
+// Create client after server
+const client: Client = new osc.Client('127.0.0.1', 3333);
+
+// Test Message type
+const message: Message = new osc.Message('/test', 1, 2, 3);
+
+// Test Bundle type
+const bundle: Bundle = new osc.Bundle(['/one', 1]);
+
+// Test encode/decode with consistent type annotations
+const encoded: Buffer = osc.encode(message);
+const decoded: Object = osc.decode(encoded);

package/test/fixtures/types/test-esm-types.ts

@@ -0,0 +1,35 @@
+// Test ESM TypeScript imports with Top-Level Await
+import { once } from 'node:events';
+import { Client, Server, Message, Bundle, encode, decode } from 'node-osc';
+
+// Create server first (typical usage pattern)
+const server: Server = new Server(3333, '0.0.0.0');
+
+// Wait for server to be ready (pattern from examples)
+await once(server, 'listening');
+
+server.on('message', (msg) => {
+  console.log('Received message:', msg);
+});
+
+// Create client after server
+const client: Client = new Client('127.0.0.1', 3333);
+
+// Test async usage with Top-Level Await (ESM feature)
+await client.send('/test', 1, 2, 3);
+await client.close();
+await server.close();
+
+// Test Message type
+const message: Message = new Message('/oscillator/frequency', 440);
+message.append(3.14);
+message.append('hello');
+message.append(true);
+
+// Test Bundle type
+const bundle: Bundle = new Bundle(['/one', 1], ['/two', 2]);
+bundle.append(['/three', 3]);
+
+// Test encode/decode with consistent type annotations
+const encoded: Buffer = encode(message);
+const decoded: Object = decode(encoded);

package/test/fixtures/types/tsconfig-cjs.test.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "noEmit": true,
+    "skipLibCheck": true,
+    "module": "commonjs",
+    "esModuleInterop": true,
+    "target": "ES2022",
+    "moduleResolution": "node",
+    "baseUrl": ".",
+    "paths": {
+      "node-osc": ["../../../types/index.d.mts"]
+    }
+  },
+  "include": [
+    "test-cjs-types.ts"
+  ]
+}

package/test/fixtures/types/tsconfig-esm.test.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "noEmit": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "module": "ES2022",
+    "target": "ES2022",
+    "moduleResolution": "node",
+    "baseUrl": ".",
+    "paths": {
+      "node-osc": ["../../../types/index.d.mts"]
+    }
+  },
+  "include": [
+    "test-esm-types.ts"
+  ]
+}

package/test/test-bundle.mjs

@@ -86,4 +86,3 @@ test('bundle: nested bundle', (t) => {
 
   client.send(payload);
 });
-

package/test/test-client.mjs

@@ -106,3 +106,155 @@ test('client: failure', (t) => {
     t.equal(err.code, 'ERR_SOCKET_DGRAM_NOT_RUNNING');
   });
 });
+
+test('client: close with callback', (t) => {
+  const client = new Client('127.0.0.1', t.context.port);
+
+  t.plan(1);
+
+  client.close((err) => {
+    t.error(err, 'close should not error');
+  });
+});
+
+test('client: send bundle with non-numeric timetag', (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);
+
+  oscServer.on('bundle', (bundle) => {
+    oscServer.close();
+    t.equal(bundle.timetag, 0, 'should receive immediate execution timetag as 0');
+    t.ok(bundle.elements.length > 0, 'should have elements');
+    client.close();
+  });
+
+  // Send bundle with non-numeric timetag (will be encoded as immediate execution)
+  const bundle = {
+    oscType: 'bundle',
+    timetag: 'immediate', // Non-numeric, will trigger the else branch in writeTimeTag
+    elements: [
+      {
+        oscType: 'message',
+        address: '/test1',
+        args: [{ type: 'i', value: 42 }]
+      }
+    ]
+  };
+  
+  client.send(bundle);
+});
+
+test('client: send bundle with null timetag', (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);
+
+  oscServer.on('bundle', (bundle) => {
+    oscServer.close();
+    t.equal(bundle.timetag, 0, 'should receive immediate execution timetag as 0');
+    t.ok(bundle.elements.length > 0, 'should have elements');
+    client.close();
+  });
+
+  // Send bundle with null timetag (will be encoded as immediate execution)
+  const bundle = {
+    oscType: 'bundle',
+    timetag: null, // Null, will trigger the else branch in writeTimeTag
+    elements: [
+      {
+        oscType: 'message',
+        address: '/test2',
+        args: [{ type: 's', value: 'hello' }]
+      }
+    ]
+  };
+  
+  client.send(bundle);
+});
+
+test('client: send message with float type arg', (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);
+
+  oscServer.on('message', (msg) => {
+    oscServer.close();
+    t.equal(msg[0], '/float-test', 'should receive address');
+    t.ok(Math.abs(msg[1] - 9.876) < 0.001, 'should receive float value');
+    client.close();
+  });
+
+  // Send raw message with 'float' type to hit that case label
+  client.send({
+    oscType: 'message',
+    address: '/float-test',
+    args: [{ type: 'float', value: 9.876 }]
+  });
+});
+
+test('client: send message with blob type arg', (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);
+
+  oscServer.on('message', (msg) => {
+    oscServer.close();
+    t.equal(msg[0], '/blob-test', 'should receive address');
+    t.ok(Buffer.isBuffer(msg[1]), 'should receive blob as buffer');
+    client.close();
+  });
+
+  // Send raw message with 'blob' type to hit that case label
+  client.send({
+    oscType: 'message',
+    address: '/blob-test',
+    args: [{ type: 'blob', value: Buffer.from([0xAA, 0xBB]) }]
+  });
+});
+
+test('client: send message with double type arg', (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);
+
+  oscServer.on('message', (msg) => {
+    oscServer.close();
+    t.equal(msg[0], '/double-test', 'should receive address');
+    t.ok(Math.abs(msg[1] - 1.23456789) < 0.001, 'should receive double value as float');
+    client.close();
+  });
+
+  // Send raw message with 'double' type to hit that case label
+  client.send({
+    oscType: 'message',
+    address: '/double-test',
+    args: [{ type: 'double', value: 1.23456789 }]
+  });
+});
+
+test('client: send message with midi type arg', (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);
+
+  oscServer.on('message', (msg) => {
+    oscServer.close();
+    t.equal(msg[0], '/midi-test', 'should receive address');
+    t.ok(Buffer.isBuffer(msg[1]), 'should receive MIDI as buffer');
+    client.close();
+  });
+
+  // Send raw message with 'midi' type to hit that case label
+  client.send({
+    oscType: 'message',
+    address: '/midi-test',
+    args: [{ type: 'midi', value: Buffer.from([0x00, 0x90, 0x40, 0x60]) }]
+  });
+});

package/test/test-e2e.mjs

@@ -22,9 +22,12 @@ test('osc: argument message no callback', (t) => {
 
   t.plan(1);
 
-  oscServer.on('message', (msg) => {
+  t.teardown(() => {
     oscServer.close();
     client.close();
+  });
+
+  oscServer.on('message', (msg) => {
     t.same(msg, ['/test', 1, 2, 'testing'], 'We should receive expected payload');
   });
 
@@ -39,13 +42,16 @@ test('osc: client with callback and message as arguments', (t) => {
 
   t.plan(2);
 
-  oscServer.on('message', (msg) => {
+  t.teardown(() => {
     oscServer.close();
+    client.close();
+  });
+
+  oscServer.on('message', (msg) => {
     t.same(msg, ['/test', 1, 2, 'testing'], 'We should receive expected payload');
   });
 
   client.send('/test', 1, 2, 'testing', (err) => {
     t.error(err, 'there should be no error');
-    client.close();
   });
 });