Installation

@cosyte/x12 is a TypeScript ASC X12 toolkit for Node.js. It ships dual ESM + CJS builds with per-condition type declarations, so it works from either module system without configuration, and it has zero runtime dependencies: Node stdlib only.

Status: the 0.1 line, published on npm and public. The npm install below is live. Below 1.0 a breaking change bumps the minor version and is called out in the changelog with its migration. Run npm view @cosyte/x12 version for the current version: it is the source of truth.

Prerequisites

• Node.js 22 or later, tested on 22 and 24. The whole @cosyte/* suite targets ES2023.
• A package manager: pnpm, npm, or yarn.
• No runtime dependencies. The parser, serializer, builders, and bundled HIPAA code-list snapshots are all Node stdlib only. The zero-dep rule is a release gate, not a preference. A new runtime dep needs an ADR and a changelog entry.

Install

npm install @cosyte/x12

Smoke test

Confirm the package resolves and a real entry point is callable. Decode the smallest valid interchange envelope and read its detected delimiters back:

import { parseX12 } from "@cosyte/x12";

const raw =
  "ISA*00*          *00*          *ZZ*SENDER         *ZZ*RECEIVER       " +
  "*260601*1200*^*00501*000000001*0*P*:~" +
  "IEA*0*000000001~";

const ix = parseX12(raw);

ix.delimiters.element; // => "*"
ix.delimiters.segment; // => "~"
ix.isa.elements[16]; // => ":"
Array.isArray(ix.warnings); // => true

If that resolves and returns, the install is good. Head to the Quickstart.

Module systems

@cosyte/x12 is "type": "module" and exposes both conditions, so both of these resolve to the right build without extra configuration:

// ESM / TypeScript
import { parseX12, get835 } from "@cosyte/x12";

// CommonJS
const { parseX12, get835 } = require("@cosyte/x12");

The single top-level entry point (@cosyte/x12) publishes per-condition types (.d.ts for import, .d.cts for require), gated by attw on every release, and resolves under both node16 and legacy node10 module resolution. Editor IntelliSense matches the build you actually load.

PHI discipline

Every example in this documentation uses synthetic fixtures: fabricated names, obviously-fake IDs, pre-2024 control numbers. Do the same in your own tests: X12 healthcare interchanges carry PHI, and a real interchange committed to a repository is a leak the moment it publishes. See Troubleshooting for how the parser keeps field content out of its warnings and logs.