fhirsmith 0.18.1 → 1.0.0

package/tx/sct/documentation.md

@@ -35,14 +35,20 @@ that the server does not use. `filterECL` is the one that matters.
   reference set's own fields (concept, integer and string typed from the RF2
   file name). Since inactive member rows are dropped at import, `active = false`
   never matches.
-- `AND` / `OR` / `MINUS` (and `,`), with the ECL 6.4 rule that conjunction and
+- Refinements: `=` and `!=` against an expression value (`!=` counts the
+  occurrences whose value is outside the set, so `A != X` needs at least one
+  A that is not X, and `[0..0] A != X` means every A is X); reversed
+  attributes (`R A = X`: the concept is the value of an A on something in X,
+  evaluated over the concept's inbound relationships); attribute names that
+  are a concept, `*`, or any sub expression (`<< 762705008 = ...`); attribute
+  sets joined by `AND`, `OR` or `,`, with brackets; attribute groups,
+  including `AND`/`OR` inside and between groups; attribute and group
+  cardinality, including `[0..0]`. Cardinality counts occurrences per role
+  group, per the SNOMED Computable Languages Group ruling (see
+  `_countAttributeMatches`).
+- `AND` / `OR` / `MINUS`, and `,` as a conjunction at the expression level as
+  well as in refinements, with the ECL 6.4 rule that conjunction and
   disjunction cannot be mixed without brackets.
-- Refinements: `=` against an expression value; attribute names that are a
-  concept, `*`, or any sub expression (`<< 762705008 = ...`); attribute sets
-  joined by `AND`, `OR` or `,`, with brackets; attribute groups, including
-  `AND`/`OR` inside and between groups; attribute and group cardinality,
-  including `[0..0]`. Cardinality counts occurrences per role group, per the
-  SNOMED Computable Languages Group ruling (see `_countAttributeMatches`).
 - Dotted expressions (`< X . 363698007`, `. << 363698007`, `. (A OR B)`).
 - `{{ C ... }}` concept filters on `active`, `definitionStatus`,
   `definitionStatusId`, `moduleId` and `effectiveTime`.
@@ -56,26 +62,37 @@ that the server does not use. `filterECL` is the one that matters.
   must be satisfied by a single description; separate blocks may be satisfied
   by different descriptions. Only active descriptions are considered unless
   the block has an `active` filter.
+- Concrete values in refinements - numeric (`= #5`, `>= #1.5`, `!= #-1`),
+  string (`= "x"`, `= match:"x"`, a set) and boolean (`= true`) - against the
+  concrete value relationships, which the importer reads from
+  `sct2_RelationshipConcreteValues_*` into cache version 19. Numbers compare
+  as numbers (`#5` matches `#5.0`); strings use the same match / wild
+  semantics as description terms; a value of another kind never matches.
+  An edition imported before version 19 has no concrete values and reports
+  such a refinement as unsupported rather than answering with nothing.
+- History supplements: `{{ + HISTORY }}` (= MAX), `HISTORY-MIN` (SAME AS),
+  `HISTORY-MOD` (SAME AS, WAS A, REPLACED BY, PARTIALLY EQUIVALENT TO),
+  `HISTORY-MAX` (every reference set under 900000000000522004 |Historical
+  association|), `HISTORY (*)` and `HISTORY (expression)`: the inactive
+  concepts that the selected association reference sets associate with a
+  concept in the result are added to it. A reference set the edition does not
+  carry contributes nothing. Whether a bare `HISTORY` means MAX is taken from
+  Snow Owl's reading of the specification - to be confirmed.
+- Alternate identifiers (`LOINC#14394-1`, `"LOINC#14394-1"`): the scheme
+  alias names an identifier scheme (`IDENTIFIER_SCHEMES` in `cs-snomed.js`:
+  LOINC = 30051010000102, from the LOINC Extension's `sct2_Identifier` file,
+  cache version 18+), the code resolves to the concept(s) carrying it, and
+  hierarchy operators apply to them as to any set. An unknown scheme or a
+  code nobody carries is `INVALID_ECL`.
 - Comments (`/* ... */`), terms (`|...|`, not checked against descriptions).
 
 ### Parsed but reported as unsupported
 
-- Reverse attributes (`R 363698007 = ...`).
-- `!=` against an expression value in a refinement.
-- Concrete values in refinements - numeric (`= #5`, `>= #1.5`), string
-  (`= "x"`, `= match:"x"`), boolean (`= true`). The importer does not read
-  `sct2_RelationshipConcreteValues_*`, so no concrete values are in the cache
-  to compare against. Supporting them means extending the importer and the
-  relationship record, and rebuilding every cache.
-- Alternate identifiers (`"ICD10#A01.1"`, `SCTID#123`). No alternate
-  identifier reference sets are loaded.
 - Reference set field selection on member-of (`^ [targetComponentId] refset`,
   `^ [referencedComponentId, targetComponentId] refset`). Deliberate: the
   selected fields, and the referenced components of many reference sets,
   are descriptions or other non-concept components, which an expansion has
   no way to represent.
-- History supplements (`{{ + HISTORY-MIN / MOD / MAX }}`). The association
-  reference sets they draw on are loaded, so this is implementable.
 
 ### Not parsed
 
@@ -99,7 +116,13 @@ that the server does not use. `filterECL` is the one that matters.
 - `^` on a concept that is not a reference set yields an empty result rather
   than an error (Snowstorm's behaviour; agreed in the tx-ecosystem suite).
   `^` on a reference set whose members are descriptions (a language reference
-  set) is reported as unsupported - there are no concepts to return.
+  set) is reported as unsupported when that reference set is named explicitly
+  - there are no concepts to return. Inside a computed operand (`^ *`,
+  `^ (< 900000000000455006)`) such a reference set contributes nothing and
+  the rest of the operand still counts.
+- An attribute name without a comparison (`< X : 363698007`, or `(< X : A = v
+  OR B)` where the OR binds inside the refinement) is a syntax error, as the
+  grammar requires.
 - The ECL result for a value set filter is cached per (value set, code system
   version), so the first expansion of a large constraint is slow and later ones
   are not.
@@ -181,8 +204,9 @@ role group pairing.
 
 - Stated relationships and the OWL axiom reference sets. Everything is driven
   by the distributed inferred relationships; there is no classification.
-- Concrete value relationships (see ECL above).
-- Alternate identifier reference sets.
+- Concrete value relationships are read into cache version 19 (October 2026);
+  caches built before that have none, and a concrete-value ECL refinement on
+  them is reported as unsupported.
 - Inactive reference set member rows (only active rows are stored).
 - Module ids and definition status on concepts are recorded by the current
   importer; caches built before mid-2026 have neither (every concept looks

package/tx/sct/ecl.js

@@ -479,6 +479,22 @@ class ECLLexer {
   }
 }
 
+/**
+ * Bounds on the shape of an ECL expression, so that a hostile expression is a
+ * clean parse error rather than a RangeError (stack overflow) here, in the
+ * evaluator, or in any of the other recursive AST walkers.
+ *
+ * MAX_ECL_DEPTH limits nesting - bracketed expression constraints, bracketed
+ * refinements and attribute sets. Real ECL nests a handful of levels.
+ *
+ * MAX_ECL_TERMS limits the number of sub expression constraints (focus
+ * concepts, refinement values, ...). It is needed as well as the depth limit
+ * because a compound chain ("A OR B OR C ...") is parsed iteratively but builds
+ * a left-deep tree, one level per operator, which every walker then recurses.
+ */
+const MAX_ECL_DEPTH = 100;
+const MAX_ECL_TERMS = 500;
+
 /**
  * ECL Parser - Parses tokens into AST
  */
@@ -487,6 +503,20 @@ class ECLParser {
     this.tokens = tokens;
     this.position = 0;
     this.current = this.tokens[0] || { type: ECLTokenType.EOF };
+    this.depth = 0;
+    this.terms = 0;
+  }
+
+  /** Run a parse step one nesting level deeper, enforcing MAX_ECL_DEPTH. */
+  #nested(fn) {
+    if (++this.depth > MAX_ECL_DEPTH) {
+      this.error(`The expression nests more than ${MAX_ECL_DEPTH} levels deep`);
+    }
+    try {
+      return fn();
+    } finally {
+      this.depth--;
+    }
   }
 
   error(message) {
@@ -526,7 +556,7 @@ class ECLParser {
   }
 
   parseExpressionConstraint() {
-    return this.parseCompoundExpressionConstraint();
+    return this.#nested(() => this.parseCompoundExpressionConstraint());
   }
 
   parseCompoundExpressionConstraint() {
@@ -538,8 +568,11 @@ class ECLParser {
     // this compound sequence and reject a mix (e.g. "<< A OR << B AND << C").
     let compoundOp = null;
 
-    while (this.match(ECLTokenType.AND, ECLTokenType.OR, ECLTokenType.MINUS)) {
-      const operator = this.current;
+    // "," is a conjunction in the ECL grammar (conjunction = "AND" / ","), at
+    // this level as well as in refinements; a comma that reaches here was not
+    // claimed by a refinement.
+    while (this.match(ECLTokenType.AND, ECLTokenType.OR, ECLTokenType.MINUS, ECLTokenType.COMMA)) {
+      const operator = this.match(ECLTokenType.COMMA) ? { ...this.current, type: ECLTokenType.AND } : this.current;
       if (compoundOp !== null && operator.type !== compoundOp) {
         throw new Error(
           'Ambiguous ECL expression: conjunction, disjunction and exclusion ' +
@@ -604,6 +637,9 @@ class ECLParser {
   }
 
   parseSubExpressionConstraint() {
+    if (++this.terms > MAX_ECL_TERMS) {
+      this.error(`The expression has more than ${MAX_ECL_TERMS} terms`);
+    }
     // Handle constraint operators
     let operator = null;
     if (this.match(
@@ -698,7 +734,8 @@ class ECLParser {
   }
 
   /**
-   * Parse one "{{ ... }}" block. Returns { kind: 'M'|'D'|'C'|'+', filters } where
+   * Parse one "{{ ... }}" block (the D of a description filter is optional). Returns
+   * { kind: 'M'|'D'|'C'|'+', filters } where
    * filters is only populated for member filters; the other kinds keep their
    * raw token text so the evaluator can report them as unsupported.
    */
@@ -711,8 +748,13 @@ class ECLParser {
     } else if (this.match(ECLTokenType.SCTID) && /^[MDCmdc]$/.test(this.current.value)) {
       kind = this.current.value.toUpperCase();
       this.advance();
+    } else if (this.match(ECLTokenType.SCTID) && /^[A-Za-z_]/.test(this.current.value)) {
+      // ECL 2.2: descriptionFilterConstraint = "{{" ws [ "d" / "D" ] ws descriptionFilter ...
+      // - the D is optional, so a filter that starts with a field name (term, language,
+      // type, ...) is a description filter
+      kind = 'D';
     } else {
-      this.error('Expected M, D, C or + after {{');
+      this.error('Expected M, D, C, + or a description filter after {{');
     }
 
     if (kind === 'C' || kind === 'D') {
@@ -726,18 +768,30 @@ class ECLParser {
       return { type: ECLNodeType.FILTER_CONSTRAINT, kind, filters };
     }
 
-    if (kind !== 'M') {
-      // Skip to the closing }} keeping the raw text for diagnostics
-      const raw = [];
-      while (!this.match(ECLTokenType.RFILTER)) {
-        if (this.match(ECLTokenType.EOF)) {
-          this.error('Unterminated filter constraint - missing }}');
+    if (kind === '+') {
+      // historySupplement = "{{" "+" "HISTORY" [ "-MIN" / "-MOD" / "-MAX" / "(" (expressionConstraint / "*") ")" ] "}}"
+      if (!this.match(ECLTokenType.SCTID) || !/^HISTORY(-MIN|-MOD|-MAX)?$/i.test(this.current.value)) {
+        this.error('Expected HISTORY, HISTORY-MIN, HISTORY-MOD or HISTORY-MAX after {{ +');
+      }
+      const word = this.current.value.toUpperCase();
+      this.advance();
+      const node = { type: ECLNodeType.FILTER_CONSTRAINT, kind, profile: word === 'HISTORY' ? 'MAX' : word.substring(8) };
+      if (this.match(ECLTokenType.LPAREN)) {
+        if (node.profile !== 'MAX' || word !== 'HISTORY') {
+          this.error('A history profile (HISTORY-MIN/MOD/MAX) cannot also name reference sets');
         }
-        raw.push(this.current.value);
         this.advance();
+        if (this.match(ECLTokenType.WILDCARD)) {
+          this.advance();
+          node.profile = 'MAX';
+        } else {
+          node.profile = 'EXPLICIT';
+          node.refsets = this.parseExpressionConstraint();
+        }
+        this.expect(ECLTokenType.RPAREN);
       }
-      this.advance(); // }}
-      return { type: ECLNodeType.FILTER_CONSTRAINT, kind, raw: raw.join(' ') };
+      this.expect(ECLTokenType.RFILTER);
+      return node;
     }
 
     const filters = [this.parseMemberFilter()];
@@ -1241,7 +1295,7 @@ class ECLParser {
    * returned as-is; otherwise an ATTRIBUTE_SET with operator 'AND' or 'OR'.
    */
   parseRefinement() {
-    return this.parseRefinementSet(() => this.parseSubRefinement(), 'refinement');
+    return this.#nested(() => this.parseRefinementSet(() => this.parseSubRefinement(), 'refinement'));
   }
 
   parseRefinementSet(parseItem, what) {
@@ -1317,7 +1371,7 @@ class ECLParser {
    * (the contents of an attribute group - no nested groups)
    */
   parseAttributeSet() {
-    return this.parseRefinementSet(() => {
+    return this.#nested(() => this.parseRefinementSet(() => {
       if (this.match(ECLTokenType.LPAREN) && !this.#parenIsAttributeName()) {
         this.advance();
         const inner = this.parseAttributeSet();
@@ -1325,7 +1379,7 @@ class ECLParser {
         return inner;
       }
       return this.parseAttribute();
-    }, 'attribute set');
+    }, 'attribute set'));
   }
 
   parseAttributeGroup(cardinality = null) {
@@ -1430,6 +1484,14 @@ class ECLParser {
       };
     }
 
+    if (!comparison) {
+      // eclAttribute = [cardinality] [reverseFlag] eclAttributeName comparison - a
+      // bare name is a syntax error. This is what "(A : B = C OR D)" trips on:
+      // the OR binds inside the refinement, so D is an attribute name without a
+      // comparison.
+      this.error('Expected a comparison operator (=, !=, <, <=, >, >=) after the attribute name');
+    }
+
     return {
       type: ECLNodeType.ATTRIBUTE,
       cardinality,
@@ -2332,6 +2394,8 @@ class ECLValidator {
 }
 
 module.exports = {
+  MAX_ECL_DEPTH,
+  MAX_ECL_TERMS,
   ECLValidator,
   ECLLexer,
   ECLParser,

package/tx/sct/editions.js

@@ -63,8 +63,47 @@ function editionCode(edition) {
   return e ? e.code : null;
 }
 
+/**
+ * The editions snomed.info can resolve an edition-specific concept link for: the same list as
+ * SnomedUtilities.getEditionFromVersion in org.hl7.fhir.core. A code from any other edition
+ * links to http://snomed.info/id/<code>. Also the editions offered when an edition is chosen
+ * (the IPS module's national profiles), in this order.
+ */
+const SNOMED_LINKABLE_EDITIONS = new Set([
+  '900000000000207008', // International
+  '449081005', // International Spanish
+  '11000221109', // Argentinian
+  '32506021000036107', // Australian (with drug extension)
+  '11000234105', // Austrian
+  '11000172109', // Belgian
+  '20621000087109', // Canadian English
+  '20611000087101', // Canadian Canadian French
+  '21000325107', // Chilean
+  '11000279109', // Czech
+  '554471000005108', // Danish
+  '11000181102', // Estonian
+  '11000229106', // Finnish
+  '11000274103', // German
+  '1121000189102', // Indian
+  '11000220105', // Irish
+  '11000146104', // Netherlands
+  '21000210109', // New Zealand
+  '51000202101', // Norwegian
+  '11000267109', // Republic of Korea (South Korea)
+  '900000001000122104', // Spanish National
+  '45991000052106', // Swedish
+  '2011000195101', // Swiss
+  '83821000000107', // UK
+  '999000021000000109', // UK Clinical
+  '5631000179106', // Uruguay
+  '731000124108', // US
+  '5991000124107', // US (with ICD-10-CM maps)
+  '827022005' // IPS Terminology
+]);
+
 module.exports = {
   EDITIONS,
+  SNOMED_LINKABLE_EDITIONS,
   editionName,
   editionCode
 };

package/tx/sct/expressions.js

@@ -13,6 +13,10 @@ const MAX_TERM_LENGTH = 1024;
 // Attribute values are themselves expanded, so a chain of definitions can descend a
 // long way; in real data it is a handful of levels.
 const MAX_NORMALISATION_DEPTH = 50;
+// How deep bracketed attribute values may nest in an expression the parser accepts. The parser
+// (and everything that walks the parsed expression) recurses once per level, so without a bound
+// a hostile expression is a RangeError (stack overflow) rather than a parse error.
+const MAX_EXPRESSION_DEPTH = 100;
 
 const NO_REFERENCE = 0xFFFFFFFF;
 
@@ -483,6 +487,7 @@ class SnomedExpressionParser {
   parse(source) {
     this.source = source;
     this.cursor = 0;
+    this.depth = 0;
 
     const result = new SnomedExpression();
     result.start = this.cursor;
@@ -681,9 +686,12 @@ class SnomedExpressionParser {
     this.ws();
 
     if (this.gchar('(')) {
+      this.depth++;
+      this.rule(this.depth <= MAX_EXPRESSION_DEPTH, `The expression nests more than ${MAX_EXPRESSION_DEPTH} levels deep`);
       const result = this.expression();
       this.ws();
       this.fixed(')');
+      this.depth--;
       return result;
     } else {
       const result = new SnomedExpression();
@@ -2951,6 +2959,7 @@ module.exports = {
 
   // Enums and constants
   SnomedServicesRenderOption,
-  SnomedRefinementGroupMatchState
+  SnomedRefinementGroupMatchState,
+  MAX_EXPRESSION_DEPTH
 };
 

package/tx/sct/load-config.js

@@ -0,0 +1,107 @@
+'use strict';
+
+/**
+ * How each SNOMED CT cache file is loaded, from the tx module's "snomed" block in config.json:
+ *
+ *   "snomed": {
+ *     "load": "read" | "mmap",   // the default for every edition (absent: "read")
+ *     "prewarm": [ ... ],        // map these, then read them through once in the background at startup
+ *     "read": [ ... ]            // read these into the process even when load is "mmap"
+ *   }
+ *
+ * An entry names a cache file (e.g. "sct_us_20250901b.cache"), an edition version URI
+ * ("http://snomed.info/sct/731000124108/version/20250901"), or an edition URI
+ * ("http://snomed.info/sct/731000124108", every loaded version of the edition). "read" wins
+ * over "prewarm", which wins over "load".
+ *
+ *   read    - the file is read into this process (private memory, as before)
+ *   mmap    - the file is mapped read-only; pages are read from disk when first touched, and
+ *             shared with every other process that maps the same file
+ *   prewarm - mapped, and read through once in the background at startup so its pages are
+ *             already in the shared page cache when the first requests arrive
+ */
+
+const path = require('path');
+
+const MODES = ['read', 'mmap'];
+
+class SnomedLoadConfig {
+  /**
+   * @param {object} [block] - the "snomed" block of the tx module config
+   * @param {function(string)} [warn]
+   */
+  constructor(block, warn = () => {}) {
+    this.warn = warn;
+    block = block || {};
+    this.load = 'read';
+    if (block.load !== undefined) {
+      if (MODES.includes(block.load)) {
+        this.load = block.load;
+      } else {
+        warn(`snomed.load must be "read" or "mmap", not ${JSON.stringify(block.load)}; using "read"`);
+      }
+    }
+    this.lists = {};
+    for (const name of ['prewarm', 'read']) {
+      const v = block[name];
+      if (v === undefined) {
+        this.lists[name] = [];
+      } else if (Array.isArray(v) && v.every(e => typeof e === 'string' && e.trim())) {
+        this.lists[name] = v.map(e => e.trim());
+      } else {
+        warn(`snomed.${name} must be a list of cache file names or edition URIs; ignored`);
+        this.lists[name] = [];
+      }
+    }
+    for (const e of this.lists.prewarm) {
+      if (this.lists.read.includes(e)) {
+        warn(`snomed: ${e} is in both "prewarm" and "read"; it will be read`);
+      }
+    }
+    this.used = new Set();
+  }
+
+  /** True if any edition can end up mapped. */
+  mapsAnything() {
+    return this.load === 'mmap' || this.lists.prewarm.length > 0;
+  }
+
+  static #matches(entry, fileName, versionUri) {
+    if (entry === fileName) return true;
+    if (!versionUri) return false;
+    return entry === versionUri || versionUri.startsWith(entry.replace(/\/+$/, '') + '/version/');
+  }
+
+  #find(list, fileName, versionUri) {
+    const hit = this.lists[list].filter(e => SnomedLoadConfig.#matches(e, fileName, versionUri));
+    hit.forEach(e => this.used.add(e));
+    return hit.length > 0;
+  }
+
+  /**
+   * @param {string} filePath - the cache file
+   * @param {string|null} versionUri - its edition version URI, e.g. http://snomed.info/sct/900000000000207008/version/20250201
+   * @returns {'read'|'mmap'|'prewarm'}
+   */
+  modeFor(filePath, versionUri) {
+    const fileName = path.basename(filePath);
+    const read = this.#find('read', fileName, versionUri);
+    const prewarm = this.#find('prewarm', fileName, versionUri);
+    if (read) return 'read';
+    if (prewarm) return 'prewarm';
+    return this.load;
+  }
+
+  /** Warn about entries that matched no loaded edition. Call once every edition is loaded. */
+  checkUnused() {
+    for (const list of ['prewarm', 'read']) {
+      for (const e of this.lists[list]) {
+        if (!this.used.has(e)) {
+          this.warn(`snomed.${list}: "${e}" matches no SNOMED CT edition in the library`);
+        }
+      }
+    }
+  }
+}
+
+module.exports = { SnomedLoadConfig };

package/tx/sct/mmap.js

@@ -0,0 +1,109 @@
+'use strict';
+
+/**
+ * Read-only memory mapping of SNOMED CT cache files ("snomed": {"load": "mmap"} in config.json).
+ *
+ * Node has no mmap of its own, so this calls the C library's mmap() through koffi (an FFI
+ * module that ships prebuilt binaries for Linux glibc and musl, macOS and the BSDs, so
+ * nothing is compiled at install time). The mapping is never unmapped: a loaded edition
+ * stays loaded for the life of the process.
+ *
+ * mapFile() returns null where mapping is not available (Windows, koffi missing, mmap
+ * failing), and the caller then reads the file into memory as before. It says why through the
+ * warn function it is given (the server log), or console.warn where there is none.
+ */
+
+const fs = require('fs');
+
+const PROT_READ = 1;
+const MAP_PRIVATE = 2;          // same value on Linux, macOS and the BSDs
+const MAP_FAILED = 0xFFFFFFFFFFFFFFFFn;
+
+let libcMmap;                   // undefined: not tried yet; null: not available
+let unavailable = null;         // why libcMmap is null
+
+function getMmap() {
+  if (libcMmap === undefined) {
+    libcMmap = null;
+    if (process.platform === 'win32' || !process.arch.endsWith('64')) {
+      unavailable = `not supported on ${process.platform}/${process.arch}`;
+    } else {
+      try {
+        const koffi = require('koffi');
+        const mmap = koffi.load(null).func('void *mmap(void *addr, size_t len, int prot, int flags, int fd, int64_t off)');
+        libcMmap = { koffi, mmap };
+      } catch (e) {
+        unavailable = e.message;
+      }
+    }
+  }
+  return libcMmap;
+}
+
+/** True if mapFile() can map files on this platform (it may still fail for a given file). */
+function mappingAvailable() {
+  return getMmap() !== null;
+}
+
+/**
+ * @param {string} filePath
+ * @param {function(string)} [warn] - where to say why the file was not mapped
+ * @returns {Buffer|null} a read-only Buffer over the whole file, or null
+ */
+function mapFile(filePath, warn = (msg) => console.warn(msg)) {
+  const lib = getMmap();
+  if (!lib) {
+    warn(`SNOMED CT: memory mapping is not available here (${unavailable}); reading ${filePath} into memory`);
+    return null;
+  }
+  const fd = fs.openSync(filePath, 'r');
+  try {
+    const size = fs.fstatSync(fd).size;
+    if (size === 0) return null;
+    const ptr = lib.mmap(null, size, PROT_READ, MAP_PRIVATE, fd, 0);
+    if (ptr === null || lib.koffi.address(ptr) === MAP_FAILED) {
+      warn(`SNOMED CT: could not map ${filePath} (errno ${lib.koffi.errno()}); reading it into memory`);
+      return null;
+    }
+    return Buffer.from(lib.koffi.view(ptr, size));
+  } finally {
+    fs.closeSync(fd);   // the mapping keeps its own reference to the file
+  }
+}
+
+/**
+ * Read a file through once, in the background, so its pages are in the page cache before
+ * requests need them (madvise(MADV_WILLNEED) is only a hint, and on Linux it read almost
+ * nothing of a mapped file). The reads go through one small buffer, so this costs no process
+ * memory; the pages land in the page cache that every mapping of the file shares.
+ *
+ * @param {string} filePath
+ * @returns {Promise<number>} milliseconds taken
+ */
+async function prewarmFile(filePath) {
+  const start = Date.now();
+  const buf = Buffer.allocUnsafe(4 * 1024 * 1024);
+  const fh = await fs.promises.open(filePath, 'r');
+  try {
+    let pos = 0;
+    for (;;) {
+      const { bytesRead } = await fh.read(buf, 0, buf.length, pos);
+      if (bytesRead === 0) break;
+      pos += bytesRead;
+    }
+  } finally {
+    await fh.close();
+  }
+  return Date.now() - start;
+}
+
+/**
+ * For tests: replace the mmap binding ({koffi, mmap}, or null with a reason for "not
+ * available"), or with no arguments go back to the real one.
+ */
+function _setMmapForTesting(lib, reason = 'disabled by a test') {
+  libcMmap = arguments.length === 0 ? undefined : lib;
+  unavailable = lib ? null : reason;
+}
+
+module.exports = { mapFile, prewarmFile, mappingAvailable, _setMmapForTesting };