@petrarca/sonnet-fhir 0.0.1 → 0.9.0

package/dist/questionnaire/index.d.ts

@@ -0,0 +1,299 @@
+import { BuiltinAnswerType, ValueTypeAnswer, DesignerModel } from '@petrarca/sonnet-schema-designer/questionnaire';
+import { Extension } from '../R4/index.js';
+import { QuestionnaireItem, QuestionnaireItemEnableWhen, QuestionnaireResponseItemAnswer, Questionnaire, QuestionnaireResponse } from '../R4/index.js';
+import { FhirConversionOptions } from '../index.js';
+
+/** What a questionnaire conversion reports, whatever the FHIR version. */
+/** A part that did not convert, and why. */
+interface NotConverted {
+    linkId: string;
+    what: string;
+}
+interface FhirConversion<T> {
+    resource: T;
+    notConverted: NotConverted[];
+}
+
+/**
+ * The vocabulary of the questionnaire conversions: the FHIR R4 extension URLs
+ * they read and write, and the `x-fhir-*` annotations that carry, on a schema,
+ * what FHIR says and JSON Schema does not -- declared once, here (ADR-0003: an
+ * `x-` keyword is never a local decision). An annotation is read only by these
+ * conversions; the questionnaire designer keeps it untouched, as any keyword it
+ * does not understand.
+ */
+/** The extension of a value that is missing, and why. */
+declare const DATA_ABSENT_REASON = "http://hl7.org/fhir/StructureDefinition/data-absent-reason";
+/** The extension that says how an item is shown (help, a radio button, ...). */
+declare const ITEM_CONTROL = "http://hl7.org/fhir/StructureDefinition/questionnaire-itemControl";
+/** The code system of the item controls. */
+declare const ITEM_CONTROL_SYSTEM = "http://hl7.org/fhir/questionnaire-item-control";
+/** The extension of a unit a quantity may be given in, one per unit. */
+declare const UNIT_OPTION = "http://hl7.org/fhir/StructureDefinition/questionnaire-unitOption";
+/** The extensions of an answer's limits: its length, pattern, range, count. */
+declare const MIN_LENGTH = "http://hl7.org/fhir/StructureDefinition/minLength";
+declare const REGEX = "http://hl7.org/fhir/StructureDefinition/regex";
+declare const MIN_VALUE = "http://hl7.org/fhir/StructureDefinition/minValue";
+declare const MAX_VALUE = "http://hl7.org/fhir/StructureDefinition/maxValue";
+declare const MIN_OCCURS = "http://hl7.org/fhir/StructureDefinition/questionnaire-minOccurs";
+declare const MAX_OCCURS = "http://hl7.org/fhir/StructureDefinition/questionnaire-maxOccurs";
+/**
+ * Our own extension: the option of an open choice that asks for a text of one's
+ * own -- "other, please describe" -- its value and label, as a coding. FHIR's
+ * open-choice names no such option; written only when it is not the default
+ * `other` / "Other". Other tools ignore it.
+ */
+declare const OTHER_OPTION_EXTENSION = "https://schemas.petrarca-labs.com/fhir/StructureDefinition/questionnaire-otherOption";
+/** The extension of an example shown in an empty field. */
+declare const ENTRY_FORMAT = "http://hl7.org/fhir/StructureDefinition/entryFormat";
+/**
+ * The prefix of every annotation. An element the conversion does not map is
+ * kept as `x-fhir-<element>`, its value as FHIR writes it -- an item's
+ * `prefix`, `code`, `answerValueSet`, a Questionnaire's `url`, `version`,
+ * `status` -- and written back as that element.
+ */
+declare const X_FHIR = "x-fhir-";
+/** An item's linkId, when it is not its key path. */
+declare const X_FHIR_LINK_ID = "x-fhir-linkId";
+/** The extensions the conversion does not map, as FHIR writes them. */
+declare const X_FHIR_EXTENSION = "x-fhir-extension";
+/** The code system of a choice's options. */
+declare const X_FHIR_SYSTEM = "x-fhir-system";
+/** The linkId of a question's help item, when it is not `<linkId>.help`. */
+declare const X_FHIR_HELP_LINK_ID = "x-fhir-helpLinkId";
+/** A section's lead question, by key: the section is a question with follow-up questions in FHIR. */
+declare const X_FHIR_LEAD_QUESTION = "x-fhir-leadQuestion";
+/** An item that does not convert, kept whole: written back as it was. */
+declare const X_FHIR_ITEM = "x-fhir-item";
+/**
+ * The annotations of a question that do not depend on its answer type -- its
+ * linkId, its help's linkId, its prefix, its codes, its definition -- so that a
+ * questionnaire read from FHIR and edited in the questionnaire designer goes
+ * back with them. Hand them to the designer (`keptOnTypeChange`); the others
+ * (a choice's code system, extensions of the old type) go with the type.
+ */
+declare const FHIR_TYPE_INDEPENDENT_ANNOTATIONS: readonly string[];
+/** Whether a keyword is an annotation of these conversions. */
+declare function isFhirAnnotation(keyword: string): boolean;
+
+/**
+ * How a FHIR version spells a questionnaire's items -- the one thing the
+ * conversions ask their version: the item type of each built-in answer type,
+ * and the answer type of an item. Everything else is version-neutral. Each
+ * version implements it in its module (r4.ts, r5.ts).
+ */
+
+/** An item as a version writes a built-in answer type. */
+interface ItemSpelling {
+    type: string;
+    repeats?: boolean;
+    /** R5: whether a choice takes a text of one's own. */
+    answerConstraint?: string;
+}
+interface Spelling {
+    /** The item a built-in answer type is written as; `open`: a choice that takes a text of one's own. */
+    write(answerType: BuiltinAnswerType, open: boolean): ItemSpelling;
+    /** The built-in answer type of an item; none when it has none (a choice with text is read from its shape). */
+    answerTypeOf(item: QuestionnaireItem): BuiltinAnswerType | undefined;
+    /** Whether an item is a choice of its options only -- one that may carry a note. */
+    isChoice(item: QuestionnaireItem): boolean;
+    /** Whether an item is a choice that also takes a text of one's own: "other, please describe". */
+    isOpen(item: QuestionnaireItem): boolean;
+    /** The item elements the spelling itself maps (R5's `answerConstraint`). */
+    elements: string[];
+}
+
+/**
+ * Value types in FHIR -- a value type contributed to the questionnaire
+ * conversions: the item type it is, its settings as the item's extensions,
+ * its answers. Sonnet contributes the core types the same way an application
+ * contributes its own; a value type without one is kept whole, as any item of
+ * no answer type. See docs/design/value-types.md (workspace).
+ */
+
+/** What a condition compares with: a value -- or, `asText`, a text of one's own. */
+interface Comparand {
+    value: string;
+    asText?: boolean;
+}
+/** What a value type's settings and answers are read and written with. */
+interface ValueTypeContext {
+    settings: Record<string, unknown>;
+    /** The code system the question keeps (`x-fhir-system`), when it names one. */
+    system?: string;
+}
+/**
+ * What a value type writes on its item: extensions, and elements of the item
+ * (`answerValueSet`) -- and, written without them, what of its settings FHIR
+ * cannot say, reported.
+ */
+interface ItemParts {
+    [element: string]: unknown;
+    extension?: Extension[];
+    answerValueSet?: string;
+    notConverted?: string[];
+}
+/** A value type contributed to the questionnaire conversions. */
+interface FhirValueType {
+    /** The answer type it is in the questionnaire designer. */
+    answer: ValueTypeAnswer;
+    /** The item type it is written as, the same in every version; or `spell` it. */
+    itemType?: string;
+    /**
+     * How a version spells its item -- for a type whose item type differs by
+     * version, or when it takes a text of one's own (`orText`: a coded value's
+     * open list, R4 `open-choice`, R5 `optionsOrString`). A type that spells its
+     * item reads only the items it `claims`.
+     */
+    spell?(spelling: Spelling, orText: boolean): ItemSpelling;
+    /**
+     * Whether an item is its own -- needed when it shares the item type with a
+     * built-in answer type (a decimal with a currency); default: every item of
+     * its `itemType`. An item it does not claim is read as the built-in type.
+     */
+    claims?(item: QuestionnaireItem, spelling: Spelling): boolean;
+    /**
+     * Whether it takes several answers -- an array of the type, a repeating
+     * item, one answer each; default: one answer, a repeating item kept whole.
+     */
+    repeats?: boolean;
+    /** Its settings as the item's extensions and elements -- and, in `notConverted`, those FHIR cannot say. */
+    toItem(context: ValueTypeContext): ItemParts;
+    /** Its settings read from an item, with the extensions and elements read; why not, when they cannot be. */
+    fromItem(item: QuestionnaireItem, spelling: Spelling): {
+        settings: Record<string, unknown>;
+        system?: string;
+        extensions: Extension[];
+        /** The item's elements it read (`answerValueSet`), so they are not kept a second time. */
+        elements?: string[];
+    } | {
+        why: string;
+    };
+    /** A show-if's comparand -- a value, or a text of one's own -- as an enableWhen answer; default: `answerString`. */
+    toEnableAnswer?(comparand: Comparand, context: ValueTypeContext): Partial<QuestionnaireItemEnableWhen>;
+    /** An enableWhen answer as a show-if's comparand; why not, when it cannot say it. */
+    fromEnableAnswer?(e: QuestionnaireItemEnableWhen, context: ValueTypeContext): Comparand | {
+        why: string;
+    };
+    toAnswer(value: unknown, context: ValueTypeContext): QuestionnaireResponseItemAnswer;
+    fromAnswer(answer: QuestionnaireResponseItemAnswer, context: ValueTypeContext): unknown;
+}
+/** The options of the questionnaire conversions: the version, and the value types they know. */
+type QuestionnaireConversionOptions = FhirConversionOptions & {
+    /** The value types contributed; default: the core types. */
+    valueTypes?: readonly FhirValueType[];
+};
+/** The quantity: item type `quantity`, its units as unit options, its answers `valueQuantity`. */
+declare const QUANTITY_FHIR: FhirValueType;
+/** The value types sonnet contributes: the core types. */
+declare const DEFAULT_FHIR_VALUE_TYPES: readonly FhirValueType[];
+/**
+ * The item a value type is written as, in a version; `orText`: it also takes a
+ * text of one's own; `multiple`: several answers, a repeating item.
+ */
+declare function itemOf(type: FhirValueType, spelling: Spelling, orText: boolean, multiple: boolean): ItemSpelling;
+/** Whether an item is a value type's: its own claim, else its item type. */
+declare function claimsItem(type: FhirValueType, item: QuestionnaireItem, spelling: Spelling): boolean;
+/** The value types a conversion knows: its options', else the core types. */
+declare function valueTypesOf(options: QuestionnaireConversionOptions): readonly FhirValueType[];
+/** The answer types those value types are, for the questionnaire designer's classification. */
+declare function answerTypesOf(types: readonly FhirValueType[]): readonly ValueTypeAnswer[];
+/** The value type of an answer type, when it is one. */
+declare function fhirValueType(answerType: string, types: readonly FhirValueType[]): FhirValueType | undefined;
+
+/**
+ * The coded value in FHIR: a question whose answers come from a value set --
+ * R4 `choice` with `answerValueSet`, R5 `coding`; one that also takes a text of
+ * one's own R4 `open-choice`, R5 `optionsOrString`. Its answers are
+ * `valueCoding`, a text of one's own `valueString`; a show-if on it compares a
+ * coding's system and code, as FHIR's `answerCoding` does. See
+ * docs/design/coded-values.md (workspace).
+ */
+
+/** The coded value: a question on a value set, its answers codings -- or texts of one's own. */
+declare const CODING_FHIR: FhirValueType;
+
+/**
+ * The codeable concept in a FHIR questionnaire. FHIR has no codeable-concept
+ * answer -- an answer is one `Coding`, R4 and R5 alike -- so a codeable concept
+ * question is written as a coded value's (`choice` with its first list as
+ * `answerValueSet`, R5 `coding`), its answer its first coding, or its text
+ * alone as `valueString`. Its further lists and the text beside its codes are
+ * ours, more than FHIR says: reported, not owed. A questionnaire read from FHIR
+ * has no codeable concept question, so none is ever read as one. In a resource
+ * a codeable concept is a `CodeableConcept` (`@petrarca/sonnet-fhir/datatypes`).
+ * See docs/design/codeable-concepts.md (workspace).
+ */
+
+/** The codeable concept: written as a coded value's question, its answer its first coding. */
+declare const CODEABLE_CONCEPT_FHIR: FhirValueType;
+
+/**
+ * A questionnaire to FHIR R4 -- the schema, read by classifyQuestionnaire, as a
+ * `Questionnaire`. Pure, no FHIR library. The `x-fhir-*` annotations are
+ * written back as the elements they keep. What does not convert -- a part the
+ * questionnaire designer does not understand, a keyword beyond an answer type
+ * -- is reported in `notConverted`, never dropped silently. See
+ * docs/design/questionnaire-conversion.md.
+ */
+
+/** The questionnaire as a FHIR R4 `Questionnaire` -- a draft, unless it was read with a status; what did not convert, reported. */
+declare function toFhirQuestionnaire(model: DesignerModel, options: QuestionnaireConversionOptions): FhirConversion<Questionnaire>;
+
+/**
+ * Answers to FHIR R4 -- one set of a questionnaire's answers as a
+ * `QuestionnaireResponse`. Pure, no FHIR library. See
+ * docs/design/questionnaire-conversion.md.
+ */
+
+type Answers$1 = Record<string, unknown>;
+/** One set of answers as a FHIR R4 `QuestionnaireResponse` to the questionnaire. */
+/**
+ * A response's own elements, beside its answers -- `id`, `subject`, `author`,
+ * `authored`, `meta`, its extensions, ... -- as read (fromFhirQuestionnaireResponse)
+ * and written back.
+ */
+interface ResponseElements {
+    [element: string]: unknown;
+    questionnaire?: string;
+    status?: QuestionnaireResponse["status"];
+}
+declare function toFhirQuestionnaireResponse(model: DesignerModel, data: Answers$1, options: QuestionnaireConversionOptions & {
+    status?: QuestionnaireResponse["status"];
+    /** The response's own elements, as read: written back beside the answers. */
+    elements?: ResponseElements;
+}): QuestionnaireResponse;
+
+/**
+ * A FHIR R4 `Questionnaire` as a questionnaire on JSON Schema -- built with
+ * the questionnaire designer's own edits, so it reads as one authored there.
+ * Pure, no FHIR library. What JSON Schema does not say is kept in `x-fhir-*`
+ * annotations; an item of no answer type is kept whole -- shown locked, written
+ * back as it came. What is kept but does not work as in FHIR is reported in
+ * `notConverted`. See docs/design/questionnaire-conversion.md.
+ */
+
+/** A FHIR R4 `Questionnaire` as a questionnaire on JSON Schema; what does not work as in FHIR, reported. */
+declare function fromFhirQuestionnaire(questionnaire: Questionnaire, options: QuestionnaireConversionOptions): {
+    model: DesignerModel;
+    notConverted: NotConverted[];
+};
+
+/**
+ * A FHIR R4 `QuestionnaireResponse` as one set of a questionnaire's answers --
+ * the reverse of toFhirQuestionnaireResponse. Pure, no FHIR library. An answer
+ * to no question of the questionnaire, or to one of no answer type, is reported
+ * in `notConverted`. See docs/design/questionnaire-conversion.md.
+ */
+
+type Answers = Record<string, unknown>;
+/** A FHIR R4 `QuestionnaireResponse` as the answers to the questionnaire; what has no place, reported. */
+declare function fromFhirQuestionnaireResponse(model: DesignerModel, response: QuestionnaireResponse, options: QuestionnaireConversionOptions): {
+    data: Answers;
+    /** The response's own elements -- id, subject, author, authored, ... -- for writing it back. */
+    elements: ResponseElements;
+    notConverted: NotConverted[];
+};
+
+export { CODEABLE_CONCEPT_FHIR, CODING_FHIR, DATA_ABSENT_REASON, DEFAULT_FHIR_VALUE_TYPES, ENTRY_FORMAT, FHIR_TYPE_INDEPENDENT_ANNOTATIONS, ITEM_CONTROL, ITEM_CONTROL_SYSTEM, MAX_OCCURS, MAX_VALUE, MIN_LENGTH, MIN_OCCURS, MIN_VALUE, OTHER_OPTION_EXTENSION, QUANTITY_FHIR, REGEX, UNIT_OPTION, X_FHIR, X_FHIR_EXTENSION, X_FHIR_HELP_LINK_ID, X_FHIR_ITEM, X_FHIR_LEAD_QUESTION, X_FHIR_LINK_ID, X_FHIR_SYSTEM, answerTypesOf, claimsItem, fhirValueType, fromFhirQuestionnaire, fromFhirQuestionnaireResponse, isFhirAnnotation, itemOf, toFhirQuestionnaire, toFhirQuestionnaireResponse, valueTypesOf };
+export type { Comparand, FhirConversion, FhirValueType, ItemParts, NotConverted, QuestionnaireConversionOptions, ResponseElements, ValueTypeContext };