npm package: @hla4ts/fom-codegen
Description: FOM XML parser, registry, and TypeScript code generation tooling for hla4typescript
Latest version: 0.1.1

# @hla4ts/fom-codegen

**TypeScript-first FOM/SOM code generator (IEEE 1516-2025 OMT/FDD XML)**

This package provides a registry API for describing object/interaction classes and data types in TypeScript, then generating valid IEEE 1516-2025 XML (OMT or FDD). It is designed to be the base for higher-level SpaceFOM-friendly frameworks.

## Goals

- Let users describe HLA classes in TypeScript without hand-editing XML.
- Generate deterministic, schema-valid XML for import into RTIs.
- Keep metadata explicit (update types, ownership, transport/order, semantics).

## Installation

```bash
bun add @hla4ts/fom-codegen
```

## Quick Start

```ts
import {
  FomRegistry,
  type ObjectClassSchema,
} from "@hla4ts/fom-codegen";

const registry = new FomRegistry();

registry.setModelIdentification({
  name: "MyFederate FOM",
  type: "FOM",
  version: "0.1.0",
  modificationDate: "2026-01-22",
  securityClassification: "Unclassified",
  description: "Custom SpaceFOM extensions for MyFederate",
});

const vehicle: ObjectClassSchema = {
  name: "SpaceVehicle",
  parent: "PhysicalEntity",
  sharing: "PublishSubscribe",
  semantics: "A user-defined vehicle class.",
  attributes: [
    {
      name: "name",
      dataType: "HLAunicodeString",
      updateType: "Static",
      updateCondition: "during initialization",
      ownership: "NoTransfer",
      sharing: "PublishSubscribe",
      transportation: "HLAreliable",
      order: "TimeStamp",
      semantics: "Unique name.",
      valueRequired: true,
    },
  ],
};

registry.addObjectClass(vehicle);

const xml = registry.toXml({ format: "omt" });
console.log(xml);
```

## Sequence Diagram

```mermaid
sequenceDiagram
  participant User as Developer
  participant Registry as FomRegistry
  participant Writer as renderFomXml
  User->>Registry: addObjectClass / addDataType
  User->>Registry: toXml({ format })
  Registry->>Writer: buildModel()
  Writer-->>User: OMT/FDD XML
```

## Registry API

- `setModelIdentification(...)`
- `setTime(...)`
- `addObjectClass(...)`
- `addInteractionClass(...)`
- `addDataType(...)`
- `addDimension(...)`
- `addTransportation(...)`
- `setSwitches(...)`
- `toXml({ format: "omt" | "fdd" })`

## XML Parsing

You can parse an existing XML FOM into a `FomModel` and then re-emit or convert it:

```ts
import { parseFomXml, generateFomTypescript } from "@hla4ts/fom-codegen";

const model = parseFomXml(xmlString);
const ts = generateFomTypescript(model, { mode: "registry" });
```

## XSD-Based Type Generation

This package includes TypeScript types generated directly from the IEEE 1516-2025 XSD schemas. These types provide:

- **Autocomplete** based on the official XML schema
- **Type checking** that matches XSD validation
- **Documentation** extracted from XSD annotations

### Using XSD Types

The generated types are available from the `generated` submodule:

```ts
import type {
  ModelIdentification,
  ObjectClass,
  InteractionClass,
  SharingEnumeration,
  OrderEnumeration,
} from "@hla4ts/fom-codegen/generated";

// Use XSD types for autocomplete
const modelId: ModelIdentification = {
  name: "MyFOM",
  type: "FOM", // Autocomplete: "FOM" | "SOM"
  version: "1.0",
  modificationDate: "2026-01-23",
  securityClassification: "Unclassified", // Autocomplete shows valid values
  description: "My federation object model",
};

const objectClass: ObjectClass = {
  name: "MyObject",
  sharing: "PublishSubscribe", // Autocomplete: "Publish" | "Subscribe" | "PublishSubscribe" | "Neither"
  // ... other properties with full autocomplete
};
```

### Generating Types

Types are generated from the XSD schemas in the `schema/` directory:

```bash
bun run generate-types
```

This parses `IEEE1516-DIF-2025.xsd` and generates TypeScript types in `src/generated/xsd-types.ts`.

### Type Adapters

Use the adapter functions to convert XSD types to FomRegistry schema types:

```ts
import {
  FomRegistry,
  adaptModelIdentification,
  adaptObjectClass,
  adaptInteractionClass,
} from "@hla4ts/fom-codegen";
import type {
  ModelIdentification,
  ObjectClass,
  InteractionClass,
} from "@hla4ts/fom-codegen/generated";

const registry = new FomRegistry();

// Define using XSD types for autocomplete and type checking
const modelId: ModelIdentification = {
  name: "MyFOM",
  type: "FOM", // TypeScript autocomplete: "FOM" | "SOM"
  version: "1.0",
  modificationDate: "2026-01-23",
  securityClassification: "Unclassified", // Autocomplete shows valid values
  description: "My federation object model",
};

// Convert and use with FomRegistry
registry.setModelIdentification(adaptModelIdentification(modelId));

// Object classes with XSD autocomplete
const vehicle: ObjectClass = {
  name: "SpaceVehicle",
  sharing: "PublishSubscribe", // Autocomplete: "Publish" | "Subscribe" | "PublishSubscribe" | "Neither"
  semantics: "A space vehicle",
  attribute: [
    {
      name: "name",
      dataType: "HLAunicodeString",
      updateType: "Static", // Autocomplete: "Static" | "Periodic" | "Conditional" | "NA"
      ownership: "NoTransfer", // Autocomplete: "Divest" | "Acquire" | "DivestAcquire" | "NoTransfer"
      sharing: "PublishSubscribe",
      transportation: "HLAreliable",
      order: "TimeStamp", // Autocomplete: "Receive" | "TimeStamp"
    },
  ],
};

registry.addObjectClass(adaptObjectClass(vehicle));
```

### Benefits

- **Compile-time type checking**: TypeScript will catch invalid enum values, missing required fields, and type mismatches
- **Autocomplete**: Your IDE will suggest valid values for enums and available properties
- **XSD alignment**: The generated types match the XSD schema exactly, so what TypeScript accepts will pass XSD validation
- **Documentation**: JSDoc comments from XSD annotations are preserved in the generated types

### Parser Notes

- The parser targets IEEE 1516-2025 OMT/FDD structures and ignores unrelated XML.
- Namespaces are stripped from element and attribute names.
- Missing attribute metadata is defaulted to safe values (e.g., `updateType = "NA"`).

## Notes

- OMT output requires `modelIdentification` fields. FDD output is more relaxed.
- The generator always writes `HLAobjectRoot` and `HLAinteractionRoot` if not provided.
- Attribute/interaction metadata is not inferred from TS types; it must be explicit.

## Testing

```bash
cd packages/fom-codegen
bun test
```

## CLI

Generate XML from a registry module:

```bash
bun run @hla4ts/fom-codegen cli -- --entry src/fom.ts --out dist/fom.xml --format omt
```

Entry modules can export:

- `registry`: a `FomRegistry` instance
- `default`: a `FomRegistry` instance
- `buildFom()`: function returning `FomModel`
- `default`: a `FomModel` object

Parse XML and emit TypeScript:

```bash
bun run @hla4ts/fom-codegen cli -- --from-xml spacefom/SISO_SpaceFOM_entity.xml --out-ts src/fom.ts --ts-mode registry
```