Merge pull request #231 from atomic-ehr/feat/extension-valid-flat-mode

TS: Split the complex extension flat getter into flat and vflat

Author: ryukzak

examples/typescript-custom-packages/__snapshots__/profile-complex-extension-flat.test.ts.snap

@@ -460,6 +460,9 @@ import {
     validateMustSupport,
 } from "../../profile-helpers";
 
+export type NotedPatient_NotedExtracted = Partial<Pick<NotedComplexExtensionProfileFlat, "note" | "detail">>;
+export type NotedPatient_NotedVFlat = Pick<NotedComplexExtensionProfileFlat, "note" | "detail">;
+
 // CanonicalURL: http://example.test/StructureDefinition/noted-patient (pkg: example.folder.structures#0.0.1)
 export class NotedPatientProfile {
     static readonly resourceType = "Patient";
@@ -524,17 +527,23 @@ export class NotedPatientProfile {
         return this
     }
 
-    public getNoted(mode: 'flat'): NotedComplexExtensionProfileFlat | undefined;
+    public getNoted(mode: 'flat'): NotedPatient_NotedExtracted | undefined;
+    public getNoted(mode: 'vflat'): NotedPatient_NotedVFlat | undefined;
     public getNoted(mode: 'profile'): NotedComplexExtensionProfile | undefined;
     public getNoted(mode: 'raw'): Extension | undefined;
-    public getNoted(): NotedComplexExtensionProfileFlat | undefined;
-    public getNoted (mode: 'flat' | 'profile' | 'raw' = 'flat'): NotedComplexExtensionProfileFlat | NotedComplexExtensionProfile | Extension | undefined {
+    public getNoted(): NotedPatient_NotedExtracted | undefined;
+    public getNoted (mode: 'flat' | 'vflat' | 'profile' | 'raw' = 'flat'): NotedPatient_NotedExtracted | NotedPatient_NotedVFlat | NotedComplexExtensionProfile | Extension | undefined {
         const ext = this.resource.extension?.find(e => e.url === "http://example.test/StructureDefinition/noted-complex-extension")
         if (!ext) return undefined
         if (mode === 'raw') return ext
         if (mode === 'profile') return NotedComplexExtensionProfile.apply(ext)
         const config = [{ name: "note", valueField: "valueString", isArray: false }, { name: "detail", valueField: "valueString", isArray: false }]
-        return extractComplexExtension<NotedComplexExtensionProfileFlat>(ext, config)
+        if (mode === 'vflat') {
+            const { errors } = NotedComplexExtensionProfile.apply(ext).validate()
+            if (errors.length > 0) throw new Error(errors.join("; "))
+            return extractComplexExtension<NotedPatient_NotedVFlat>(ext, config)
+        }
+        return extractComplexExtension<NotedPatient_NotedExtracted>(ext, config)
     }
 
     // Slices

examples/typescript-custom-packages/profile-complex-extension-flat.test.ts

@@ -28,8 +28,9 @@ describe("demo: carry a complex extension on a patient", () => {
         expect(resource).toMatchSnapshot();
     });
 
-    test("the getter returns a flat value missing a member its type declares as required", () => {
-        const patient = NotedPatientProfile.apply({
+    // An incomplete extension: `note` is required by the profile but was never written.
+    const incompletePatient = () =>
+        NotedPatientProfile.apply({
             resourceType: "Patient",
             extension: [
                 {
@@ -40,13 +41,32 @@ describe("demo: carry a complex extension on a patient", () => {
             ],
         });
 
-        // The getter is typed with the factory's flat type while extraction only ever
-        // fills sub-extension values — `note` is declared required but is absent.
-        const flat = patient.getNoted();
-        // @ts-expect-error the getter's type promises members extraction never fills
+    test("the default getter returns only the sub-extension values extraction could find", () => {
+        // Every member is optional: extraction fills what it finds, and the ordinary
+        // field the factory takes (`id`) is not a sub-extension, so it is never filled.
+        const flat = incompletePatient().getNoted();
+
         expect(flat).toEqual({ detail: "d" });
         expect(flat?.note).toBeUndefined();
     });
+
+    test("the vflat getter validates first, so its members are guaranteed", () => {
+        const patient = NotedPatientProfile.create().setNoted({ id: "n1", note: "hello", detail: "d" });
+
+        // `note` is typed as string, not string | undefined — the check backs the type.
+        const note: string = patient.getNoted("vflat")!.note;
+
+        expect(note).toBe("hello");
+    });
+
+    test("the vflat getter throws on an extension the profile would reject", () => {
+        expect(() => incompletePatient().getNoted("vflat")).toThrow(
+            "NotedComplexExtension.extension: slice 'note' requires at least 1 item(s), found 0",
+        );
+
+        // The lenient arm still reads the same resource without complaint.
+        expect(incompletePatient().getNoted()).toEqual({ detail: "d" });
+    });
 });
 
 describe("demo: the extension factory input variants", () => {
@@ -89,6 +109,21 @@ export const _flatContractTypes = () => {
     IdentifiedComplexExtensionProfile.createResource({ optionalValue: "present" });
     // @ts-expect-error The parent's setter inherits the extension's flat contract.
     NotedPatientProfile.create().setNoted({ note: "hello" });
+
+    // The default getter promises nothing extraction may fail to produce.
+    const flat = NotedPatientProfile.create().getNoted();
+    // @ts-expect-error extraction never populates the ordinary field
+    void flat?.id;
+    // @ts-expect-error a member extraction may not populate is optional
+    const _note: string = flat!.note;
+    void flat?.note?.trim();
+
+    // The vflat getter validated the extension, so the required member is guaranteed —
+    // while the ordinary field is still not part of what extraction produces.
+    const vFlat = NotedPatientProfile.create().getNoted("vflat");
+    const _validNote: string = vFlat!.note;
+    // @ts-expect-error extraction never populates the ordinary field, validated or not
+    void vFlat?.id;
 };
 
 describe("the generated modules", () => {

examples/typescript-r4-us-core/fhir-types/hl7-fhir-us-core/profiles/Patient_USCorePatientProfile.ts

@@ -40,6 +40,15 @@ import {
     validateMustSupport,
 } from "../../profile-helpers";
 
+export type USCorePatientProfile_RaceExtracted = Partial<Pick<USCoreRaceExtensionProfileFlat, "ombCategory" | "detailed" | "text">>;
+export type USCorePatientProfile_RaceVFlat = Pick<USCoreRaceExtensionProfileFlat, "ombCategory" | "detailed" | "text">;
+
+export type USCorePatientProfile_EthnicityExtracted = Partial<Pick<USCoreEthnicityExtensionProfileFlat, "ombCategory" | "detailed" | "text">>;
+export type USCorePatientProfile_EthnicityVFlat = Pick<USCoreEthnicityExtensionProfileFlat, "ombCategory" | "detailed" | "text">;
+
+export type USCorePatientProfile_TribalAffiliationExtracted = Partial<Pick<USCoreTribalAffiliationExtensionProfileFlat, "tribalAffiliation" | "isEnrolled">>;
+export type USCorePatientProfile_TribalAffiliationVFlat = Pick<USCoreTribalAffiliationExtensionProfileFlat, "tribalAffiliation" | "isEnrolled">;
+
 export type USCorePatientProfileRaw = {
     identifier: Identifier[];
     name: HumanName[];
@@ -129,17 +138,23 @@ export class USCorePatientProfile {
         return this
     }
 
-    public getRace(mode: 'flat'): USCoreRaceExtensionProfileFlat | undefined;
+    public getRace(mode: 'flat'): USCorePatientProfile_RaceExtracted | undefined;
+    public getRace(mode: 'vflat'): USCorePatientProfile_RaceVFlat | undefined;
     public getRace(mode: 'profile'): USCoreRaceExtensionProfile | undefined;
     public getRace(mode: 'raw'): Extension | undefined;
-    public getRace(): USCoreRaceExtensionProfileFlat | undefined;
-    public getRace (mode: 'flat' | 'profile' | 'raw' = 'flat'): USCoreRaceExtensionProfileFlat | USCoreRaceExtensionProfile | Extension | undefined {
+    public getRace(): USCorePatientProfile_RaceExtracted | undefined;
+    public getRace (mode: 'flat' | 'vflat' | 'profile' | 'raw' = 'flat'): USCorePatientProfile_RaceExtracted | USCorePatientProfile_RaceVFlat | USCoreRaceExtensionProfile | Extension | undefined {
         const ext = this.resource.extension?.find(e => e.url === "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race")
         if (!ext) return undefined
         if (mode === 'raw') return ext
         if (mode === 'profile') return USCoreRaceExtensionProfile.apply(ext)
         const config = [{ name: "ombCategory", valueField: "valueCoding", isArray: false }, { name: "detailed", valueField: "valueCoding", isArray: true }, { name: "text", valueField: "valueString", isArray: false }]
-        return extractComplexExtension<USCoreRaceExtensionProfileFlat>(ext, config)
+        if (mode === 'vflat') {
+            const { errors } = USCoreRaceExtensionProfile.apply(ext).validate()
+            if (errors.length > 0) throw new Error(errors.join("; "))
+            return extractComplexExtension<USCorePatientProfile_RaceVFlat>(ext, config)
+        }
+        return extractComplexExtension<USCorePatientProfile_RaceExtracted>(ext, config)
     }
 
     public setEthnicity (input: USCoreEthnicityExtensionProfileFlat | USCoreEthnicityExtensionProfile | Extension): this {
@@ -154,17 +169,23 @@ export class USCorePatientProfile {
         return this
     }
 
-    public getEthnicity(mode: 'flat'): USCoreEthnicityExtensionProfileFlat | undefined;
+    public getEthnicity(mode: 'flat'): USCorePatientProfile_EthnicityExtracted | undefined;
+    public getEthnicity(mode: 'vflat'): USCorePatientProfile_EthnicityVFlat | undefined;
     public getEthnicity(mode: 'profile'): USCoreEthnicityExtensionProfile | undefined;
     public getEthnicity(mode: 'raw'): Extension | undefined;
-    public getEthnicity(): USCoreEthnicityExtensionProfileFlat | undefined;
-    public getEthnicity (mode: 'flat' | 'profile' | 'raw' = 'flat'): USCoreEthnicityExtensionProfileFlat | USCoreEthnicityExtensionProfile | Extension | undefined {
+    public getEthnicity(): USCorePatientProfile_EthnicityExtracted | undefined;
+    public getEthnicity (mode: 'flat' | 'vflat' | 'profile' | 'raw' = 'flat'): USCorePatientProfile_EthnicityExtracted | USCorePatientProfile_EthnicityVFlat | USCoreEthnicityExtensionProfile | Extension | undefined {
         const ext = this.resource.extension?.find(e => e.url === "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity")
         if (!ext) return undefined
         if (mode === 'raw') return ext
         if (mode === 'profile') return USCoreEthnicityExtensionProfile.apply(ext)
         const config = [{ name: "ombCategory", valueField: "valueCoding", isArray: false }, { name: "detailed", valueField: "valueCoding", isArray: true }, { name: "text", valueField: "valueString", isArray: false }]
-        return extractComplexExtension<USCoreEthnicityExtensionProfileFlat>(ext, config)
+        if (mode === 'vflat') {
+            const { errors } = USCoreEthnicityExtensionProfile.apply(ext).validate()
+            if (errors.length > 0) throw new Error(errors.join("; "))
+            return extractComplexExtension<USCorePatientProfile_EthnicityVFlat>(ext, config)
+        }
+        return extractComplexExtension<USCorePatientProfile_EthnicityExtracted>(ext, config)
     }
 
     public setTribalAffiliation (input: USCoreTribalAffiliationExtensionProfileFlat | USCoreTribalAffiliationExtensionProfile | Extension): this {
@@ -179,17 +200,23 @@ export class USCorePatientProfile {
         return this
     }
 
-    public getTribalAffiliation(mode: 'flat'): USCoreTribalAffiliationExtensionProfileFlat | undefined;
+    public getTribalAffiliation(mode: 'flat'): USCorePatientProfile_TribalAffiliationExtracted | undefined;
+    public getTribalAffiliation(mode: 'vflat'): USCorePatientProfile_TribalAffiliationVFlat | undefined;
     public getTribalAffiliation(mode: 'profile'): USCoreTribalAffiliationExtensionProfile | undefined;
     public getTribalAffiliation(mode: 'raw'): Extension | undefined;
-    public getTribalAffiliation(): USCoreTribalAffiliationExtensionProfileFlat | undefined;
-    public getTribalAffiliation (mode: 'flat' | 'profile' | 'raw' = 'flat'): USCoreTribalAffiliationExtensionProfileFlat | USCoreTribalAffiliationExtensionProfile | Extension | undefined {
+    public getTribalAffiliation(): USCorePatientProfile_TribalAffiliationExtracted | undefined;
+    public getTribalAffiliation (mode: 'flat' | 'vflat' | 'profile' | 'raw' = 'flat'): USCorePatientProfile_TribalAffiliationExtracted | USCorePatientProfile_TribalAffiliationVFlat | USCoreTribalAffiliationExtensionProfile | Extension | undefined {
         const ext = this.resource.extension?.find(e => e.url === "http://hl7.org/fhir/us/core/StructureDefinition/us-core-tribal-affiliation")
         if (!ext) return undefined
         if (mode === 'raw') return ext
         if (mode === 'profile') return USCoreTribalAffiliationExtensionProfile.apply(ext)
         const config = [{ name: "tribalAffiliation", valueField: "valueCodeableConcept", isArray: false }, { name: "isEnrolled", valueField: "valueBoolean", isArray: false }]
-        return extractComplexExtension<USCoreTribalAffiliationExtensionProfileFlat>(ext, config)
+        if (mode === 'vflat') {
+            const { errors } = USCoreTribalAffiliationExtensionProfile.apply(ext).validate()
+            if (errors.length > 0) throw new Error(errors.join("; "))
+            return extractComplexExtension<USCorePatientProfile_TribalAffiliationVFlat>(ext, config)
+        }
+        return extractComplexExtension<USCorePatientProfile_TribalAffiliationExtracted>(ext, config)
     }
 
     public setSex (value: USCoreIndividualSexExtensionProfile | Extension | Coding): this {

src/api/writer-generator/typescript/name.ts

@@ -100,6 +100,16 @@ export const tsExtensionFlatTypeName = (profileName: string, extensionName: stri
     return `${uppercaseFirstLetter(profileName)}_${uppercaseFirstLetter(normalizeTsName(extensionName))}Flat`;
 };
 
+/** The shape `extractComplexExtension` can produce from any resource: every member optional. */
+export const tsExtensionExtractedTypeName = (profileName: string, extensionName: string): string => {
+    return `${uppercaseFirstLetter(profileName)}_${uppercaseFirstLetter(normalizeTsName(extensionName))}Extracted`;
+};
+
+/** The same shape once the extension validated: required sub-extensions are guaranteed. */
+export const tsExtensionVFlatTypeName = (profileName: string, extensionName: string): string => {
+    return `${uppercaseFirstLetter(profileName)}_${uppercaseFirstLetter(normalizeTsName(extensionName))}VFlat`;
+};
+
 export const tsSliceStaticName = (name: string): string => name.replace(/\[x\]/g, "").replace(/[^a-zA-Z0-9_$]/g, "_");
 
 export const tsValueFieldName = (id: TypeIdentifier): string => `value${uppercaseFirstLetter(id.name)}`;