@ediflow/core

Modern EDI Parser, Validator & Builder — EDIFACT, X12, EANCOM & HIPAA

Clean Architecture • Type-Safe • Zero Config • Battle-Tested

🆕 What's New in v0.3.0

• ✅ X12 Support — Full ISA/GS/ST/SE/GE/IEA envelope parsing & validation (850, 810, 837, 856, ...)
• ✅ Business Object Mapping — StructureMappingService.map() / unmap() with 5 key strategies
• ✅ Schema Export — ExportSchemaUseCase for JSON Schema + YAML via CLI
• ✅ HIPAA — @ediflow/hipaa-x12-005010 data package (14 transaction sets)
• ✅ EANCOM — @ediflow/eancom-2002 data package (50 message types)
• ✅ 857 tests passing across all packages

📦 What is @ediflow/core?

@ediflow/core is the core engine for EDIFlow — a modern EDI library for EDIFACT, X12, EANCOM and HIPAA, built with Clean Architecture principles.

This package provides:

• ✅ Parser - EDIFACT string → EDIMessage
• ✅ Validator - 3-phase validation (Syntax → Structure → Business)
• ✅ Builder - EDIMessage → EDIFACT string
• ✅ Mapper - Auto-convert to/from business objects
• ✅ Envelope Generator - UNH/UNT/UNB/UNZ support
• ✅ CLI - Command-line tools
• ✅ TypeScript - Full type safety

What this package does NOT include:

• ❌ EDIFACT standard definitions (install separately)

🚀 Installation

# Always required
npm install @ediflow/core

# ── EDIFACT ──────────────────────────────────────────────────────────────────
npm install @ediflow/edifact            # EDIFACT parsers & builders
npm install @ediflow/edifact-d20b       # D.20B (2020) — 195 messages, latest
npm install @ediflow/edifact-d01b       # D.01B (2001) — 211 messages
npm install @ediflow/edifact-d12a       # D.12A (2012) — 196 messages
npm install @ediflow/edifact-d96a       # D.96A (1996) — 126 messages

# ── EANCOM (GS1 retail) ──────────────────────────────────────────────────────
npm install @ediflow/eancom-2002        # EANCOM 2002 — 49 messages

# ── X12 (USA / North America) ────────────────────────────────────────────────
npm install @ediflow/x12                # X12 parsers & validators
npm install @ediflow/x12-004010         # X12 004010 — 293 transaction sets
npm install @ediflow/x12-006040         # X12 006040 — 319 transaction sets (latest 2026)

# ── HIPAA (US healthcare) ─────────────────────────────────────────────────────
npm install @ediflow/hipaa-x12-005010   # HIPAA 005010 — 14 transaction sets

# ── Shared infrastructure (required for schema/mapping features) ──────────────
npm install @ediflow/infrastructure-shared

📖 Quick Start

Parse EDIFACT Message

import {
  EdifactMessageParser,
  EdifactDelimiterDetector,
  EdifactTokenizer,
  EdifactSegmentParser,
} from '@ediflow/edifact';

const parser = new EdifactMessageParser(
  new EdifactDelimiterDetector(),
  new EdifactTokenizer(),
  new EdifactSegmentParser(),
);

const message = parser.parse(edifactString);
console.log(message.standard);           // 'EDIFACT'
console.log(message.messageType.value);  // 'ORDERS'
console.log(message.version.value);      // 'D.96A'
console.log(message.segments.length);    // segment count

Map to Business Object

import { StructureMappingService } from '@ediflow/core';
import { FileBasedMessageStructureRepository } from '@ediflow/infrastructure-shared';

const repository = new FileBasedMessageStructureRepository('./node_modules');
const structure  = await repository.getMessageStructure('EDIFACT', 'D.96A', 'ORDERS');

const mapper = new StructureMappingService();
const order  = mapper.map(message, structure!, 'camelCase');
// order.beginningOfMessage.documentMessageNumber === 'PO-001'

Validate Message

import { EdifactValidationServiceBuilder } from '@ediflow/edifact';

const validator = EdifactValidationServiceBuilder.forEDIFACT();
const result    = validator.validate(message);

if (result.isValid) {
  console.log('✅ Valid!');
} else {
  result.errors.forEach(e => console.error(`❌ ${e.code}: ${e.message}`));
}

Build EDIFACT Message

import { EdifactMessageBuilder, EdifactEnvelopeBuilder } from '@ediflow/edifact';
import { EDIMessage, Standard, Version, MessageType, EDISegment, EDIElement } from '@ediflow/core';

const msg = new EDIMessage('1', Standard.EDIFACT, new Version(Standard.EDIFACT, 'D.20B'), new MessageType(Standard.EDIFACT, 'ORDERS'));
msg.addSegment(new EDISegment('BGM', [new EDIElement('220'), new EDIElement('PO-001'), new EDIElement('9')]));

const envelopeBuilder = new EdifactEnvelopeBuilder();
const wrapped         = envelopeBuilder.wrapMessage(msg, { messageRef: '1', messageType: msg.messageType, version: msg.version });

const builder    = new EdifactMessageBuilder();
const edifactStr = builder.build(wrapped);
console.log(edifactStr); // UNH+1+ORDERS:D:20B:UN'BGM+220+PO-001+9'UNT+2+1'

🎯 Features

Core Features

• Parse - EDIFACT → EDIMessage (with envelope support)
• Validate - 3-phase validation (Syntax, Structure, Business)
• Build - EDIMessage → EDIFACT (with envelope generation)
• Map - Business Objects ↔ EDIMessage
• CLI - Command-line interface

Clean Architecture

• Domain Layer - Pure business logic (zero dependencies)
• Application Layer - Use Cases (ParseEDI, ValidateMessage, BuildEDI)
• Infrastructure Layer - Parsers, Repositories
• Presentation Layer - CLI, Future: REST API

TypeScript Support

• Full TypeScript definitions
• Advanced type inference
• IntelliSense support
• Strict type checking

Zero Config

• Works out of the box
• Sensible defaults
• Easy to customize

📦 Related Packages

EDIFACT:

• @ediflow/edifact - EDIFACT parsers & builders (required for EDIFACT)
• @ediflow/edifact-d96a - D.96A (1996) — 126 message types
• @ediflow/edifact-d01b - D.01B (2001) — 211 message types
• @ediflow/edifact-d12a - D.12A (2012) — 196 message types
• @ediflow/edifact-d20b - D.20B (2020) — 195 message types (latest)

EANCOM (GS1 retail):

• @ediflow/eancom-2002 - EANCOM 2002 — 49 message types

X12 (USA / North America):

• @ediflow/x12 - X12 parsers & validators (required for X12)
• @ediflow/x12-004010 - X12 004010 — 293 transaction sets
• @ediflow/x12-006040 - X12 006040 — 319 transaction sets (latest 2026)

HIPAA (US healthcare):

• @ediflow/hipaa-x12-005010 - HIPAA 005010 — 14 transaction sets

Shared Infrastructure:

• @ediflow/infrastructure-shared - Repositories, loaders, cache

🏗️ Architecture

┌─────────────────────────────────────┐
│      Presentation Layer             │  CLI
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│      Application Layer              │  Use Cases
│  • ParseEDIUseCase                  │
│  • ValidateMessageUseCase           │
│  • BuildEDIUseCase                  │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│      Domain Layer                   │  Entities
│  • EDIMessage                       │
│  • EDISegment                       │
│  • EDIElement                       │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│      Infrastructure Layer           │  Parsers
│  • EdifactMessageParser             │
│  • FileBasedRepository              │
└─────────────────────────────────────┘

Read more: Architecture Documentation

📚 Documentation

• Quick Start Guide - Get started in 5 minutes
• Architecture - Clean Architecture explained
• Developer Guide - Contributing
• Examples - Runnable TypeScript examples

🧪 Testing

Extensively tested with TDD:

• 857 tests passing across all packages
• Unit tests - Domain & Application layers
• Integration tests - Cross-layer interactions
• E2E tests - Complete roundtrip validation

npm test
npm run test:watch
npm run test:coverage

🤝 Contributing

We welcome contributions! See:

• Contributing Guide
• Developer Guide

📄 License

MIT License - see LICENSE

🔗 Links

• GitHub: ediflow-lib/core
• NPM: @ediflow/core
• Issues: Report bugs
• Discussions: Ask questions

Made with ❤️ for the EDI community