A Node.js library for parsing and generating X12 EDI files
npm install node-x12-edi
Build, parse, and master X12 with precision — the Node.js way.
mapSegments(mapLogic) and generate JSON → EDI using toX12(json, mapLogic).
FieldMap and LoopMap to define how your JSON schema connects to segments and loops, offering clarity and reusability.
_type keys — perfect for serverless environments, configuration files, and database storage.
bash
npm install node‑x12‑edi
`
`js
import Transaction from "node‑x12‑edi";
import { FieldMap, LoopMap } from "node‑x12‑edi";
// 1. Define your mapping logic (class-based)
const mapLogic = {
header: {
date: new FieldMap({ segmentIdentifier: "GS", valuePosition: 4 }),
receiptNumber: new FieldMap({ segmentIdentifier: "W17", valuePosition: 2 }),
},
detail: {
items: new LoopMap({
position: 0,
values: {
itemCode: new FieldMap({ segmentIdentifier: "W07", valuePosition: 4 }),
lotCode: new FieldMap({ segmentIdentifier: "W07", valuePosition: 7 }),
weight: new FieldMap({ segmentIdentifier: "W20", valuePosition: 3 }),
},
}),
},
};
// 1. Alternative: Define mapping logic as plain JSON (great for serverless!)
const jsonMapLogic = {
header: {
date: { _type: "FieldMap", segmentIdentifier: "GS", valuePosition: 4 },
receiptNumber: {
_type: "FieldMap",
segmentIdentifier: "W17",
valuePosition: 2,
},
},
detail: {
items: {
_type: "LoopMap",
position: 0,
values: {
itemCode: {
_type: "FieldMap",
segmentIdentifier: "W07",
valuePosition: 4,
},
lotCode: {
_type: "FieldMap",
segmentIdentifier: "W07",
valuePosition: 7,
},
weight: {
_type: "FieldMap",
segmentIdentifier: "W20",
valuePosition: 3,
},
},
},
},
};
// 2. Parse EDI to JSON (works with either mapLogic format)
const transaction = new Transaction();
transaction.generateSegments(ediString);
transaction.runLoops(); // necessary to build loop contexts
const json = transaction.mapSegments(jsonMapLogic); // auto-revives JSON to classes
console.log("Parsed JSON:", json);
// 3. Generate EDI back from JSON
const edi = transaction.toX12(json, jsonMapLogic);
console.log("Regenerated EDI:", edi);
`
---
$3
| Feature | Description |
| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
| Flexible mapping | Use FieldMap and LoopMap to easily map between hierarchical JSON and flat EDI formats. |
| JSON mapLogic | Define mapping logic as plain JSON with _type keys — perfect for config files and serverless environments. |
| Two-way conversion | Fully supports EDI → JSON and JSON → EDI conversion using the same mapping structure. |
| Loop support | Automatically handles repeating segments via LoopMap and RepeatingSegmentMap. |
| High performance | Pre-compiles mapping logic to minimize per-conversion overhead. |
| Clear API | Intuitive class methods — generateSegments, mapSegments, toX12. |
---
$3
- Create reusable mapLogic: Define a library of mappings per transaction type (e.g. 944, 850, 810) for reuse.
- Serverless-friendly: Store JSON mapLogic in databases, config files, or environment variables — no class instantiation needed.
- Add formats: Implement validation, segment padding, or normalized date formatting.
- Test coverage: Use real-world EDI samples and round-trip your JSON mappings.
- CLI wrapper: Create a lightweight CLI tool like edi2json or json2edi` leveraging this library.