Format Converter

A TypeScript library for converting various data formats (CSV, XML, HL7 v2) to JSON.

Features

• 🔄 Multi-format support: Convert CSV, XML, HL7 v2 to JSON
• 🏥 Healthcare focused: Specialized HL7 v2 message parsing and conversion to JSON
• 🔍 Format detection: Automatic content type detection
• 🛡️ Type-safe: Written in TypeScript with full type definitions
• 🧪 Well-tested: Comprehensive test suite

Installation

npm install @outburn/format-converter

Browser Compatibility

This library provides different builds for different environments:

Node.js (Full functionality)

import { FormatConverter, TypeConverter, FormatDetector } from '@outburn/format-converter';
// All features available including HL7 v2 conversion

Browser (Limited functionality)

Using IIFE (script tag):

<script src="node_modules/@outburn/format-converter/dist/browser.js"></script>
<script>
const { TypeConverter, FormatDetector } = FormatUtils;
// FormatConverter is not available in browser due to HL7.js dependency
</script>

Using ESM (module import):

import { TypeConverter, FormatDetector } from '@outburn/format-converter/browser';
// FormatConverter is not available in browser due to HL7.js dependency

Available exports:

// Classes
import { TypeConverter, FormatDetector } from '@outburn/format-converter/browser';

// Types
import type { ITypeConverter, IFormatDetector } from '@outburn/format-converter/browser';

// Enums
import { ContentType, ContentFormat, EditorLanguage } from '@outburn/format-converter/browser';

Browser limitations:

• ❌ FormatConverter is not available (requires HL7.js which is not browser-compatible)
• ❌ HL7 v2 parsing and conversion
• ✅ TypeConverter for type detection and conversion
• ✅ FormatDetector for format detection (JSON, XML, CSV, HL7)
• ✅ All type definitions and enums (ContentType, ContentFormat, EditorLanguage)
• ✅ TypeScript interfaces (ITypeConverter, IFormatDetector)

For full functionality including HL7 processing, use the Node.js version.

Usage

Basic Usage

import { FormatConverter } from '@outburn/format-converter';

const converter = new FormatConverter();

// Convert CSV to JSON
const csvData = `name,age,city
John,25,New York
Jane,30,Los Angeles`;

const jsonResult = await converter.toJson(csvData, 'text/csv');
console.log(jsonResult);

// Convert XML to JSON
const xmlData = `<?xml version="1.0"?>
<root>
  <person>
    <name>John</name>
    <age>25</age>
  </person>
</root>`;

const xmlToJson = await converter.toJson(xmlData, 'application/xml');
console.log(xmlToJson);

HL7 v2 Message Conversion

import { FormatConverter } from '@outburn/format-converter';

const converter = new FormatConverter();

// Convert HL7 v2 message to JSON
const hl7Message = `MSH|^~\\&|GHH LAB|ELAB-3|GHH OE|BLDG4|200202150930||ORU^R01|CNTRL-3456|P|2.4
PID|||PATID1234^5^M11^ADT1^MR^UNIVERSITY HOSPITAL~123456789^^^USSSA^SS||EVERYMAN^ADAM^A^III||19610615|M||C|1200 N ELM STREET^^GREENSBORO^NC^27401-1020|GL|(919)379-1212|(919)271-3434||S||PATID12345001^2^M10^ADT1^AN^A|123456789|9-87654^NC`;

const hl7ToJson = await converter.toJson(hl7Message, 'x-application/hl7-v2+er7');
console.log(hl7ToJson);

With Logging

import { FormatConverter } from '@outburn/format-converter';

// Custom logger implementation
const logger = {
  info: (message: string) => console.log(`[INFO] ${message}`),
  warn: (message: string) => console.warn(`[WARN] ${message}`),
  error: (message: string) => console.error(`[ERROR] ${message}`)
};

const converter = new FormatConverter(logger);

Type Conversion Utilities

import { TypeConverter } from '@outburn/format-converter';

const typeConverter = new TypeConverter();

// Convert MIME type strings to ContentType enum
const contentType = typeConverter.stringToContentType('text/csv');

// Detect format from content
const detectedFormat = typeConverter.detectFormat(csvData);

Supported Formats

This library converts the following input formats to JSON:

API Reference

FormatConverter

The main class for converting various formats to JSON.

Constructor

new FormatConverter(logger?: ILogger)

Parameters:

• logger (optional): Custom logger implementing the ILogger interface

Methods

toJson(input: any, contentType?: ContentType | string): Promise<any>

Converts input data to JSON format. This is the primary method for format conversion.

Parameters:

• input: The data to convert (string or object)
• contentType (optional): The MIME type or ContentType enum value of the input data. If not provided, defaults to application/json

Returns: Promise resolving to the converted JSON data

Example:

const result = await converter.toJson(csvData, 'text/csv');

csvToJson(input: string): Promise<any>

Converts CSV data to JSON format.

Parameters:

• input: CSV string to convert

Returns: Promise resolving to the converted JSON data

xmlToJson(input: string): Promise<any>

Converts XML data to JSON format.

Parameters:

• input: XML string to convert

Returns: Promise resolving to the converted JSON data

hl7v2ToJson(input: string): Promise<any>

Converts HL7 v2 message to JSON format.

Parameters:

• input: HL7 v2 message string to convert

Returns: Promise resolving to the converted JSON data

TypeConverter

Utility class for converting between different content type representations.

Methods

stringToContentType(contentType: string): ContentType | null

Converts a MIME type string to a ContentType enum value.

Parameters:

• contentType: MIME type string (e.g., 'text/csv', 'application/xml')

Returns: ContentType enum value or null if not found

Example:

const contentType = typeConverter.stringToContentType('text/csv');
// Returns: ContentType.CSV

stringToContentFormat(format: string): ContentFormat | null

Converts a format string to a ContentFormat enum value.

Parameters:

• format: Format string (e.g., 'json', 'csv', 'xml', 'hl7')

Returns: ContentFormat enum value or null if not found

stringToEditorLanguage(editorLanguage: string): EditorLanguage | null

Converts a language string to an EditorLanguage enum value.

Parameters:

• editorLanguage: Editor language string (e.g., 'json', 'xml', 'plaintext')

Returns: EditorLanguage enum value or null if not found

contentTypeToContentFormat(contentType: ContentType): ContentFormat

Converts a ContentType enum to a ContentFormat enum.

Parameters:

• contentType: ContentType enum value

Returns: Corresponding ContentFormat enum value

contentTypeToEditorLanguage(contentType: ContentType): EditorLanguage

Converts a ContentType enum to an EditorLanguage enum.

Parameters:

• contentType: ContentType enum value

Returns: Corresponding EditorLanguage enum value

contentFormatToContentType(format: ContentFormat): ContentType | null

Converts a ContentFormat enum to a ContentType enum.

Parameters:

• format: ContentFormat enum value

Returns: Corresponding ContentType enum value or null if not applicable

contentFormatToEditorLanguage(format: ContentFormat): EditorLanguage

Converts a ContentFormat enum to an EditorLanguage enum.

Parameters:

• format: ContentFormat enum value

Returns: Corresponding EditorLanguage enum value

FormatDetector

Utility class for automatically detecting content formats from input strings.

Methods

detectContentType(input: string): ContentType | null

Detects the content type of the input string and returns the corresponding ContentType enum.

Parameters:

• input: String content to analyze

Returns: ContentType enum value or null if format cannot be determined

Example:

const detector = new FormatDetector();
const contentType = detector.detectContentType(csvData);
// Returns: ContentType.CSV

detectFormat(input: string): ContentFormat

Analyzes the input string and detects its format.

Parameters:

• input: String content to analyze

Returns: ContentFormat enum value (returns ContentFormat.UNKNOWN if format cannot be determined)

Example:

const detector = new FormatDetector();
const format = detector.detectFormat(xmlData);
// Returns: ContentFormat.XML

detectEditorLanguage(input: string): EditorLanguage

Detects the appropriate editor language syntax highlighting for the input content.

Parameters:

• input: String content to analyze

Returns: EditorLanguage enum value

Example:

const detector = new FormatDetector();
const language = detector.detectEditorLanguage(jsonData);
// Returns: EditorLanguage.JSON

Development

Building

npm run build

Testing

npm test

Linting

npm run lint

Dependencies

• csvtojson: CSV parsing functionality
• fast-xml-parser: XML parsing and conversion
• hl7-dictionary: HL7 v2 message definitions
• hl7js: HL7 message parsing utilities
• jsonata: JSON transformation and querying

License

MIT © Outburn Ltd. 2025. All Rights Reserved.

Disclaimer

This project is part of the FUME open-source initiative and intended for use in FHIR tooling and development environments.

Support

For issues and questions, please use the GitHub Issues page.