@hla4ts/hla-api 0.1.0

package/src/types.ts

@@ -0,0 +1,440 @@
+/**
+ * HLA 4 Type Definitions
+ *
+ * This module provides type-safe wrappers and type definitions for HLA 4 concepts.
+ */
+
+import {
+  CallbackModel,
+  ResignAction,
+  OrderType,
+  SynchronizationPointFailureReason,
+  SaveFailureReason,
+  RestoreFailureReason,
+  SaveStatus,
+  RestoreStatus,
+} from "@hla4ts/proto";
+
+// Re-export enums for convenience
+export {
+  CallbackModel,
+  ResignAction,
+  OrderType,
+  SynchronizationPointFailureReason,
+  SaveFailureReason,
+  RestoreFailureReason,
+  SaveStatus,
+  RestoreStatus,
+};
+
+// =============================================================================
+// Handle Types
+// =============================================================================
+
+/**
+ * Opaque handle representing a federate in the federation.
+ * Handles are represented as Uint8Array (byte arrays) in the Federate Protocol.
+ */
+export type FederateHandle = Uint8Array;
+
+/**
+ * Opaque handle representing an object class in the FOM.
+ */
+export type ObjectClassHandle = Uint8Array;
+
+/**
+ * Opaque handle representing an attribute within an object class.
+ */
+export type AttributeHandle = Uint8Array;
+
+/**
+ * Opaque handle representing an interaction class in the FOM.
+ */
+export type InteractionClassHandle = Uint8Array;
+
+/**
+ * Opaque handle representing a parameter within an interaction class.
+ */
+export type ParameterHandle = Uint8Array;
+
+/**
+ * Opaque handle representing a registered object instance.
+ */
+export type ObjectInstanceHandle = Uint8Array;
+
+/**
+ * Opaque handle representing a message retraction.
+ */
+export type MessageRetractionHandle = Uint8Array;
+
+/**
+ * Opaque handle representing a transportation type.
+ */
+export type TransportationTypeHandle = Uint8Array;
+
+/**
+ * Opaque handle representing a dimension for DDM.
+ */
+export type DimensionHandle = Uint8Array;
+
+/**
+ * Opaque handle representing a region for DDM.
+ */
+export type RegionHandle = Uint8Array;
+
+// =============================================================================
+// Logical Time
+// =============================================================================
+
+/**
+ * Encoded logical time (RTI-specific encoding).
+ * The actual time representation depends on the LogicalTimeFactory used.
+ */
+export type LogicalTime = Uint8Array;
+
+/**
+ * Encoded logical time interval (RTI-specific encoding).
+ */
+export type LogicalTimeInterval = Uint8Array;
+
+// =============================================================================
+// Handle Sets
+// =============================================================================
+
+/**
+ * Set of federate handles.
+ */
+export type FederateHandleSet = FederateHandle[];
+
+/**
+ * Set of attribute handles.
+ */
+export type AttributeHandleSet = AttributeHandle[];
+
+/**
+ * Set of dimension handles.
+ */
+export type DimensionHandleSet = DimensionHandle[];
+
+/**
+ * Set of region handles.
+ */
+export type RegionHandleSet = RegionHandle[];
+
+/**
+ * Set of interaction class handles.
+ */
+export type InteractionClassHandleSet = InteractionClassHandle[];
+
+// =============================================================================
+// Handle-Value Maps
+// =============================================================================
+
+/**
+ * A single attribute handle-value pair.
+ */
+export interface AttributeHandleValue {
+  attributeHandle: AttributeHandle;
+  value: Uint8Array;
+}
+
+/**
+ * Map of attribute handles to their values.
+ */
+export type AttributeHandleValueMap = AttributeHandleValue[];
+
+/**
+ * A single parameter handle-value pair.
+ */
+export interface ParameterHandleValue {
+  parameterHandle: ParameterHandle;
+  value: Uint8Array;
+}
+
+/**
+ * Map of parameter handles to their values.
+ */
+export type ParameterHandleValueMap = ParameterHandleValue[];
+
+// =============================================================================
+// Federation Information
+// =============================================================================
+
+/**
+ * Information about a federation execution.
+ */
+export interface FederationExecutionInformation {
+  federationName: string;
+  logicalTimeImplementationName: string;
+}
+
+/**
+ * Set of federation execution information.
+ */
+export type FederationExecutionInformationSet = FederationExecutionInformation[];
+
+/**
+ * Information about a member of a federation execution.
+ */
+export interface FederationExecutionMemberInformation {
+  federateName: string;
+  federateType: string;
+}
+
+/**
+ * Set of federation execution member information.
+ */
+export type FederationExecutionMemberInformationSet = FederationExecutionMemberInformation[];
+
+/**
+ * Result of joining a federation execution.
+ */
+export interface JoinResult {
+  federateHandle: FederateHandle;
+  logicalTimeImplementationName: string;
+}
+
+// =============================================================================
+// Save/Restore Information
+// =============================================================================
+
+/**
+ * Federate restore status.
+ */
+export interface FederateRestoreStatus {
+  preHandle: FederateHandle;
+  postHandle: FederateHandle;
+  status: RestoreStatus;
+}
+
+/**
+ * Array of federate restore statuses.
+ */
+export type FederateRestoreStatusArray = FederateRestoreStatus[];
+
+/**
+ * Federate handle and save status pair.
+ */
+export interface FederateHandleSaveStatusPair {
+  federateHandle: FederateHandle;
+  saveStatus: SaveStatus;
+}
+
+/**
+ * Array of federate save status pairs.
+ */
+export type FederateHandleSaveStatusPairArray = FederateHandleSaveStatusPair[];
+
+// =============================================================================
+// Time Query Returns
+// =============================================================================
+
+/**
+ * Result of a time query operation.
+ */
+export interface TimeQueryReturn {
+  logicalTimeIsValid: boolean;
+  logicalTime?: LogicalTime;
+}
+
+/**
+ * Result of an operation that may return a message retraction handle.
+ */
+export interface MessageRetractionReturn {
+  retractionHandleIsValid: boolean;
+  retractionHandle?: MessageRetractionHandle;
+}
+
+// =============================================================================
+// DDM (Data Distribution Management) Types
+// =============================================================================
+
+/**
+ * Range bounds for a dimension.
+ */
+export interface RangeBounds {
+  lower: bigint;
+  upper: bigint;
+}
+
+/**
+ * Dimension and its range specification.
+ */
+export interface DimensionAndRange {
+  dimensionHandle: DimensionHandle;
+  range: RangeBounds;
+}
+
+/**
+ * A conveyed region (list of dimension-range pairs).
+ */
+export type ConveyedRegion = DimensionAndRange[];
+
+/**
+ * Set of conveyed regions.
+ */
+export type ConveyedRegionSet = ConveyedRegion[];
+
+/**
+ * Pair of attribute set and region set.
+ */
+export interface AttributeSetRegionSetPair {
+  attributeSet: AttributeHandleSet;
+  regionSet: RegionHandleSet;
+}
+
+/**
+ * List of attribute-set/region-set pairs.
+ */
+export type AttributeSetRegionSetPairList = AttributeSetRegionSetPair[];
+
+// =============================================================================
+// Supplemental Information
+// =============================================================================
+
+/**
+ * Supplemental information for attribute reflections.
+ */
+export interface SupplementalReflectInfo {
+  hasProducingFederate: boolean;
+  producingFederate?: FederateHandle;
+  hasSentRegions: boolean;
+  sentRegions?: ConveyedRegionSet;
+}
+
+/**
+ * Supplemental information for interaction receipts.
+ */
+export interface SupplementalReceiveInfo {
+  hasProducingFederate: boolean;
+  producingFederate?: FederateHandle;
+  hasSentRegions: boolean;
+  sentRegions?: ConveyedRegionSet;
+}
+
+// =============================================================================
+// FOM Module Types
+// =============================================================================
+
+/**
+ * A FOM module as inline content.
+ */
+export interface FomModuleInline {
+  type: "inline";
+  content: string;
+}
+
+/**
+ * A FOM module as a file reference.
+ */
+export interface FomModuleFile {
+  type: "file";
+  name: string;
+  content: Uint8Array;
+}
+
+/**
+ * A FOM module as a URL/designator reference.
+ */
+export interface FomModuleUrl {
+  type: "url";
+  url: string;
+}
+
+/**
+ * A FOM module (one of inline, file, or URL).
+ */
+export type FomModule = FomModuleInline | FomModuleFile | FomModuleUrl;
+
+/**
+ * Set of FOM modules.
+ */
+export type FomModuleSet = FomModule[];
+
+// =============================================================================
+// Configuration Types
+// =============================================================================
+
+/**
+ * RTI configuration for connecting.
+ */
+export interface RtiConfiguration {
+  configurationName?: string;
+  rtiAddress?: string;
+  additionalSettings?: string;
+}
+
+/**
+ * Result of RTI configuration.
+ */
+export interface ConfigurationResult {
+  configurationUsed: boolean;
+  reportedConfiguration?: RtiConfiguration;
+  message?: string;
+}
+
+/**
+ * Credentials for authenticated connections.
+ */
+export interface Credentials {
+  type: string;
+  data: Uint8Array;
+}
+
+// =============================================================================
+// Connection Options
+// =============================================================================
+
+/**
+ * Options for connecting to the RTI.
+ */
+export interface ConnectionOptions {
+  /** The callback model to use (EVOKED or IMMEDIATE) */
+  callbackModel: CallbackModel;
+
+  /** RTI configuration (optional) */
+  rtiConfiguration?: RtiConfiguration;
+
+  /** Credentials for authentication (optional) */
+  credentials?: Credentials;
+}
+
+// =============================================================================
+// Utility Types
+// =============================================================================
+
+/**
+ * User-supplied tag (arbitrary byte array).
+ */
+export type UserSuppliedTag = Uint8Array;
+
+/**
+ * Compare two handles for equality.
+ */
+export function handlesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * Convert a handle to a hex string for debugging/logging.
+ */
+export function handleToHex(handle: Uint8Array): string {
+  return Array.from(handle)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/**
+ * Create a handle from a hex string.
+ */
+export function handleFromHex(hex: string): Uint8Array {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}