Skip to main content
Version: v0.0.4

Guides

Task-oriented recipes - "how do I X?" - for @cosyte/synth. Each guide is a short, copy-pasteable answer to one real fixture-generation question.

Status: the seeded-PRNG core, the synthetic-safety providers and the round-trip harness ship, alongside the HL7 v2 message set (ADT, ORU^R01, ORM^O01, SIU^S12, VXU^V04); FHIR R4 / US Core (see the FHIR guide); C-CDA generation (CCD + Referral Note via @cosyte/ccda's buildCcda, the C-CDA guide); X12 005010 (837P/I/D, 835, 271 via @cosyte/x12, the X12 guide); NCPDP (SCRIPT + Telecom via @cosyte/ncpdp, the NCPDP guide); and ASTM (E1394 records + E1381 framing via @cosyte/astm, the ASTM guide) - the spec-clean generation core across all six formats. On top of it, vendor-quirk generation for HL7 v2, C-CDA, and ASTM (see the quirk guide). A guide is only written once the behavior it documents is shipped and its runnable example passes the doc/code-agreement check.

Pin a seed for a reusable golden fixture​

A Corpus is a seed plus a manifest of what was generated - deep-frozen and self-describing. Pin the seed (and the synth version) and every downstream run regenerates the identical set:

import { hl7Corpus } from "@cosyte/synth/hl7";

const corpus = hl7Corpus({ seed: 1867, count: 4 });

corpus.seed; // => 1867

Verify an artifact round-trips before you trust it​

The round-trip harness proves spec-cleanliness by the parser's own judgment - a spec-clean artifact re-parses with zero warnings and re-serializes byte-identically:

import { generateAdt, roundTrip } from "@cosyte/synth/hl7";

const { warnings, byteStable } = roundTrip(generateAdt({ seed: 21 }));

[warnings.length, byteStable]; // => [0, true]

Planned guides​

Shipped: vendor-quirk generation - inject the deviations a parser tolerates, each round-tripping to exactly the intended warning code (HL7 v2, C-CDA, and ASTM). Expect recipes such as:

  • Feed a parser's three-tier conformance corpus - tiers 1 and 2, mechanically and seedably.
  • Pair with @cosyte/deid - generate clean, plant tagged synthetic sentinels, de-identify, verify.
  • Quirk recipes for FHIR, X12, and NCPDP - as those parsers' profile/quirk surface lands.

Until then, the Quickstart covers the core primitives and the HL7 corpus.