@atomic-ehr/codegen 0.0.1-canary.20250826204510.8c2fcc0 → 0.0.1-canary.20250830224431.6d211a5

package/README.md

@@ -29,14 +29,14 @@ yarn add @atomic-ehr/codegen
 ### 1. Using the CLI
 
 ```bash
-# Initialize configuration
-bunx atomic-codegen config init
+# Generate using configuration file
+bunx atomic-codegen generate
 
-# Generate TypeScript types from FHIR R4
-bunx atomic-codegen generate typescript
+# Generate with verbose output
+bunx atomic-codegen generate --verbose
 
-# Generate from specific package
-bunx atomic-codegen typeschema generate --package hl7.fhir.r4.core
+# Generate TypeSchemas from FHIR package
+bunx atomic-codegen typeschema generate hl7.fhir.r4.core@4.0.1 -o schemas.ndjson
 ```
 
 ### 2. Using the Fluent API
@@ -74,23 +74,25 @@ await builder
 Create `atomic-codegen.config.ts`:
 
 ```typescript
-import { defineConfig } from '@atomic-ehr/codegen';
+import { defineConfig } from "@atomic-ehr/codegen";
 
 export default defineConfig({
-  packages: [
-    {
-      name: 'hl7.fhir.r4.core',
-      version: '4.0.1'
-    }
-  ],
-  generators: {
-    typescript: {
-      outputDir: './src/types/fhir',
-      generateIndex: true,
-      namingConvention: 'PascalCase',
-      includeExtensions: false,
-      includeProfiles: true
-    }
+  outputDir: "./generated",
+  overwrite: true,
+  validate: true,
+  cache: true,
+  packages: ["hl7.fhir.r4.core@4.0.1"],
+  typescript: {
+    includeDocuments: true,
+    namingConvention: "PascalCase",
+    includeProfiles: false,
+    includeExtensions: false,
+    generateIndex: true,
+    strictMode: true,
+    generateValueSets: true,
+    includeValueSetHelpers: true,
+    valueSetStrengths: ["required", "preferred"],
+    valueSetMode: "custom"
   }
 });
 ```
@@ -98,7 +100,7 @@ export default defineConfig({
 Then run:
 
 ```bash
-bunx atomic-codegen generate typescript
+bunx atomic-codegen generate
 ```
 
 ## Architecture
@@ -225,24 +227,32 @@ const bundle: Bundle = {
 ## CLI Commands
 
 ```bash
-# Configuration
-atomic-codegen config init        # Initialize configuration
-atomic-codegen config validate    # Validate configuration
-
-# Generation
-atomic-codegen generate typescript  # Generate TypeScript types
-atomic-codegen generate python     # Generate Python types (coming soon)
+# Generate code using configuration file
+atomic-codegen generate                    # Uses atomic-codegen.config.ts
+atomic-codegen generate --verbose          # With detailed output
+atomic-codegen generate --config custom.ts # Custom config file
 
 # TypeSchema operations
-atomic-codegen typeschema generate  # Generate TypeSchema from FHIR
-atomic-codegen typeschema validate  # Validate TypeSchema documents
+atomic-codegen typeschema generate hl7.fhir.r4.core@4.0.1 -o schemas.ndjson
+atomic-codegen typeschema validate schemas.ndjson
 
-# Development
-atomic-codegen dev               # Start development mode with watch
+# Help and debugging
+atomic-codegen --help                      # Show help
+atomic-codegen --debug generate            # Debug mode
 ```
 
 ## Configuration Options
 
+### Global Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `outputDir` | `string` | `./generated` | Base output directory for all generated files |
+| `overwrite` | `boolean` | `false` | Overwrite existing files without prompting |
+| `validate` | `boolean` | `true` | Validate generated TypeSchema before processing |
+| `cache` | `boolean` | `true` | Enable caching for improved performance |
+| `packages` | `string[]` | `[]` | FHIR packages to process (e.g., `"hl7.fhir.r4.core@4.0.1"`) |
+
 ### TypeScript Generator Options
 
 | Option | Type | Default | Description |
@@ -254,7 +264,77 @@ atomic-codegen dev               # Start development mode with watch
 | `namingConvention` | `'PascalCase' \| 'camelCase'` | `'PascalCase'` | Type naming convention |
 | `includeExtensions` | `boolean` | `false` | Include FHIR extensions |
 | `includeProfiles` | `boolean` | `false` | Include FHIR profiles |
+| `generateValueSets` | `boolean` | `false` | Generate strongly-typed value sets from FHIR bindings |
+| `valueSetStrengths` | `string[]` | `['required']` | Which binding strengths to generate |
+| `includeValueSetHelpers` | `boolean` | `false` | Include validation helper functions |
+| `valueSetDirectory` | `string` | `'valuesets'` | Output directory for value set files |
+## Value Set Generation
+
+Generate strongly-typed TypeScript enums from FHIR value sets for enhanced type safety:
+
+```typescript
+// Configuration
+export default defineConfig({
+  generators: {
+    typescript: {
+      generateValueSets: true,
+      valueSetStrengths: ['required', 'preferred'],
+      includeValueSetHelpers: true,
+    },
+  },
+});
+```
+
+### Generated Structure
+
+```
+generated/
+├── types/
+│   ├── Patient.ts           # Uses value set types
+│   └── Address.ts           # Uses value set types  
+└── valuesets/
+    ├── AdministrativeGender.ts
+    ├── AddressUse.ts
+    └── index.ts             # Re-exports all value sets
+```
+
+### Type-Safe Usage
+
+```typescript
+// Import generated types
+import { Patient } from './generated/types/Patient.js';
+import { AdministrativeGender } from './generated/valuesets/index.js';
+
+// Type-safe patient creation
+const patient: Patient = {
+  resourceType: 'Patient',
+  gender: 'male', // Type-safe! Only valid values accepted
+  // gender: 'invalid', // ❌ Compile error
+};
+```
+
+### Runtime Validation
+
+```typescript
+import { isValidAdministrativeGender } from './generated/valuesets/AdministrativeGender.js';
+
+function validateGender(input: string) {
+  if (isValidAdministrativeGender(input)) {
+    // input is now typed as AdministrativeGender
+    return input;
+  }
+  throw new Error(`Invalid gender: ${input}`);
+}
+```
+
+### Value Set Configuration Options
+
+- **generateValueSets**: Enable value set generation
+- **valueSetStrengths**: Control which binding strengths generate types (`'required'`, `'preferred'`, `'extensible'`, `'example'`)
+- **includeValueSetHelpers**: Include runtime validation functions
+- **valueSetDirectory**: Customize output directory name
 
+For comprehensive usage examples and migration guides, see [Value Set Documentation](docs/features/value-set-generation.md).
 ## Advanced Features
 
 ### Custom Type Mappings
@@ -428,6 +508,7 @@ See our detailed [**ROADMAP.md**](ROADMAP.md) for the complete development plan.
 - [x] FHIR R4 core package support
 - [x] Configuration file support
 - [x] Comprehensive test suite (72+ tests)
+- [x] **Value Set Generation** - Strongly-typed enums from FHIR bindings
 - [~] **Profile & Extension Support** - Basic parsing (US Core in development)
 - [ ] **Complete Multi-Package Support** - Custom packages and dependencies
 - [ ] **REST Client Generation** - Fetch-based FHIR clients

package/dist/api/builder.d.ts

@@ -73,6 +73,11 @@ export declare class APIBuilder {
         namingConvention?: "PascalCase" | "camelCase";
         includeExtensions?: boolean;
         includeProfiles?: boolean;
+        generateValueSets?: boolean;
+        includeValueSetHelpers?: boolean;
+        valueSetStrengths?: ('required' | 'preferred' | 'extensible' | 'example')[];
+        valueSetMode?: 'all' | 'required-only' | 'custom';
+        valueSetDirectory?: string;
     }): APIBuilder;
     /**
      * Configure REST client generation
@@ -153,4 +158,3 @@ export declare function generateTypesFromFiles(inputFiles: string[], outputDir:
     verbose?: boolean;
     validate?: boolean;
 }): Promise<GenerationResult>;
-//# sourceMappingURL=builder.d.ts.map

package/dist/api/builder.js

@@ -85,7 +85,12 @@ export class APIBuilder {
             namingConvention: options.namingConvention || "PascalCase",
             includeExtensions: options.includeExtensions ?? false,
             includeProfiles: options.includeProfiles ?? false,
+            generateValueSets: options.generateValueSets ?? false,
+            includeValueSetHelpers: options.includeValueSetHelpers ?? false,
+            valueSetStrengths: options.valueSetStrengths ?? ['required'],
             logger: this.logger.child("TS"),
+            valueSetMode: options.valueSetMode ?? 'required-only',
+            valueSetDirectory: options.valueSetDirectory ?? 'valuesets',
             verbose: this.options.verbose,
             validate: true, // Enable validation for debugging
             overwrite: this.options.overwrite,

package/dist/api/generators/base/BaseGenerator.d.ts

@@ -184,4 +184,3 @@ export declare abstract class BaseGenerator<TOptions extends BaseGeneratorOption
         cacheHitRate: number;
     };
 }
-//# sourceMappingURL=BaseGenerator.d.ts.map

package/dist/api/generators/base/FileManager.d.ts

@@ -86,4 +86,3 @@ export declare class FileManager {
      */
     getBatchSize(): number;
 }
-//# sourceMappingURL=FileManager.d.ts.map

package/dist/api/generators/base/PythonTypeMapper.d.ts

@@ -14,4 +14,3 @@ export declare class PythonTypeMapper extends TypeMapper {
     formatFieldName(name: string): string;
     formatFileName(name: string): string;
 }
-//# sourceMappingURL=PythonTypeMapper.d.ts.map

package/dist/api/generators/base/TemplateEngine.d.ts

@@ -124,4 +124,3 @@ export declare abstract class TemplateEngine {
      */
     protected registerDefaultHelpers(): void;
 }
-//# sourceMappingURL=TemplateEngine.d.ts.map

package/dist/api/generators/base/TypeMapper.d.ts

@@ -127,4 +127,3 @@ export declare abstract class TypeMapper {
      */
     protected shouldBeNullable(required: boolean): boolean;
 }
-//# sourceMappingURL=TypeMapper.d.ts.map

package/dist/api/generators/base/TypeScriptTypeMapper.d.ts

@@ -49,4 +49,3 @@ export declare class TypeScriptTypeMapper extends TypeMapper {
      */
     getRequiredImports(types: LanguageType[]): string[];
 }
-//# sourceMappingURL=TypeScriptTypeMapper.d.ts.map

package/dist/api/generators/base/builders/DirectoryBuilder.d.ts

@@ -97,4 +97,3 @@ export declare class DirectoryBuilder {
      */
     getIndexBuilder(): IndexBuilder | undefined;
 }
-//# sourceMappingURL=DirectoryBuilder.d.ts.map

package/dist/api/generators/base/builders/FileBuilder.d.ts

@@ -158,4 +158,3 @@ export declare class FileBuilder {
      */
     getExports(): Set<string>;
 }
-//# sourceMappingURL=FileBuilder.d.ts.map

package/dist/api/generators/base/builders/IndexBuilder.d.ts

@@ -124,4 +124,3 @@ export declare class IndexBuilder {
      */
     getReExports(): Map<string, string>;
 }
-//# sourceMappingURL=IndexBuilder.d.ts.map

package/dist/api/generators/base/enhanced-errors.d.ts

@@ -82,4 +82,3 @@ export declare class EnhancedTemplateError extends GeneratorError {
     private findSimilarTemplates;
     private levenshteinDistance;
 }
-//# sourceMappingURL=enhanced-errors.d.ts.map

package/dist/api/generators/base/error-handler.d.ts

@@ -87,4 +87,3 @@ export declare class GeneratorErrorBoundary {
         operationName?: string;
     }): Promise<T[]>;
 }
-//# sourceMappingURL=error-handler.d.ts.map

package/dist/api/generators/base/errors.d.ts

@@ -249,4 +249,3 @@ export declare class BatchOperationError extends GeneratorError {
  * Helps maintain consistent error creation patterns
  */
 export declare function createErrorWithContext<T extends GeneratorError>(ErrorClass: new (...args: any[]) => T, message: string, context: FileContext, additionalContext?: Record<string, unknown>): T;
-//# sourceMappingURL=errors.d.ts.map

package/dist/api/generators/base/index.d.ts

@@ -97,4 +97,3 @@ export { BaseGenerator as Generator } from "./BaseGenerator.js";
  * Provided for backwards compatibility only
  */
 export { GeneratorError as BaseError } from "./errors.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/api/generators/base/types.d.ts

@@ -431,4 +431,3 @@ export interface GeneratorCapabilities {
     /** Additional metadata about capabilities */
     metadata?: Record<string, unknown>;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/api/generators/rest-client.d.ts

@@ -115,4 +115,3 @@ export declare class RestClientGenerator {
     private generateUtilityFile;
     private ensureDirectoryExists;
 }
-//# sourceMappingURL=rest-client.d.ts.map

package/dist/api/generators/search-parameter-enhancer.d.ts

@@ -183,4 +183,3 @@ export declare class SearchParameterEnhancer {
      */
     getResourceTypes(): Set<string>;
 }
-//# sourceMappingURL=search-parameter-enhancer.d.ts.map

package/dist/api/generators/types.d.ts

@@ -51,4 +51,3 @@ export interface ResourceTypeMap {
 export type CreateResourceTypeMap<T extends readonly string[]> = {
     [K in T[number]]: any;
 };
-//# sourceMappingURL=types.d.ts.map

package/dist/api/generators/typescript.d.ts

@@ -24,6 +24,29 @@ export interface TypeScriptGeneratorOptions extends BaseGeneratorOptions {
     includeExtensions?: boolean;
     /** Include FHIR profiles */
     includeProfiles?: boolean;
+    /** Generate value set files (default: false) */
+    generateValueSets?: boolean;
+    /** Include helper validation functions (default: false) */
+    includeValueSetHelpers?: boolean;
+    /**
+     * Which binding strengths to generate value sets for
+     * Only used when valueSetMode is 'custom'
+     * @default ['required']
+     */
+    valueSetStrengths?: ('required' | 'preferred' | 'extensible' | 'example')[];
+    /**
+     * Directory name for value set files (relative to outputDir)
+     * @default 'valuesets'
+     */
+    valueSetDirectory?: string;
+    /**
+     * Value set generation mode
+     * - 'all': Generate for all binding strengths with enums
+     * - 'required-only': Generate only for required bindings (safe default)
+     * - 'custom': Use valueSetStrengths array to control
+     * @default 'required-only'
+     */
+    valueSetMode?: 'all' | 'required-only' | 'custom';
     /** Type mapper options */
     typeMapperOptions?: TypeScriptTypeMapperOptions;
 }
@@ -45,6 +68,7 @@ export interface GeneratedTypeScript {
 export declare class TypeScriptGenerator extends BaseGenerator<TypeScriptGeneratorOptions, GeneratedFile[]> {
     private readonly profilesByPackage;
     private readonly resourceTypes;
+    private collectedValueSets;
     private get tsOptions();
     protected getLanguageName(): string;
     protected getFileExtension(): string;
@@ -60,6 +84,22 @@ export declare class TypeScriptGenerator extends BaseGenerator<TypeScriptGenerat
      * Transform a single schema into TypeScript
      */
     transformSchema(schema: TypeSchema): Promise<GeneratedTypeScript | undefined>;
+    /**
+     * Check if a binding schema should generate a value set file
+     */
+    private shouldGenerateValueSet;
+    /**
+     * Collect value sets from schemas that should generate value set files
+     */
+    private collectValueSets;
+    /**
+     * Check if a field binding should use a value set type
+     */
+    private shouldUseValueSetType;
+    /**
+     * Get the TypeScript type name for a binding
+     */
+    private getValueSetTypeName;
     private shouldSkipSchema;
     private getFilenameForSchema;
     private extractImportsFromContent;
@@ -121,5 +161,20 @@ export declare class TypeScriptGenerator extends BaseGenerator<TypeScriptGenerat
      * Generate utilities.ts file with ResourceType union
      */
     private generateUtilitiesFile;
+    /**
+     * Generate a complete value set TypeScript file
+     */
+    private generateValueSetFile;
+    /**
+     * Create valuesets directory and generate all value set files
+     */
+    private generateValueSetFiles;
+    /**
+     * Generate index.ts file that re-exports all value sets
+     */
+    private generateValueSetIndexFile;
+    /**
+     * Generate main types/index.ts file that exports all types and value sets
+     */
+    private generateMainIndexFile;
 }
-//# sourceMappingURL=typescript.d.ts.map