x12-parser

library1.3.0jsnpmunverified

x12-parser is a robust and efficient Node.js library designed for parsing X12 Electronic Data Interchange (EDI) files. Leveraging the native Node.js stream API, it specializes in handling exceptionally large multi-gigabyte files by processing them in chunks, significantly reducing RAM usage compared to in-memory parsers. The library is fully typed with TypeScript, boasts 100% code coverage, and has zero production dependencies, making it a lightweight and reliable choice for EDI processing workflows. The current stable version is 1.3.0, with recent updates focusing on TypeScript and ESM conversion, indicating an active development cadence. It exports both CommonJS and ES Modules, easing integration into modern Node.js environments. Key differentiators include its stream-first approach for performance and memory efficiency, complete type definitions, and minimal external footprint, ideal for scenarios requiring high-throughput EDI parsing.

data

npm install x12-parser

github ↗package ↗

INSTALL

IMPORT

SIG · X12-PARSER

x12-parser

datajavascriptv1.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

X12parser

✓ import { X12parser } from 'x12-parser';

✗ const { X12parser } = require('x12-parser');

The library transitioned to ESM-only imports for its main exports in versions >=1.2.0. Ensure your project is configured for ES modules or use dynamic import.

createReadStream

✓ import { createReadStream } from 'node:fs';

✗ const { createReadStream } = require('fs');

While CommonJS `require('fs')` works, `node:fs` is the modern and recommended Node.js convention for core modules in ESM projects.

X12Segment

✓ import type { X12Segment } from 'x12-parser';

Although the `data` event emits a plain object, if explicit typing for the parsed segment object is desired for TypeScript projects, `X12Segment` (or similar) is the recommended type import pattern.

Demonstrates how to parse an X12 EDI file using `X12parser` as a Node.js Transform stream, handling data and errors for each parsed segment.

import { X12parser } from 'x12-parser'; import { createReadStream } from 'node:fs'; const myParser = new X12parser(); myParser.on('error', (err) => { console.error('Parser error:', err); }); // Create a read stream from a file (replace './test-file.edi' with your X12 file path) const ediFile = createReadStream('./test-file.edi'); ediFile.on('error', (err) => { console.error('File read error:', err); }); // Handle events from the parser by piping the file stream into it console.log('Starting X12 parsing...'); ediFile.pipe(myParser) .on('data', (data) => { // Each 'data' event provides a parsed segment object console.log('Parsed Segment:', data); }) .on('end', () => { console.log('X12 parsing complete.'); }) .on('close', () => { console.log('Parser stream closed.'); }); // Example of how to stop the stream early if needed // setTimeout(() => { // ediFile.destroy(); // console.log('Stream destroyed early.'); // }, 5000);

Debug

Known issues

breakingVersion 1.2.0 introduced a significant refactor, converting the library to TypeScript and ES Modules (ESM). This change breaks CommonJS `require()` syntax for the main exports and requires projects to use `import` statements.

fix

Migrate your project to use ES module `import { X12parser } from 'x12-parser';` statements. Ensure your `package.json` specifies `"type": "module"` or use `.mjs` file extensions.

affects: >=1.2.0

gotchaThe `X12parser` constructor expects an options object for configuration (e.g., `{ defaultEncoding: 'utf8' }`). Directly passing a string, as suggested in an older README example like `X12parser('utf8')`, is incorrect and will likely be ignored or cause a TypeError.

fix

When providing options to the parser, always pass an object: `new X12parser({ defaultEncoding: 'utf8' })`.

affects: >=1.2.0

gotchaThe parser normalizes X12 segment and component element names in the output object by removing leading zeros. For example, `ISA01` becomes `ISA1`, and `SVC01-01` becomes `SVC1-1`. This might require adjustments to downstream processing logic.

fix

Adapt your logic that consumes the parsed segment objects to account for the normalized (zero-stripped) numerical keys instead of expecting original X12 format keys.

affects: *

gotchaWhen using the optional 'Grouping' stage (not shown in quickstart), defining overly broad or unbounded loops in your schema can lead to significant memory consumption and reduced stream performance, especially with very large EDI files. The entire group must be held in memory before it is pushed downstream.

fix

Design your grouping schemas to break down X12 files into smaller, manageable chunks or logical envelopes, rather than attempting to group entire multi-gigabyte files into a single object.

affects: *

Errors

Common errors & fixes

TypeError: X12parser is not a constructor

Attempting to import `X12parser` using CommonJS `require()` syntax or trying to use it as a regular function after the library transitioned to ES Modules.

fix

Ensure your project is configured for ES Modules and use `import { X12parser } from 'x12-parser';` then `new X12parser();`.

ReferenceError: createReadStream is not defined

The `createReadStream` function from Node.js's built-in `fs` module was not imported before use.

fix

Add the import statement `import { createReadStream } from 'node:fs';` at the top of your file.

Parser error: Invalid character at position X

The input X12 EDI file contains unexpected or malformed characters, incorrect delimiters, or is not compliant with the expected X12 standard, causing the parser to fail.

fix

Inspect the X12 file for data integrity, correct encoding, and adherence to the X12 standard. You may need to sanitize or pre-process the input file.

ERR_STREAM_WRITE_AFTER_END

An attempt was made to write data to the `X12parser` stream after it had already ended or been closed, often due to improper handling of stream lifecycle events.

fix

Ensure that the input stream (e.g., `fs.createReadStream`) properly signals its end and no further data is piped into the parser once the source is exhausted or destroyed. Implement proper error handling and 'end' event listeners.

Upgrade

Version history

1.3.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

29 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/tastypackets/x12-parser ↗

packagehttps://www.npmjs.com/package/x12-parser ↗