npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@formancy/health-document

v0.1.0

Published

Formancy Health's documents: a document Bundle and its Composition, and a DocumentReference and Binary carrying a PDF's bytes unchanged, for the HL7® FHIR® standard, R4 4.0.1, built from what the host supplies and never sent. No framework, no Node, no net

Readme

@formancy/health-document

A PDF's bytes as an R4 DocumentReference, in its attachment or in a Binary beside it, and a document Bundle for the HL7® FHIR® standard, R4 4.0.1: the host's Composition first, then only what it refers to, every reference resolved before anything is written. Every part of it is the host's -- identifiers, names, dates, codes, the PDF -- and nothing is made up, sent or fetched. What a document cannot be is refused whole, every refusal at once, naming where and never a value. No framework, no Node, no network, and no dependency but health-core, whose readers of a host's context it reads the context with. Decision 0008 says why each part is as it is, and what it costs.

import { writeJson } from '@formancy/health-core'
import { toDocumentBundle, toDocumentReference } from '@formancy/health-document'

const attached = toDocumentReference(
  { bytes: pdf, profile: 'PDF' }, // a Uint8Array, and what the host says it is
  {
    status: 'current',
    type: { system: 'http://terminology.hl7.org/CodeSystem/v2-0270', code: 'CN', display: 'Consultation' },
    subject: { reference: 'urn:uuid:…' }, // by name, never an address
    date: '2026-10-17T10:00:00+02:00', // the host's clock
    title: 'Zuweisung',
    binary: { fullUrl: 'urn:uuid:…' }, // leave out to put the bytes in the attachment
  },
)
if (!attached.ok) throw attached.refusals[0]

const result = toDocumentBundle({
  identifier: { system: 'urn:ietf:rfc:3986', value: 'urn:uuid:…' }, // never re-used
  timestamp: '2026-10-17T10:05:00+02:00',
  composition: { fullUrl: 'urn:uuid:…', status: 'final', type, subject, date, author, title, section },
  entries: [
    { fullUrl: 'urn:uuid:…', resource: patient },
    { fullUrl: 'urn:uuid:…', resource: attached.documentReference },
    { fullUrl: 'urn:uuid:…', resource: attached.binary },
  ],
})
if (result.ok) send(writeJson(result.bundle))
else for (const refusal of result.refusals) log(refusal.rule, refusal.path)

The PDF

toDocumentReference(pdf, context) writes content.attachment from the bytes themselves: contentType application/pdf; the bytes as base64 in data, or, with binary, a Binary that holds them and a url that names it; size, their number; hash, their SHA-1 as R4 asks, base64, computed here; and the host's title. The bytes are copied once, when checked, by calling nothing they bring -- a Node Buffer's slice shares its memory, so a Buffer the host reuses afterwards changes nothing attached -- and read back unchanged: the tests decode what was written and compare every byte, and health-corpus does the same with Node's base64 on the PDF Formancy Report renders.

What the host says the PDF is, profile, is checked, never assumed:

| Declared | Here | | --- | --- | | PDF | Attached, when its first line is a header ISO 32000 defines (%PDF-1.0 to %PDF-1.7, %PDF-2.0) and its last %%EOF alone. Nothing else of it is read: no parser, and nothing said of whether it is well formed. | | PDF/A-1a to PDF/A-4f | Refused, as unproved: no gate here has proved that a producer makes PDF/A, and a receiver archives a document as PDF/A because its sender said so. veraPDF arrives with H09, on a Report release that writes it. | | Anything else, PDF/UA-1 among them | Refused, as unmapped. |

PROVED_PDF_PROFILES is the list of what is attached: ['PDF'].

The context gives the DocumentReference's status (current, superseded, entered-in-error), type and category by one coding each, subject and author by name, date, an instant with its zone, and title. R4 makes most of them optional; each of status, type, subject, date and title is refused as absent when missing, since a DocumentReference without one says nothing a receiver files it by.

The document

toDocumentBundle(context) writes R4's document: type document, the host's identifier with its system and value (bdl-9), its timestamp (bdl-10), written as meta.lastUpdated too, the document date documents.html makes mandatory, since R4 calls each the moment the document was assembled; the Composition first (bdl-11), under the urn:uuid: the host gives it; then the host's entries, in its order. The Composition takes, in R4's names, its status, type, category, subject, date, author, title and sections, each a title, a code where given and its entry references; and its identifier where the host gives one. A section has no narrative. The Composition has one, written here and never taken from the host: generated, a div in the XHTML namespace of its title as a heading and each section's title as one below it, escaped by health-core's xhtmlText, and nothing else -- what R4 calls "entirely generated from the core elements in the content". A title XML cannot carry is refused where it stands. A guide may ask for it, as CH ORF makes Composition.text 1..1; R4 presents a document by its Composition's narrative and its sections'. Headings alone meet a guide's 1..1 and not R4's definition of a narrative "clinically safe" for a human to read alone, which 0009 records as a cost (0009). The host may name the profile the Bundle claims, profile, written in its meta after lastUpdated, and the one the Composition claims, composition.profile: canonicals, never fetched, each held to R4's uri.

Every reference in every entry is resolved before output: to the urn:uuid: of an entry, or refused -- dangling when it names nothing the Bundle holds, a Type/id included, since entries named by urn:uuid: answer to no other name; reference when it is an address, contained or versioned, or names a type R4 does not allow at its element. A DocumentReference's attachment url must name a Binary entry. Then every entry the Composition does not reach, following references forwards, is refused as unreferenced, and two entries of one name as duplicate-entry. Every attachment of a DocumentReference's content is held to its bytes, in its data or in the Binary its url names: a size or a SHA-1 they do not have, or a media type the Binary does not state, is refused as mismatch, so a DocumentReference that states one PDF's size or hash is never written beside another PDF's Binary; an attachment that states neither is not read. That reads and hashes the bytes again, about 0.1 s a megabyte (25 MB in 2.7 s, measured on 17 October 2026). Each entry's resource is written and read back by health-core, which refuses what FHIR JSON cannot carry at its path, and the Bundle holds that copy: a host that changes its objects afterwards does not change the document. Every Resource.id is R4's id. The same input gives the same bytes, whatever order the context names things in; the host's resources are written in the order the host gave them.

That is stricter than R4, which asks the Bundle to hold what the Composition refers to and lets what those resources refer to be left out: here a DocumentReference whose author is Practitioner/<id> on the receiver's server is refused as dangling.

Paths start at pdf or context and walk the host's names: context.entries[2].resource.subject.reference.

Each part of the context, and the PDF, is read for the members it names and no others, by health-core's known: one more -- a Composition's confidentiality, a coding's version, a reference's display, an entry's search, a PDF's file name -- is something the host meant to say, and is refused as unmapped at the object that holds it, its name not repeated. A part that is no object is refused as absent, and a hole in a list, which a host's array may have and JSON never does, at its index (0009).

What it does not prove, and does not do

The validator gate judges what this package makes of health-corpus's referral letter against R4 4.0.1, with the HL7 FHIR validator 7.0.2, offline, and accepts it with no error and no warning but dom-6, which every resource but the Composition raises, having no narrative; it checks the attachment's size and SHA-1 against its data, and with the bytes in a Binary says it did not check them ("not a directly accessible link"), which toDocumentBundle does, and health-corpus's tests on its output. An attachment url that names no entry it accepts, with only an information that it cannot find it (measured on 17 October 2026): this package's dangling is what refuses it. A media type is not checked offline.

Not here: a narrative of any resource but the Composition, or one of more than its titles; a Provenance or a stylesheet, which R4 admits in a document and which are refused as unreferenced; Composition's encounter, attester, custodian, confidentiality and events, refused where given; DocumentReference's format code, context and security labels; a bound on the PDF's size, which nothing has measured; reading a document back; and the MHD provide Bundle, which comes with CH EPR. An Attachment's url is followed only in a DocumentReference's content. A reference's target type is checked where this package knows its element -- Composition.author, DocumentReference's subject and author -- and elsewhere only against a type the reference itself states.

HL7, FHIR and the FHIR [FLAME DESIGN] are the registered trademarks of Health Level Seven International and their use does not constitute endorsement by HL7.

Source-available, not open source: see LICENSE.md.