@hla4ts/session 0.1.0 → 0.1.1

package/src/types.ts

@@ -1,235 +1,235 @@
-/**
- * Session Types and State Machine
- *
- * Defines the session state machine, options, and event types for
- * the HLA 4 Federate Protocol session layer.
- */
-
-/**
- * Session states following the IEEE 1516-2025 specification.
- *
- * States can be divided into two categories:
- * - **Stable states**: NEW, RUNNING, DROPPED, TERMINATED
- * - **Transitory states**: STARTING, RESUMING, TERMINATING
- *
- * When in a transitory state, the thread that initiated the transition
- * has exclusive access to the session.
- */
-export enum SessionState {
-  /**
-   * Session instance created but not yet started.
-   * Initial state after construction.
-   */
-  NEW = "NEW",
-
-  /**
-   * Session start() has been called, establishing connection with RTI.
-   * Transitory state - caller has exclusive access.
-   */
-  STARTING = "STARTING",
-
-  /**
-   * Session is connected and running normally.
-   * HLA calls and callbacks can be exchanged.
-   */
-  RUNNING = "RUNNING",
-
-  /**
-   * Session has experienced a connection loss.
-   * Can be resumed with resume() or terminated.
-   */
-  DROPPED = "DROPPED",
-
-  /**
-   * Session is attempting to resume after a connection loss.
-   * Transitory state - caller has exclusive access.
-   */
-  RESUMING = "RESUMING",
-
-  /**
-   * Session termination has been requested.
-   * Waiting for server acknowledgment.
-   */
-  TERMINATING = "TERMINATING",
-
-  /**
-   * Session is terminated and can no longer be used.
-   * Final state - session cannot be restarted.
-   */
-  TERMINATED = "TERMINATED",
-}
-
-/**
- * Valid state transitions for the session state machine.
- * Maps from current state to array of valid next states.
- */
-export const VALID_TRANSITIONS: Record<SessionState, SessionState[]> = {
-  [SessionState.NEW]: [SessionState.STARTING],
-  [SessionState.STARTING]: [SessionState.RUNNING, SessionState.TERMINATED],
-  [SessionState.RUNNING]: [SessionState.DROPPED, SessionState.TERMINATING],
-  [SessionState.DROPPED]: [
-    SessionState.RESUMING,
-    SessionState.TERMINATING,
-    SessionState.RUNNING, // Direct transition when resume succeeds quickly
-  ],
-  [SessionState.RESUMING]: [
-    SessionState.RUNNING,
-    SessionState.DROPPED,
-    SessionState.TERMINATED,
-  ],
-  [SessionState.TERMINATING]: [SessionState.TERMINATED],
-  [SessionState.TERMINATED]: [], // Terminal state
-};
-
-/**
- * Check if a state transition is valid
- */
-export function isValidTransition(
-  from: SessionState,
-  to: SessionState
-): boolean {
-  return VALID_TRANSITIONS[from].includes(to);
-}
-
-/**
- * Check if a state allows operations (sending messages)
- */
-export function isOperationalState(state: SessionState): boolean {
-  return (
-    state === SessionState.RUNNING ||
-    state === SessionState.DROPPED ||
-    state === SessionState.RESUMING
-  );
-}
-
-/**
- * Session configuration options
- */
-export interface SessionOptions {
-  /**
-   * Timeout for initial connection response (milliseconds).
-   * @default 30000
-   */
-  connectionTimeout?: number;
-
-  /**
-   * Timeout for responses from the server (milliseconds).
-   * The session will be considered lost if no response is received within this time.
-   * @default 180000 (3 minutes)
-   */
-  responseTimeout?: number;
-
-  /**
-   * Maximum number of connection retry attempts.
-   * @default 3
-   */
-  maxRetryAttempts?: number;
-
-  /**
-   * Size of the message queue for outgoing messages.
-   * @default 1000
-   */
-  messageQueueSize?: number;
-
-  /**
-   * Enable rate limiting for outgoing messages.
-   * @default false
-   */
-  rateLimitEnabled?: boolean;
-
-  /**
-   * Interval between heartbeat checks (milliseconds).
-   * @default 10000 (10 seconds)
-   */
-  heartbeatInterval?: number;
-}
-
-/**
- * Default session options
- */
-export const DEFAULT_SESSION_OPTIONS: Required<SessionOptions> = {
-  connectionTimeout: 30000,
-  responseTimeout: 180000,
-  maxRetryAttempts: 3,
-  messageQueueSize: 1000,
-  rateLimitEnabled: false,
-  heartbeatInterval: 10000,
-};
-
-/**
- * Callback invoked when an HLA callback request is received from the RTI
- */
-export interface HlaCallbackRequestListener {
-  /**
-   * Handle an incoming HLA callback from the RTI.
-   *
-   * @param sequenceNumber - The sequence number of the callback request
-   * @param hlaCallback - The encoded callback data (protobuf CallbackRequest)
-   */
-  onHlaCallbackRequest(sequenceNumber: number, hlaCallback: Uint8Array): void;
-}
-
-/**
- * Callback invoked when the session state changes
- */
-export interface SessionStateListener {
-  /**
-   * Handle a session state transition.
-   *
-   * @param oldState - The previous session state
-   * @param newState - The new session state
-   * @param reason - Description of why the transition occurred
-   */
-  onStateTransition(
-    oldState: SessionState,
-    newState: SessionState,
-    reason: string
-  ): void;
-}
-
-/**
- * Callback invoked when a message is sent
- */
-export interface MessageSentListener {
-  /**
-   * Called when a message has been sent to the server.
-   * Can be used to implement heartbeat logic.
-   */
-  onMessageSent(): void;
-}
-
-/**
- * Session statistics
- */
-export interface SessionStats {
-  /** Total HLA calls sent */
-  hlaCallCount: number;
-  /** Total HLA callbacks received */
-  hlaCallbackCount: number;
-  /** Number of times the session was resumed */
-  resumeCount: number;
-  /** Number of messages in the call request queue */
-  callRequestQueueLength: number;
-  /** Number of messages in the callback response queue */
-  callbackResponseQueueLength: number;
-  /** Number of HLA calls awaiting response */
-  pendingRequestCount: number;
-}
-
-/**
- * New session status message payload structure
- */
-export interface NewSessionStatusPayload {
-  /** Status code (0 = success) */
-  status: number;
-}
-
-/**
- * Resume status message payload structure
- */
-export interface ResumeStatusPayload {
-  /** Status code (0 = success) */
-  status: number;
-  /** Last sequence number received by the server */
-  lastReceivedFederateSequenceNumber: number;
-}
+/**
+ * Session Types and State Machine
+ *
+ * Defines the session state machine, options, and event types for
+ * the HLA 4 Federate Protocol session layer.
+ */
+
+/**
+ * Session states following the IEEE 1516-2025 specification.
+ *
+ * States can be divided into two categories:
+ * - **Stable states**: NEW, RUNNING, DROPPED, TERMINATED
+ * - **Transitory states**: STARTING, RESUMING, TERMINATING
+ *
+ * When in a transitory state, the thread that initiated the transition
+ * has exclusive access to the session.
+ */
+export enum SessionState {
+  /**
+   * Session instance created but not yet started.
+   * Initial state after construction.
+   */
+  NEW = "NEW",
+
+  /**
+   * Session start() has been called, establishing connection with RTI.
+   * Transitory state - caller has exclusive access.
+   */
+  STARTING = "STARTING",
+
+  /**
+   * Session is connected and running normally.
+   * HLA calls and callbacks can be exchanged.
+   */
+  RUNNING = "RUNNING",
+
+  /**
+   * Session has experienced a connection loss.
+   * Can be resumed with resume() or terminated.
+   */
+  DROPPED = "DROPPED",
+
+  /**
+   * Session is attempting to resume after a connection loss.
+   * Transitory state - caller has exclusive access.
+   */
+  RESUMING = "RESUMING",
+
+  /**
+   * Session termination has been requested.
+   * Waiting for server acknowledgment.
+   */
+  TERMINATING = "TERMINATING",
+
+  /**
+   * Session is terminated and can no longer be used.
+   * Final state - session cannot be restarted.
+   */
+  TERMINATED = "TERMINATED",
+}
+
+/**
+ * Valid state transitions for the session state machine.
+ * Maps from current state to array of valid next states.
+ */
+export const VALID_TRANSITIONS: Record<SessionState, SessionState[]> = {
+  [SessionState.NEW]: [SessionState.STARTING],
+  [SessionState.STARTING]: [SessionState.RUNNING, SessionState.TERMINATED],
+  [SessionState.RUNNING]: [SessionState.DROPPED, SessionState.TERMINATING],
+  [SessionState.DROPPED]: [
+    SessionState.RESUMING,
+    SessionState.TERMINATING,
+    SessionState.RUNNING, // Direct transition when resume succeeds quickly
+  ],
+  [SessionState.RESUMING]: [
+    SessionState.RUNNING,
+    SessionState.DROPPED,
+    SessionState.TERMINATED,
+  ],
+  [SessionState.TERMINATING]: [SessionState.TERMINATED],
+  [SessionState.TERMINATED]: [], // Terminal state
+};
+
+/**
+ * Check if a state transition is valid
+ */
+export function isValidTransition(
+  from: SessionState,
+  to: SessionState
+): boolean {
+  return VALID_TRANSITIONS[from].includes(to);
+}
+
+/**
+ * Check if a state allows operations (sending messages)
+ */
+export function isOperationalState(state: SessionState): boolean {
+  return (
+    state === SessionState.RUNNING ||
+    state === SessionState.DROPPED ||
+    state === SessionState.RESUMING
+  );
+}
+
+/**
+ * Session configuration options
+ */
+export interface SessionOptions {
+  /**
+   * Timeout for initial connection response (milliseconds).
+   * @default 30000
+   */
+  connectionTimeout?: number;
+
+  /**
+   * Timeout for responses from the server (milliseconds).
+   * The session will be considered lost if no response is received within this time.
+   * @default 180000 (3 minutes)
+   */
+  responseTimeout?: number;
+
+  /**
+   * Maximum number of connection retry attempts.
+   * @default 3
+   */
+  maxRetryAttempts?: number;
+
+  /**
+   * Size of the message queue for outgoing messages.
+   * @default 1000
+   */
+  messageQueueSize?: number;
+
+  /**
+   * Enable rate limiting for outgoing messages.
+   * @default false
+   */
+  rateLimitEnabled?: boolean;
+
+  /**
+   * Interval between heartbeat checks (milliseconds).
+   * @default 10000 (10 seconds)
+   */
+  heartbeatInterval?: number;
+}
+
+/**
+ * Default session options
+ */
+export const DEFAULT_SESSION_OPTIONS: Required<SessionOptions> = {
+  connectionTimeout: 30000,
+  responseTimeout: 180000,
+  maxRetryAttempts: 3,
+  messageQueueSize: 1000,
+  rateLimitEnabled: false,
+  heartbeatInterval: 10000,
+};
+
+/**
+ * Callback invoked when an HLA callback request is received from the RTI
+ */
+export interface HlaCallbackRequestListener {
+  /**
+   * Handle an incoming HLA callback from the RTI.
+   *
+   * @param sequenceNumber - The sequence number of the callback request
+   * @param hlaCallback - The encoded callback data (protobuf CallbackRequest)
+   */
+  onHlaCallbackRequest(sequenceNumber: number, hlaCallback: Uint8Array): void;
+}
+
+/**
+ * Callback invoked when the session state changes
+ */
+export interface SessionStateListener {
+  /**
+   * Handle a session state transition.
+   *
+   * @param oldState - The previous session state
+   * @param newState - The new session state
+   * @param reason - Description of why the transition occurred
+   */
+  onStateTransition(
+    oldState: SessionState,
+    newState: SessionState,
+    reason: string
+  ): void;
+}
+
+/**
+ * Callback invoked when a message is sent
+ */
+export interface MessageSentListener {
+  /**
+   * Called when a message has been sent to the server.
+   * Can be used to implement heartbeat logic.
+   */
+  onMessageSent(): void;
+}
+
+/**
+ * Session statistics
+ */
+export interface SessionStats {
+  /** Total HLA calls sent */
+  hlaCallCount: number;
+  /** Total HLA callbacks received */
+  hlaCallbackCount: number;
+  /** Number of times the session was resumed */
+  resumeCount: number;
+  /** Number of messages in the call request queue */
+  callRequestQueueLength: number;
+  /** Number of messages in the callback response queue */
+  callbackResponseQueueLength: number;
+  /** Number of HLA calls awaiting response */
+  pendingRequestCount: number;
+}
+
+/**
+ * New session status message payload structure
+ */
+export interface NewSessionStatusPayload {
+  /** Status code (0 = success) */
+  status: number;
+}
+
+/**
+ * Resume status message payload structure
+ */
+export interface ResumeStatusPayload {
+  /** Status code (0 = success) */
+  status: number;
+  /** Last sequence number received by the server */
+  lastReceivedFederateSequenceNumber: number;
+}