@hla4ts/proto 0.1.0

package/README.md

@@ -0,0 +1,237 @@
+# @hla4ts/proto
+
+**HLA 4 Federate Protocol TypeScript Types**
+
+This package contains TypeScript type definitions generated from the official IEEE 1516.1-2025 HLA 4 Federate Protocol `.proto` files. It provides type-safe interfaces for all protocol messages, enabling TypeScript federates to communicate with HLA 4 RTIs.
+
+## Overview
+
+The HLA 4 standard (IEEE 1516-2025) introduces the **Federate Protocol**, a language-neutral wire protocol that allows federates to communicate with RTIs without requiring vendor-specific native libraries. This package provides the TypeScript bindings for that protocol.
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+  participant App as Federate Code
+  participant Types as @hla4ts/proto
+  participant PB as protobufjs
+  App->>Types: Create CallRequest / CallbackRequest
+  Types->>PB: encode(...)
+  PB-->>App: Uint8Array payload
+  App->>Types: decode(bytes)
+  Types-->>App: Typed response/callback
+```
+
+### What's Included
+
+| File | Description |
+|------|-------------|
+| `datatypes.ts` | Core HLA types: handles, enums, FOM modules, credentials |
+| `RTIambassador.ts` | 178 request/response message types for RTI service calls |
+| `FederateAmbassador.ts` | 62 callback message types from RTI to federate |
+
+## Installation
+
+```bash
+bun add @hla4ts/proto
+```
+
+## Usage
+
+### Importing Types
+
+```typescript
+import {
+  // Enums
+  ResignAction,
+  OrderType,
+  CallbackModel,
+  
+  // Handle types
+  type FederateHandle,
+  type ObjectClassHandle,
+  type AttributeHandle,
+  type ObjectInstanceHandle,
+  
+  // Request/Response types
+  type JoinFederationExecutionRequest,
+  type JoinFederationExecutionResponse,
+  type CallRequest,
+  type CallResponse,
+  
+  // Callback types
+  type CallbackRequest,
+  type DiscoverObjectInstance,
+  type ReflectAttributeValues,
+  type TimeAdvanceGrant,
+} from '@hla4ts/proto';
+```
+
+### Creating Messages
+
+```typescript
+import { 
+  type JoinFederationExecutionWithNameRequest,
+  ResignAction,
+} from '@hla4ts/proto';
+
+// Create a join request
+const joinRequest: JoinFederationExecutionWithNameRequest = {
+  federateName: 'MyFederate',
+  federateType: 'SimulationType',
+  federationName: 'TestFederation',
+};
+
+// Use enums
+const resignAction = ResignAction.DELETE_OBJECTS_THEN_DIVEST;
+```
+
+### Encoding/Decoding Messages
+
+The generated types include encode/decode methods using `protobufjs`:
+
+```typescript
+import { 
+  CallRequest,
+  JoinFederationExecutionRequest,
+} from '@hla4ts/proto/rti';
+
+// Encode a message to bytes
+const request: JoinFederationExecutionRequest = {
+  federateType: 'MyType',
+  federationName: 'MyFederation',
+};
+
+const encoded: Uint8Array = JoinFederationExecutionRequest.encode(request).finish();
+
+// Decode bytes to a message
+const decoded = JoinFederationExecutionRequest.decode(encoded);
+```
+
+## Message Categories
+
+### RTI Ambassador Messages (Federate → RTI)
+
+These are service calls from the federate to the RTI:
+
+| Category | Examples |
+|----------|----------|
+| **Federation Management** | `CreateFederationExecution`, `JoinFederationExecution`, `ResignFederationExecution` |
+| **Declaration Management** | `PublishObjectClassAttributes`, `SubscribeObjectClassAttributes`, `PublishInteractionClass` |
+| **Object Management** | `RegisterObjectInstance`, `UpdateAttributeValues`, `SendInteraction`, `DeleteObjectInstance` |
+| **Time Management** | `EnableTimeRegulation`, `EnableTimeConstrained`, `TimeAdvanceRequest` |
+| **Ownership Management** | `AttributeOwnershipAcquisition`, `NegotiatedAttributeOwnershipDivestiture` |
+| **Support Services** | `GetObjectClassHandle`, `GetAttributeHandle`, `GetInteractionClassHandle` |
+
+### Federate Ambassador Callbacks (RTI → Federate)
+
+These are callbacks from the RTI to the federate:
+
+| Category | Examples |
+|----------|----------|
+| **Object Discovery** | `DiscoverObjectInstance`, `RemoveObjectInstance` |
+| **Attribute Updates** | `ReflectAttributeValues`, `ProvideAttributeValueUpdate` |
+| **Interactions** | `ReceiveInteraction`, `ReceiveDirectedInteraction` |
+| **Time Grants** | `TimeAdvanceGrant`, `TimeRegulationEnabled`, `TimeConstrainedEnabled` |
+| **Ownership** | `RequestAttributeOwnershipAssumption`, `AttributeOwnershipAcquisitionNotification` |
+| **Synchronization** | `AnnounceSynchronizationPoint`, `FederationSynchronized` |
+
+### Envelope Types
+
+All messages are wrapped in envelope types for the wire protocol:
+
+```typescript
+// RTI calls use CallRequest/CallResponse
+type CallRequest = {
+  callRequest: 
+    | { connectRequest: ConnectRequest }
+    | { joinFederationExecutionRequest: JoinFederationExecutionRequest }
+    | { updateAttributeValuesRequest: UpdateAttributeValuesRequest }
+    // ... 175 more variants
+};
+
+// Callbacks use CallbackRequest/CallbackResponse
+type CallbackRequest = {
+  callbackRequest:
+    | { discoverObjectInstance: DiscoverObjectInstance }
+    | { reflectAttributeValues: ReflectAttributeValues }
+    | { timeAdvanceGrant: TimeAdvanceGrant }
+    // ... 59 more variants
+};
+```
+
+## Key Types
+
+### Handles
+
+HLA uses opaque handles to reference objects. These are represented as byte arrays:
+
+```typescript
+interface FederateHandle { data: Uint8Array }
+interface ObjectClassHandle { data: Uint8Array }
+interface AttributeHandle { data: Uint8Array }
+interface InteractionClassHandle { data: Uint8Array }
+interface ParameterHandle { data: Uint8Array }
+interface ObjectInstanceHandle { data: Uint8Array }
+interface LogicalTime { data: Uint8Array }
+```
+
+### Enums
+
+```typescript
+enum ResignAction {
+  UNCONDITIONALLY_DIVEST_ATTRIBUTES = "UNCONDITIONALLY_DIVEST_ATTRIBUTES",
+  DELETE_OBJECTS = "DELETE_OBJECTS",
+  CANCEL_PENDING_OWNERSHIP_ACQUISITIONS = "CANCEL_PENDING_OWNERSHIP_ACQUISITIONS",
+  DELETE_OBJECTS_THEN_DIVEST = "DELETE_OBJECTS_THEN_DIVEST",
+  CANCEL_THEN_DELETE_THEN_DIVEST = "CANCEL_THEN_DELETE_THEN_DIVEST",
+  NO_ACTION = "NO_ACTION",
+}
+
+enum OrderType {
+  RECEIVE = "RECEIVE",
+  TIMESTAMP = "TIMESTAMP",
+}
+
+enum CallbackModel {
+  EVOKED = "EVOKED",
+  IMMEDIATE = "IMMEDIATE",
+}
+```
+
+## Regenerating Types
+
+If you need to regenerate the TypeScript types from updated `.proto` files:
+
+1. Place `.proto` files in `proto/` directory
+2. Ensure `protoc` is installed
+3. Run:
+
+```bash
+bun run generate
+```
+
+### Prerequisites
+
+- **protoc** (Protocol Buffer Compiler)
+  - Windows: `choco install protoc` or `scoop install protobuf`
+  - macOS: `brew install protobuf`
+  - Linux: `apt install protobuf-compiler`
+
+## Source
+
+The `.proto` files are from the IEEE 1516.1-2025 standard:
+
+```
+Reprinted with permission from IEEE 1516.1(TM)-2025
+```
+
+## Related Packages
+
+- [`@hla4ts/transport`](../transport) - Transport layer (TLS/TCP, message framing)
+- [`@hla4ts/session`](../session) - Session management
+- [`@hla4ts/hla-api`](../hla-api) - High-level HLA API facade
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@hla4ts/proto",
+  "version": "0.1.0",
+  "description": "HLA 4 Federate Protocol Protobuf definitions and generated TypeScript types",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "README.md",
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./datatypes": "./src/generated/datatypes.ts",
+    "./rti": "./src/generated/RTIambassador.ts",
+    "./federate": "./src/generated/FederateAmbassador.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "generate": "bun run scripts/generate.ts",
+    "clean": "rm -rf src/generated",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "protobufjs": "^7.2.6"
+  },
+  "devDependencies": {
+    "ts-proto": "^1.169.0",
+    "typescript": "^5.3.3"
+  }
+}