@atomic-ehr/codegen 0.0.16 → 0.0.17

package/README.md

@@ -16,6 +16,7 @@
   - [Quick Start](#quick-start)
     - [Usage Examples](#usage-examples)
   - [Architecture](#architecture)
+    - [Generator Options](#generator-options)
     - [Input - FHIR packages & resolves canonicals](#input---fhir-packages--resolves-canonicals)
       - [Load Local StructureDefinitions & TGZ Archives](#load-local-structuredefinitions--tgz-archives)
     - [Intermediate - Type Schema](#intermediate---type-schema)
@@ -188,6 +189,44 @@ const builder = new APIBuilder()
 
 Each method returns the builder instance, allowing method chaining. The `generate()` method executes the pipeline and returns a report with success status and generated file details.
 
+### Generator Options
+
+Each language generator accepts its own option object. All options are optional; the tables below list the defaults.
+
+**TypeScript** — `.typescript({ ... })`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `generateProfile` | `boolean` | `true` | Generate profile wrapper classes (factories, typed slice/extension accessors, `validate()`). |
+| `primitiveTypeExtension` | `boolean` | `true` | Emit sibling `_field` properties for [primitive element extensions](https://www.hl7.org/fhir/element.html#json). |
+| `openResourceTypeSet` | `boolean` | `false` | For resource families (`Resource`, `DomainResource`), keep the `resourceType` union open by adding a `string` fallback instead of a closed literal union. |
+| `extensionGetterDefault` | `"flat" \| "profile" \| "raw"` | `"flat"` | Default return shape for generated extension getters. |
+| `sliceGetterDefault` | `"flat" \| "raw"` | `"flat"` | Default return shape for generated slice getters (`flat` strips discriminators, `raw` returns the full FHIR element). |
+| `lineWidth` | `number` | `120` | Maximum line width before wrapping. |
+| `withDebugComment` | `boolean` | `false` | Emit comments tracing each generated type back to its source schema. |
+
+**Python** — `.python({ ... })`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `client` | `"fhirpy" \| "none"` | `"fhirpy"` | Client integration baked into the models: `"fhirpy"` makes models extend `FhirpyBaseModel` for the fhirpy async client; `"none"` emits plain Pydantic models. |
+| `fieldFormat` | `"camelCase" \| "snake_case" \| "PascalCase"` | `"camelCase"` | Naming convention for generated model fields. |
+| `generateProfile` | `boolean` | `false` | Generate profile wrapper classes (`create()`, typed accessors, `validate()`) around the Pydantic models. |
+| `primitiveTypeExtension` | `boolean` | `false` | Emit primitive element extension fields. |
+| `allowExtraFields` | `boolean` | `false` | Allow fields not present in the schema on generated models (Pydantic `extra`). |
+| `rootPackageName` | `string` | `"fhir_types"` | Root Python package name for the generated module tree. |
+| `withDebugComment` | `boolean` | `false` | Emit comments tracing each generated type back to its source schema. |
+
+> `fhirpyClient?: boolean` is **deprecated** — use `client` instead (`true` → `"fhirpy"`, `false` → `"none"`).
+
+**C#** — `.csharp({ ... })`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `rootNamespace` | `string` | `"Fhir.Types"` | Root namespace for generated classes. |
+| `staticSourceDir` | `string` | — | Directory of static `.cs` source files copied verbatim into the output. |
+| `withDebugComment` | `boolean` | `false` | Emit comments tracing each generated type back to its source schema. |
+
 ### Input - FHIR packages & resolves canonicals
 
 The input stage leverages [Canonical Manager](https://github.com/atomic-ehr/canonical-manager) to handle FHIR package management and dependency resolution. It processes FHIR packages from multiple sources (registry, local files, TGZ archives) and resolves all canonical URLs to their concrete definitions, ensuring all references between resources are properly linked before transformation.

package/assets/api/writer-generator/python/fhirpy_base_model.py

@@ -1,5 +1,6 @@
 from typing import Any, Union, Optional, Iterator, Tuple, Dict
 from pydantic import BaseModel, Field
+from pydantic_core import PydanticUndefined
 from typing import Protocol
 
 
@@ -22,7 +23,10 @@ class FhirpyBaseModel(BaseModel):
     def __pydantic_init_subclass__(cls, **kwargs: Any) -> None:
         super().__pydantic_init_subclass__(**kwargs)
         field = cls.model_fields.get("resource_type") or cls.model_fields.get("resourceType")
-        if field is not None and field.default is not None:
+        # Only concrete resources carry a default resourceType. Abstract/family base types
+        # (Resource, DomainResource) leave it unset, so we skip them to avoid registering a
+        # class attribute that concrete subclasses would shadow.
+        if field is not None and field.default is not None and field.default is not PydanticUndefined:
             type.__setattr__(cls, "resourceType", str(field.default))
 
     def __iter__(self) -> Iterator[Tuple[str, Any]]:  # type: ignore[override]

package/assets/api/writer-generator/python/fhirpy_base_model_camel_case.py

@@ -1,5 +1,6 @@
 from typing import Any, Union, Optional, Iterator, Tuple, Dict
 from pydantic import BaseModel, Field
+from pydantic_core import PydanticUndefined
 from typing import Protocol
 
 
@@ -21,7 +22,10 @@ class FhirpyBaseModel(BaseModel):
     def __pydantic_init_subclass__(cls, **kwargs: Any) -> None:
         super().__pydantic_init_subclass__(**kwargs)
         field = cls.model_fields.get("resource_type") or cls.model_fields.get("resourceType")
-        if field is not None and field.default is not None:
+        # Only concrete resources carry a default resourceType. Abstract/family base types
+        # (Resource, DomainResource) leave it unset, so we skip them to avoid registering a
+        # class attribute that concrete subclasses would shadow.
+        if field is not None and field.default is not None and field.default is not PydanticUndefined:
             type.__setattr__(cls, "resourceType", str(field.default))
 
     def __iter__(self) -> Iterator[Tuple[str, Any]]:  # type: ignore[override]

package/assets/api/writer-generator/python/profile_helpers.py

@@ -26,6 +26,8 @@ from __future__ import annotations
 import copy
 from typing import Any, Iterable, Mapping, MutableMapping, MutableSequence, Sequence, TypeVar
 
+from typing_extensions import TypeGuard
+
 T = TypeVar("T")
 
 # ---------------------------------------------------------------------------
@@ -33,9 +35,9 @@ T = TypeVar("T")
 # ---------------------------------------------------------------------------
 
 
-def is_record(value: Any) -> bool:
+def is_record(value: Any) -> TypeGuard[MutableMapping[str, Any]]:
     """True when ``value`` is a non-None mapping (dict-like, not a list)."""
-    return isinstance(value, Mapping)
+    return isinstance(value, MutableMapping)
 
 
 def ensure_path(root: MutableMapping[str, Any], path: Sequence[str]) -> MutableMapping[str, Any]:

package/dist/index.js

@@ -1459,7 +1459,16 @@ var generateExtensionMethods = (w, tsIndex, flatProfile, className, extensionBas
       const valueField = pyValueFieldName(valueType, w.nameFormatFunction);
       const pyType = pyTypeFromIdentifier(valueType);
       generateSingleValueExtensionGetter(w, ext, baseName, targetPath, valueField, pyType, extProfileInfo);
-      generateSingleValueExtensionSetter(w, ext, className, baseName, targetPath, valueField, extProfileInfo);
+      generateSingleValueExtensionSetter(
+        w,
+        ext,
+        className,
+        baseName,
+        targetPath,
+        valueField,
+        pyType,
+        extProfileInfo
+      );
     } else {
       generateGenericExtensionGetter(w, ext, baseName, targetPath, extProfileInfo);
       generateGenericExtensionSetter(w, ext, className, baseName, targetPath, extProfileInfo);
@@ -1566,6 +1575,7 @@ var generateExtensionSetter = (w, ext, className, baseName, flatParamType, targe
 };
 var generateComplexExtensionSetter = (w, ext, className, baseName, targetPath, extProfileInfo) => {
   generateExtensionSetter(w, ext, className, baseName, "dict[str, Any]", targetPath, extProfileInfo, () => {
+    w.line("assert is_record(value)");
     w.line("sub_extensions = []");
     for (const sub of ext.subExtensions ?? []) {
       const valueField = sub.valueFieldType ? pyValueFieldName(sub.valueFieldType, w.nameFormatFunction) : "value";
@@ -1594,8 +1604,9 @@ var generateSingleValueExtensionGetter = (w, ext, baseName, targetPath, valueFie
     w.line(`return cast('${pyType} | None', get_extension_value(ext, ${JSON.stringify(valueField)}))`);
   });
 };
-var generateSingleValueExtensionSetter = (w, ext, className, baseName, targetPath, valueField, extProfileInfo) => {
-  generateExtensionSetter(w, ext, className, baseName, "Any", targetPath, extProfileInfo, () => {
+var generateSingleValueExtensionSetter = (w, ext, className, baseName, targetPath, valueField, pyType, extProfileInfo) => {
+  generateExtensionSetter(w, ext, className, baseName, pyType, targetPath, extProfileInfo, () => {
+    w.line("assert not isinstance(value, Extension)");
     emitExtPush(w, targetPath, `Extension(url=${JSON.stringify(ext.url)}, ${valueField}=value)`);
   });
 };
@@ -1608,6 +1619,7 @@ var generateGenericExtensionGetter = (w, ext, baseName, targetPath, extProfileIn
 };
 var generateGenericExtensionSetter = (w, ext, className, baseName, targetPath, extProfileInfo) => {
   generateExtensionSetter(w, ext, className, baseName, "dict[str, Any]", targetPath, extProfileInfo, () => {
+    w.line("assert is_record(value)");
     emitExtPush(w, targetPath, `{"url": ${JSON.stringify(ext.url)}, **value}`);
   });
 };
@@ -1808,15 +1820,17 @@ var generateSliceSetters = (w, className, sliceDefs, sliceBaseNames) => {
         } else {
           w.line(`merged = apply_slice_match(${inputExpr}, match)`);
         }
+        let elementExpr = "merged";
         if (sliceDef.elementTypeName) {
-          w.line(`merged = ${sliceDef.elementTypeName}(**merged)`);
+          w.line(`element = ${sliceDef.elementTypeName}(**merged)`);
+          elementExpr = "element";
         }
         if (sliceDef.array) {
           w.line(`items = getattr(self._resource, ${JSON.stringify(fieldName)}, None) or []`);
-          w.line("set_array_slice(items, match, merged)");
+          w.line(`set_array_slice(items, match, ${elementExpr})`);
           w.line(`setattr(self._resource, ${JSON.stringify(fieldName)}, items)`);
         } else {
-          w.line(`setattr(self._resource, ${JSON.stringify(fieldName)}, merged)`);
+          w.line(`setattr(self._resource, ${JSON.stringify(fieldName)}, ${elementExpr})`);
         }
         w.line("return self");
       });
@@ -2188,6 +2202,10 @@ var collectHelperImports = (isResourceBase, factoryInfo, sliceDefs, extensions,
     imports.push("_get_key", "is_extension", "get_extension_value", "push_extension");
     if (extensions.some((ext) => ext.isComplex && ext.subExtensions)) imports.push("extract_complex_extension");
     if (extensions.some((ext) => ext.path.split(".").some((s) => s !== "extension"))) imports.push("ensure_path");
+    const hasDictFormSetter = extensions.some(
+      (ext) => ext.isComplex && ext.subExtensions || !(ext.valueFieldTypes?.length === 1 && ext.valueFieldTypes[0])
+    );
+    if (hasDictFormSetter) imports.push("is_record");
   }
   imports.push(...validationHelpers);
   imports.sort();
@@ -2789,13 +2807,9 @@ var Python = class extends Writer {
   }
   generateResourceTypeField(schema) {
     const hasChildren = (schema.typeFamily?.resources?.length ?? 0) > 0;
-    if (hasChildren) {
-      this.line(`${this.nameFormatFunction("resourceType")}: str = Field(`);
-    } else {
-      this.line(`${this.nameFormatFunction("resourceType")}: Literal['${schema.identifier.name}'] = Field(`);
-    }
+    this.line(`${this.nameFormatFunction("resourceType")}: str = Field(`);
     this.indentBlock(() => {
-      this.line(`default='${schema.identifier.name}',`);
+      if (!hasChildren) this.line(`default='${schema.identifier.name}',`);
       this.line(`alias='resourceType',`);
       this.line(`serialization_alias='resourceType',`);
       if (!this.forFhirpyClient) {