DDEX Parser - JavaScript/TypeScript Bindings

DDEX XML Parser for Node.js

Fully functional DDEX XML parser for JavaScript and TypeScript with complete data structure access. Built on Rust with native Node.js bindings and WASM browser support - parse DDEX files with full access to releases, resources, deals, and tracks.

Installation

npm install ddex-parser
# or for specific version
npm install [email protected]
# or
yarn add ddex-parser

⚠️ v0.4.4 Breaking Changes Enhanced validation now properly fails on missing required fields instead of using placeholder values. Ensure your error handling can catch validation errors for incomplete DDEX files.

Quick Start

Node.js (ESM/CommonJS)

const { DdexParser } = require('ddex-parser');
const fs = require('fs');

const parser = new DdexParser();
const xmlContent = fs.readFileSync('release.xml', 'utf8');
const result = parser.parseSync(xmlContent);

// Full access to parsed data structures
console.log('Message ID:', result.messageId);
console.log('Total Releases:', result.releases.length);
console.log('Total Resources:', Object.keys(result.resources).length);
console.log('Total Deals:', result.deals.length);

// Access individual releases
result.releases.forEach((release, index) => {
  console.log(`Release ${index + 1}:`, {
    id: release.releaseId,
    title: release.title,
    artist: release.displayArtist,
    trackCount: release.tracks.length
  });
});

Error Handling (v0.4.4+)

const { DdexParser } = require('ddex-parser');

const parser = new DdexParser();

try {
  const result = parser.parseSync(xmlContent);
  console.log('Parse successful:', result.messageId);
} catch (error) {
  console.error('Parse failed:', error.message);

  // v0.4.4+ provides detailed field-specific errors
  if (error.message.includes('missing required field')) {
    console.log('Incomplete DDEX file - missing required fields');
  } else if (error.message.includes('XML parsing failed')) {
    console.log('Malformed XML structure');
  }
}

Browser (ES Modules)

import { DdexParser } from 'ddex-parser/browser';

const parser = new DdexParser();
const result = await parser.parseString(xmlContent);

// Process the parsed data
result.flattened.tracks.forEach(track => {
  console.log(`${track.position}. ${track.title} - ${track.duration}s`);
});

Features

🚀 Blazing Performance

• 15x faster than traditional XML parsers
• Native Node.js addon with Rust performance
• Optimized WASM for browsers (<500KB gzipped)
• Streaming support for large catalog files

🌐 Cross-Platform Compatibility

• Node.js 16+ with native bindings
• Browser support via optimized WASM
• TypeScript-first with comprehensive type definitions
• Framework agnostic - works with React, Vue, Angular, Svelte

🔒 Security & Reliability

• Built-in XXE (XML External Entity) protection
• Entity expansion limits and memory bounds
• Comprehensive error handling with detailed messages
• Production-tested against malformed XML

🎵 Music Industry Ready

• Complete support for DDEX ERN profiles (3.8.2, 4.2, 4.3+)
• Release, track, and resource metadata extraction
• Rights, territory, and deal information
• Image and audio resource handling
• Genre and mood classification support

Complete Data Structure

The parser now provides full access to all DDEX data structures:

interface ParsedMessage {
  // Message metadata
  messageId: string;
  messageType: string;
  messageDate: string;
  senderName: string;
  senderId: string;
  recipientName: string;
  recipientId: string;
  version: string;
  profile?: string;

  // Legacy counts (for backward compatibility)
  releaseCount: number;
  trackCount: number;
  dealCount: number;
  resourceCount: number;
  totalDurationSeconds: number;

  // COMPLETE DATA STRUCTURES
  releases: Release[];              // Full release objects with tracks
  resources: { [key: string]: Resource }; // Resource dictionary with IDs as keys
  deals: Deal[];                   // Complete deal information

  // Enhanced features
  statistics?: ParseStatistics;
  fidelityInfo?: FidelityInfo;
}

interface Release {
  releaseId: string;
  title: string;
  defaultTitle: string;
  subtitle?: string;
  displayArtist: string;
  releaseType: string;
  genre?: string;
  subGenre?: string;
  trackCount: number;
  discCount?: number;
  releaseDate?: string;
  originalReleaseDate?: string;
  labelName?: string;
  tracks: Track[];                 // Full track array
}

interface Track {
  trackId: string;
  title: string;
  artist: string;
  duration?: string;
  position?: number;
  discNumber?: number;
  isrc?: string;
  resourceReference?: string;
}

interface Resource {
  resourceId: string;
  resourceType: string;
  title: string;
  durationSeconds?: number;
  durationString?: string;
  fileFormat?: string;
  bitrate?: number;
  sampleRate?: number;
  fileSize?: string;
}

interface Deal {
  dealId: string;
  releases: string[];
  startDate?: string;
  endDate?: string;
  territories: string[];
  usageRights: string[];
  restrictions: string[];
  commercialModel: string;
}

API Reference

DdexParser

class DdexParser {
  constructor();

  // Synchronous parsing with complete data access
  parseSync(xml: string, options?: ParseOptions): ParsedMessage;

  // Asynchronous parsing with complete data access
  parse(xml: string, options?: ParseOptions): Promise<ParsedMessage>;

  // Utilities
  detectVersion(xml: string): string;
  sanityCheck(xml: string): Promise<SanityCheckResult>;

  // Streaming (returns async iterator)
  stream(xml: string, options?: StreamOptions): ReleaseStream;
}

Comprehensive Usage Examples

Working with Releases and Tracks

const { DdexParser } = require('ddex-parser');
const parser = new DdexParser();
const result = parser.parseSync(xmlContent);

// Access all releases
console.log(`Found ${result.releases.length} releases`);

result.releases.forEach(release => {
  console.log(`\nRelease: ${release.title}`);
  console.log(`Artist: ${release.displayArtist}`);
  console.log(`Type: ${release.releaseType}`);
  console.log(`Release Date: ${release.releaseDate}`);
  console.log(`Track Count: ${release.tracks.length}`);

  // Access individual tracks
  release.tracks.forEach((track, index) => {
    console.log(`  Track ${index + 1}: ${track.title}`);
    console.log(`    Artist: ${track.artist}`);
    console.log(`    Duration: ${track.duration}`);
    console.log(`    ISRC: ${track.isrc}`);
  });
});

Working with Resources

const parser = new DdexParser();
const result = parser.parseSync(xmlContent);

// Access all resources
const resourceIds = Object.keys(result.resources);
console.log(`Found ${resourceIds.length} resources`);

resourceIds.forEach(resourceId => {
  const resource = result.resources[resourceId];
  console.log(`\nResource: ${resource.title}`);
  console.log(`Type: ${resource.resourceType}`);
  console.log(`Duration: ${resource.durationString}`);
  console.log(`File Format: ${resource.fileFormat}`);
  console.log(`Bitrate: ${resource.bitrate}`);
  console.log(`Sample Rate: ${resource.sampleRate}`);
});

Working with Deals

const parser = new DdexParser();
const result = parser.parseSync(xmlContent);

// Access all deals
console.log(`Found ${result.deals.length} deals`);

result.deals.forEach(deal => {
  console.log(`\nDeal: ${deal.dealId}`);
  console.log(`Releases: ${deal.releases.join(', ')}`);
  console.log(`Territories: ${deal.territories.join(', ')}`);
  console.log(`Start Date: ${deal.startDate}`);
  console.log(`End Date: ${deal.endDate}`);
  console.log(`Commercial Model: ${deal.commercialModel}`);
  console.log(`Usage Rights: ${deal.usageRights.join(', ')}`);
});

Async Parsing

const parser = new DdexParser();

try {
  const result = await parser.parse(xmlContent);
  console.log('Successfully parsed:', {
    messageId: result.messageId,
    releases: result.releases.length,
    resources: Object.keys(result.resources).length,
    deals: result.deals.length
  });
} catch (error) {
  console.error('Parse failed:', error.message);
}

Version Detection and Validation

const parser = new DdexParser();

// Detect DDEX version
const version = parser.detectVersion(xmlContent);
console.log('DDEX Version:', version); // e.g., "V4_3"

// Comprehensive validation
const sanityResult = await parser.sanityCheck(xmlContent);
if (sanityResult.isValid) {
  console.log(`Valid DDEX ${sanityResult.version}`);
} else {
  console.log('Validation errors:', sanityResult.errors);
  console.log('Warnings:', sanityResult.warnings);
}

Performance Benchmarks

Performance comparison in different environments:

Node.js (Native Addon)

| File Size | ddex-parser | xml2js | fast-xml-parser | Speedup | |-----------|-------------|--------|-----------------|----------| | 10KB | 1.2ms | 15ms | 8ms | 7x-12x | | 100KB | 4ms | 120ms | 65ms | 16x-30x | | 1MB | 32ms | 980ms | 520ms | 16x-30x | | 10MB | 240ms | 8.2s | 4.1s | 17x-34x |

Browser (WASM)

| File Size | ddex-parser | DOMParser | xml2js | Speedup | |-----------|-------------|-----------|--------|----------| | 10KB | 2.1ms | 12ms | 25ms | 6x-12x | | 100KB | 8ms | 85ms | 180ms | 11x-22x | | 1MB | 65ms | 750ms | 1.8s | 11x-28x |

Memory usage is consistently 40-60% lower across all environments.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Projects

• ddex-builder - Build deterministic DDEX XML files
• ddex-parser (Python) - Python bindings
• DDEX Suite - Complete DDEX processing toolkit

Built for the music industry. Powered by Rust + WASM for universal performance.