@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

bun add @hla4ts/fom-codegen

Quick Start

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

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:

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:

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:

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:

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

cd packages/fom-codegen
bun test

CLI

Generate XML from a registry module:

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:

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