Skip to main content

TypeScript API Reference

Complete API documentation for the DDEX Parser TypeScript/JavaScript bindings.

Installation​

npm install ddex-parser

Imports​

import { DdexParser, DdexParserOptions, ParseResult } from 'ddex-parser';

// Or using require (CommonJS)
const { DdexParser } = require('ddex-parser');

Classes​

DdexParser​

High-level parser class with automatic WASM/Native detection.

class DdexParser {
  constructor();
  parse(xml: string, options?: DdexParserOptions): Promise<ParseResult>;
  stream(source: ReadableStream | NodeJS.ReadableStream, options?: DdexParserOptions): Promise<ParseResult>;
  get version(): string;
}

Constructor​

const parser = new DdexParser();

Creates a new DDEX parser instance. The parser automatically detects the best available implementation (native or WASM).

parse()​

parse(xml: string, options?: DdexParserOptions): Promise<ParseResult>

Parses DDEX XML content and returns structured data.

Parameters:

  • xml: string - The DDEX XML content to parse
  • options?: DdexParserOptions - Optional parsing configuration

Returns: Promise<ParseResult> - Parsed DDEX message data

Example:

const parser = new DdexParser();
const result = await parser.parse(xmlContent, {
  includeRawExtensions: true,
  validateReferences: true
});

console.log(`Parsed ${result.flat.releases.length} releases`);

stream()​

stream(source: ReadableStream | NodeJS.ReadableStream, options?: DdexParserOptions): Promise<ParseResult>

Streams DDEX XML from a readable source for memory-efficient processing.

Parameters:

  • source: ReadableStream | NodeJS.ReadableStream - Input stream
  • options?: DdexParserOptions - Optional parsing configuration

Returns: Promise<ParseResult> - Parsed DDEX message data

Example:

import { createReadStream } from 'fs';

const parser = new DdexParser();
const stream = createReadStream('large-catalog.xml');
const result = await parser.stream(stream, {
  streaming: true
});

version​

get version(): string

Returns the parser version string.

Example:

const parser = new DdexParser();
console.log(`Parser version: ${parser.version}`);

DdexParser (Native)​

Low-level native parser class providing direct access to Rust implementation.

class DdexParser {
  constructor();
  detectVersion(xml: string): string;
  parseSync(xml: string, options?: ParseOptions): ParsedMessage;
  parse(xml: string, options?: ParseOptions): Promise<ParsedMessage>;
  sanityCheck(xml: string): Promise<SanityCheckResult>;
  stream(xml: string, options?: StreamOptions): ReleaseStream;
}

Constructor​

const parser = new DdexParser();

Creates a new native parser instance.

detectVersion()​

detectVersion(xml: string): string

Detects the DDEX version from XML content.

Parameters:

  • xml: string - DDEX XML content

Returns: string - Detected version (e.g., "4.3", "4.2", "3.8.2")

Example:

const parser = new DdexParser();
const version = parser.detectVersion(xmlContent);
console.log(`Detected DDEX version: ${version}`);

parseSync()​

parseSync(xml: string, options?: ParseOptions): ParsedMessage

Synchronously parses DDEX XML content.

Parameters:

  • xml: string - DDEX XML content
  • options?: ParseOptions - Optional parsing configuration

Returns: ParsedMessage - Parsed message data

Example:

const parser = new DdexParser();
const result = parser.parseSync(xmlContent, {
  includeRaw: true,
  resolveReferences: true
});

parse()​

parse(xml: string, options?: ParseOptions): Promise<ParsedMessage>

Asynchronously parses DDEX XML content.

Parameters:

  • xml: string - DDEX XML content
  • options?: ParseOptions - Optional parsing configuration

Returns: Promise<ParsedMessage> - Parsed message data

sanityCheck()​

sanityCheck(xml: string): Promise<SanityCheckResult>

Performs a quick validation check on DDEX XML.

Parameters:

  • xml: string - DDEX XML content

Returns: Promise<SanityCheckResult> - Validation results

Example:

const parser = new DdexParser();
const check = await parser.sanityCheck(xmlContent);
if (!check.isValid) {
  console.error('Validation errors:', check.errors);
}

stream()​

stream(xml: string, options?: StreamOptions): ReleaseStream

Creates a streaming parser for large DDEX files.

Parameters:

  • xml: string - DDEX XML content
  • options?: StreamOptions - Optional streaming configuration

Returns: ReleaseStream - Stream iterator for releases

Example:

const parser = new DdexParser();
const stream = parser.stream(xmlContent, { chunkSize: 1024 });

let release;
while ((release = await stream.next()) !== null) {
  console.log(`Processing: ${release.title}`);
  
  // Check progress
  const progress = await stream.progress();
  console.log(`Progress: ${progress.elapsedMs}ms`);
}

ReleaseStream​

Iterator for streaming through releases in large DDEX files.

class ReleaseStream {
  next(): Promise<StreamedRelease | null>;
  progress(): Promise<ProgressInfo>;
}

next()​

next(): Promise<StreamedRelease | null>

Gets the next release from the stream.

Returns: Promise<StreamedRelease | null> - Next release or null if finished

progress()​

progress(): Promise<ProgressInfo>

Gets current streaming progress information.

Returns: Promise<ProgressInfo> - Progress statistics

Interfaces​

DdexParserOptions​

High-level parser configuration options.

interface DdexParserOptions {
  includeRawExtensions?: boolean;
  includeComments?: boolean;
  validateReferences?: boolean;
  streaming?: boolean;
}

Properties​

  • includeRawExtensions?: boolean (default: false)
    Include raw XML for extension elements to preserve round-trip fidelity

  • includeComments?: boolean (default: false)
    Include XML comments in the parsed output

  • validateReferences?: boolean (default: true)
    Validate that all resource references are resolvable

  • streaming?: boolean (default: false)
    Enable streaming mode for large files

Example:

const options: DdexParserOptions = {
  includeRawExtensions: true,
  validateReferences: false,
  streaming: true
};

ParseOptions​

Native parser configuration options.

interface ParseOptions {
  mode?: string;
  autoThreshold?: number;
  resolveReferences?: boolean;
  includeRaw?: boolean;
  maxMemory?: number;
  timeoutMs?: number;
  allowBlocking?: boolean;
  chunkSize?: number;
}

Properties​

  • mode?: string (default: "auto")
    Parsing mode: "auto", "streaming", or "blocking"

  • autoThreshold?: number (default: 1048576)
    File size threshold for automatic streaming mode (bytes)

  • resolveReferences?: boolean (default: true)
    Resolve and validate resource references

  • includeRaw?: boolean (default: false)
    Include raw XML content for extensions

  • maxMemory?: number (default: 134217728)
    Maximum memory usage for parsing (bytes)

  • timeoutMs?: number (default: 30000)
    Parsing timeout in milliseconds

  • allowBlocking?: boolean (default: false)
    Allow blocking operations during parsing

  • chunkSize?: number (default: 8192)
    Chunk size for streaming operations

StreamOptions​

Streaming parser configuration.

interface StreamOptions {
  chunkSize?: number;
  maxMemory?: number;
}

Properties​

  • chunkSize?: number (default: 8192)
    Size of chunks for streaming operations

  • maxMemory?: number (default: 67108864)
    Maximum memory usage for streaming (bytes)

ParseResult​

High-level parse result structure.

interface ParseResult {
  graph: any;
  flat: any;
}

Properties​

  • graph: any
    Faithful representation of the DDEX XML structure

  • flat: any
    Flattened, developer-friendly representation

Example:

const result = await parser.parse(xmlContent);

// Access graph structure (faithful to XML)
console.log(result.graph.MessageHeader.MessageId);

// Access flat structure (developer-friendly)
console.log(result.flat.releases[0].title);
console.log(result.flat.soundRecordings[0].isrc);

ParsedMessage​

Native parser result structure.

interface ParsedMessage {
  messageId: string;
  messageType: string;
  messageDate: string;
  senderName: string;
  senderId: string;
  recipientName: string;
  recipientId: string;
  version: string;
  profile?: string;
  releaseCount: number;
  trackCount: number;
  dealCount: number;
  resourceCount: number;
  totalDurationSeconds: number;
}

Properties​

  • messageId: string - Unique message identifier
  • messageType: string - Type of DDEX message (e.g., "NewReleaseMessage")
  • messageDate: string - Message creation date (ISO 8601)
  • senderName: string - Name of the message sender
  • senderId: string - Identifier of the message sender
  • recipientName: string - Name of the message recipient
  • recipientId: string - Identifier of the message recipient
  • version: string - DDEX version (e.g., "4.3")
  • profile?: string - Optional message profile
  • releaseCount: number - Number of releases in the message
  • trackCount: number - Number of tracks across all releases
  • dealCount: number - Number of commercial deals
  • resourceCount: number - Number of sound recordings and other resources
  • totalDurationSeconds: number - Total duration of all audio content

SanityCheckResult​

Result of XML validation check.

interface SanityCheckResult {
  isValid: boolean;
  version: string;
  errors: Array<string>;
  warnings: Array<string>;
}

Properties​

  • isValid: boolean - Whether the XML passes basic validation
  • version: string - Detected DDEX version
  • errors: Array<string> - List of validation errors
  • warnings: Array<string> - List of validation warnings

StreamedRelease​

Individual release from streaming parser.

interface StreamedRelease {
  releaseReference: string;
  title: string;
  releaseType?: string;
  resourceCount: number;
}

Properties​

  • releaseReference: string - Unique release identifier
  • title: string - Release title
  • releaseType?: string - Type of release (e.g., "Album", "Single")
  • resourceCount: number - Number of resources in this release

ProgressInfo​

Streaming progress information.

interface ProgressInfo {
  bytesProcessed: number;
  releasesParsed: number;
  elapsedMs: number;
}

Properties​

  • bytesProcessed: number - Number of bytes processed so far
  • releasesParsed: number - Number of releases parsed so far
  • elapsedMs: number - Elapsed time in milliseconds

Error Handling​

The parser throws standard JavaScript errors for various failure conditions:

try {
  const result = await parser.parse(xmlContent);
} catch (error) {
  if (error.message.includes('Invalid XML')) {
    console.error('XML parsing failed:', error.message);
  } else if (error.message.includes('Unsupported version')) {
    console.error('Unsupported DDEX version:', error.message);
  } else {
    console.error('Unexpected error:', error.message);
  }
}

Common Error Types​

  • XML Parsing Errors: Invalid or malformed XML structure
  • Schema Validation Errors: DDEX schema violations
  • Reference Resolution Errors: Unresolvable resource references
  • Memory Limit Errors: File too large for available memory
  • Timeout Errors: Parsing took longer than specified timeout

Performance Tips​

Memory Management​

// For large files, use streaming
const parser = new DdexParser();
const result = await parser.parse(largeXml, { streaming: true });

// Set memory limits for native parser
const nativeParser = new DdexParser();
const result = nativeParser.parseSync(xml, { maxMemory: 50 * 1024 * 1024 });

Batch Processing​

// Process multiple files efficiently
const parser = new DdexParser();
const results = await Promise.all(
  xmlFiles.map(xml => parser.parse(xml, { validateReferences: false }))
);

Reference Resolution​

// Skip reference validation for faster parsing
const result = await parser.parse(xml, {
  validateReferences: false,
  includeRawExtensions: false
});