DEV Community

hello-ediflow
hello-ediflow

Posted on

EDIFlow v0.3.0: X12, HIPAA & EANCOM Support for TypeScript — The Way of Water

#opensource #typescript #showdev #javascript

"Water doesn't fight obstacles. It flows." — Lao Tzu

EDI data should move through systems naturally — adapting to any standard, connecting everything, never fighting complexity. That's the philosophy behind EDIFlow. And v0.3.0 is the biggest step yet.

What is EDIFlow?

EDIFlow is an open-source TypeScript library for parsing, validating and building EDI messages — type-safe, zero-config, built with Clean Architecture.

If you've ever dealt with raw EDI like this:

ISA*00*          *00*          *ZZ*SENDER         *ZZ*RECEIVER       *260101*1200*^*00401*000000001*0*T*:~
GS*PO*SENDER*RECEIVER*20260101*1200*1*X*004010~
ST*850*0001~
BEG*00*SA*ORDER12345**20260101~
Enter fullscreen mode Exit fullscreen mode

...and wished there was a modern, type-safe TypeScript API to work with it — that's exactly what EDIFlow solves.

v0.3.0 — What's new

🔷 X12 — Two full versions

X12 is the dominant EDI standard in North America — used in retail, logistics, healthcare, finance.

v0.3.0 ships two complete X12 version packages:

Package Version Transaction Sets
@ediflow/x12-004010 X12 004010 293 transaction sets
@ediflow/x12-006040 X12 006040 319 transaction sets

850 (Purchase Order), 810 (Invoice), 856 (Ship Notice), 837 (Healthcare Claim), 835 (Remittance), 997 (Acknowledgment), 214, 204, 210 and hundreds more.

import { X12ServiceBuilder } from '@ediflow/x12';
import { x12_004010Repository } from '@ediflow/x12-004010';

const service = new X12ServiceBuilder()
  .withRepository(x12_004010Repository)
  .build();

const result = await service.parse(rawX12String);
// Fully typed — TypeScript knows the structure
console.log(result.message.segments[0].tag); // 'ISA'
Enter fullscreen mode Exit fullscreen mode

Switch to 006040 by swapping one import — no other code changes needed.

🏥 HIPAA X12 005010 — Healthcare EDI

14 HIPAA-specific transaction sets out of the box:

  • 837P — Professional Claim
  • 837I — Institutional Claim
  • 835 — Remittance Advice
  • 270/271 — Eligibility Inquiry & Response
  • 276/277 — Claim Status
  • 834 — Benefit Enrollment
  • 820 — Payment Order 
npm install @ediflow/core @ediflow/x12 @ediflow/hipaa-x12-005010
Enter fullscreen mode Exit fullscreen mode

🌍 EDIFACT — Full coverage across 4 versions

EDIFACT is the international standard — dominant in Europe, logistics, supply chain.

All four versions are supported with complete message sets:

Package Version Messages
@ediflow/edifact-d96a D.96A 126 message types
@ediflow/edifact-d01b D.01B full standard
@ediflow/edifact-d12a D.12A full standard
@ediflow/edifact-d20b D.20B 195 message types

Every message type in the standard — ORDERS, INVOIC, DESADV, RECADV, SLSRPT, PRICAT, REMADV, IFTMIN, COPARN, APERAK, CONTRL, and hundreds more — available out of the box. No custom definitions needed.

npm install @ediflow/core @ediflow/edifact @ediflow/edifact-d20b
Enter fullscreen mode Exit fullscreen mode

🛒 EANCOM 2002 — GS1 Retail Standard

50 GS1 retail message types built on EDIFACT syntax. Covers the complete retail supply chain with full GS1 GLN party identification and EAN-13/GTIN product codes:

ORDERS, ORDRSP, DESADV, RECADV, INVOIC, REMADV, SLSRPT, PRICAT, INVRPT, PRODAT and more.

npm install @ediflow/core @ediflow/edifact @ediflow/eancom-2002
Enter fullscreen mode Exit fullscreen mode

🔄 Business Object Mapping — Round-Trip

This is the feature I'm most excited about. Instead of manually navigating segment arrays, you map EDI messages directly to/from typed JSON objects:

import { StructureMappingService } from '@ediflow/core';

const mappingService = new StructureMappingService();

// EDI → Business Object (JSON)
const order = mappingService.map(parsedMessage);
console.log(order['BGM']['1004']); // "ORDER12345" — document number

// Modify the business object
order['BGM']['1004'] = 'ORDER99999';

// Business Object → EDI (rebuild round-trip)
const rebuilt = mappingService.unmap(order);
Enter fullscreen mode Exit fullscreen mode

Five key strategies for property names: code, name, camelCase, snake_case, kebab-case — choose what fits your codebase.

⚙️ CLI enhancements

The @ediflow/cli package now supports business object output and schema export for both EDIFACT and X12:

# Parse to business object
npx @ediflow/cli parse invoice.edi --output-type business-object

# Export full JSON schema for a message type
npx @ediflow/cli export-schema --standard x12 --version 004010 --message 850

# Build EDI from a JSON business object
npx @ediflow/cli build order.json --standard edifact --version d20b --message ORDERS
Enter fullscreen mode Exit fullscreen mode

📂 Ready-to-run examples

Clone the repo and run any example with npx tsx:

git clone https://github.com/ediflow-lib/core.git
npm install

# X12
npx tsx examples/x12/parse-850/index.ts        # Parse Purchase Order
npx tsx examples/x12/build-850/index.ts        # Build 850 + round-trip
npx tsx examples/x12/validate-837/index.ts     # Validate Healthcare Claim
npx tsx examples/x12/multi-message/index.ts    # Parse 850 + 810 + 856 + 997

# EDIFACT
npx tsx examples/edifact/parse-orders/index.ts    # Parse ORDERS
npx tsx examples/edifact/build-invoic/index.ts    # Build INVOIC + round-trip

# HIPAA
npx tsx examples/hipaa/parse-837/index.ts     # Parse 837P Professional Claim

# EANCOM
npx tsx examples/eancom/parse-desadv/index.ts # Parse DESADV (GLN + EAN-13)
Enter fullscreen mode Exit fullscreen mode

All examples include real EDI sample data and commented output — no setup beyond npm install.

By the numbers

  • 📦 13 packages on NPM
  • 🔷 X12: 293 + 319 transaction sets across 2 versions
  • 🌍 EDIFACT: 126 + 195 message types across 4 versions
  • 🛒 EANCOM: 50 GS1 retail messages
  • 🏥 HIPAA: 14 transaction sets
  • ✅ 711 tests passing
  • 📊 ≥ 90% code coverage (@ediflow/core)
  • 0 TypeScript errors, 0 warnings
  • ⚖️ MIT License

Install 

# X12 004010 (293 transaction sets)
npm install @ediflow/core @ediflow/x12 @ediflow/x12-004010

# X12 006040 (319 transaction sets)
npm install @ediflow/core @ediflow/x12 @ediflow/x12-006040

# EDIFACT D.20B (195 messages)
npm install @ediflow/core @ediflow/edifact @ediflow/edifact-d20b

# HIPAA
npm install @ediflow/core @ediflow/x12 @ediflow/hipaa-x12-005010

# EANCOM 2002
npm install @ediflow/core @ediflow/edifact @ediflow/eancom-2002
Enter fullscreen mode Exit fullscreen mode

→ Full changelog
→ Examples
→ Quick Start

The Way of Water 🌊

I've been building EDIFlow alone — no team, no funding. Just a belief that TypeScript developers working in supply chain, logistics, and healthcare deserve better EDI tooling than what exists today.

The name isn't accidental. Inspired by the Taoist "Way of Water": EDI data should move through systems naturally — adapting to any standard, connecting everything, never forcing complexity on the developer.

💧 Finds its way — intelligent parsing, adaptive error handling
🌊 Adapts to any form — EDIFACT, X12, HIPAA, EANCOM, more coming
💪 Powerful but gentle — enterprise-grade performance, clean API
🔄 Connects everything — one unified interface for all EDI standards

If this resonates — or if you're tired of fighting brittle EDI parsers — consider giving the project a ⭐ on GitHub. It helps others find it.

⭐ Star EDIFlow on GitHub

What EDI standard are you working with? Drop a comment — I'd love to know what matters most for the next release.

Top comments (0)