@hla4ts/hla-api 0.1.0

package/src/converters.ts

@@ -0,0 +1,449 @@
+/**
+ * Type Converters
+ *
+ * This module provides conversion functions between protobuf types and
+ * the TypeScript HLA API types.
+ */
+
+import type {
+  AttributeHandleSet as ProtoAttributeHandleSet,
+  AttributeHandleValueMap as ProtoAttributeHandleValueMap,
+  ParameterHandleValueMap as ProtoParameterHandleValueMap,
+  FederateHandleSet as ProtoFederateHandleSet,
+  FederationExecutionInformationSet as ProtoFederationExecutionInformationSet,
+  FederationExecutionMemberInformationSet as ProtoFederationExecutionMemberInformationSet,
+  FederateHandleSaveStatusPairArray as ProtoFederateHandleSaveStatusPairArray,
+  FederateRestoreStatusArray as ProtoFederateRestoreStatusArray,
+  ConveyedRegionSet as ProtoConveyedRegionSet,
+  JoinResult as ProtoJoinResult,
+  TimeQueryReturn as ProtoTimeQueryReturn,
+  MessageRetractionReturn as ProtoMessageRetractionReturn,
+  FomModule as ProtoFomModule,
+  FomModuleSet as ProtoFomModuleSet,
+  RtiConfiguration as ProtoRtiConfiguration,
+  ConfigurationResult as ProtoConfigurationResult,
+  Credentials as ProtoCredentials,
+  ObjectClassHandle as ProtoObjectClassHandle,
+  AttributeHandle as ProtoAttributeHandle,
+  InteractionClassHandle as ProtoInteractionClassHandle,
+  ParameterHandle as ProtoParameterHandle,
+  ObjectInstanceHandle as ProtoObjectInstanceHandle,
+  FederateHandle as ProtoFederateHandle,
+  TransportationTypeHandle as ProtoTransportationTypeHandle,
+  LogicalTime as ProtoLogicalTime,
+  LogicalTimeInterval as ProtoLogicalTimeInterval,
+  MessageRetractionHandle as ProtoMessageRetractionHandle,
+} from "@hla4ts/proto";
+
+import type {
+  AttributeHandleSet,
+  AttributeHandleValueMap,
+  ParameterHandleValueMap,
+  FederationExecutionInformationSet,
+  FederationExecutionMemberInformationSet,
+  FederateHandleSaveStatusPairArray,
+  FederateRestoreStatusArray,
+  ConveyedRegionSet,
+  JoinResult,
+  TimeQueryReturn,
+  MessageRetractionReturn,
+  FomModule,
+  FomModuleSet,
+  RtiConfiguration,
+  ConfigurationResult,
+  Credentials,
+  ObjectClassHandle,
+  AttributeHandle,
+  InteractionClassHandle,
+  ParameterHandle,
+  ObjectInstanceHandle,
+  FederateHandle,
+  TransportationTypeHandle,
+  LogicalTime,
+  LogicalTimeInterval,
+  MessageRetractionHandle,
+  FederateHandleSet,
+} from "./types.ts";
+
+import {
+  SaveStatus,
+  RestoreStatus,
+  SynchronizationPointFailureReason,
+  SaveFailureReason,
+  RestoreFailureReason,
+  OrderType,
+} from "@hla4ts/proto";
+
+// =============================================================================
+// Handle Conversions (Proto -> TS)
+// =============================================================================
+
+/**
+ * Convert a protobuf handle to TypeScript (essentially a passthrough since both are Uint8Array-like).
+ */
+function convertHandle(protoHandle: { data: Uint8Array } | undefined): Uint8Array {
+  return protoHandle?.data ?? new Uint8Array(0);
+}
+
+export function convertObjectClassHandle(handle: ProtoObjectClassHandle | undefined): ObjectClassHandle {
+  return convertHandle(handle);
+}
+
+export function convertAttributeHandle(handle: ProtoAttributeHandle | undefined): AttributeHandle {
+  return convertHandle(handle);
+}
+
+export function convertInteractionClassHandle(handle: ProtoInteractionClassHandle | undefined): InteractionClassHandle {
+  return convertHandle(handle);
+}
+
+export function convertParameterHandle(handle: ProtoParameterHandle | undefined): ParameterHandle {
+  return convertHandle(handle);
+}
+
+export function convertObjectInstanceHandle(handle: ProtoObjectInstanceHandle | undefined): ObjectInstanceHandle {
+  return convertHandle(handle);
+}
+
+export function convertFederateHandle(handle: ProtoFederateHandle | undefined): FederateHandle {
+  return convertHandle(handle);
+}
+
+export function convertTransportationTypeHandle(handle: ProtoTransportationTypeHandle | undefined): TransportationTypeHandle {
+  return convertHandle(handle);
+}
+
+export function convertLogicalTime(time: ProtoLogicalTime | undefined): LogicalTime {
+  return convertHandle(time);
+}
+
+export function convertLogicalTimeInterval(interval: ProtoLogicalTimeInterval | undefined): LogicalTimeInterval {
+  return convertHandle(interval);
+}
+
+export function convertMessageRetractionHandle(handle: ProtoMessageRetractionHandle | undefined): MessageRetractionHandle {
+  return convertHandle(handle);
+}
+
+// =============================================================================
+// Handle Set Conversions (Proto -> TS)
+// =============================================================================
+
+export function convertAttributeHandleSet(protoSet: ProtoAttributeHandleSet | undefined): AttributeHandleSet {
+  if (!protoSet?.attributeHandle) return [];
+  return protoSet.attributeHandle.map(h => convertHandle(h));
+}
+
+export function convertFederateHandleSet(protoSet: ProtoFederateHandleSet | undefined): FederateHandleSet {
+  if (!protoSet?.federateHandle) return [];
+  return protoSet.federateHandle.map(h => convertHandle(h));
+}
+
+// =============================================================================
+// Handle-Value Map Conversions (Proto -> TS)
+// =============================================================================
+
+export function convertAttributeHandleValueMap(
+  protoMap: ProtoAttributeHandleValueMap | undefined
+): AttributeHandleValueMap {
+  if (!protoMap?.attributeHandleValue) return [];
+  return protoMap.attributeHandleValue.map(entry => ({
+    attributeHandle: convertHandle(entry.attributeHandle),
+    value: entry.value ?? new Uint8Array(0),
+  }));
+}
+
+export function convertParameterHandleValueMap(
+  protoMap: ProtoParameterHandleValueMap | undefined
+): ParameterHandleValueMap {
+  if (!protoMap?.parameterHandleValue) return [];
+  return protoMap.parameterHandleValue.map(entry => ({
+    parameterHandle: convertHandle(entry.parameterHandle),
+    value: entry.value ?? new Uint8Array(0),
+  }));
+}
+
+// =============================================================================
+// Federation Information Conversions (Proto -> TS)
+// =============================================================================
+
+export function convertFederationExecutionInformationSet(
+  protoSet: ProtoFederationExecutionInformationSet | undefined
+): FederationExecutionInformationSet {
+  if (!protoSet?.federationExecutionInformation) return [];
+  return protoSet.federationExecutionInformation.map(info => ({
+    federationName: info.federationExecutionName ?? "",
+    logicalTimeImplementationName: info.logicalTimeImplementationName ?? "",
+  }));
+}
+
+export function convertFederationExecutionMemberInformationSet(
+  protoSet: ProtoFederationExecutionMemberInformationSet | undefined
+): FederationExecutionMemberInformationSet {
+  if (!protoSet?.federationExecutionMemberInformation) return [];
+  return protoSet.federationExecutionMemberInformation.map(info => ({
+    federateName: info.federateName ?? "",
+    federateType: info.federateType ?? "",
+  }));
+}
+
+// =============================================================================
+// Save/Restore Conversions (Proto -> TS)
+// =============================================================================
+
+export function convertFederateHandleSaveStatusPairArray(
+  protoArray: ProtoFederateHandleSaveStatusPairArray | undefined
+): FederateHandleSaveStatusPairArray {
+  if (!protoArray?.federateHandleSaveStatusPair) return [];
+  return protoArray.federateHandleSaveStatusPair.map(pair => ({
+    federateHandle: convertHandle(pair.federateHandle),
+    saveStatus: pair.saveStatus ?? SaveStatus.NO_SAVE_IN_PROGRESS,
+  }));
+}
+
+export function convertFederateRestoreStatusArray(
+  protoArray: ProtoFederateRestoreStatusArray | undefined
+): FederateRestoreStatusArray {
+  if (!protoArray?.federateRestoreStatus) return [];
+  return protoArray.federateRestoreStatus.map(status => ({
+    preHandle: convertHandle(status.preRestoreHandle),
+    postHandle: convertHandle(status.postRestoreHandle),
+    status: status.restoreStatus ?? RestoreStatus.NO_RESTORE_IN_PROGRESS,
+  }));
+}
+
+// =============================================================================
+// DDM Conversions (Proto -> TS)
+// =============================================================================
+
+export function convertConveyedRegionSet(
+  protoSet: ProtoConveyedRegionSet | undefined
+): ConveyedRegionSet | undefined {
+  if (!protoSet?.conveyedRegions) return undefined;
+  return protoSet.conveyedRegions.map((region: { dimensionAndRange?: Array<{ dimensionHandle?: { data: Uint8Array }; range?: { lower?: bigint; upper?: bigint } }> }) => {
+    if (!region.dimensionAndRange) return [];
+    return region.dimensionAndRange.map((dar: { dimensionHandle?: { data: Uint8Array }; range?: { lower?: bigint; upper?: bigint } }) => ({
+      dimensionHandle: convertHandle(dar.dimensionHandle),
+      range: {
+        lower: dar.range?.lower ?? 0n,
+        upper: dar.range?.upper ?? 0n,
+      },
+    }));
+  });
+}
+
+// =============================================================================
+// Result Conversions (Proto -> TS)
+// =============================================================================
+
+export function convertJoinResult(protoResult: ProtoJoinResult | undefined): JoinResult {
+  return {
+    federateHandle: convertHandle(protoResult?.federateHandle),
+    logicalTimeImplementationName: protoResult?.logicalTimeImplementationName ?? "",
+  };
+}
+
+export function convertTimeQueryReturn(protoReturn: ProtoTimeQueryReturn | undefined): TimeQueryReturn {
+  return {
+    logicalTimeIsValid: protoReturn?.logicalTimeIsValid ?? false,
+    logicalTime: protoReturn?.logicalTime ? convertLogicalTime(protoReturn.logicalTime) : undefined,
+  };
+}
+
+export function convertMessageRetractionReturn(
+  protoReturn: ProtoMessageRetractionReturn | undefined
+): MessageRetractionReturn {
+  return {
+    retractionHandleIsValid: protoReturn?.retractionHandleIsValid ?? false,
+    retractionHandle: protoReturn?.messageRetractionHandle 
+      ? convertMessageRetractionHandle(protoReturn.messageRetractionHandle) 
+      : undefined,
+  };
+}
+
+// =============================================================================
+// Configuration Conversions (Proto -> TS)
+// =============================================================================
+
+export function convertConfigurationResult(
+  protoResult: ProtoConfigurationResult | undefined
+): ConfigurationResult {
+  return {
+    configurationUsed: protoResult?.configurationUsed ?? false,
+    // Note: Proto ConfigurationResult has different structure than our simplified type
+    message: protoResult?.message,
+  };
+}
+
+export function convertRtiConfiguration(
+  protoConfig: ProtoRtiConfiguration | undefined
+): RtiConfiguration {
+  return {
+    configurationName: protoConfig?.configurationName,
+    rtiAddress: protoConfig?.rtiAddress,
+    additionalSettings: protoConfig?.additionalSettings,
+  };
+}
+
+// =============================================================================
+// Enum Conversions (Proto -> TS)
+// =============================================================================
+
+export function convertSynchronizationPointFailureReason(
+  reason: SynchronizationPointFailureReason
+): SynchronizationPointFailureReason {
+  return reason; // Same enum type
+}
+
+export function convertSaveFailureReason(reason: SaveFailureReason): SaveFailureReason {
+  return reason;
+}
+
+export function convertRestoreFailureReason(reason: RestoreFailureReason): RestoreFailureReason {
+  return reason;
+}
+
+export function convertOrderType(orderType: OrderType): OrderType {
+  return orderType;
+}
+
+// =============================================================================
+// Handle Conversions (TS -> Proto)
+// =============================================================================
+
+function createProtoHandle(data: Uint8Array): { data: Uint8Array } {
+  return { data };
+}
+
+export function toProtoObjectClassHandle(handle: ObjectClassHandle): ProtoObjectClassHandle {
+  return createProtoHandle(handle);
+}
+
+export function toProtoAttributeHandle(handle: AttributeHandle): ProtoAttributeHandle {
+  return createProtoHandle(handle);
+}
+
+export function toProtoInteractionClassHandle(handle: InteractionClassHandle): ProtoInteractionClassHandle {
+  return createProtoHandle(handle);
+}
+
+export function toProtoParameterHandle(handle: ParameterHandle): ProtoParameterHandle {
+  return createProtoHandle(handle);
+}
+
+export function toProtoObjectInstanceHandle(handle: ObjectInstanceHandle): ProtoObjectInstanceHandle {
+  return createProtoHandle(handle);
+}
+
+export function toProtoFederateHandle(handle: FederateHandle): ProtoFederateHandle {
+  return createProtoHandle(handle);
+}
+
+export function toProtoTransportationTypeHandle(handle: TransportationTypeHandle): ProtoTransportationTypeHandle {
+  return createProtoHandle(handle);
+}
+
+export function toProtoLogicalTime(time: LogicalTime): ProtoLogicalTime {
+  return createProtoHandle(time);
+}
+
+export function toProtoLogicalTimeInterval(interval: LogicalTimeInterval): ProtoLogicalTimeInterval {
+  return createProtoHandle(interval);
+}
+
+export function toProtoMessageRetractionHandle(handle: MessageRetractionHandle): ProtoMessageRetractionHandle {
+  return createProtoHandle(handle);
+}
+
+// =============================================================================
+// Handle Set Conversions (TS -> Proto)
+// =============================================================================
+
+export function toProtoAttributeHandleSet(handles: AttributeHandleSet): ProtoAttributeHandleSet {
+  return {
+    attributeHandle: handles.map(h => createProtoHandle(h)),
+  };
+}
+
+export function toProtoFederateHandleSet(handles: FederateHandleSet): ProtoFederateHandleSet {
+  return {
+    federateHandle: handles.map(h => createProtoHandle(h)),
+  };
+}
+
+// =============================================================================
+// Handle-Value Map Conversions (TS -> Proto)
+// =============================================================================
+
+export function toProtoAttributeHandleValueMap(
+  map: AttributeHandleValueMap
+): ProtoAttributeHandleValueMap {
+  return {
+    attributeHandleValue: map.map(entry => ({
+      attributeHandle: createProtoHandle(entry.attributeHandle),
+      value: entry.value,
+    })),
+  };
+}
+
+export function toProtoParameterHandleValueMap(
+  map: ParameterHandleValueMap
+): ProtoParameterHandleValueMap {
+  return {
+    parameterHandleValue: map.map(entry => ({
+      parameterHandle: createProtoHandle(entry.parameterHandle),
+      value: entry.value,
+    })),
+  };
+}
+
+// =============================================================================
+// FOM Module Conversions (TS -> Proto)
+// =============================================================================
+
+export function toProtoFomModule(module: FomModule): ProtoFomModule {
+  switch (module.type) {
+    case "inline":
+      // Convert inline XML string to UTF-8 bytes and use file format
+      const encoder = new TextEncoder();
+      const content = encoder.encode(module.content);
+      return {
+        compressedModule: undefined,
+        url: undefined,
+        file: { name: "fom.xml", content },
+      };
+    case "file":
+      return {
+        compressedModule: undefined,
+        url: undefined,
+        file: { name: module.name, content: module.content },
+      };
+    case "url":
+      return { compressedModule: undefined, url: module.url, file: undefined };
+  }
+}
+
+export function toProtoFomModuleSet(modules: FomModuleSet): ProtoFomModuleSet {
+  return {
+    fomModule: modules.map(toProtoFomModule),
+  };
+}
+
+// =============================================================================
+// Configuration Conversions (TS -> Proto)
+// =============================================================================
+
+export function toProtoRtiConfiguration(config: RtiConfiguration): ProtoRtiConfiguration {
+  return {
+    configurationName: config.configurationName ?? "",
+    rtiAddress: config.rtiAddress ?? "",
+    additionalSettings: config.additionalSettings ?? "",
+  };
+}
+
+export function toProtoCredentials(credentials: Credentials): ProtoCredentials {
+  return {
+    type: credentials.type,
+    data: credentials.data,
+  };
+}

package/src/encoding.ts

@@ -0,0 +1,52 @@
+/**
+ * HLA Encoding Helpers
+ *
+ * IEEE 1516.2 encodings for HLAinteger64Time and HLAinteger64Interval.
+ * These are 8-byte, big-endian, two's-complement integers.
+ */
+
+const INTEGER_64_SIZE = 8;
+
+function assertLength(data: Uint8Array, expected: number, label: string): void {
+  if (data.length !== expected) {
+    throw new Error(`${label}: expected ${expected} bytes, got ${data.length}`);
+  }
+}
+
+/**
+ * Encode a BigInt as HLAinteger64Time (IEEE 1516.2).
+ */
+export function encodeHLAinteger64Time(value: bigint): Uint8Array {
+  const buffer = new Uint8Array(INTEGER_64_SIZE);
+  const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+  view.setBigInt64(0, value, false);
+  return buffer;
+}
+
+/**
+ * Decode an HLAinteger64Time (IEEE 1516.2) into a BigInt.
+ */
+export function decodeHLAinteger64Time(data: Uint8Array): bigint {
+  assertLength(data, INTEGER_64_SIZE, "HLAinteger64Time");
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  return view.getBigInt64(0, false);
+}
+
+/**
+ * Encode a BigInt as HLAinteger64Interval (IEEE 1516.2).
+ */
+export function encodeHLAinteger64Interval(value: bigint): Uint8Array {
+  const buffer = new Uint8Array(INTEGER_64_SIZE);
+  const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+  view.setBigInt64(0, value, false);
+  return buffer;
+}
+
+/**
+ * Decode an HLAinteger64Interval (IEEE 1516.2) into a BigInt.
+ */
+export function decodeHLAinteger64Interval(data: Uint8Array): bigint {
+  assertLength(data, INTEGER_64_SIZE, "HLAinteger64Interval");
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  return view.getBigInt64(0, false);
+}