src/x12

@cosyte/synth/x12: the X12 EDI generation surface, exposed as its own subpath so importing the package root does not pull @cosyte/x12. This is the lazy, per-format boundary: a consumer who only needs X12 fixtures imports @cosyte/synth/x12; one who needs only the core primitives never loads a parser. @cosyte/x12 is an optional peer dependency, present only for this subpath.

This subpath ships spec-clean HIPAA 005010 generation via @cosyte/x12's domain builders: 837P/I/D claims (generate837P/generate837I/generate837D), the 835 remittance (generate835), and the 271 eligibility response (generate271), each built through the parser's own builder so the ISA/GS/ST…SE/GE/IEA envelope and every segment are spec-clean by construction, each round-tripping through @cosyte/x12 with zero warnings, and each drawing every subscriber/patient/provider identifier from the synthetic-safety providers.

Deferred (coverage tracks the builder): the 270 request (@cosyte/x12 ships no build270) and quirk mode.

Interfaces

Generate271Options

Options for generate271.

Properties

seed

readonly seed: number

The seed (deterministic: same seed yields a byte-identical interchange).

---

Generate835Options

Options for generate835.

Properties

seed

readonly seed: number

The seed (deterministic: same seed yields a byte-identical interchange).

---

Generate837Options

Options for generate837.

Properties

seed

readonly seed: number

The seed (deterministic: same seed yields a byte-identical interchange).

---

RoundTripResult

The verdict of one round-trip through @cosyte/x12.

Properties

byteStable

readonly byteStable: boolean

Whether re-serializing the re-parsed interchange is byte-identical to content.

content

readonly content: string

The serialized X12 EDI (the builder/serializer's own conservative emit).

specClean

readonly specClean: boolean

true iff the artifact is spec-clean: zero warnings and byte-stable.

warnings

readonly warnings: readonly string[]

The warning codes the parser emitted on re-parse. Empty ⇒ spec-clean.

---

X12CorpusOptions

Options for x12Corpus.

Properties

count?

readonly optional count?: number

How many transactions to generate. Defaults to the length of the mix.

mix?

readonly optional mix?: readonly X12CorpusKind[]

The transaction kinds to cycle through. Defaults to one of each.

seed

readonly seed: number

The seed for the whole corpus (deterministic).

---

X12EnvelopeTiming

A seeded interchange/group/transaction envelope timing + control-number bundle.

Properties

groupControlNumber

readonly groupControlNumber: string

GS-06 group control number.

interchangeControlNumber

readonly interchangeControlNumber: string

ISA-13 interchange control number (9 digits).

interchangeDate

readonly interchangeDate: string

ISA-09 interchange date YYMMDD.

interchangeTime

readonly interchangeTime: string

ISA-10 interchange time HHMM.

serviceDate

readonly serviceDate: string

A CCYYMMDD transaction/service base date (recent, seeded).

transactionSetControlNumber

readonly transactionSetControlNumber: string

ST-02 transaction set control number (4+ digits).

---

X12ExampleCode

A code drawn from a pool, with the X12 qualifier that names its code system.

Properties

code

readonly code: string

The code value (the element or composite component).

label

readonly label: string

A short human label, documentation only, never emitted.

---

X12Organization

A synthetic billing organization: org name + invalid-Luhn NPI + never-issued-SSN tax id.

Properties

address

readonly address: SyntheticAddress

Synthetic postal address.

name

readonly name: string

A clearly-fictional organization name.

npi

readonly npi: string

A 10-digit NPI with a deliberately-invalid Luhn check digit (never a real NPI).

taxIdSsn

readonly taxIdSsn: string

The provider tax id as a never-issued (900-range) SSN, emitted at REF*SY.

---

X12Payer

A synthetic payer: name + a synthetic payer id (PI).

Properties

name

readonly name: string

A clearly-fictional payer name.

payerId

readonly payerId: string

The payer identifier (NM1PR...*PI), synthetic.

---

X12Person

A synthetic person (subscriber / patient / rendering provider): all fields from ../safe.

Properties

address

readonly address: SyntheticAddress

Synthetic postal address (reserved non-real ZIP).

dob

readonly dob: string

Date of birth CCYYMMDD from the seeded generator.

memberId

readonly memberId: string

Member/cardholder id, synthetic-AA scoped (all-digit under a synthetic namespace).

person

readonly person: SyntheticName

Name from the shipped fake-name pool.

sex

readonly sex: "M" | "F"

Administrative sex (X12 DMG-03 M/F).

---

X12TradingPartners

The submitter / receiver trading-partner identity for the interchange envelope.

Properties

receiverId

readonly receiverId: string

ISA-08 / receiver id.

senderId

readonly senderId: string

ISA-06 / submitter id.

Type Aliases

Claim837Variant

Claim837Variant = "P" | "I" | "D"

The 837 variant to generate.

---

X12CorpusKind

X12CorpusKind = "837P" | "837I" | "837D" | "835" | "271"

Every X12 transaction kind x12Corpus generates: the label used as the corpus kind.

Variables

CARC_CODES

const CARC_CODES: readonly string[]

Claim adjustment reason codes (CARC: CAS-02) paired with a group code. CARC is a public WPC code list; these are the handful used in the 835 TR3 examples. Structural placeholders only.

---

DENTAL_PROCEDURES

const DENTAL_PROCEDURES: readonly X12ExampleCode[]

CDT dental procedure codes (837D SV3-01-2, qualifier AD): spec-example codes.

---

DIAGNOSES

const DIAGNOSES: readonly X12ExampleCode[]

ICD-10-CM diagnosis codes (HI qualifier ABK principal / ABF secondary): codes from the TR3 examples. Structural placeholders only. Each is written without its decimal point (J209 for J20.9), as the 005010 claim guides transmit a diagnosis code.

---

INSTITUTIONAL_PROCEDURES

const INSTITUTIONAL_PROCEDURES: readonly X12ExampleCode[]

Institutional procedure codes paired with revenue lines (837I SV2-02-2, qualifier HC).

---

PLACES_OF_SERVICE

const PLACES_OF_SERVICE: readonly string[]

Place-of-service codes (CLM-05-1 / SV1-05).

---

PROCEDURE_MODIFIERS

const PROCEDURE_MODIFIERS: readonly string[]

Professional procedure modifiers (SV1-01-3..6).

---

PROFESSIONAL_PROCEDURES

const PROFESSIONAL_PROCEDURES: readonly X12ExampleCode[]

HCPCS/CPT professional procedure codes (SV1-01-2, qualifier HC): office-visit / lab E&M codes from the 837P TR3 examples. Structural placeholders only.

---

REVENUE_CODES

const REVENUE_CODES: readonly X12ExampleCode[]

NUBC revenue codes (837I SV2-01): spec-example codes.

---

SERVICE_TYPE_CODES

const SERVICE_TYPE_CODES: readonly string[]

Service type codes (271 EB-03): the public X12 code list 1365, spec-example subset.

---

TOOTH_CODES

const TOOTH_CODES: readonly string[]

ADA tooth codes (837D TOO-02, qualifier JP) + surfaces (TOO-03).

---

TOOTH_SURFACES

const TOOTH_SURFACES: readonly string[]

Tooth surface codes (TOO-03).

Functions

dec()

dec(value): X12Decimal

A non-null X12Decimal from a decimal string. Throws on an unparseable string: the generators only ever pass literals or ${n}.00 strings, so the throw is a defensive guard, never a runtime path.

Parameters

value

string

A decimal string, e.g. "150.00".

Returns

X12Decimal

The parsed "@cosyte/x12".X12Decimal.

Throws

SynthError SYNTH_INVALID_DECIMAL if value is not a valid X12 decimal. The refusal does not quote value: it is caller-supplied and a diagnostic is not a place to put caller input.

Example

import { dec } from "@cosyte/synth/x12";
dec("150.00"); // X12Decimal

---

generate271()

generate271(options): X12Interchange

Generate a spec-clean 005010X279A1 271 eligibility response, built through @cosyte/x12's build271: one information source (payer) → one information receiver (provider) → one subscriber with an active-coverage benefit. Every identity value is synthetic-by-construction; the returned interchange round-trips with zero warnings.

Parameters

options

Generate271Options

The seed. See Generate271Options.

Returns

X12Interchange

A frozen X12Interchange (feed it to ./round-trip.roundTrip to verify).

Example

import { generate271, roundTrip } from "@cosyte/synth/x12";
const { specClean } = roundTrip(generate271({ seed: 3 }));
// specClean === true

---

generate835()

generate835(options): X12Interchange

Generate a spec-clean 005010X221A1 835 remittance, built through @cosyte/x12's build835. A single balanced claim with one service line: charge = payment + patientResponsibility, and the remit total equals the claim payment (no provider-level adjustments). Every identity value is synthetic-by-construction; the returned interchange round-trips with zero warnings.

Parameters

options

Generate835Options

The seed. See Generate835Options.

Returns

X12Interchange

A frozen X12Interchange (feed it to ./round-trip.roundTrip to verify).

Example

import { generate835, roundTrip } from "@cosyte/synth/x12";
const { specClean } = roundTrip(generate835({ seed: 7 }));
// specClean === true

---

generate837()

generate837(variant, options): X12Interchange

Generate a spec-clean 005010 837 claim of the given variant, built through @cosyte/x12's build837P / build837I / build837D. Every identity value is synthetic-by-construction; the returned interchange round-trips through @cosyte/x12 with zero warnings.

Parameters

variant

Claim837Variant

"P" professional, "I" institutional, or "D" dental.

options

Generate837Options

The seed. See Generate837Options.

Returns

X12Interchange

A frozen X12Interchange (feed it to ./round-trip.roundTrip to verify).

Example

import { generate837, roundTrip } from "@cosyte/synth/x12";
const { specClean } = roundTrip(generate837("P", { seed: 42 }));
// specClean === true

---

generate837D()

generate837D(options): X12Interchange

Generate a spec-clean 837D (Dental) claim.

Parameters

options

Generate837Options

The seed.

Returns

X12Interchange

A frozen X12Interchange.

Example

import { generate837D } from "@cosyte/synth/x12";
const ix = generate837D({ seed: 1 });

---

generate837I()

generate837I(options): X12Interchange

Generate a spec-clean 837I (Institutional) claim.

Parameters

options

Generate837Options

The seed.

Returns

X12Interchange

A frozen X12Interchange.

Example

import { generate837I } from "@cosyte/synth/x12";
const ix = generate837I({ seed: 1 });

---

generate837P()

generate837P(options): X12Interchange

Generate a spec-clean 837P (Professional) claim.

Parameters

options

Generate837Options

The seed.

Returns

X12Interchange

A frozen X12Interchange.

Example

import { generate837P } from "@cosyte/synth/x12";
const ix = generate837P({ seed: 1 });

---

money()

money(n): string

A whole-dollar ${n}.00 money string.

Parameters

n

number

The whole-dollar amount.

Returns

string

The ${n}.00 string.

Example

import { money } from "@cosyte/synth/x12";
money(150); // "150.00"

---

roundTrip()

roundTrip(interchange): RoundTripResult

Round-trip a built @cosyte/x12 X12Interchange through serialize → parse → serialize and report the verdict. A spec-clean interchange re-parses with zero warnings and re-serializes byte-identically.

Parameters

interchange

X12Interchange

The interchange to check (typically from a generate837P / generate835 / generate271).

Returns

RoundTripResult

The RoundTripResult.

Example

import { generate837P, roundTrip } from "@cosyte/synth/x12";
const { specClean, warnings } = roundTrip(generate837P({ seed: 1 }));
// specClean === true, warnings.length === 0

---

x12Corpus()

x12Corpus(options): Corpus

Build a reproducible Corpus of spec-clean X12 transactions. Each transaction is generated from a distinct sub-seed derived from the corpus seed (so the set is deterministic) and round-tripped through @cosyte/x12; the per-artifact warnings record the parser's verdict (empty ⇒ spec-clean).

Parameters

options

X12CorpusOptions

Seed, count, and the transaction mix. See X12CorpusOptions.

Returns

Corpus

A deep-frozen Corpus.

Example

import { x12Corpus } from "@cosyte/synth/x12";
const corpus = x12Corpus({ seed: 42 });
corpus.artifacts.every((a) => a.warnings.length === 0); // true, spec-clean

---

x12EnvelopeTiming()

x12EnvelopeTiming(rng): X12EnvelopeTiming

Mint a seeded envelope timing + control-number bundle. The service/transaction date is drawn in a recent plausible window (2024 to 2026) so a generated transaction reads like a current one; every value is seeded, so the interchange is byte-reproducible.

Parameters

rng

Rng

The seeded generator.

Returns

X12EnvelopeTiming

A synthetic X12EnvelopeTiming.

Example

import { createRng } from "@cosyte/synth";
import { x12EnvelopeTiming } from "@cosyte/synth/x12";
const timing = x12EnvelopeTiming(createRng(1));

---

x12Organization()

x12Organization(rng): X12Organization

Mint a synthetic billing organization: org name, an invalid-Luhn NPI, a never-issued-SSN tax id, and an address.

Parameters

rng

Rng

The seeded generator.

Returns

X12Organization

A synthetic X12Organization.

Example

import { createRng } from "@cosyte/synth";
import { x12Organization } from "@cosyte/synth/x12";
const org = x12Organization(createRng(1)); // org.npi is invalid-Luhn; org.taxIdSsn is 900-range

---

x12Payer()

x12Payer(rng): X12Payer

Mint a synthetic payer: a fictional name and a synthetic payer id.

Parameters

rng

Rng

The seeded generator.

Returns

X12Payer

A synthetic X12Payer.

Example

import { createRng } from "@cosyte/synth";
import { x12Payer } from "@cosyte/synth/x12";
const payer = x12Payer(createRng(1));

---

x12Person()

x12Person(rng): X12Person

Mint a synthetic person. Fixed draw order (name → member id → DOB → sex → address) so the same seed yields the same person.

Parameters

rng

Rng

The seeded generator.

Returns

X12Person

A synthetic X12Person.

Example

import { createRng } from "@cosyte/synth";
import { x12Person } from "@cosyte/synth/x12";
const { person, memberId } = x12Person(createRng(1));

---

x12ProviderPerson()

x12ProviderPerson(rng): object

Mint a synthetic rendering/service provider person: a person name plus an invalid-Luhn NPI.

Parameters

rng

Rng

The seeded generator.

Returns

object

The provider name and NPI.

npi

readonly npi: string

person

readonly person: SyntheticName

Example

import { createRng } from "@cosyte/synth";
import { x12ProviderPerson } from "@cosyte/synth/x12";
const rendering = x12ProviderPerson(createRng(1));

---

x12TradingPartners()

x12TradingPartners(rng): X12TradingPartners

Mint synthetic submitter/receiver trading-partner ids for the interchange envelope. These are not PHI, but are kept clearly synthetic for consistency.

Parameters

rng

Rng

The seeded generator.

Returns

X12TradingPartners

Synthetic X12TradingPartners.

Example

import { createRng } from "@cosyte/synth";
import { x12TradingPartners } from "@cosyte/synth/x12";
const { senderId, receiverId } = x12TradingPartners(createRng(1));