@hla4ts/hla-api 0.1.0

package/src/index.ts

@@ -0,0 +1,378 @@
+/**
+ * @hla4ts/hla-api - High-level HLA 4 API for TypeScript
+ *
+ * This package provides a TypeScript-friendly API for HLA 4 (IEEE 1516-2025)
+ * federates using the Federate Protocol.
+ *
+ * Main components:
+ * - RTIAmbassador: Interface for federate-to-RTI communication
+ * - FederateAmbassador: Callback interface for RTI-to-federate communication
+ * - Exception classes: Type-safe HLA exception handling
+ *
+ * @example
+ * ```ts
+ * import {
+ *   RTIAmbassador,
+ *   BaseFederateAmbassador,
+ *   CallbackModel,
+ *   ResignAction,
+ * } from '@hla4ts/hla-api';
+ *
+ * // Create your federate ambassador
+ * class MyFederateAmbassador extends BaseFederateAmbassador {
+ *   discoverObjectInstance(objectInstance, objectClass, name, producer) {
+ *     console.log(`Discovered object: ${name}`);
+ *   }
+ *
+ *   reflectAttributeValues(objectInstance, attributeValues, tag) {
+ *     console.log(`Received update`);
+ *   }
+ * }
+ *
+ * // Create RTI ambassador and connect
+ * const rtiAmbassador = new RTIAmbassador({ host: 'rti.example.com' });
+ * const federateAmbassador = new MyFederateAmbassador();
+ *
+ * await rtiAmbassador.connect(federateAmbassador, {
+ *   callbackModel: CallbackModel.EVOKED,
+ * });
+ *
+ * // Join a federation
+ * const joinResult = await rtiAmbassador.joinFederationExecution(
+ *   'MyFederateType',
+ *   'TestFederation'
+ * );
+ *
+ * // Get handles for FOM elements
+ * const objectClassHandle = await rtiAmbassador.getObjectClassHandle('HLAobjectRoot.MyClass');
+ * const attributeHandle = await rtiAmbassador.getAttributeHandle(objectClassHandle, 'MyAttribute');
+ *
+ * // Publish and register
+ * await rtiAmbassador.publishObjectClassAttributes(objectClassHandle, [attributeHandle]);
+ * const objectInstance = await rtiAmbassador.registerObjectInstance(objectClassHandle);
+ *
+ * // Update attributes
+ * await rtiAmbassador.updateAttributeValues(
+ *   objectInstance,
+ *   [{ attributeHandle, value: new Uint8Array([1, 2, 3]) }],
+ *   new Uint8Array()
+ * );
+ *
+ * // Clean up
+ * await rtiAmbassador.resignFederationExecution(ResignAction.DELETE_OBJECTS_THEN_DIVEST);
+ * await rtiAmbassador.disconnect();
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// =============================================================================
+// RTI Ambassador
+// =============================================================================
+export { RTIAmbassador, type RTIAmbassadorOptions } from "./rti-ambassador.ts";
+
+// =============================================================================
+// Federate Ambassador
+// =============================================================================
+export {
+  type FederateAmbassador,
+  NullFederateAmbassador,
+  BaseFederateAmbassador,
+} from "./federate-ambassador.ts";
+
+// =============================================================================
+// Types
+// =============================================================================
+export {
+  // Enums (re-exported from proto)
+  CallbackModel,
+  ResignAction,
+  OrderType,
+  SynchronizationPointFailureReason,
+  SaveFailureReason,
+  RestoreFailureReason,
+  SaveStatus,
+  RestoreStatus,
+
+  // Handle types
+  type FederateHandle,
+  type ObjectClassHandle,
+  type AttributeHandle,
+  type InteractionClassHandle,
+  type ParameterHandle,
+  type ObjectInstanceHandle,
+  type MessageRetractionHandle,
+  type TransportationTypeHandle,
+  type DimensionHandle,
+  type RegionHandle,
+
+  // Time types
+  type LogicalTime,
+  type LogicalTimeInterval,
+
+  // Handle sets
+  type FederateHandleSet,
+  type AttributeHandleSet,
+  type DimensionHandleSet,
+  type RegionHandleSet,
+  type InteractionClassHandleSet,
+
+  // Handle-value maps
+  type AttributeHandleValue,
+  type AttributeHandleValueMap,
+  type ParameterHandleValue,
+  type ParameterHandleValueMap,
+
+  // Federation info
+  type FederationExecutionInformation,
+  type FederationExecutionInformationSet,
+  type FederationExecutionMemberInformation,
+  type FederationExecutionMemberInformationSet,
+  type JoinResult,
+
+  // Save/Restore
+  type FederateRestoreStatus,
+  type FederateRestoreStatusArray,
+  type FederateHandleSaveStatusPair,
+  type FederateHandleSaveStatusPairArray,
+
+  // Time returns
+  type TimeQueryReturn,
+  type MessageRetractionReturn,
+
+  // DDM types
+  type RangeBounds,
+  type DimensionAndRange,
+  type ConveyedRegion,
+  type ConveyedRegionSet,
+  type AttributeSetRegionSetPair,
+  type AttributeSetRegionSetPairList,
+
+  // Supplemental info
+  type SupplementalReflectInfo,
+  type SupplementalReceiveInfo,
+
+  // FOM modules
+  type FomModule,
+  type FomModuleInline,
+  type FomModuleFile,
+  type FomModuleUrl,
+  type FomModuleSet,
+
+  // Configuration
+  type RtiConfiguration,
+  type ConfigurationResult,
+  type Credentials,
+  type ConnectionOptions,
+
+  // Utilities
+  type UserSuppliedTag,
+  handlesEqual,
+  handleToHex,
+  handleFromHex,
+} from "./types.ts";
+
+// =============================================================================
+// Exceptions
+// =============================================================================
+export {
+  // Base
+  RTIexception,
+  RTIinternalError,
+
+  // Connection
+  AlreadyConnected,
+  ConnectionFailed,
+  NotConnected,
+  Unauthorized,
+  InvalidCredentials,
+  UnsupportedCallbackModel,
+  CallNotAllowedFromWithinCallback,
+
+  // Federation Management
+  FederationExecutionAlreadyExists,
+  FederationExecutionDoesNotExist,
+  FederatesCurrentlyJoined,
+  FederateAlreadyExecutionMember,
+  FederateNotExecutionMember,
+  FederateIsExecutionMember,
+  FederateNameAlreadyInUse,
+  FederateOwnsAttributes,
+
+  // FOM/MIM
+  InconsistentFOM,
+  InvalidFOM,
+  CouldNotOpenFOM,
+  ErrorReadingFOM,
+  InvalidMIM,
+  CouldNotOpenMIM,
+  ErrorReadingMIM,
+  DesignatorIsHLAstandardMIM,
+
+  // Time Management
+  CouldNotCreateLogicalTimeFactory,
+  FederateUnableToUseTime,
+  InvalidLogicalTime,
+  InvalidLogicalTimeInterval,
+  InvalidLookahead,
+  LogicalTimeAlreadyPassed,
+  InTimeAdvancingState,
+  TimeConstrainedAlreadyEnabled,
+  TimeConstrainedIsNotEnabled,
+  TimeRegulationAlreadyEnabled,
+  TimeRegulationIsNotEnabled,
+  RequestForTimeConstrainedPending,
+  RequestForTimeRegulationPending,
+  IllegalTimeArithmetic,
+
+  // Save/Restore
+  SaveInProgress,
+  SaveNotInProgress,
+  SaveNotInitiated,
+  RestoreInProgress,
+  RestoreNotInProgress,
+  RestoreNotRequested,
+  FederateHasNotBegunSave,
+
+  // Object Class
+  ObjectClassNotDefined,
+  ObjectClassNotPublished,
+  InvalidObjectClassHandle,
+
+  // Object Instance
+  ObjectInstanceNotKnown,
+  ObjectInstanceNameInUse,
+  ObjectInstanceNameNotReserved,
+  InvalidObjectInstanceHandle,
+  DeletePrivilegeNotHeld,
+
+  // Attribute
+  AttributeNotDefined,
+  AttributeNotOwned,
+  AttributeNotPublished,
+  AttributeAlreadyOwned,
+  AttributeAlreadyBeingAcquired,
+  AttributeAlreadyBeingChanged,
+  AttributeAlreadyBeingDivested,
+  AttributeAcquisitionWasNotRequested,
+  AttributeDivestitureWasNotRequested,
+  InvalidAttributeHandle,
+
+  // Interaction
+  InteractionClassNotDefined,
+  InteractionClassNotPublished,
+  InteractionClassAlreadyBeingChanged,
+  InteractionParameterNotDefined,
+  InvalidInteractionClassHandle,
+  InvalidParameterHandle,
+
+  // Federate Handle
+  FederateHandleNotKnown,
+  InvalidFederateHandle,
+
+  // Ownership
+  NoAcquisitionPending,
+  OwnershipAcquisitionPending,
+
+  // Region
+  InvalidRegion,
+  InvalidRegionContext,
+  RegionNotCreatedByThisFederate,
+  RegionDoesNotContainSpecifiedDimension,
+  RegionInUseForUpdateOrSubscription,
+  InvalidDimensionHandle,
+  InvalidRangeBound,
+
+  // Message Retraction
+  InvalidMessageRetractionHandle,
+  MessageCanNoLongerBeRetracted,
+
+  // Transportation
+  InvalidTransportationName,
+  InvalidTransportationTypeHandle,
+
+  // Order
+  InvalidOrderName,
+  InvalidOrderType,
+
+  // Service/Switch
+  InvalidServiceGroup,
+  InvalidUpdateRateDesignator,
+  AsynchronousDeliveryAlreadyEnabled,
+  AsynchronousDeliveryAlreadyDisabled,
+  FederateServiceInvocationsAreBeingReportedViaMOM,
+  ReportServiceInvocationsAreSubscribed,
+
+  // Synchronization
+  SynchronizationPointLabelNotAnnounced,
+
+  // Miscellaneous
+  NameNotFound,
+  NameSetWasEmpty,
+  IllegalName,
+  InvalidResignAction,
+  CouldNotDecode,
+  CouldNotEncode,
+  FederateInternalError,
+
+  // Exception utilities
+  createException,
+  createExceptionFromProto,
+  throwException,
+  throwExceptionFromProto,
+} from "./exceptions.ts";
+
+// =============================================================================
+// Callback Dispatcher (advanced use)
+// =============================================================================
+export {
+  CallbackDispatcher,
+  type CallbackDispatchResult,
+} from "./callback-dispatcher.ts";
+
+// =============================================================================
+// Encoding Helpers
+// =============================================================================
+export {
+  encodeHLAinteger64Time,
+  decodeHLAinteger64Time,
+  encodeHLAinteger64Interval,
+  decodeHLAinteger64Interval,
+} from "./encoding.ts";
+
+// =============================================================================
+// Converters (advanced use)
+// =============================================================================
+export {
+  // Proto -> TS conversions
+  convertObjectClassHandle,
+  convertAttributeHandle,
+  convertInteractionClassHandle,
+  convertParameterHandle,
+  convertObjectInstanceHandle,
+  convertFederateHandle,
+  convertTransportationTypeHandle,
+  convertLogicalTime,
+  convertLogicalTimeInterval,
+  convertMessageRetractionHandle,
+  convertAttributeHandleSet,
+  convertFederateHandleSet,
+  convertAttributeHandleValueMap,
+  convertParameterHandleValueMap,
+  convertJoinResult,
+  convertConfigurationResult,
+
+  // TS -> Proto conversions
+  toProtoObjectClassHandle,
+  toProtoAttributeHandle,
+  toProtoInteractionClassHandle,
+  toProtoParameterHandle,
+  toProtoObjectInstanceHandle,
+  toProtoFederateHandle,
+  toProtoLogicalTime,
+  toProtoLogicalTimeInterval,
+  toProtoAttributeHandleSet,
+  toProtoFederateHandleSet,
+  toProtoAttributeHandleValueMap,
+  toProtoParameterHandleValueMap,
+} from "./converters.ts";