FELgt TypeScript Contribution Plan

🎯 Objective

Add TypeScript code generation support to the FELgt repository, similar to how it currently generates C# classes from XSD files.

---

💡 Why This is a Great Idea

Benefits for the Community

1. ✅ Broader Language Support

   • FELgt currently only supports C#
   • TypeScript/Node.js is very popular for FEL integrations
   • Many developers in Guatemala use TypeScript

2. ✅ Your Experience

   • You already have code generation patterns in your codebase
   • You understand FEL requirements deeply
   • You're actively working on FEL implementation

3. ✅ Open Source Contribution

   • Helps the entire FEL developer community
   • Establishes you as a contributor
   • Builds your reputation

4. ✅ Mutual Benefit

   • You get a maintained tool
   • Community gets TypeScript support
   • Everyone wins

---

🔍 Pre-Contribution Research

Step 1: Analyze Current Repository

Check:

• Repository structure
• How C# generation works
• XSD parsing approach
• Code generation patterns
• Maintainer activity/response

Questions to Answer:

1. Is the repository actively maintained?
2. What's the code generation architecture?
3. How does it parse XSD files?
4. What's the output format for C#?
5. Are there tests?
6. What's the contribution process?

Step 2: Understand the Codebase

Key Files to Review:

• XSD parser implementation
• C# code generator
• Main entry point
• Configuration files
• Tests

Pattern to Understand:

XSD File → Parser → AST/Model → Code Generator → Output Files

---

🏗️ Implementation Approach

Option 1: Add TypeScript Generator (Recommended)

Structure:

FELgt/
├── src/
│   ├── parser/          # XSD parser (shared)
│   ├── generators/
│   │   ├── csharp/      # Existing C# generator
│   │   └── typescript/  # New TypeScript generator
│   └── cli.ts           # CLI with --lang flag
└── output/
    ├── csharp/          # Generated C# files
    └── typescript/      # Generated TypeScript files

CLI Usage:

# Generate C# (existing)
felgt --lang csharp --input xsd/ --output output/csharp/

# Generate TypeScript (new)
felgt --lang typescript --input xsd/ --output output/typescript/

Option 2: Separate TypeScript Tool

If repository is inactive:

• Fork and create your own version
• Add TypeScript support
• Maintain independently
• Link back to original

---

📋 Implementation Plan

Phase 1: Research & Preparation

1. Fork the Repository

   git clone https://github.com/krudos/FELgt.git
   cd FELgt

2. Analyze Structure

   • Understand XSD parsing
   • Understand C# generation
   • Identify shared components

3. Create Feature Branch

   git checkout -b feature/typescript-generator

Phase 2: TypeScript Generator Implementation

Key Components:

1. TypeScript Type Generator

   class TypeScriptGenerator {
     generateTypes(xsdModel: XSDModel): string {
       // Generate TypeScript interfaces
       // Handle namespaces
       // Handle types (string, number, date, etc.)
       // Handle required/optional fields
     }
   }

2. Type Mapping

   const typeMapping = {
     'xs:string': 'string',
     'xs:decimal': 'number',
     'xs:date': 'string', // ISO date string
     'xs:dateTime': 'string',
     'xs:boolean': 'boolean',
     'xs:integer': 'number',
     // ... more mappings
   };

3. Namespace Handling

   // Generate namespace imports
   // Handle qualified names
   // Generate type aliases

Phase 3: Output Format

Generated TypeScript Structure:

// Generated from XSD
// File: fact.types.ts

export namespace DTE {
  export interface GTDocumento {
    SAT: SAT;
    Signature?: Signature;
  }

  export interface SAT {
    ClaseDocumento: string;
    DTE: DTE_Type;
    Adenda?: Adenda;
  }

  export interface DatosGenerales {
    Tipo: 'FACT' | 'NCRE' | 'NDEB' | 'ANULACION';
    FechaHoraEmision: string; // ISO dateTime
    CodigoMoneda: string;
  }

  // ... more interfaces
}

Features:

• ✅ TypeScript interfaces
• ✅ Proper typing (unions, enums, etc.)
• ✅ JSDoc comments from XSD
• ✅ Namespace support
• ✅ Optional vs required fields

Phase 4: Integration

Update CLI:

// cli.ts
import { CSharpGenerator } from './generators/csharp';
import { TypeScriptGenerator } from './generators/typescript';

const generators = {
  csharp: new CSharpGenerator(),
  typescript: new TypeScriptGenerator(),
};

const generator = generators[language];
const output = generator.generate(xsdModel);

---

🎨 TypeScript-Specific Considerations

1. Naming Conventions

C# vs TypeScript:

• C#: PascalCase classes, camelCase properties
• TypeScript: PascalCase interfaces, camelCase properties

Example:

// C#
public class DatosGenerales {
    public string Tipo { get; set; }
}

// TypeScript
export interface DatosGenerales {
  Tipo: string;
}

2. Type System

TypeScript Advantages:

• Union types: 'FACT' | 'NCRE' | 'NDEB'
• Optional fields: field?: string
• Readonly: readonly field: string
• Generics: <T extends BaseType>

3. XML Builder Helpers (Optional)

Could Generate:

// Helper functions for building XML
export function createFactDocument(data: FactDocument): string {
  // XML builder logic
}

---

📝 Contribution Checklist

Before PR

• Fork repository
• Understand existing codebase
• Implement TypeScript generator
• Add tests
• Update README
• Add examples
• Test with real XSD files
• Ensure backward compatibility

PR Contents

• TypeScript generator implementation
• CLI integration (--lang typescript)
• Tests for TypeScript generation
• Updated documentation
• Example output files
• Migration guide (if needed)

Documentation Updates

• README.md - Add TypeScript section
• USAGE.md - TypeScript examples
• CONTRIBUTING.md - Update if needed

---

🚀 Recommended Approach

Strategy: Start Small, Iterate

1. Phase 1: Proof of Concept

   • Implement basic TypeScript generator
   • Generate simple interfaces
   • Test with one XSD file

2. Phase 2: Full Feature

   • Handle all XSD features
   • Namespaces, types, constraints
   • Comprehensive testing

3. Phase 3: Polish

   • Documentation
   • Examples
   • Error handling
   • CLI integration

Alternative: Standalone Tool First

If repository is inactive:

1. Create Your Own Tool

   • fel-typescript-generator
   • Standalone npm package
   • Can be contributed back later

2. Benefits:

   • Full control
   • Can publish to npm
   • Can contribute to FELgt later

3. Structure:

   fel-typescript-generator/
   ├── src/
   │   ├── parser/
   │   ├── generator/
   │   └── cli.ts
   ├── package.json
   └── README.md

---

💻 Implementation Example

TypeScript Generator Skeleton

// generators/typescript/generator.ts

import type { XSDModel, XSDElement } from '../parser/types';

export class TypeScriptGenerator {
  generate(model: XSDModel): string {
    const interfaces = model.elements.map(el => this.generateInterface(el));
    return this.wrapInNamespace(interfaces, model.namespace);
  }

  private generateInterface(element: XSDElement): string {
    const properties = element.attributes.map(attr => 
      this.generateProperty(attr)
    );
    
    return `
export interface ${element.name} {
${properties.join('\n')}
}
    `.trim();
  }

  private generateProperty(attr: XSDAttribute): string {
    const optional = attr.required ? '' : '?';
    const type = this.mapXSDTypeToTS(attr.type);
    return `  ${attr.name}${optional}: ${type};`;
  }

  private mapXSDTypeToTS(xsdType: string): string {
    const mapping: Record<string, string> = {
      'xs:string': 'string',
      'xs:decimal': 'number',
      'xs:dateTime': 'string',
      'xs:boolean': 'boolean',
      // ... more
    };
    return mapping[xsdType] || 'any';
  }
}

---

🎯 My Recommendation

Option A: Contribute to FELgt (If Active)

Steps:

1. Check repository activity
2. Open an issue first: "Feature Request: TypeScript Generator"
3. Get maintainer feedback
4. Implement if positive response
5. Submit PR

Pros:

• ✅ Helps entire community
• ✅ Maintained in one place
• ✅ Open source contribution

Cons:

• ⚠️ Depends on maintainer response
• ⚠️ May be slow if inactive

Option B: Create Standalone Tool (If Inactive)

Steps:

1. Create fel-typescript-generator package
2. Implement TypeScript generation
3. Publish to npm
4. Link back to FELgt in README
5. Can contribute later if FELgt becomes active

Pros:

• ✅ Full control
• ✅ Can publish immediately
• ✅ Can use in your project
• ✅ Can contribute back later

Cons:

• ⚠️ You maintain it
• ⚠️ Split community

Option C: Hybrid Approach (Recommended)

Steps:

1. Create standalone tool first
2. Use it in your project
3. Open issue/PR to FELgt
4. If accepted → contribute
5. If not → maintain standalone, link to FELgt

Best of Both Worlds:

• ✅ Immediate use in your project
• ✅ Can contribute to community
• ✅ Flexible approach

---

📚 Resources

• FELgt Repository
• SAT XSD Repository
• TypeScript Handbook - Advanced Types
• XSD to TypeScript Tools

---

🎯 Next Steps

1. Research FELgt Repository:

   • Check activity level
   • Understand structure
   • Review contribution guidelines

2. Decide on Approach:

   • Contribute to FELgt?
   • Create standalone tool?
   • Hybrid approach?

3. Start Implementation:

   • Proof of concept first
   • Test with real XSD files
   • Iterate based on results

---

Last Updated: 2025-12-18
Status: Contribution Strategy - Ready for Decision