@cosyte/synth 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.1.6
+
+### Patch Changes
+
+- d3c649c: Each format subpath now imports without loading its parser, and a corpus checks its artifacts in less time.
+
+  - Importing `@cosyte/synth/hl7`, `/fhir`, `/ccda`, `/x12`, `/ncpdp`, `/astm` or `/deid` no longer loads the sibling parser it builds through. The parser loads on the first call that needs it, synchronously, so every function keeps its signature. It is the same build an `import` or a `require` of the parser gives you, so a returned message, resource, document or interchange is an instance of the parser classes your own code imports. One thing moves: when an optional parser is not installed, the error that names it now comes from the first call that needs it, not from the import of the subpath. Install the parser for each format you generate, as before.
+  - Every corpus generator (`hl7Corpus`, `fhirCorpus`, `ccdaCorpus`, `x12Corpus`, `ncpdpCorpus`, `astmCorpus`) takes a new `verify` option. It defaults to `true`, which reads each artifact back through its parser and records the parser's findings as its `warnings`, as before. A corpus now reads each artifact back once and no longer serializes it a second time, since a corpus never reported byte stability; `roundTrip` and the other round-trip functions still check it. `verify: false` skips the read, a large share of a corpus's time, and leaves every artifact's `warnings` empty without checking it. Pass it when the corpus feeds a load test and the parser's verdict is not needed.
+  - The sibling parsers move to their latest releases: `@cosyte/hl7` 0.1.8, `@cosyte/fhir` 0.1.8, `@cosyte/ccda` 0.1.6, `@cosyte/x12` 0.1.10, `@cosyte/ncpdp` 0.1.6, `@cosyte/astm` 0.1.6 and `@cosyte/deid` 0.1.5, and each optional peer range now starts at that release.
+
+  Output change: X12. Every generated 271 now carries the BHT segment the 005010X279A1 guide requires right after its ST, because `@cosyte/x12` 0.1.10 writes it; its SE segment count is one higher, and the X12 271 de-identification loop result moves with it. A 271 golden file committed from an earlier release has to be regenerated. Every other generated artifact is byte for byte what it was for the same seed.
+
+## 0.1.5
+
+### Patch Changes
+
+- 3d13238: The exported example-code pools and the fatal-code registry are now frozen all the way down. `EXAMPLE_ASTM_TESTS` (`@cosyte/synth/astm`), `EXAMPLE_DRUGS` (`@cosyte/synth/ncpdp`) and the X12 pools `PROFESSIONAL_PROCEDURES`, `INSTITUTIONAL_PROCEDURES`, `DENTAL_PROCEDURES`, `REVENUE_CODES` and `DIAGNOSES` (`@cosyte/synth/x12`) froze the array but left each entry writable, so a JavaScript caller could rewrite an entry and change what every later call with the same seed generated. `SYNTH_FATAL_CODES` was not frozen at all, so a caller could change the code a later `SynthError` carried. Each entry and the registry are now frozen, as the other pools already were, and a write to one throws in strict mode.
+
+  No generated value, export, warning code or seed mapping changes.
+
+- cbae766: Doc comments only. `luhnMod10` is exported from `@cosyte/synth`, so it is public: its doc comment no longer marks it internal, and it now carries an example like any other export. The comment on the fatal-code module that ships in the type declarations now says in plain words how a parser handles bad input.
+
+  No generated value, export, warning code or seed mapping changes.
+
 ## 0.1.4
 
 ### Patch Changes

package/README.md

@@ -62,8 +62,9 @@ Node.js 22 or later, tested on 22, 24, and 26.
 `@cosyte/hl7`, `@cosyte/fhir`, `@cosyte/ccda`, `@cosyte/x12`, `@cosyte/ncpdp`, `@cosyte/astm`, and
 `@cosyte/deid` are **optional peer dependencies**, each needed only for its subpath (`@cosyte/synth/hl7`,
 `@cosyte/synth/fhir`, `@cosyte/synth/ccda`, `@cosyte/synth/x12`, `@cosyte/synth/ncpdp`,
-`@cosyte/synth/astm`, and `@cosyte/synth/deid`: the last needs `@cosyte/deid` **plus** the parsers for
-the formats it pairs): install only the packages whose fixtures you generate. The package core has
+`@cosyte/synth/astm`, and `@cosyte/synth/deid`: the last loads `@cosyte/deid` **plus** the five
+parsers it pairs, `@cosyte/hl7`, `@cosyte/fhir`, `@cosyte/ccda`, `@cosyte/x12`, and `@cosyte/ncpdp`,
+as soon as it is imported): install only the packages whose fixtures you generate. The package core has
 **zero third-party runtime dependencies**.
 
 ## Usage
@@ -367,21 +368,24 @@ isSyntheticNpi(safe.npi(rng)); // true, always a deliberately-invalid-Luhn NPI (
 
 The full reference is on [docs.cosyte.com/synth](https://docs.cosyte.com/synth):
 
-- [Installation](https://docs.cosyte.com/synth/installation) and the [quickstart](https://docs.cosyte.com/synth/quickstart).
-- Core concepts: [the archetype](https://docs.cosyte.com/synth/concepts-archetype) and the [limitations](https://docs.cosyte.com/synth/limitations).
-- Guides: [the overview](https://docs.cosyte.com/synth/guides-overview), [FHIR R4 and US Core](https://docs.cosyte.com/synth/guides-fhir),
+- [Installation](https://docs.cosyte.com/synth/installation), the [quickstart](https://docs.cosyte.com/synth/quickstart), and
+  a tutorial: [test your HL7 handling with generated fixtures](https://docs.cosyte.com/synth/test-hl7-handling-with-fixtures).
+- How-to guides: [HL7 v2](https://docs.cosyte.com/synth/guides-hl7), [FHIR R4 and US Core](https://docs.cosyte.com/synth/guides-fhir),
   [C-CDA](https://docs.cosyte.com/synth/guides-ccda), [X12](https://docs.cosyte.com/synth/guides-x12), [NCPDP](https://docs.cosyte.com/synth/guides-ncpdp),
-  [ASTM](https://docs.cosyte.com/synth/guides-astm), [vendor quirks](https://docs.cosyte.com/synth/guides-quirks), and
-  [the `@cosyte/deid` pairing loop](https://docs.cosyte.com/synth/guides-deid).
-- [Troubleshooting](https://docs.cosyte.com/synth/troubleshooting).
+  [ASTM](https://docs.cosyte.com/synth/guides-astm), [vendor quirks](https://docs.cosyte.com/synth/guides-quirks),
+  [the `@cosyte/deid` pairing loop](https://docs.cosyte.com/synth/guides-deid), [synthetic values](https://docs.cosyte.com/synth/draw-synthetic-values),
+  and [pinning a golden fixture](https://docs.cosyte.com/synth/guides-overview).
+- Explanation: [how it works](https://docs.cosyte.com/synth/concepts-archetype) and [what it does and does not do](https://docs.cosyte.com/synth/limitations).
+- Reference: [fatal codes](https://docs.cosyte.com/synth/fatal-codes), the [quirk catalog](https://docs.cosyte.com/synth/quirk-catalog), and the API reference.
+- [Troubleshooting](https://docs.cosyte.com/synth/troubleshooting), [testing and quality](https://docs.cosyte.com/synth/testing-and-quality), and [performance](https://docs.cosyte.com/synth/performance).
 - [`CHANGELOG.md`](https://github.com/cosyte/synth/blob/main/CHANGELOG.md): every release.
 
 ## Support
 
 Questions, bug reports, and requests for a format or a quirk go in
 [GitHub issues](https://github.com/cosyte/synth/issues). Every fixture this package makes is
-synthetic: never attach a real patient's data to an issue. For help with an integration test suite,
-see our [integration services](https://cosyte.com/integration-services).
+synthetic: never attach a real patient's data to an issue. Need an integration built and tested, or
+hosted and run for you? See our [integration services](https://cosyte.com/integration-services).
 
 ## Security
 

package/dist/astm/index.cjs

@@ -1,6 +1,15 @@
 'use strict';
 
-var astm = require('@cosyte/astm');
+var module$1 = require('module');
+var url = require('url');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
 
 // src/rng/splitmix32.ts
 function splitmix32(seed) {
@@ -32,7 +41,16 @@ function sfc32Next(s) {
 }
 
 // src/codes.ts
-var SYNTH_FATAL_CODES = {
+var SYNTH_FATAL_CODES = Object.freeze({
+  /**
+   * A format was requested that this build cannot generate through a real parser builder/serializer.
+   * Fatal, never a hand-written byte fallback.
+   *
+   * **No code path in this build raises it.** All six formats generate, so it is reserved for a
+   * future format that does not, and is kept because removing a published code is a breaking change.
+   * An unsupported *kind* within a format that does generate is `SYNTH_UNSUPPORTED_KIND`.
+   */
+  SYNTH_UNSUPPORTED_FORMAT: "SYNTH_UNSUPPORTED_FORMAT",
   /**
    * A vendor quirk was requested that the target format's profile system does not support. Fatal,
    * never a silent no-op and never a fabricated quirk.
@@ -49,6 +67,10 @@ var SYNTH_FATAL_CODES = {
    * warning code(s). Fatal, never emit a mislabeled fixture.
    */
   SYNTH_INTENDED_WARNING_MISMATCH: "SYNTH_INTENDED_WARNING_MISMATCH",
+  /** A concept's code-system URI has no OID mapping in the C-CDA example-code table. Fatal. */
+  SYNTH_UNMAPPED_CODE_SYSTEM: "SYNTH_UNMAPPED_CODE_SYSTEM",
+  /** A money value could not be read as an X12 decimal. Fatal: a generator never rounds to a float. */
+  SYNTH_INVALID_DECIMAL: "SYNTH_INVALID_DECIMAL",
   /** An integer range was requested with its maximum below its minimum. Fatal. */
   SYNTH_INVALID_RANGE: "SYNTH_INVALID_RANGE",
   /** A value was drawn from an empty pool. Fatal, never a fabricated substitute. */
@@ -61,7 +83,17 @@ var SYNTH_FATAL_CODES = {
    * see `resolveKind`: a selector union is erased at run time, and a selector that falls through
    * either mislabels the fixture or hands the value to a peer builder that quotes it back.
    */
-  SYNTH_UNSUPPORTED_KIND: "SYNTH_UNSUPPORTED_KIND"};
+  SYNTH_UNSUPPORTED_KIND: "SYNTH_UNSUPPORTED_KIND",
+  /**
+   * A requested profile IS published by the adopted implementation guide, and this build does not
+   * generate it. Deliberately distinct from `SYNTH_UNSUPPORTED_KIND`, which says the name is not in
+   * the adopted set at all: "the guide does not publish this" and "we do not generate this yet" are
+   * different answers, and a caller building to a regulatory profile set has to be able to tell them
+   * apart without matching message text. Fatal, and raised **before** anything is generated: a
+   * mislabelled artifact is worse than no artifact.
+   */
+  SYNTH_PROFILE_NOT_GENERATED: "SYNTH_PROFILE_NOT_GENERATED"
+});
 var SYNTH_FATAL_MESSAGES = Object.freeze({
   SYNTH_UNSUPPORTED_FORMAT: "The requested format is not generable by this build. A generator has no byte fallback: it builds through a parser's own serializer or it refuses.",
   SYNTH_UNSUPPORTED_QUIRK: "The requested vendor quirk is not in the target format's quirk registry. Compare the request against that format's exported registry (HL7_QUIRKS, CCDA_QUIRKS, ASTM_QUIRKS).",
@@ -127,6 +159,7 @@ function createRng(seed) {
 }
 
 // src/corpus.ts
+var UNCHECKED = Object.freeze([]);
 function makeCorpus(seed, artifacts, quirks = []) {
   const counts = {};
   const formats = /* @__PURE__ */ new Set();
@@ -472,88 +505,90 @@ function astmHeaderIdentity(rng) {
 }
 
 // src/astm/example-codes.ts
-var EXAMPLE_ASTM_TESTS = Object.freeze([
-  {
-    localCode: "GLU",
-    loinc: "2345-7",
-    name: "Glucose",
-    units: "mg/dL",
-    referenceRange: "70-110",
-    valueLow: 55,
-    valueHigh: 260,
-    decimals: 0
-  },
-  {
-    localCode: "K",
-    loinc: "2823-3",
-    name: "Potassium",
-    units: "mmol/L",
-    referenceRange: "3.5-5.1",
-    valueLow: 28,
-    valueHigh: 62,
-    decimals: 1
-  },
-  {
-    localCode: "NA",
-    loinc: "2951-2",
-    name: "Sodium",
-    units: "mmol/L",
-    referenceRange: "136-145",
-    valueLow: 125,
-    valueHigh: 155,
-    decimals: 0
-  },
-  {
-    localCode: "CREA",
-    loinc: "2160-0",
-    name: "Creatinine",
-    units: "mg/dL",
-    referenceRange: "0.6-1.3",
-    valueLow: 4,
-    valueHigh: 32,
-    decimals: 1
-  },
-  {
-    localCode: "HGB",
-    loinc: "718-7",
-    name: "Hemoglobin",
-    units: "g/dL",
-    referenceRange: "12.0-17.5",
-    valueLow: 80,
-    valueHigh: 190,
-    decimals: 1
-  },
-  {
-    localCode: "WBC",
-    loinc: "6690-2",
-    name: "Leukocytes",
-    units: "10*3/uL",
-    referenceRange: "4.5-11.0",
-    valueLow: 30,
-    valueHigh: 150,
-    decimals: 1
-  },
-  {
-    localCode: "TSH",
-    loinc: "3016-3",
-    name: "Thyrotropin",
-    units: "mIU/L",
-    referenceRange: "0.40-4.50",
-    valueLow: 2,
-    valueHigh: 90,
-    decimals: 2
-  },
-  {
-    localCode: "ALT",
-    loinc: "1742-6",
-    name: "Alanine aminotransferase",
-    units: "U/L",
-    referenceRange: "7-56",
-    valueLow: 5,
-    valueHigh: 120,
-    decimals: 0
-  }
-]);
+var EXAMPLE_ASTM_TESTS = Object.freeze(
+  [
+    {
+      localCode: "GLU",
+      loinc: "2345-7",
+      name: "Glucose",
+      units: "mg/dL",
+      referenceRange: "70-110",
+      valueLow: 55,
+      valueHigh: 260,
+      decimals: 0
+    },
+    {
+      localCode: "K",
+      loinc: "2823-3",
+      name: "Potassium",
+      units: "mmol/L",
+      referenceRange: "3.5-5.1",
+      valueLow: 28,
+      valueHigh: 62,
+      decimals: 1
+    },
+    {
+      localCode: "NA",
+      loinc: "2951-2",
+      name: "Sodium",
+      units: "mmol/L",
+      referenceRange: "136-145",
+      valueLow: 125,
+      valueHigh: 155,
+      decimals: 0
+    },
+    {
+      localCode: "CREA",
+      loinc: "2160-0",
+      name: "Creatinine",
+      units: "mg/dL",
+      referenceRange: "0.6-1.3",
+      valueLow: 4,
+      valueHigh: 32,
+      decimals: 1
+    },
+    {
+      localCode: "HGB",
+      loinc: "718-7",
+      name: "Hemoglobin",
+      units: "g/dL",
+      referenceRange: "12.0-17.5",
+      valueLow: 80,
+      valueHigh: 190,
+      decimals: 1
+    },
+    {
+      localCode: "WBC",
+      loinc: "6690-2",
+      name: "Leukocytes",
+      units: "10*3/uL",
+      referenceRange: "4.5-11.0",
+      valueLow: 30,
+      valueHigh: 150,
+      decimals: 1
+    },
+    {
+      localCode: "TSH",
+      loinc: "3016-3",
+      name: "Thyrotropin",
+      units: "mIU/L",
+      referenceRange: "0.40-4.50",
+      valueLow: 2,
+      valueHigh: 90,
+      decimals: 2
+    },
+    {
+      localCode: "ALT",
+      loinc: "1742-6",
+      name: "Alanine aminotransferase",
+      units: "U/L",
+      referenceRange: "7-56",
+      valueLow: 5,
+      valueHigh: 120,
+      decimals: 0
+    }
+  ].map((entry) => Object.freeze(entry))
+);
 var ASTM_ABNORMAL_FLAGS = Object.freeze(["N", "L", "H", "A"]);
 var ASTM_RESULT_STATUSES = Object.freeze(["F", "P", "C"]);
 var ASTM_COMMENT_TEXT = Object.freeze([
@@ -561,6 +596,28 @@ var ASTM_COMMENT_TEXT = Object.freeze([
   "Sample generated by @cosyte/synth.",
   "Placeholder result comment for conformance testing."
 ]);
+function defaultHost() {
+  if (typeof undefined !== "function") return { require: __require, resolve: void 0 };
+  return { require: module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href))), resolve: (s) => undefined(s) };
+}
+function isRequireEsmRefusal(error) {
+  return error?.code === "ERR_REQUIRE_ESM";
+}
+function loadPeer(specifier, host) {
+  if (host.resolve === void 0) return host.require(specifier);
+  const entry = url.fileURLToPath(host.resolve(specifier));
+  try {
+    return host.require(entry);
+  } catch (error) {
+    if (!isRequireEsmRefusal(error)) throw error;
+    return host.require(specifier);
+  }
+}
+function lazyPeer(specifier, host) {
+  let loaded;
+  return () => loaded ??= loadPeer(specifier, defaultHost());
+}
+var astmPeer = lazyPeer("@cosyte/astm");
 
 // src/astm/message.ts
 function resultValue(rng, low, high, decimals) {
@@ -615,7 +672,7 @@ function buildResultInput(options) {
   };
 }
 function generateAstmResult(options) {
-  return astm.buildAstmMessage(buildResultInput(options));
+  return astmPeer().buildAstmMessage(buildResultInput(options));
 }
 function generateAstmOrder(options) {
   return generateAstmResult({ ...options, resultCount: 0, comment: false });
@@ -623,21 +680,23 @@ function generateAstmOrder(options) {
 function generateAstmResultFramed(options) {
   const raw = generateAstmResult(options);
   const recordLines = raw.split("\r").filter((line) => line.length > 0).map((line) => `${line}\r`);
-  return astm.composeAstmFrames(recordLines);
+  return astmPeer().composeAstmFrames(recordLines);
 }
+
+// src/astm/round-trip.ts
 function astmRoundTrip(raw) {
-  const message = astm.parseAstmRecords(raw);
+  const message = astmPeer().parseAstmRecords(raw);
   const warnings = message.warnings.map((w) => String(w.code));
-  const byteStable = astm.serializeAstmRecords(message) === raw;
+  const byteStable = astmPeer().serializeAstmRecords(message) === raw;
   return { content: raw, warnings, byteStable, specClean: warnings.length === 0 && byteStable };
 }
 function astmFramedRoundTrip(bytes) {
-  const { message, frameWarnings } = astm.parseFramedAstm(bytes);
+  const { message, frameWarnings } = astmPeer().parseFramedAstm(bytes);
   const warnings = [
     ...frameWarnings.map((w) => String(w.code)),
     ...message.warnings.map((w) => String(w.code))
   ];
-  const reframed = astm.serializeFramedAstm(message);
+  const reframed = astmPeer().serializeFramedAstm(message);
   const byteStable = bytesEqual(reframed, bytes);
   const content = latin1(bytes);
   return { content, warnings, byteStable, specClean: warnings.length === 0 && byteStable };
@@ -652,6 +711,11 @@ function latin1(bytes) {
   for (const b of bytes) out += String.fromCharCode(b);
   return out;
 }
+function astmCorpusArtifact(raw, verify) {
+  if (!verify) return { content: raw, warnings: UNCHECKED };
+  const warnings = astmPeer().parseAstmRecords(raw).warnings.map((w) => String(w.code));
+  return { content: raw, warnings };
+}
 
 // src/select.ts
 function resolveKind(allowed, requested) {
@@ -739,7 +803,7 @@ var ASTM_QUIRKS = Object.freeze({
   })
 });
 function toleratingProfile(quirk) {
-  return quirk === "unknown-escape" ? astm.astmProfiles.referenceCorpus : void 0;
+  return quirk === "unknown-escape" ? astmPeer().astmProfiles.referenceCorpus : void 0;
 }
 var CR = "\r";
 function applyQuirk(quirk, records) {
@@ -783,7 +847,7 @@ function generateAstmQuirk(options) {
   }
   assertIntendedWarnings(
     descriptor.intendedWarnings,
-    astm.parseAstmRecords(content).warnings.map((w) => String(w.code))
+    astmPeer().parseAstmRecords(content).warnings.map((w) => String(w.code))
   );
   return Object.freeze({
     format: "astm",
@@ -796,12 +860,10 @@ function generateAstmQuirk(options) {
 function astmQuirkRoundTrip(artifact) {
   const quirk = artifact.quirk;
   const descriptor = resolveQuirk(ASTM_QUIRKS, "astm", quirk);
-  const bare = astm.parseAstmRecords(artifact.content).warnings.map((w) => String(w.code));
+  const bare = astmPeer().parseAstmRecords(artifact.content).warnings.map((w) => String(w.code));
   const profile = toleratingProfile(quirk);
   const withProfile = profile !== void 0 && descriptor.toleratingProfile !== void 0 ? (() => {
-    const warnings = astm.parseAstmRecords(artifact.content, { profile }).warnings.map(
-      (w) => String(w.code)
-    );
+    const warnings = astmPeer().parseAstmRecords(artifact.content, { profile }).warnings.map((w) => String(w.code));
     return {
       profileName: descriptor.toleratingProfile,
       disposition: descriptor.disposition,
@@ -851,23 +913,23 @@ var astmQuirkProfile = defineSynthProfile({
 // src/astm/index.ts
 var ALL_KINDS = Object.freeze(["Result", "Order"]);
 var DEFAULT_MIX = ALL_KINDS;
-function generateKind(kind, seed) {
+function generateKind(kind, seed, verify) {
   switch (kind) {
     case "Result":
-      return astmRoundTrip(generateAstmResult({ seed }));
+      return astmCorpusArtifact(generateAstmResult({ seed }), verify);
     case "Order":
-      return astmRoundTrip(generateAstmOrder({ seed }));
+      return astmCorpusArtifact(generateAstmOrder({ seed }), verify);
   }
 }
 function astmCorpus(options) {
-  const { seed } = options;
+  const { seed, verify = true } = options;
   const mix = resolveMix(ALL_KINDS, options.mix, DEFAULT_MIX);
   const count = options.count ?? mix.length;
   const seedStream = createRng(seed);
   const artifacts = Array.from({ length: count }, (_unused, i) => {
     const kind = mix[i % mix.length] ?? "Result";
     const msgSeed = seedStream.nextUint32();
-    const rt = generateKind(kind, msgSeed);
+    const rt = generateKind(kind, msgSeed, verify);
     return {
       format: "astm",
       kind,