feat(compiler): Add JavaScript/TypeScript IDL code generation (#3394)

## Summary

Implements TypeScript code generation for Fory IDL within the
fory-compiler, converting FDL (Fory Definition Language) schema files
into pure TypeScript type definitions. Zero runtime dependencies, with
comprehensive test coverage (12/12 tests passing), supporting messages,
enums, unions, and all primitive types.

## Changes

### Core Implementation
- **compiler/fory_compiler/generators/typescript.py** - TypeScript code
generator extending BaseGenerator (365 lines)
- Generates type-safe TypeScript interfaces, enums, and discriminated
unions
  - Supports nested types, collections, and optional fields
  - Proper type mapping for all 25 FDL primitive kinds
  - Field name conversion (snake_case → camelCase)
- Registration helper function generation for Fory serialization
integration

- **compiler/fory_compiler/generators/__init__.py** - Registration of
TypeScriptGenerator in the compiler ecosystem

- **compiler/fory_compiler/cli.py** - Added --typescript_out CLI
argument for TypeScript code generation

- **compiler/fory_compiler/tests/test_typescript_codegen.py** - 12
golden codegen tests covering:
  - Enum and message generation
  - Nested types (messages and enums)
  - Discriminated unions
  - All primitive type mappings
  - Collection types (arrays, maps)
  - Field naming conventions
  - File structure and licensing
  - Zero runtime dependencies validation

### Features
- **Message-to-Interface Generation**: Auto-converts FDL messages to
TypeScript interfaces
- **Enum Support**: Generates TypeScript enums with proper value
stripping and type IDs
- **Discriminated Unions**: Creates union types with discriminator enums
for type safety
- **Type Mappings**: Full support for all FDL primitives (bool→boolean,
int32→number, int64→bigint|number, float/double→number, etc.)
- **Nested Types**: Supports nested messages and enums within parent
types
- **Collection Types**: Arrays (repeated fields) and maps with type-safe
generics
- **Zero Runtime Dependencies**: Pure TypeScript type definitions, no
gRPC or external imports
- **Field Naming**: Automatic conversion to camelCase per TypeScript
conventions
- **Package/Module Handling**: Uses last segment of package name for
module name and registration functions
- **License Headers**: All generated files include Apache 2.0 license
headers
- **Registration Helpers**: Generates registration functions for Fory
serialization framework integration

### AI Assistance Checklist
- [x] Substantial AI assistance was used in this PR (yes)
- [x] I included the standardized AI Usage Disclosure block below
- [x] I can explain and defend all important changes without AI help
- [x] I reviewed AI-assisted code changes line by line before submission
- [x] I ran adequate human verification and recorded evidence (local/CI
checks, pass/fail summary, and review confirmation)
- [x] I added/updated tests and specs where required
- [x] I validated protocol/performance impacts with evidence when
applicable
- [x] I verified licensing and provenance compliance

AI Usage Disclosure
- substantial_ai_assistance: yes
- scope: <design drafting | code drafting>
- affected_files_or_subsystems: <high-level paths/modules>
- human_verification: <checks run locally or in CI + pass/fail summary +
contributor reviewed results>
- performance_verification: <N/A>
- provenance_license_confirmation: <Apache-2.0-compatible provenance
confirmed; no incompatible third-party code introduced>

### AI Review Evidence
#### General AI Review
Initial Review
• Identified issues in decimal type mapping, array type precedence, tag
id drop, and traversalContainer doesn't traverse union cases
Fixes Applied
• Updated DECIMAL mapping to string to avoid precision loss
• fix array type precedence issue.
• tag id drop prevention for id ==
0
• Aligned map type documentation with generated output
Final Review (Fresh Session)
• Re reviewed updated changes
• All issues resolved
• All tests pass. No
actionable issues remain

#### Fory-Specific AI Review
Scope
• Reviewed serialization and deserialization logic
• Verified typeInfo
handling, struct embedding, and reference tracking
• Checked alignment with Java reference implementation
• Validated cross
language compatibility and code generation
Result
• No actionable issues found

• Implementation aligns with Fory wire format and runtime behavior

Fixes #3280

---------

Co-authored-by: Shawn Yang <shawn.ck.yang@gmail.com>

Author: miantalha45

.github/workflows/ci.yml

@@ -494,6 +494,7 @@ jobs:
         run: |
           cd javascript
           npm install
+          npm run build
       - name: Run JavaScript Xlang Test
         env:
           FORY_JAVASCRIPT_JAVA_CI: "1"
@@ -502,6 +503,8 @@ jobs:
           mvn -T16 --no-transfer-progress clean install -DskipTests -Dmaven.javadoc.skip=true -Dmaven.source.skip=true
           cd fory-core
           mvn --no-transfer-progress test -Dtest=org.apache.fory.xlang.JavaScriptXlangTest -DforkCount=0
+      - name: Run JavaScript IDL Tests
+        run: ./integration_tests/idl_tests/run_javascript_tests.sh
 
   rust:
     name: Rust CI

compiler/README.md

@@ -4,7 +4,7 @@ The FDL compiler generates cross-language serialization code from schema definit
 
 ## Features
 
-- **Multi-language code generation**: Java, Python, Go, Rust, C++, C#
+- **Multi-language code generation**: Java, Python, Go, Rust, C++, C#, JavaScript, and Swift
 - **Rich type system**: Primitives, enums, messages, lists, maps
 - **Cross-language serialization**: Generated code works seamlessly with Apache Fory
 - **Type ID and namespace support**: Both numeric IDs and name-based type registration
@@ -64,16 +64,16 @@ message Cat [id=103] {
 foryc schema.fdl --output ./generated
 
 # Generate for specific languages
-foryc schema.fdl --lang java,python,csharp --output ./generated
+foryc schema.fdl --lang java,python,csharp,javascript --output ./generated
 
 # Override package name
 foryc schema.fdl --package myapp.models --output ./generated
 
 # Language-specific output directories (protoc-style)
-foryc schema.fdl --java_out=./src/main/java --python_out=./python/src --csharp_out=./csharp/src/Generated
+foryc schema.fdl --java_out=./src/main/java --python_out=./python/src --csharp_out=./csharp/src/Generated --javascript_out=./javascript
 
 # Combine with other options
-foryc schema.fdl --java_out=./gen --go_out=./gen/go --csharp_out=./gen/csharp -I ./proto
+foryc schema.fdl --java_out=./gen --go_out=./gen/go --csharp_out=./gen/csharp --javascript_out=./gen/js -I ./proto
 ```
 
 ### 3. Use Generated Code
@@ -185,19 +185,19 @@ message Config { ... }  // Registered as "package.Config"
 
 ### Primitive Types
 
-| FDL Type    | Java        | Python              | Go          | Rust                    | C++                    | C#               |
-| ----------- | ----------- | ------------------- | ----------- | ----------------------- | ---------------------- | ---------------- |
-| `bool`      | `boolean`   | `bool`              | `bool`      | `bool`                  | `bool`                 | `bool`           |
-| `int8`      | `byte`      | `pyfory.int8`       | `int8`      | `i8`                    | `int8_t`               | `sbyte`          |
-| `int16`     | `short`     | `pyfory.int16`      | `int16`     | `i16`                   | `int16_t`              | `short`          |
-| `int32`     | `int`       | `pyfory.int32`      | `int32`     | `i32`                   | `int32_t`              | `int`            |
-| `int64`     | `long`      | `pyfory.int64`      | `int64`     | `i64`                   | `int64_t`              | `long`           |
-| `float32`   | `float`     | `pyfory.float32`    | `float32`   | `f32`                   | `float`                | `float`          |
-| `float64`   | `double`    | `pyfory.float64`    | `float64`   | `f64`                   | `double`               | `double`         |
-| `string`    | `String`    | `str`               | `string`    | `String`                | `std::string`          | `string`         |
-| `bytes`     | `byte[]`    | `bytes`             | `[]byte`    | `Vec<u8>`               | `std::vector<uint8_t>` | `byte[]`         |
-| `date`      | `LocalDate` | `datetime.date`     | `time.Time` | `chrono::NaiveDate`     | `fory::Date`           | `DateOnly`       |
-| `timestamp` | `Instant`   | `datetime.datetime` | `time.Time` | `chrono::NaiveDateTime` | `fory::Timestamp`      | `DateTimeOffset` |
+| FDL Type    | Java        | Python              | Go          | Rust                    | C++                    | C#               | JavaScript         |
+| ----------- | ----------- | ------------------- | ----------- | ----------------------- | ---------------------- | ---------------- | ------------------ |
+| `bool`      | `boolean`   | `bool`              | `bool`      | `bool`                  | `bool`                 | `bool`           | `boolean`          |
+| `int8`      | `byte`      | `pyfory.int8`       | `int8`      | `i8`                    | `int8_t`               | `sbyte`          | `number`           |
+| `int16`     | `short`     | `pyfory.int16`      | `int16`     | `i16`                   | `int16_t`              | `short`          | `number`           |
+| `int32`     | `int`       | `pyfory.int32`      | `int32`     | `i32`                   | `int32_t`              | `int`            | `number`           |
+| `int64`     | `long`      | `pyfory.int64`      | `int64`     | `i64`                   | `int64_t`              | `long`           | `bigint \| number` |
+| `float32`   | `float`     | `pyfory.float32`    | `float32`   | `f32`                   | `float`                | `float`          | `number`           |
+| `float64`   | `double`    | `pyfory.float64`    | `float64`   | `f64`                   | `double`               | `double`         | `number`           |
+| `string`    | `String`    | `str`               | `string`    | `String`                | `std::string`          | `string`         | `string`           |
+| `bytes`     | `byte[]`    | `bytes`             | `[]byte`    | `Vec<u8>`               | `std::vector<uint8_t>` | `byte[]`         | `Uint8Array`       |
+| `date`      | `LocalDate` | `datetime.date`     | `time.Time` | `chrono::NaiveDate`     | `fory::Date`           | `DateOnly`       | `Date`             |
+| `timestamp` | `Instant`   | `datetime.datetime` | `time.Time` | `chrono::NaiveDateTime` | `fory::Timestamp`      | `DateTimeOffset` | `Date`             |
 
 ### Collection Types
 
@@ -285,7 +285,8 @@ fory_compiler/
     ├── go.py             # Go struct generator
     ├── rust.py           # Rust struct generator
     ├── cpp.py            # C++ struct generator
-    └── csharp.py         # C# class generator
+    ├── csharp.py         # C# class generator
+    └── javascript.py     # JavaScript interface generator
 ```
 
 ### FDL Frontend
@@ -422,6 +423,25 @@ cd integration_tests/idl_tests
 ./run_csharp_tests.sh
 ```
 
+### JavaScript
+
+Generates interfaces with:
+
+- `export interface` declarations for messages
+- `export enum` declarations for enums
+- Discriminated unions with case enums
+- Registration helper function
+
+```javascript
+export interface Cat {
+  friend?: Dog | null;
+  name?: string | null;
+  tags: string[];
+  scores: Map<string, number>;
+  lives: number;
+}
+```
+
 ## CLI Reference
 
 ```
@@ -431,7 +451,7 @@ Arguments:
   FILES                 FDL files to compile
 
 Options:
-  --lang TEXT          Target languages (java,python,cpp,rust,go,csharp or "all")
+  --lang TEXT          Target languages (java,python,cpp,rust,go,csharp,javascript or "all")
                        Default: all
   --output, -o PATH    Output directory
                        Default: ./generated

compiler/fory_compiler/cli.py

@@ -264,7 +264,7 @@ def parse_args(args: Optional[List[str]] = None) -> argparse.Namespace:
         "--lang",
         type=str,
         default="all",
-        help="Comma-separated list of target languages (java,python,cpp,rust,go,csharp,swift). Default: all",
+        help="Comma-separated list of target languages (java,python,cpp,rust,go,csharp,javascript,swift). Default: all",
     )
 
     parser.add_argument(
@@ -343,6 +343,14 @@ def parse_args(args: Optional[List[str]] = None) -> argparse.Namespace:
         help="Generate C# code in DST_DIR",
     )
 
+    parser.add_argument(
+        "--javascript_out",
+        type=Path,
+        default=None,
+        metavar="DST_DIR",
+        help="Generate JavaScript code in DST_DIR",
+    )
+
     parser.add_argument(
         "--swift_out",
         type=Path,
@@ -650,6 +658,7 @@ def cmd_compile(args: argparse.Namespace) -> int:
         "go": args.go_out,
         "rust": args.rust_out,
         "csharp": args.csharp_out,
+        "javascript": args.javascript_out,
         "swift": args.swift_out,
     }
 

compiler/fory_compiler/generators/__init__.py

@@ -24,6 +24,7 @@
 from fory_compiler.generators.rust import RustGenerator
 from fory_compiler.generators.go import GoGenerator
 from fory_compiler.generators.csharp import CSharpGenerator
+from fory_compiler.generators.javascript import JavaScriptGenerator
 from fory_compiler.generators.swift import SwiftGenerator
 
 GENERATORS = {
@@ -33,6 +34,7 @@
     "rust": RustGenerator,
     "go": GoGenerator,
     "csharp": CSharpGenerator,
+    "javascript": JavaScriptGenerator,
     "swift": SwiftGenerator,
 }
 
@@ -44,6 +46,7 @@
     "RustGenerator",
     "GoGenerator",
     "CSharpGenerator",
+    "JavaScriptGenerator",
     "SwiftGenerator",
     "GENERATORS",
 ]