fhirpath-ts 0.0.0-bootstrap.0

package/src/fhir/html-checks.ts

@@ -0,0 +1,266 @@
+/**
+ * FHIR narrative validation for htmlChecks(): the xhtml must be well formed, use
+ * only the elements and attributes the FHIR spec allows in Narrative.div, and
+ * carry no active content. (https://hl7.org/fhir/narrative.html)
+ */
+
+const ALLOWED_ELEMENTS = new Set([
+  'div',
+  'p',
+  'b',
+  'i',
+  'em',
+  'strong',
+  'u',
+  's',
+  'strike',
+  'small',
+  'big',
+  'tt',
+  'sub',
+  'sup',
+  'span',
+  'br',
+  'hr',
+  'ul',
+  'ol',
+  'li',
+  'dl',
+  'dt',
+  'dd',
+  'table',
+  'caption',
+  'col',
+  'colgroup',
+  'thead',
+  'tbody',
+  'tfoot',
+  'tr',
+  'td',
+  'th',
+  'pre',
+  'blockquote',
+  'q',
+  'a',
+  'img',
+  'code',
+  'samp',
+  'kbd',
+  'var',
+  'abbr',
+  'acronym',
+  'cite',
+  'dfn',
+  'address',
+  'bdo',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+])
+
+const VOID_ELEMENTS = new Set(['br', 'hr', 'img', 'col'])
+
+const ALLOWED_ATTRIBUTES = new Set([
+  'abbr',
+  'accesskey',
+  'align',
+  'alt',
+  'axis',
+  'bgcolor',
+  'border',
+  'cellhalign',
+  'cellpadding',
+  'cellspacing',
+  'cellvalign',
+  'char',
+  'charoff',
+  'charset',
+  'cite',
+  'class',
+  'colspan',
+  'compact',
+  'coords',
+  'dir',
+  'frame',
+  'headers',
+  'height',
+  'href',
+  'hreflang',
+  'hspace',
+  'id',
+  'lang',
+  'longdesc',
+  'name',
+  'nowrap',
+  'rel',
+  'rev',
+  'rowspan',
+  'rules',
+  'scope',
+  'shape',
+  'span',
+  'src',
+  'start',
+  'style',
+  'summary',
+  'tabindex',
+  'title',
+  'type',
+  'valign',
+  'value',
+  'vspace',
+  'width',
+  'xmlns',
+  'xml:id',
+  'xml:lang',
+  'xml:space',
+])
+
+const TAG_PATTERN = /<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|<[^>]*>|[^<]+/g
+const OPEN_TAG = /^<([a-zA-Z][a-zA-Z0-9]*)((?:\s+[^\s=>/]+(?:\s*=\s*(?:"[^"]*"|'[^']*'))?)*)\s*(\/?)>$/
+const CLOSE_TAG = /^<\/([a-zA-Z][a-zA-Z0-9]*)\s*>$/
+const ATTRIBUTE = /([^\s=>/]+)(?:\s*=\s*("[^"]*"|'[^']*'))?/g
+
+export function validateNarrative(xhtml: string): boolean {
+  const stack: string[] = []
+  let sawRoot = false
+  let position = 0
+  for (const match of xhtml.matchAll(TAG_PATTERN)) {
+    if (match.index !== position) {
+      return false
+    }
+    position = match.index + match[0].length
+    const token = match[0]
+    if (!token.startsWith('<')) {
+      // Text content: a stray '>' is fine, but only whitespace may sit outside the root.
+      if (stack.length === 0 && token.trim() !== '') {
+        return false
+      }
+      // Well-formed XHTML only uses the five XML entities and numeric references;
+      // an unknown entity (e.g. &Tab;) means the document is not well-formed.
+      if (decodeEntities(token) === undefined) {
+        return false
+      }
+      continue
+    }
+    if (token.startsWith('<!--') || token.startsWith('<![CDATA[')) {
+      continue
+    }
+    const close = CLOSE_TAG.exec(token)
+    if (close) {
+      const name = (close[1] as string).toLowerCase()
+      if (stack.pop() !== name) {
+        return false
+      }
+      continue
+    }
+    const open = OPEN_TAG.exec(token)
+    if (!open) {
+      return false
+    }
+    const name = (open[1] as string).toLowerCase()
+    if (!ALLOWED_ELEMENTS.has(name)) {
+      return false
+    }
+    if (stack.length === 0) {
+      if (sawRoot || name !== 'div') {
+        return false
+      }
+      sawRoot = true
+      if (!/xmlns\s*=\s*["']http:\/\/www\.w3\.org\/1999\/xhtml["']/.test(token)) {
+        return false
+      }
+    }
+    if (!validAttributes(open[2] as string)) {
+      return false
+    }
+    const selfClosing = open[3] === '/' || VOID_ELEMENTS.has(name)
+    if (!selfClosing) {
+      stack.push(name)
+    }
+  }
+  return sawRoot && stack.length === 0 && position === xhtml.length
+}
+
+function validAttributes(attributesText: string): boolean {
+  for (const match of attributesText.matchAll(ATTRIBUTE)) {
+    const name = (match[1] as string).toLowerCase()
+    if (name.startsWith('on') || !ALLOWED_ATTRIBUTES.has(name)) {
+      return false
+    }
+    const value = match[2]?.slice(1, -1) ?? ''
+    if ((name === 'href' || name === 'src') && !safeUrl(value, name)) {
+      return false
+    }
+  }
+  return true
+}
+
+const SAFE_SCHEMES = new Set(['http', 'https', 'mailto', 'tel', 'ftp', 'urn', 'cid'])
+
+/**
+ * Allow only inert URL schemes. Browsers entity-decode attribute values and skip
+ * control characters before resolving the scheme, so the check must see the value
+ * the way a browser does — `java&#115;cript:` is still `javascript:`.
+ */
+function safeUrl(rawValue: string, attributeName: string): boolean {
+  const decoded = decodeEntities(rawValue)
+  if (decoded === undefined) {
+    // An unknown entity in the URL (e.g. javascript&colon;) is malformed; reject.
+    return false
+  }
+  // eslint-disable-next-line no-control-regex -- stripping control characters is the point
+  const value = decoded.replace(/[\u0000-\u0020]/gu, '')
+  const scheme = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(value)
+  if (!scheme) {
+    // Relative URL or fragment: no scheme to smuggle code through.
+    return true
+  }
+  const name = (scheme[1] as string).toLowerCase()
+  if (attributeName === 'src' && name === 'data') {
+    // Inline images are common in narratives; data: must never reach href.
+    return /^data:image\//i.test(value)
+  }
+  return SAFE_SCHEMES.has(name)
+}
+
+const NAMED_ENTITIES: Readonly<Record<string, string>> = {
+  lt: '<',
+  gt: '>',
+  amp: '&',
+  quot: '"',
+  apos: "'",
+}
+
+/**
+ * Resolve XML entity and numeric character references. Returns undefined when the
+ * text contains an entity XHTML does not define — those five names plus numeric
+ * references are the only well-formed forms, so anything else fails validation
+ * instead of passing through unresolved (which is how &Tab;/&colon; smuggled a
+ * javascript: URL past the scheme check).
+ */
+function decodeEntities(text: string): string | undefined {
+  let malformed = false
+  const decoded = text.replace(/&(?:#x([0-9a-fA-F]+)|#(\d+)|([a-zA-Z0-9]+));/g, (whole, hex, dec, named) => {
+    if (hex !== undefined) {
+      return fromCodePoint(Number.parseInt(hex, 16))
+    }
+    if (dec !== undefined) {
+      return fromCodePoint(Number.parseInt(dec, 10))
+    }
+    const resolved = NAMED_ENTITIES[named as string]
+    if (resolved === undefined) {
+      malformed = true
+      return whole
+    }
+    return resolved
+  })
+  return malformed ? undefined : decoded
+}
+
+function fromCodePoint(codePoint: number): string {
+  return codePoint >= 0 && codePoint <= 0x10ffff ? String.fromCodePoint(codePoint) : '\uFFFD'
+}

package/src/fhir/model-navigation.ts

@@ -0,0 +1,148 @@
+import type { ModelProvider } from '../model/provider.ts'
+import { Temporal } from '../values/datetime.ts'
+import { Decimal } from '../values/decimal.ts'
+import { FHIR_PRIMITIVE_TO_SYSTEM, toTypedValue, type TypedValue } from '../values/typed-value.ts'
+
+export function isFhirPrimitiveType(typeName: string): boolean {
+  return FHIR_PRIMITIVE_TO_SYSTEM[typeName] !== undefined
+}
+
+/**
+ * Read one element with model knowledge: choice elements resolve their suffixed
+ * JSON key, primitives parse into System values (dates become Temporal, decimals
+ * become Decimal) and carry their `_field` sibling for extension/id access.
+ * Undefined when the model does not know the element.
+ */
+export function readModelProperty(model: ModelProvider, item: TypedValue, name: string): TypedValue[] | undefined {
+  const metadata = readPrimitiveMetadata(item, name)
+  if (metadata !== undefined) {
+    return metadata
+  }
+  const info = model.getElement(item.type, name)
+  if (!info) {
+    return undefined
+  }
+  const container = item.value
+  if (typeof container !== 'object' || container === null || Array.isArray(container)) {
+    return []
+  }
+  const record = container as Record<string, unknown>
+  if (info.isChoice) {
+    for (const typeName of info.types) {
+      const key = name + typeName.charAt(0).toUpperCase() + typeName.slice(1)
+      if (record[key] !== undefined && record[key] !== null) {
+        return convertValues(record[key], record[`_${key}`], typeName)
+      }
+      // A choice primitive may be present through its `_field` sibling alone,
+      // e.g. { _valueString: { extension: [...] } } with no valueString.
+      const sibling = record[`_${key}`]
+      if (sibling !== undefined && sibling !== null && isFhirPrimitiveType(typeName)) {
+        return convertValues(undefined, sibling, typeName)
+      }
+    }
+    return []
+  }
+  const raw = record[name]
+  if (raw === undefined || raw === null) {
+    // A primitive may be present through its `_field` sibling alone.
+    const sibling = record[`_${name}`]
+    if (sibling !== undefined && sibling !== null && isFhirPrimitiveType(info.types[0] as string)) {
+      return convertValues(undefined, sibling, info.types[0] as string)
+    }
+    return []
+  }
+  return convertValues(raw, record[`_${name}`], info.types[0] as string)
+}
+
+/** `id` and `extension` on an already-navigated primitive come from its `_field` sibling. */
+function readPrimitiveMetadata(item: TypedValue, name: string): TypedValue[] | undefined {
+  if (item.primitiveElement === undefined || (name !== 'id' && name !== 'extension')) {
+    return undefined
+  }
+  const metadata = item.primitiveElement as Record<string, unknown>
+  const value = metadata[name]
+  if (value === undefined || value === null) {
+    return []
+  }
+  if (name === 'id') {
+    return [{ type: 'System.String', value }]
+  }
+  return (Array.isArray(value) ? value : [value]).map(extension => ({
+    type: 'FHIR.Extension',
+    value: extension,
+  }))
+}
+
+function convertValues(raw: unknown, sibling: unknown, typeName: string): TypedValue[] {
+  if (Array.isArray(raw) || Array.isArray(sibling)) {
+    // The value and _name arrays align by index and either may be the longer one:
+    // a tail entry present only in _name is still an element (with extensions).
+    const values = Array.isArray(raw) ? raw : []
+    const siblings = Array.isArray(sibling) ? sibling : []
+    const result: TypedValue[] = []
+    for (let index = 0; index < Math.max(values.length, siblings.length); index++) {
+      const converted = convertSingle(values[index], siblings[index], typeName)
+      if (converted) {
+        result.push(converted)
+      }
+    }
+    return result
+  }
+  const converted = convertSingle(raw, sibling, typeName)
+  return converted ? [converted] : []
+}
+
+function convertSingle(raw: unknown, sibling: unknown, typeName: string): TypedValue | undefined {
+  if ((raw === undefined || raw === null) && (sibling === undefined || sibling === null)) {
+    return undefined
+  }
+  // Element ids and primitive value elements carry System types directly.
+  if (typeName.startsWith('System.')) {
+    return raw === undefined || raw === null ? undefined : { type: typeName, value: raw }
+  }
+  const systemType = FHIR_PRIMITIVE_TO_SYSTEM[typeName]
+  if (systemType === undefined) {
+    // Complex, backbone, or resource element.
+    if (raw === undefined || raw === null) {
+      return undefined
+    }
+    if (typeName === 'Resource' || typeName === 'DomainResource') {
+      return toTypedValue(raw)
+    }
+    return { type: `FHIR.${typeName}`, value: raw }
+  }
+  // FHIR primitives keep their FHIR type (the official type() and is() tests rely
+  // on it) while the value itself parses into the System representation.
+  const typed: TypedValue = { type: `FHIR.${typeName}`, value: parsePrimitive(raw, systemType) }
+  if (sibling !== undefined && sibling !== null) {
+    typed.primitiveElement = sibling
+  }
+  return typed
+}
+
+function parsePrimitive(raw: unknown, systemType: string): unknown {
+  if (raw === undefined || raw === null) {
+    return undefined
+  }
+  switch (systemType) {
+    case 'System.Date': {
+      return typeof raw === 'string' ? (Temporal.parseDate(raw) ?? raw) : raw
+    }
+    case 'System.DateTime': {
+      return typeof raw === 'string' ? (Temporal.parseDateTime(raw) ?? raw) : raw
+    }
+    case 'System.Time': {
+      return typeof raw === 'string' ? (Temporal.parseTime(raw) ?? raw) : raw
+    }
+    case 'System.Decimal': {
+      const parsed = typeof raw === 'number' ? Decimal.fromNumber(raw) : Decimal.fromString(String(raw))
+      return parsed ?? raw
+    }
+    /* v8 ignore next 3 -- R4 has no integer64 elements; kept for R5 model reuse */
+    case 'System.Long': {
+      return typeof raw === 'number' ? BigInt(raw) : raw
+    }
+    default:
+      return raw
+  }
+}

package/src/functions/aggregate.ts

@@ -0,0 +1,136 @@
+import { withFrame } from '../engine/context.ts'
+import { FhirPathTypeError } from '../errors.ts'
+import { Decimal } from '../values/decimal.ts'
+import { asNumeric, type NumericKind, widerKind, wrapNumeric } from '../values/numeric.ts'
+import { alignQuantities, coerceQuantity } from '../values/quantity.ts'
+import { type QuantityValue, SYSTEM_DECIMAL, SYSTEM_QUANTITY, type TypedValue } from '../values/typed-value.ts'
+import { argAt, registerFunction } from './registry.ts'
+
+registerFunction('aggregate', {
+  minArity: 1,
+  maxArity: 2,
+  evaluate: (context, input, args, evaluateNode) => {
+    let total: TypedValue[] = args.length === 2 ? evaluateNode(argAt(args, 1), context, input) : []
+    input.forEach((item, index) => {
+      total = withFrame(context, { thisValue: [item], index, total }, frameContext =>
+        evaluateNode(argAt(args, 0), frameContext, [item])
+      )
+    })
+    return total
+  },
+})
+
+/** Shared by sum/min/max/avg: all items must be numeric, of a comparable kind. */
+function numericItems(name: string, input: TypedValue[]): { values: Decimal[]; kind: NumericKind } {
+  let kind: NumericKind = 'Integer'
+  const values = input.map(item => {
+    const numeric = asNumeric(item)
+    if (!numeric) {
+      throw new FhirPathTypeError(`${name}() expects numeric values, found ${item.type}`)
+    }
+    kind = widerKind(kind, numeric.kind)
+    return numeric.value
+  })
+  return { values, kind }
+}
+
+/**
+ * Quantity collections aggregate by pairwise-aligning units, exactly like
+ * repeated `+`: (1 'cm' | 3 'cm' | 1 'm').sum() = 104 'cm'. Empty when any
+ * pair of units cannot align.
+ */
+function foldQuantities(quantities: QuantityValue[], fold: (acc: Decimal, next: Decimal) => Decimal): TypedValue[] {
+  let acc = quantities[0] as QuantityValue
+  for (const quantity of quantities.slice(1)) {
+    const pair = alignQuantities(acc, quantity)
+    if (!pair) {
+      return []
+    }
+    acc = { value: fold(pair.left, pair.right), unit: pair.unit, calendar: pair.calendar }
+  }
+  return [{ type: SYSTEM_QUANTITY, value: acc }]
+}
+
+function allQuantities(input: TypedValue[]): QuantityValue[] | undefined {
+  const quantities: QuantityValue[] = []
+  for (const item of input) {
+    const quantity = coerceQuantity(item)
+    if (quantity === undefined) {
+      return undefined
+    }
+    quantities.push(quantity)
+  }
+  return quantities
+}
+
+// Convenience aggregates (ballot STU). All four are empty for empty input.
+registerFunction('sum', {
+  minArity: 0,
+  maxArity: 0,
+  evaluate: (_context, input) => {
+    if (input.length === 0) {
+      return []
+    }
+    const quantities = allQuantities(input)
+    if (quantities) {
+      return foldQuantities(quantities, (acc, next) => acc.add(next))
+    }
+    const { values, kind } = numericItems('sum', input)
+    const total = values.reduce((acc, value) => acc.add(value), Decimal.zero())
+    return [wrapNumeric(total, kind)]
+  },
+})
+
+function extremum(name: string, keep: (comparison: number) => boolean): void {
+  registerFunction(name, {
+    minArity: 0,
+    maxArity: 0,
+    evaluate: (_context, input) => {
+      if (input.length === 0) {
+        return []
+      }
+      const quantities = allQuantities(input)
+      if (quantities) {
+        return foldQuantities(quantities, (acc, next) => (keep(next.compare(acc)) ? next : acc))
+      }
+      const { values, kind } = numericItems(name, input)
+      let best = values[0] as Decimal
+      for (const value of values.slice(1)) {
+        if (keep(value.compare(best))) {
+          best = value
+        }
+      }
+      return [wrapNumeric(best, kind)]
+    },
+  })
+}
+
+extremum('min', comparison => comparison < 0)
+extremum('max', comparison => comparison > 0)
+
+registerFunction('avg', {
+  minArity: 0,
+  maxArity: 0,
+  evaluate: (_context, input) => {
+    if (input.length === 0) {
+      return []
+    }
+    const count = Decimal.fromString(String(input.length)) as Decimal
+    const quantities = allQuantities(input)
+    if (quantities) {
+      const total = foldQuantities(quantities, (acc, next) => acc.add(next))
+      if (total.length === 0) {
+        return []
+      }
+      const sum = (total[0] as TypedValue).value as QuantityValue
+      const average = sum.value.divide(count)
+      /* v8 ignore next -- the divisor is the non-zero item count */
+      return average === undefined ? [] : [{ type: SYSTEM_QUANTITY, value: { ...sum, value: average } }]
+    }
+    const { values } = numericItems('avg', input)
+    const total = values.reduce((acc, value) => acc.add(value), Decimal.zero())
+    const average = total.divide(count)
+    /* v8 ignore next -- the divisor is the non-zero item count */
+    return average === undefined ? [] : [{ type: SYSTEM_DECIMAL, value: average }]
+  },
+})