@atomic-ehr/codegen 0.0.1-canary.20250808231821.ab61009

package/README.md

@@ -0,0 +1,446 @@
+# Atomic FHIR Codegen
+
+A powerful, extensible code generation toolkit for FHIR (Fast Healthcare Interoperability Resources) that transforms FHIR specifications into strongly-typed code for multiple programming languages.
+
+## Features
+
+- 🚀 **High-Performance** - Built with Bun runtime for blazing-fast generation
+- 🔧 **Extensible Architecture** - Three-stage pipeline (Parse → Transform → Generate)
+- 📦 **Multi-Package Support** - Generate from FHIR R4 core packages (profiles in development)
+- 🎯 **Type-Safe** - Generates fully typed interfaces with proper inheritance
+- 🔄 **Intermediate Format** - TypeSchema format enables multi-language support
+- 🛠️ **Developer Friendly** - Fluent API, CLI, and configuration file support
+
+## Installation
+
+```bash
+# Using npm
+npm install @atomic-ehr/codegen
+
+# Using bun
+bun add @atomic-ehr/codegen
+
+# Using yarn
+yarn add @atomic-ehr/codegen
+```
+
+## Quick Start
+
+### 1. Using the CLI
+
+```bash
+# Initialize configuration
+bunx atomic-codegen config init
+
+# Generate TypeScript types from FHIR R4
+bunx atomic-codegen generate typescript
+
+# Generate from specific package
+bunx atomic-codegen typeschema generate --package hl7.fhir.r4.core
+```
+
+### 2. Using the Fluent API
+
+```typescript
+import { APIBuilder } from '@atomic-ehr/codegen';
+
+// Create builder instance
+const builder = new APIBuilder();
+
+// Generate FHIR R4 TypeScript types
+await builder
+  .fromPackage('hl7.fhir.r4.core', '4.0.1')
+  .typescript({
+    outputDir: './generated/types',
+    generateIndex: true,
+    includeExtensions: false,
+  })
+  .generate();
+
+// Generate with additional configuration
+await builder
+  .fromPackage('hl7.fhir.r4.core', '4.0.1')
+  .typescript({
+    outputDir: './generated/fhir',
+    generateIndex: true,
+    includeDocuments: true,
+    namingConvention: 'PascalCase'
+  })
+  .generate();
+```
+
+### 3. Using Configuration File
+
+Create `atomic-codegen.config.ts`:
+
+```typescript
+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
+    }
+  }
+});
+```
+
+Then run:
+
+```bash
+bunx atomic-codegen generate typescript
+```
+
+## Architecture
+
+The toolkit uses a three-stage architecture:
+
+```
+FHIR Package → TypeSchema Parser → TypeSchema Format → Code Generators → Output
+```
+
+1. **Input Layer** - Parses FHIR packages and profiles into TypeSchema format
+2. **Intermediate Format** - TypeSchema provides a universal representation
+3. **Output Generators** - Generate code for TypeScript, Python, and other languages
+
+## Usage Examples
+
+### Generate Types for a Custom Profile
+
+```typescript
+import { APIBuilder } from '@atomic-ehr/codegen';
+
+const builder = new APIBuilder();
+
+// Load custom profile
+await builder
+  .fromProfile('./profiles/my-patient-profile.json')
+  .withBaseProfile('http://hl7.org/fhir/StructureDefinition/Patient')
+  .typescript({
+    outputDir: './generated/profiles',
+    includeValidators: true,
+  })
+  .generate();
+```
+
+### Generate with Custom Templates
+
+```typescript
+import { APIBuilder } from '@atomic-ehr/codegen';
+
+const builder = new APIBuilder();
+
+await builder
+  .fromPackage('hl7.fhir.r4.core', '4.0.1')
+  .withTemplate('./templates/custom-interface.hbs')
+  .typescript({
+    outputDir: './generated',
+    customHelpers: {
+      upperCase: (str) => str.toUpperCase()
+    }
+  })
+  .generate();
+```
+
+### Generate Multiple Output Formats
+
+```typescript
+import { APIBuilder } from '@atomic-ehr/codegen';
+
+const builder = new APIBuilder();
+
+// Parse once, generate multiple formats
+const schemas = await builder
+  .fromPackage('hl7.fhir.r4.core', '4.0.1')
+  .parse();
+
+// Generate TypeScript
+await builder
+  .fromSchemas(schemas)
+  .typescript({ outputDir: './ts-types' })
+  .generate();
+
+// Generate Python (coming soon)
+await builder
+  .fromSchemas(schemas)
+  .python({ outputDir: './py-types' })
+  .generate();
+```
+
+### Working with Generated Types
+
+```typescript
+// Import generated types
+import { Patient, Observation, Bundle } from './generated/types';
+
+// Use with type safety
+const patient: Patient = {
+  resourceType: 'Patient',
+  id: '123',
+  name: [{
+    given: ['John'],
+    family: 'Doe'
+  }],
+  birthDate: '1990-01-01'
+};
+
+// Type-safe resource references
+const observation: Observation = {
+  resourceType: 'Observation',
+  status: 'final',
+  code: {
+    coding: [{
+      system: 'http://loinc.org',
+      code: '85354-9',
+      display: 'Blood pressure'
+    }]
+  },
+  subject: {
+    reference: 'Patient/123',
+    type: 'Patient' // Type-checked!
+  }
+};
+
+// Work with bundles
+const bundle: Bundle = {
+  resourceType: 'Bundle',
+  type: 'collection',
+  entry: [
+    { resource: patient },
+    { resource: observation }
+  ]
+};
+```
+
+## 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)
+
+# TypeSchema operations
+atomic-codegen typeschema generate  # Generate TypeSchema from FHIR
+atomic-codegen typeschema validate  # Validate TypeSchema documents
+
+# Development
+atomic-codegen dev               # Start development mode with watch
+```
+
+## Configuration Options
+
+### TypeScript Generator Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `outputDir` | `string` | `./generated` | Output directory for generated files |
+| `moduleFormat` | `'esm' \| 'cjs'` | `'esm'` | Module format |
+| `generateIndex` | `boolean` | `true` | Generate index file with exports |
+| `includeDocuments` | `boolean` | `true` | Include JSDoc documentation |
+| `namingConvention` | `'PascalCase' \| 'camelCase'` | `'PascalCase'` | Type naming convention |
+| `includeExtensions` | `boolean` | `false` | Include FHIR extensions |
+| `includeProfiles` | `boolean` | `false` | Include FHIR profiles |
+
+## Advanced Features
+
+### Custom Type Mappings
+
+```typescript
+const builder = new APIBuilder();
+
+await builder
+  .fromPackage('hl7.fhir.r4.core', '4.0.1')
+  .withTypeMappings({
+    'date': 'Date',           // Map FHIR date to JS Date
+    'instant': 'Date',        // Map FHIR instant to JS Date
+    'decimal': 'BigNumber'    // Use BigNumber for decimals
+  })
+  .typescript({ outputDir: './generated' })
+  .generate();
+```
+
+### Selective Generation
+
+```typescript
+const builder = new APIBuilder();
+
+// Generate only specific resources
+await builder
+  .fromPackage('hl7.fhir.r4.core', '4.0.1')
+  .filter({
+    resources: ['Patient', 'Observation', 'Encounter'],
+    excludeExtensions: true,
+    excludeProfiles: true
+  })
+  .typescript({ outputDir: './generated' })
+  .generate();
+```
+
+### Plugin System
+
+```typescript
+import { APIBuilder, Plugin } from '@atomic-ehr/codegen';
+
+// Create custom plugin
+const validatorPlugin: Plugin = {
+  name: 'validator-plugin',
+  transform: (schema) => {
+    // Add validation metadata
+    return {
+      ...schema,
+      validation: generateValidationRules(schema)
+    };
+  },
+  generate: (schema, options) => {
+    // Generate validator functions
+    return generateValidators(schema, options);
+  }
+};
+
+// Use plugin
+const builder = new APIBuilder();
+
+await builder
+  .fromPackage('hl7.fhir.r4.core', '4.0.1')
+  .use(validatorPlugin)
+  .typescript({ outputDir: './generated' })
+  .generate();
+```
+
+## Development
+
+### Prerequisites
+
+- [Bun](https://bun.sh) runtime (v1.0+)
+- Node.js 18+ (for compatibility)
+
+### Setup
+
+```bash
+# Clone repository
+git clone https://github.com/your-org/atomic-codegen
+cd atomic-codegen
+
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Build
+bun run build
+```
+
+### Project Structure
+
+```
+atomic-codegen/
+├── src/
+│   ├── api/              # High-level API
+│   ├── cli/              # CLI implementation
+│   ├── typeschema/       # TypeSchema parser/transformer
+│   ├── generators/       # Code generators
+│   └── config.ts         # Configuration system
+├── test/                 # Test suites
+├── examples/             # Usage examples
+└── docs/                 # Documentation
+```
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## License
+
+MIT © Atomic Healthcare
+
+## Support
+
+- 📖 [Documentation](https://docs.atomic-ehr.com/codegen)
+- 🐛 [Issue Tracker](https://github.com/atomic-ehr/codegen/issues)
+
+## Next Steps: REST Client & Advanced Features
+
+We're expanding beyond type generation to create a complete FHIR development toolkit:
+
+### 🔄 REST Client Generation (Q2 2024)
+```typescript
+// Generate type-safe FHIR clients
+await builder
+  .fromPackage('hl7.fhir.r4.core', '4.0.1')
+  .restClient({
+    clientName: 'MyFHIRClient',
+    baseUrl: 'https://api.example.com/fhir',
+    authType: 'oauth2'
+  })
+  .generate();
+
+// Use generated client
+const client = new MyFHIRClient();
+const patient = await client.Patient.read('123');
+const bundle = await client.Patient.search({ name: 'Smith' });
+```
+
+### 🔍 Smart Chained Search (Q3 2024)
+```typescript
+// Intelligent search builders
+const results = await client.Patient
+  .search()
+  .name().contains('Smith')
+  .birthdate().greaterThan('2000-01-01')
+  .address().city().equals('Boston')
+  .include('Patient:organization')
+  .sort('birthdate', 'desc')
+  .execute();
+```
+
+### ⚡ Operation Generation (Q4 2024)
+```typescript
+// Type-safe FHIR operations
+const result = await client.Patient
+  .operation('$match')
+  .withParameters({
+    resource: patient,
+    onlyCertainMatches: true
+  })
+  .execute();
+```
+
+See our detailed [**ROADMAP.md**](ROADMAP.md) for the complete development plan.
+
+## Current Roadmap
+
+- [x] TypeScript generation
+- [x] FHIR R4 core package support
+- [x] Configuration file support
+- [x] Comprehensive test suite (72+ tests)
+- [~] **Profile & Extension Support** - Basic parsing (US Core in development)
+- [ ] **Complete Multi-Package Support** - Custom packages and dependencies
+- [ ] **REST Client Generation** - Fetch-based FHIR clients
+- [ ] **Smart Chained Search** - Intelligent search builders
+- [ ] **Operation Generation** - Type-safe FHIR operations
+- [ ] **Python generation**
+- [ ] **Rust generation**
+- [ ] **GraphQL schema generation**
+- [ ] **OpenAPI specification generation**
+- [ ] **Validation functions**
+- [ ] **Mock data generation**
+- [ ] **FHIR R5 support**
+
+---
+
+Built with ❤️ by the Atomic Healthcare team

package/dist/api/builder.d.ts

@@ -0,0 +1,147 @@
+/**
+ * High-Level API Builder
+ *
+ * Provides a fluent, chainable API for common codegen use cases with pre-built generators.
+ * This builder pattern allows users to configure generation in a declarative way.
+ */
+import type { TypeSchemaConfig } from "../config";
+import { type TypeSchema } from "../typeschema";
+/**
+ * Configuration options for the API builder
+ */
+export interface APIBuilderOptions {
+    outputDir?: string;
+    verbose?: boolean;
+    overwrite?: boolean;
+    validate?: boolean;
+    cache?: boolean;
+    typeSchemaConfig?: TypeSchemaConfig;
+}
+/**
+ * Progress callback for long-running operations
+ */
+export type ProgressCallback = (phase: string, current: number, total: number, message?: string) => void;
+/**
+ * Generation result information
+ */
+export interface GenerationResult {
+    success: boolean;
+    outputDir: string;
+    filesGenerated: string[];
+    errors: string[];
+    warnings: string[];
+    duration: number;
+}
+/**
+ * High-Level API Builder class
+ *
+ * Provides a fluent interface for configuring and executing code generation
+ * from FHIR packages or TypeSchema documents.
+ */
+export declare class APIBuilder {
+    private schemas;
+    private options;
+    private generators;
+    private progressCallback?;
+    private cache?;
+    private pendingOperations;
+    private typeSchemaGenerator?;
+    private logger;
+    private typeSchemaConfig?;
+    constructor(options?: APIBuilderOptions);
+    /**
+     * Load TypeSchema from a FHIR package
+     */
+    fromPackage(packageName: string, version?: string): APIBuilder;
+    /**
+     * Load TypeSchema from files
+     */
+    fromFiles(...filePaths: string[]): APIBuilder;
+    /**
+     * Load TypeSchema from TypeSchema objects
+     */
+    fromSchemas(schemas: TypeSchema[]): APIBuilder;
+    /**
+     * Configure TypeScript generation with validation support
+     */
+    typescript(options?: {
+        moduleFormat?: "esm" | "cjs";
+        generateIndex?: boolean;
+        includeDocuments?: boolean;
+        namingConvention?: "PascalCase" | "camelCase";
+        includeExtensions?: boolean;
+        includeProfiles?: boolean;
+        generateValidators?: boolean;
+        generateGuards?: boolean;
+        generateBuilders?: boolean;
+        strictValidation?: boolean;
+        includePerformanceMetrics?: boolean;
+    }): APIBuilder;
+    /**
+     * Set a progress callback for monitoring generation
+     */
+    onProgress(callback: ProgressCallback): APIBuilder;
+    /**
+     * Set the output directory for all generators
+     */
+    outputTo(directory: string): APIBuilder;
+    /**
+     * Enable/disable verbose logging
+     */
+    verbose(enabled?: boolean): APIBuilder;
+    /**
+     * Enable/disable validation
+     */
+    validate(enabled?: boolean): APIBuilder;
+    /**
+     * Execute the generation process
+     */
+    generate(): Promise<GenerationResult>;
+    /**
+     * Generate and return the results without writing to files
+     */
+    build(): Promise<{
+        typescript?: {
+            content: string;
+            filename: string;
+        }[];
+    }>;
+    /**
+     * Clear all configuration and start fresh
+     */
+    reset(): APIBuilder;
+    /**
+     * Get loaded schemas (for inspection)
+     */
+    getSchemas(): TypeSchema[];
+    /**
+     * Get configured generators (for inspection)
+     */
+    getGenerators(): string[];
+    private loadFromPackage;
+    private loadFromFiles;
+    private resolveSchemas;
+    private validateSchemas;
+    private executeGenerators;
+    private reportProgress;
+}
+/**
+ * Create a new API builder instance
+ */
+export declare function createAPI(options?: APIBuilderOptions): APIBuilder;
+/**
+ * Convenience function for quick TypeScript generation from a package
+ */
+export declare function generateTypesFromPackage(packageName: string, outputDir: string, options?: {
+    version?: string;
+    verbose?: boolean;
+    validate?: boolean;
+}): Promise<GenerationResult>;
+/**
+ * Convenience function for quick TypeScript generation from files
+ */
+export declare function generateTypesFromFiles(inputFiles: string[], outputDir: string, options?: {
+    verbose?: boolean;
+    validate?: boolean;
+}): Promise<GenerationResult>;
+//# sourceMappingURL=builder.d.ts.map

package/dist/api/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/api/builder.ts"],"names":[],"mappings":"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"}