@cosyte/fhir 0.1.1 → 0.1.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Cosyte
+Copyright (c) 2026 Cosyte LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,7 +1,7 @@
 <a href="https://cosyte.com">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="https://cosyte.com/tile/cosyte-lockup-tile-on-dark-1200x300.png">
-    <img alt="Cosyte: a plus mark set in two overlapping rounded squares, one solid and one outlined, beside the Cosyte wordmark" src="https://cosyte.com/tile/cosyte-lockup-tile-on-light-1200x300.png">
+    <img alt="The Cosyte logo on its own white ground: the icon beside the word Cosyte." src="https://cosyte.com/tile/cosyte-lockup-tile-on-light-1200x300.png">
   </picture>
 </a>
 
@@ -12,7 +12,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@cosyte/fhir.svg)](https://www.npmjs.com/package/@cosyte/fhir)
 [![CI](https://img.shields.io/github/actions/workflow/status/cosyte/fhir/ci.yml?branch=main&label=CI)](https://github.com/cosyte/fhir/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/cosyte/fhir/blob/main/LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org)
 
 FHIR R4 for Node.js and TypeScript: a resource model that keeps every value exactly as written, JSON and XML codecs, layered validation, and a safety readout for status and negation.
@@ -20,18 +20,18 @@ FHIR R4 for Node.js and TypeScript: a resource model that keeps every value exac
 ## Why this exists
 
 Reading FHIR correctly takes more than a JSON parse: a `decimal` written `0.010` has to stay
-`0.010`, an `integer64` has to keep every digit, and a status, a modifier or a negation must never be
+`0.010`, an `integer64` has to keep every digit, and a status, a modifier, or a negation must never be
 skipped, because a missed `refuted` reads as its opposite. We built `@cosyte/fhir` for the engineer
 who reads FHIR R4 from a server or an EHR (the format ONC HTI-1 binds §170.315(g)(10) to, with US
 Core and SMART on FHIR) and has to get those values right without reading the specification first.
 Type definitions alone describe a resource's shape and check nothing at run time, and `JSON.parse`
-turns `0.010` into the number `0.01` and knows nothing about modifiers. This library reads, writes
+turns `0.010` into the number `0.01` and knows nothing about modifiers. This library reads, writes,
 and validates FHIR R4 with zero runtime dependencies, and tells you with a coded reason what it could
 not read safely.
 
 ## Status
 
-**The 0.1 line.** From 0.1 the public API is settled: the exported names, options, result shapes and
+**The 0.1 line.** From 0.1 the public API is settled: the exported names, options, result shapes, and
 issue codes are the surface we keep stable. While the package is below 1.0, a breaking change ships
 in a minor version and is called out in the
 [changelog](https://github.com/cosyte/fhir/blob/main/CHANGELOG.md). Upgrading from 0.0.10 changes
@@ -47,10 +47,10 @@ and DSTU2 documents can be read, since the model is schema-free, but they are no
 their own definitions.
 
 Not covered yet: typed per-resource models (the built-in structural schemas cover the base elements
-plus `Patient`), `type` and `profile` slicing discriminators and reslicing (reported
-`PROFILE_SLICE_UNCHECKED`), FHIRPath outside the supported subset (reported `INVARIANT_UNCHECKED`,
-never passed), bundled terminology or US Core content, spec-clean JSON written from a model read out
-of XML, unit conversion, and executing a transaction Bundle.
+plus the eight modeled resource types), `type` and `profile` slicing discriminators and reslicing
+(reported `PROFILE_SLICE_UNCHECKED`), FHIRPath outside the supported subset (reported
+`INVARIANT_UNCHECKED`, never passed), bundled terminology or US Core content, spec-clean JSON written
+from a model read out of XML, unit conversion, and executing a transaction Bundle.
 
 ## Install
 
@@ -59,9 +59,9 @@ of XML, unit conversion, and executing a transaction Bundle.
 pnpm add @cosyte/fhir
 ```
 
-Requires Node `>=22.0.0`. The package ships dual ESM and CommonJS builds with type declarations for
-both, so `import` and `require` both work and neither needs a compatibility shim. There are zero
-runtime dependencies, and it imports no Node built-in.
+Requires Node.js 22 or later, tested on 22 and 24. The package ships dual ESM and CommonJS builds
+with type declarations for both, so `import` and `require` both work and neither needs a
+compatibility shim. There are zero runtime dependencies, and it imports no Node built-in.
 
 ## Usage
 
@@ -115,13 +115,13 @@ Everything ships from one entry point; there are no subpath imports.
 - **Validate.** `validateResource` returns `valid`, the issues, and `toOperationOutcome()` to render
   them as an `OperationOutcome`. Pass the `profiles` you load with `loadStructureDefinition` or
   author with `defineProfile`, and a `terminology` service of your own for code validity.
-- **Read status and negation.** `readSafety` surfaces status, modifiers and negations.
+- **Read status and negation.** `readSafety` surfaces status, modifiers, and negations.
   `assertSafeToSummarize` throws `FhirSafetyError`, carrying locations only, when a resource holds
   something it cannot summarize honestly, such as a `modifierExtension` it does not understand.
 - **Read measured values.** `readObservationValue` branches on the `value[x]` type and keeps the
   UCUM `code`, and `readMedicationDoses` reads dose quantities. No unit is ever converted.
 - **Bundles and NDJSON.** `readBundle` tells a transaction (all or nothing) from a batch and
-  executes neither, `resolveReference` resolves relative, absolute, logical and `#fragment`
+  executes neither, `resolveReference` resolves relative, absolute, logical, and `#fragment`
   references, and `streamNdjson` reads a Bulk Data export line by line, reporting a malformed line
   and carrying on.
 
@@ -130,16 +130,16 @@ Everything ships from one entry point; there are no subpath imports.
 FHIR resources carry protected health information, so treat every document you hand this library
 as PHI.
 
-- **It works in memory.** It reads, validates and writes in memory and nothing else. It opens no
-  socket, writes nothing to disk and fetches nothing at run time; it has zero runtime dependencies,
+- **It works in memory.** It reads, validates, and writes in memory and nothing else. It opens no
+  socket, writes nothing to disk, and fetches nothing at run time; it has zero runtime dependencies,
   imports no Node built-in, and calls no terminology service unless you pass one in.
 - **Diagnostics carry no values.** An issue is a code and a FHIRPath location, never the value it
   was raised over. A location can repeat an element name the document supplied when that name has
   the published form of a FHIR name, so treat a location as derived from the document.
 - **The XML reader accepts plain XML only.** Anything else is refused with a typed `FhirXmlError`
-  that carries a code and a byte offset, never a slice of the document. The reader performs no I/O
-  and resolves no URI. The troubleshooting pages on
-  [docs.cosyte.com/fhir](https://docs.cosyte.com/fhir) list each refusal and its code.
+  that carries a code and an offset into the input string (in UTF-16 code units, not bytes), never a
+  slice of the document. The reader performs no I/O and resolves no URI. The troubleshooting pages
+  on [docs.cosyte.com/fhir](https://docs.cosyte.com/fhir) list each refusal and its code.
 - **Nesting is bounded.** Both readers stop at a fixed depth with a typed error, so a deeply nested
   document fails cleanly rather than exhausting the stack.
 - **A status or a negation is not skipped silently.** `assertSafeToSummarize` refuses a resource
@@ -151,7 +151,7 @@ as PHI.
 ## Documentation
 
 - [docs.cosyte.com/fhir](https://docs.cosyte.com/fhir): installation, the quickstart, core
-  concepts, guides, current limits and troubleshooting.
+  concepts, guides, current limits, and troubleshooting.
 - [`documentation/capabilities.md`](https://github.com/cosyte/fhir/blob/main/documentation/capabilities.md):
   the full capability readout, layer by layer, with what each one checks and what it leaves open.
 - [`documentation/`](https://github.com/cosyte/fhir/tree/main/documentation) in the repository: the
@@ -162,7 +162,7 @@ as PHI.
 
 ## Contributing
 
-Questions, bug reports and FHIR quirks from the servers and EHRs you connect to all belong in
+Questions, bug reports, and FHIR quirks from the servers and EHRs you connect to all belong in
 [GitHub issues](https://github.com/cosyte/fhir/issues). Pull requests are welcome; every fixture
 must be synthetic, never a real patient's data.
 
@@ -174,10 +174,12 @@ pnpm lint
 pnpm test
 ```
 
-Every meaningful change gets a Changeset (`pnpm changeset`: `minor` for new capability or a breaking
-change while the version is below 1.0, `patch` for a fix) and a `CHANGELOG.md` `[Unreleased]`
-entry. See [`CONTRIBUTING.md`](https://github.com/cosyte/fhir/blob/main/CONTRIBUTING.md).
+Every meaningful change gets a changeset (`pnpm changeset`: `minor` for new capability or a breaking
+change while the version is below 1.0, `patch` for a fix), and its summary becomes the change's
+entry in `CHANGELOG.md`. See [`CONTRIBUTING.md`](https://github.com/cosyte/fhir/blob/main/CONTRIBUTING.md).
 
 ## License
 
-MIT, copyright Cosyte. See [LICENSE](./LICENSE).
+MIT, copyright Cosyte LLC. See [LICENSE](https://github.com/cosyte/fhir/blob/main/LICENSE). The names of
+the standards and code systems this package works with belong to their owners; see
+[TRADEMARKS.md](https://github.com/cosyte/fhir/blob/main/TRADEMARKS.md).

package/dist/index.cjs

@@ -555,7 +555,7 @@ var FATAL_CODES = {
    * JSON nested deeper than the reader's fixed bound. Well-formed but pathological input (a tower of
    * `[[[[…]]]]` / `{"a":{"a":…}}`) is refused as a **DoS guard**, turning what would otherwise be a
    * V8 stack overflow (`RangeError`, environment-dependent, untyped) into a typed, value-free fatal
-   * carrying a byte `offset`. Mirrors the XML reader's `MAX_DEPTH_EXCEEDED` (fuzzing: deep
+   * carrying an `offset`. Mirrors the XML reader's `MAX_DEPTH_EXCEEDED` (fuzzing: deep
    * nesting must never crash/hang/OOM, always a typed error or a bounded rejection).
    */
   MAX_DEPTH_EXCEEDED: "MAX_DEPTH_EXCEEDED"
@@ -564,12 +564,16 @@ var FhirCodecError = class extends Error {
   code;
   /** FHIRPath location of the failure, when it has one (misalignment). */
   expression;
-  /** Byte offset into the input, when it has one (malformed JSON). */
+  /**
+   * Where in the input the failure was detected, when it has one (malformed JSON), as an index into
+   * the input string in UTF-16 code units (JavaScript string indexing), not a byte offset: the two
+   * differ once a non-ASCII character precedes the failure.
+   */
   offset;
   /**
    * @param code - The fatal reason.
    * @param message - A PHI-safe description, must not embed any input value.
-   * @param location - Either a FHIRPath `expression` or a byte `offset`.
+   * @param location - Either a FHIRPath `expression` or a string-index `offset`.
    * @internal
    */
   constructor(code, message, location = {}) {
@@ -6653,12 +6657,16 @@ var XML_FATAL_CODES = {
 };
 var FhirXmlError = class extends Error {
   code;
-  /** Byte offset into the input where the failure was detected. */
+  /**
+   * Where in the input the failure was detected, as an index into the input string in UTF-16 code
+   * units (JavaScript string indexing), not a byte offset: the two differ once a non-ASCII character
+   * precedes the failure.
+   */
   offset;
   /**
    * @param code - The fatal reason.
    * @param message - A PHI-safe description, must not embed any input value.
-   * @param offset - The byte offset where the failure was detected.
+   * @param offset - The string index (UTF-16 code units) where the failure was detected.
    * @internal
    */
   constructor(code, message, offset) {
@@ -7550,7 +7558,7 @@ async function* streamNdjson(source, options = {}) {
 }
 
 // src/index.ts
-var VERSION = "0.1.1";
+var VERSION = "0.1.2";
 
 exports.ABSENCE_CODES = ABSENCE_CODES;
 exports.ALLERGY_CLINICAL_SYSTEM = ALLERGY_CLINICAL_SYSTEM;

package/dist/index.d.cts

@@ -793,7 +793,7 @@ declare function parseReference(raw: string): ParsedReference;
  * **PHI discipline.** A FHIR resource is PHI by default, and diagnostics are the leak
  * vector. Every issue and every error here is **value-free by construction**: it carries a coded
  * `code`, a `severity`, and an `expression` (a FHIRPath *location* such as `Patient.name[0].given[1]`),
- * never the offending value. The `FhirCodecError` for malformed JSON carries a byte `offset`, not
+ * never the offending value. The `FhirCodecError` for malformed JSON carries an `offset`, not
  * the surrounding text.
  *
  * @packageDocumentation
@@ -1122,7 +1122,7 @@ declare const FATAL_CODES: {
      * JSON nested deeper than the reader's fixed bound. Well-formed but pathological input (a tower of
      * `[[[[…]]]]` / `{"a":{"a":…}}`) is refused as a **DoS guard**, turning what would otherwise be a
      * V8 stack overflow (`RangeError`, environment-dependent, untyped) into a typed, value-free fatal
-     * carrying a byte `offset`. Mirrors the XML reader's `MAX_DEPTH_EXCEEDED` (fuzzing: deep
+     * carrying an `offset`. Mirrors the XML reader's `MAX_DEPTH_EXCEEDED` (fuzzing: deep
      * nesting must never crash/hang/OOM, always a typed error or a bounded rejection).
      */
     readonly MAX_DEPTH_EXCEEDED: "MAX_DEPTH_EXCEEDED";
@@ -1150,12 +1150,16 @@ declare class FhirCodecError extends Error {
     readonly code: FatalCode;
     /** FHIRPath location of the failure, when it has one (misalignment). */
     readonly expression: string | undefined;
-    /** Byte offset into the input, when it has one (malformed JSON). */
+    /**
+     * Where in the input the failure was detected, when it has one (malformed JSON), as an index into
+     * the input string in UTF-16 code units (JavaScript string indexing), not a byte offset: the two
+     * differ once a non-ASCII character precedes the failure.
+     */
     readonly offset: number | undefined;
     /**
      * @param code - The fatal reason.
      * @param message - A PHI-safe description, must not embed any input value.
-     * @param location - Either a FHIRPath `expression` or a byte `offset`.
+     * @param location - Either a FHIRPath `expression` or a string-index `offset`.
      * @internal
      */
     constructor(code: FatalCode, message: string, location?: {
@@ -1175,7 +1179,7 @@ declare class FhirCodecError extends Error {
  *
  * The output is a raw JSON tree ({@link RawJson}) that preserves member order (FHIR allows
  * `resourceType` in any position) and number literals verbatim. Malformed input throws a value-free
- * {@link FhirCodecError} carrying a byte offset, never a snippet (the snippet could be PHI).
+ * {@link FhirCodecError} carrying an offset, never a snippet (the snippet could be PHI).
  *
  * @packageDocumentation
  */
@@ -1219,7 +1223,7 @@ type RawJson = RawObject | RawArray | RawString | RawNumber | RawBool | RawNull;
  * Parse a JSON document into a {@link RawJson} tree that preserves number literals verbatim and
  * member order. Throws {@link FhirCodecError} (`MALFORMED_JSON`) on invalid input, or
  * (`MAX_DEPTH_EXCEEDED`) when nesting passes the reader's fixed depth bound, both value-free, with a
- * byte `offset` and no snippet.
+ * `offset` and no snippet.
  *
  * @param src - The JSON text.
  * @example
@@ -5499,8 +5503,8 @@ declare function matchesPattern(instance: FhirNode | undefined, pattern: FhirNod
  *
  * Profile validation and slicing discriminators are expressed as **element paths** relative to a
  * resource or a slice element (e.g. `clinicalStatus.coding.code`, `value[x]`, `$this`). This module
- * resolves such a path to the set of model nodes it selects, flattening repeating elements and
- * honoring `[x]` choice variants. It is a deliberately small, FHIRPath-*shaped* navigator, not the
+ * resolves such a path to the set of model nodes it selects, flattening the repeating elements it
+ * walks through and honoring `[x]` choice variants. It is a deliberately small, FHIRPath-*shaped* navigator, not the
  * FHIRPath engine: it walks dotted member access and choice suffixes,
  * which is exactly what StructureDefinition discriminator paths and fixed/pattern locations use, and
  * nothing more (no functions, no filters, no arithmetic).
@@ -5511,8 +5515,11 @@ declare function matchesPattern(instance: FhirNode | undefined, pattern: FhirNod
 /**
  * Resolve an element path against a node, returning every node it selects (empty when nothing
  * matches). `$this` (or the empty path) selects the node itself. A `[x]` segment matches any concrete
- * choice variant (`value[x]` → `valueQuantity`, `valueString`, …). Repeating elements are flattened,
- * so `coding.code` on a `CodeableConcept` with three codings yields three nodes.
+ * choice variant (`value[x]` → `valueQuantity`, `valueString`, …). A repeating element the path
+ * walks through is flattened, so `coding.code` on a `CodeableConcept` with three codings yields three
+ * nodes. A repeating element in the last segment is not: it comes back as its list node
+ * (`kind: "list"`, members on `items`), so `name` on a Patient with two names yields one node.
+ * Flatten it with `isList(node) ? node.items : [node]`.
  *
  * @param node - The starting node (a resource, a slice element instance, …).
  * @param path - A dotted element path relative to `node` (`""` / `"$this"` selects `node`).
@@ -5692,7 +5699,9 @@ interface ProfileOptions {
  * ```ts
  * import { collectProfileIssues, loadStructureDefinition, parseResource } from "@cosyte/fhir";
  * const profile = loadStructureDefinition(parseResource(usCoreAllergyJson).resource);
- * const issues = collectProfileIssues(parseResource(allergyJson).resource, profile);
+ * if (profile !== undefined) {
+ *   const issues = collectProfileIssues(parseResource(allergyJson).resource, profile);
+ * }
  * ```
  */
 declare function collectProfileIssues(resource: FhirComplex, profile: StructureDefinition, options?: ProfileOptions): ValidationIssue[];
@@ -5769,7 +5778,9 @@ interface InvariantOptions {
  * ```ts
  * import { collectInvariantIssues, loadStructureDefinition, parseResource } from "@cosyte/fhir";
  * const profile = loadStructureDefinition(parseResource(usCoreProfileJson).resource);
- * const issues = collectInvariantIssues(parseResource(instanceJson).resource, profile);
+ * if (profile !== undefined) {
+ *   const issues = collectInvariantIssues(parseResource(instanceJson).resource, profile);
+ * }
  * ```
  */
 declare function collectInvariantIssues(resource: FhirComplex, profile: StructureDefinition, options?: InvariantOptions): ValidationIssue[];
@@ -6325,7 +6336,7 @@ type XmlNode = XmlElement | XmlText;
  * decoding the five predefined entities and numeric character references. **Refuses** any DTD
  * (`DTD_FORBIDDEN`) or non-predefined entity (`UNDEFINED_ENTITY`), and bounds nesting depth, so it
  * is XXE- and billion-laughs-safe and never crashes on adversarial input. Throws
- * {@link FhirXmlError} on any refusal or well-formedness error, with a byte `offset` and no snippet.
+ * {@link FhirXmlError} on any refusal or well-formedness error, with an `offset` and no snippet.
  *
  * @param src - The XML text.
  * @example
@@ -6363,7 +6374,7 @@ declare function readRawXml(src: string): XmlElement;
  * {@link XML_FATAL_CODES.MAX_DEPTH_EXCEEDED} so adversarial input yields a typed error, never a stack
  * overflow.
  *
- * Every message is **value-free**: it carries a coded reason and a byte `offset`, never
+ * Every message is **value-free**: it carries a coded reason and an `offset`, never
  * a slice of the offending document, because that slice could be PHI.
  *
  * @packageDocumentation
@@ -6394,7 +6405,7 @@ type XmlFatalCode = (typeof XML_FATAL_CODES)[keyof typeof XML_FATAL_CODES];
 /**
  * Thrown by the XML reader on an unrecoverable failure, a well-formedness error, a **refused** DTD
  * or entity (the safety refusals), or nesting past the depth bound. Carries the coded reason and a
- * byte `offset`, and, by design, **no** slice of the offending input, because that slice could be
+ * `offset` into the input, and, by design, **no** slice of the offending input, because that slice could be
  * PHI.
  *
  * @example
@@ -6411,12 +6422,16 @@ type XmlFatalCode = (typeof XML_FATAL_CODES)[keyof typeof XML_FATAL_CODES];
  */
 declare class FhirXmlError extends Error {
     readonly code: XmlFatalCode;
-    /** Byte offset into the input where the failure was detected. */
+    /**
+     * Where in the input the failure was detected, as an index into the input string in UTF-16 code
+     * units (JavaScript string indexing), not a byte offset: the two differ once a non-ASCII character
+     * precedes the failure.
+     */
     readonly offset: number;
     /**
      * @param code - The fatal reason.
      * @param message - A PHI-safe description, must not embed any input value.
-     * @param offset - The byte offset where the failure was detected.
+     * @param offset - The string index (UTF-16 code units) where the failure was detected.
      * @internal
      */
     constructor(code: XmlFatalCode, message: string, offset: number);

package/dist/index.d.ts

@@ -793,7 +793,7 @@ declare function parseReference(raw: string): ParsedReference;
  * **PHI discipline.** A FHIR resource is PHI by default, and diagnostics are the leak
  * vector. Every issue and every error here is **value-free by construction**: it carries a coded
  * `code`, a `severity`, and an `expression` (a FHIRPath *location* such as `Patient.name[0].given[1]`),
- * never the offending value. The `FhirCodecError` for malformed JSON carries a byte `offset`, not
+ * never the offending value. The `FhirCodecError` for malformed JSON carries an `offset`, not
  * the surrounding text.
  *
  * @packageDocumentation
@@ -1122,7 +1122,7 @@ declare const FATAL_CODES: {
      * JSON nested deeper than the reader's fixed bound. Well-formed but pathological input (a tower of
      * `[[[[…]]]]` / `{"a":{"a":…}}`) is refused as a **DoS guard**, turning what would otherwise be a
      * V8 stack overflow (`RangeError`, environment-dependent, untyped) into a typed, value-free fatal
-     * carrying a byte `offset`. Mirrors the XML reader's `MAX_DEPTH_EXCEEDED` (fuzzing: deep
+     * carrying an `offset`. Mirrors the XML reader's `MAX_DEPTH_EXCEEDED` (fuzzing: deep
      * nesting must never crash/hang/OOM, always a typed error or a bounded rejection).
      */
     readonly MAX_DEPTH_EXCEEDED: "MAX_DEPTH_EXCEEDED";
@@ -1150,12 +1150,16 @@ declare class FhirCodecError extends Error {
     readonly code: FatalCode;
     /** FHIRPath location of the failure, when it has one (misalignment). */
     readonly expression: string | undefined;
-    /** Byte offset into the input, when it has one (malformed JSON). */
+    /**
+     * Where in the input the failure was detected, when it has one (malformed JSON), as an index into
+     * the input string in UTF-16 code units (JavaScript string indexing), not a byte offset: the two
+     * differ once a non-ASCII character precedes the failure.
+     */
     readonly offset: number | undefined;
     /**
      * @param code - The fatal reason.
      * @param message - A PHI-safe description, must not embed any input value.
-     * @param location - Either a FHIRPath `expression` or a byte `offset`.
+     * @param location - Either a FHIRPath `expression` or a string-index `offset`.
      * @internal
      */
     constructor(code: FatalCode, message: string, location?: {
@@ -1175,7 +1179,7 @@ declare class FhirCodecError extends Error {
  *
  * The output is a raw JSON tree ({@link RawJson}) that preserves member order (FHIR allows
  * `resourceType` in any position) and number literals verbatim. Malformed input throws a value-free
- * {@link FhirCodecError} carrying a byte offset, never a snippet (the snippet could be PHI).
+ * {@link FhirCodecError} carrying an offset, never a snippet (the snippet could be PHI).
  *
  * @packageDocumentation
  */
@@ -1219,7 +1223,7 @@ type RawJson = RawObject | RawArray | RawString | RawNumber | RawBool | RawNull;
  * Parse a JSON document into a {@link RawJson} tree that preserves number literals verbatim and
  * member order. Throws {@link FhirCodecError} (`MALFORMED_JSON`) on invalid input, or
  * (`MAX_DEPTH_EXCEEDED`) when nesting passes the reader's fixed depth bound, both value-free, with a
- * byte `offset` and no snippet.
+ * `offset` and no snippet.
  *
  * @param src - The JSON text.
  * @example
@@ -5499,8 +5503,8 @@ declare function matchesPattern(instance: FhirNode | undefined, pattern: FhirNod
  *
  * Profile validation and slicing discriminators are expressed as **element paths** relative to a
  * resource or a slice element (e.g. `clinicalStatus.coding.code`, `value[x]`, `$this`). This module
- * resolves such a path to the set of model nodes it selects, flattening repeating elements and
- * honoring `[x]` choice variants. It is a deliberately small, FHIRPath-*shaped* navigator, not the
+ * resolves such a path to the set of model nodes it selects, flattening the repeating elements it
+ * walks through and honoring `[x]` choice variants. It is a deliberately small, FHIRPath-*shaped* navigator, not the
  * FHIRPath engine: it walks dotted member access and choice suffixes,
  * which is exactly what StructureDefinition discriminator paths and fixed/pattern locations use, and
  * nothing more (no functions, no filters, no arithmetic).
@@ -5511,8 +5515,11 @@ declare function matchesPattern(instance: FhirNode | undefined, pattern: FhirNod
 /**
  * Resolve an element path against a node, returning every node it selects (empty when nothing
  * matches). `$this` (or the empty path) selects the node itself. A `[x]` segment matches any concrete
- * choice variant (`value[x]` → `valueQuantity`, `valueString`, …). Repeating elements are flattened,
- * so `coding.code` on a `CodeableConcept` with three codings yields three nodes.
+ * choice variant (`value[x]` → `valueQuantity`, `valueString`, …). A repeating element the path
+ * walks through is flattened, so `coding.code` on a `CodeableConcept` with three codings yields three
+ * nodes. A repeating element in the last segment is not: it comes back as its list node
+ * (`kind: "list"`, members on `items`), so `name` on a Patient with two names yields one node.
+ * Flatten it with `isList(node) ? node.items : [node]`.
  *
  * @param node - The starting node (a resource, a slice element instance, …).
  * @param path - A dotted element path relative to `node` (`""` / `"$this"` selects `node`).
@@ -5692,7 +5699,9 @@ interface ProfileOptions {
  * ```ts
  * import { collectProfileIssues, loadStructureDefinition, parseResource } from "@cosyte/fhir";
  * const profile = loadStructureDefinition(parseResource(usCoreAllergyJson).resource);
- * const issues = collectProfileIssues(parseResource(allergyJson).resource, profile);
+ * if (profile !== undefined) {
+ *   const issues = collectProfileIssues(parseResource(allergyJson).resource, profile);
+ * }
  * ```
  */
 declare function collectProfileIssues(resource: FhirComplex, profile: StructureDefinition, options?: ProfileOptions): ValidationIssue[];
@@ -5769,7 +5778,9 @@ interface InvariantOptions {
  * ```ts
  * import { collectInvariantIssues, loadStructureDefinition, parseResource } from "@cosyte/fhir";
  * const profile = loadStructureDefinition(parseResource(usCoreProfileJson).resource);
- * const issues = collectInvariantIssues(parseResource(instanceJson).resource, profile);
+ * if (profile !== undefined) {
+ *   const issues = collectInvariantIssues(parseResource(instanceJson).resource, profile);
+ * }
  * ```
  */
 declare function collectInvariantIssues(resource: FhirComplex, profile: StructureDefinition, options?: InvariantOptions): ValidationIssue[];
@@ -6325,7 +6336,7 @@ type XmlNode = XmlElement | XmlText;
  * decoding the five predefined entities and numeric character references. **Refuses** any DTD
  * (`DTD_FORBIDDEN`) or non-predefined entity (`UNDEFINED_ENTITY`), and bounds nesting depth, so it
  * is XXE- and billion-laughs-safe and never crashes on adversarial input. Throws
- * {@link FhirXmlError} on any refusal or well-formedness error, with a byte `offset` and no snippet.
+ * {@link FhirXmlError} on any refusal or well-formedness error, with an `offset` and no snippet.
  *
  * @param src - The XML text.
  * @example
@@ -6363,7 +6374,7 @@ declare function readRawXml(src: string): XmlElement;
  * {@link XML_FATAL_CODES.MAX_DEPTH_EXCEEDED} so adversarial input yields a typed error, never a stack
  * overflow.
  *
- * Every message is **value-free**: it carries a coded reason and a byte `offset`, never
+ * Every message is **value-free**: it carries a coded reason and an `offset`, never
  * a slice of the offending document, because that slice could be PHI.
  *
  * @packageDocumentation
@@ -6394,7 +6405,7 @@ type XmlFatalCode = (typeof XML_FATAL_CODES)[keyof typeof XML_FATAL_CODES];
 /**
  * Thrown by the XML reader on an unrecoverable failure, a well-formedness error, a **refused** DTD
  * or entity (the safety refusals), or nesting past the depth bound. Carries the coded reason and a
- * byte `offset`, and, by design, **no** slice of the offending input, because that slice could be
+ * `offset` into the input, and, by design, **no** slice of the offending input, because that slice could be
  * PHI.
  *
  * @example
@@ -6411,12 +6422,16 @@ type XmlFatalCode = (typeof XML_FATAL_CODES)[keyof typeof XML_FATAL_CODES];
  */
 declare class FhirXmlError extends Error {
     readonly code: XmlFatalCode;
-    /** Byte offset into the input where the failure was detected. */
+    /**
+     * Where in the input the failure was detected, as an index into the input string in UTF-16 code
+     * units (JavaScript string indexing), not a byte offset: the two differ once a non-ASCII character
+     * precedes the failure.
+     */
     readonly offset: number;
     /**
      * @param code - The fatal reason.
      * @param message - A PHI-safe description, must not embed any input value.
-     * @param offset - The byte offset where the failure was detected.
+     * @param offset - The string index (UTF-16 code units) where the failure was detected.
      * @internal
      */
     constructor(code: XmlFatalCode, message: string, offset: number);

package/dist/index.mjs

@@ -553,7 +553,7 @@ var FATAL_CODES = {
    * JSON nested deeper than the reader's fixed bound. Well-formed but pathological input (a tower of
    * `[[[[…]]]]` / `{"a":{"a":…}}`) is refused as a **DoS guard**, turning what would otherwise be a
    * V8 stack overflow (`RangeError`, environment-dependent, untyped) into a typed, value-free fatal
-   * carrying a byte `offset`. Mirrors the XML reader's `MAX_DEPTH_EXCEEDED` (fuzzing: deep
+   * carrying an `offset`. Mirrors the XML reader's `MAX_DEPTH_EXCEEDED` (fuzzing: deep
    * nesting must never crash/hang/OOM, always a typed error or a bounded rejection).
    */
   MAX_DEPTH_EXCEEDED: "MAX_DEPTH_EXCEEDED"
@@ -562,12 +562,16 @@ var FhirCodecError = class extends Error {
   code;
   /** FHIRPath location of the failure, when it has one (misalignment). */
   expression;
-  /** Byte offset into the input, when it has one (malformed JSON). */
+  /**
+   * Where in the input the failure was detected, when it has one (malformed JSON), as an index into
+   * the input string in UTF-16 code units (JavaScript string indexing), not a byte offset: the two
+   * differ once a non-ASCII character precedes the failure.
+   */
   offset;
   /**
    * @param code - The fatal reason.
    * @param message - A PHI-safe description, must not embed any input value.
-   * @param location - Either a FHIRPath `expression` or a byte `offset`.
+   * @param location - Either a FHIRPath `expression` or a string-index `offset`.
    * @internal
    */
   constructor(code, message, location = {}) {
@@ -6651,12 +6655,16 @@ var XML_FATAL_CODES = {
 };
 var FhirXmlError = class extends Error {
   code;
-  /** Byte offset into the input where the failure was detected. */
+  /**
+   * Where in the input the failure was detected, as an index into the input string in UTF-16 code
+   * units (JavaScript string indexing), not a byte offset: the two differ once a non-ASCII character
+   * precedes the failure.
+   */
   offset;
   /**
    * @param code - The fatal reason.
    * @param message - A PHI-safe description, must not embed any input value.
-   * @param offset - The byte offset where the failure was detected.
+   * @param offset - The string index (UTF-16 code units) where the failure was detected.
    * @internal
    */
   constructor(code, message, offset) {
@@ -7548,7 +7556,7 @@ async function* streamNdjson(source, options = {}) {
 }
 
 // src/index.ts
-var VERSION = "0.1.1";
+var VERSION = "0.1.2";
 
 export { ABSENCE_CODES, ALLERGY_CLINICAL_SYSTEM, ALLERGY_SUBSTANCE_VALUESET, ALLERGY_VERIFICATION_SYSTEM, BINDING_STRENGTHS, BUNDLE_TYPES, CODE_SYSTEM_VERSION_RECORD_CODES, CODE_SYSTEM_VERSION_RECORD_SYSTEM, CONDITION_CATEGORY_SYSTEM, CONDITION_CLINICAL_SYSTEM, CONDITION_VERIFICATION_SYSTEM, CPT_SYSTEM, CVX_SYSTEM, DATA_ABSENT_REASON_URL, DISCRIMINATOR_TYPES, ENTERED_IN_ERROR, FATAL_CODES, FHIR_XML_NAMESPACE, FhirCodecError, FhirDecimal, FhirInteger64, FhirProfileError, FhirSafetyError, FhirSerializeError, FhirXmlError, ICD10CM_SYSTEM, ICD9CM_SYSTEM, ISSUE_CODES, ISSUE_SEVERITIES, ISSUE_TYPES, InvalidProfileError, KNOWN_MODIFIER_EXTENSION_URLS, KNOWN_SYSTEMS, LOINC_SYSTEM, MAX_REFERENCE_DEPTH, MEDICATION_VALUESET, MODIFIER_ELEMENT_ROOT_TYPES, NDC_SYSTEM, NDJSON_ERROR_CODES, NOT_DONE, NOT_TAKEN, NO_KNOWN_ALLERGY, OBSERVATION_CATEGORY_SYSTEM, OBSERVATION_VALUE_TYPES, PATIENT_IDENTIFIER_STARTER, PRIMITIVE_TYPES, REFUTED, RXNORM_SYSTEM, SAFETY_RESOURCE_TYPES, SERIALIZE_ERROR_CODES, SNOMED_SCT, STARTER_PROFILES, STARTER_PROFILE_BASE_URL, TERMINOLOGY_BINDINGS, UCUM_SYSTEM, UNBOUNDED, UnsupportedFhirPathError, VALIDATION_CODES, VERSION, VITAL_SIGNS_CATEGORY, VITAL_SIGNS_PROFILE, VITAL_SIGN_OBSERVATION_STARTER, VITAL_SIGN_UNITS, WITHHELD, XHTML_NAMESPACE, XML_FATAL_CODES, absenceMarkers, arrayWrappedScalars, assertSafeToSummarize, baseSchema, buildBindingRegistry, buildBundleIndex, buildRegistry, codeOf, codingsOf, collectBundleIssues, collectInvariantIssues, collectProfileIssues, collectProfileVersionIssues, collectQuantityIssues, collectSafetyIssues, collectTerminologyIssues, complex, conflictingAbsenceMarkers, containedIndex, convertToBoolean, decimal, decimalPrecisionAtRisk, defineProfile, diagnosticFor, droppedText, duplicateProperty, entryProcessing, evaluateInvariant, generateSnapshot, getAllProperties, getProperty, hasCodeAnySystem, hasCoding, hasContainedCycle, integer64, isAbsenceCode, isAtomicBundle, isChoice, isComplex, isDroppedText, isForeignRoot, isKnownSystem, isList, isNestedArray, isPrimitive, isPrimitiveType, isRetracted, isUndefinedNull, list, loadStructureDefinition, locateDoseQuantities, matchSlices, matchesFixed, matchesPattern, misplacedPrimitiveExtension, mixedXmlSpelling, modifierElements, nearMissNegationCodes, nestedArray, nestedArrayContent, nestedArrays, nodesEquivalent, parseFhirPath, parseNdjsonLine, parseReference, parseResource, parseResourceXml, pathExists, primitive, readBundle, readInterpretations, readMedicationDoses, readObservationValue, readQuantity, readRawJson, readRawXml, readReferenceRanges, readSafety, requiredVitalSignUnits, resolveElement, resolvePath, resolveReference, resolveSlices, resourceType, serializeResource, serializeResourceXml, shadowedProperties, snapshotElements, starterProfile, streamNdjson, toOperationOutcome, tokenize, undefinedJsonNull, unexpectedXmlContent, unhandledModifierExtensions, unknownProperty, unreadableAbsenceMarkers, unreadableBooleans, unreadableNegationCodes, validatePrimitiveValue, validateResource, validateUcumShape, validationIssue, wouldLosePrecisionAsDouble };
 //# sourceMappingURL=index.mjs.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosyte/fhir",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "FHIR R4 for Node.js and TypeScript: a resource model that keeps every value exactly as written, JSON and XML codecs, layered validation, and a safety readout for status and negation.",
   "keywords": [
     "fhir",
@@ -68,12 +68,12 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "0.18.4",
     "@changesets/cli": "2.31.0",
-    "@cosyte/eslint-config": "^0.0.3",
-    "@cosyte/prettier-config": "^0.0.2",
-    "@cosyte/test-utils": "^0.0.2",
-    "@cosyte/tsconfig": "^0.0.2",
-    "@cosyte/tsup-config": "^0.0.1",
-    "@cosyte/vitest-config": "^0.0.2",
+    "@cosyte/eslint-config": "^0.1.1",
+    "@cosyte/prettier-config": "^0.1.1",
+    "@cosyte/test-utils": "^0.1.1",
+    "@cosyte/tsconfig": "^0.1.1",
+    "@cosyte/tsup-config": "^0.1.1",
+    "@cosyte/vitest-config": "^0.1.1",
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "4.1.4",
     "eslint": "10.5.0",