DEV Community

hello-ediflow
hello-ediflow

Posted on • Edited on

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

#javascript #opensource #showdev #typescript

"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.

?? Website | ? Star 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)