@hla4ts/proto 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +237 -237
  2. package/package.json +1 -1
  3. package/src/index.ts +450 -450
package/README.md CHANGED
@@ -1,237 +1,237 @@
1
- # @hla4ts/proto
2
-
3
- **HLA 4 Federate Protocol TypeScript Types**
4
-
5
- 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.
6
-
7
- ## Overview
8
-
9
- 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.
10
-
11
- ## Sequence Diagram
12
-
13
- ```mermaid
14
- sequenceDiagram
15
- participant App as Federate Code
16
- participant Types as @hla4ts/proto
17
- participant PB as protobufjs
18
- App->>Types: Create CallRequest / CallbackRequest
19
- Types->>PB: encode(...)
20
- PB-->>App: Uint8Array payload
21
- App->>Types: decode(bytes)
22
- Types-->>App: Typed response/callback
23
- ```
24
-
25
- ### What's Included
26
-
27
- | File | Description |
28
- |------|-------------|
29
- | `datatypes.ts` | Core HLA types: handles, enums, FOM modules, credentials |
30
- | `RTIambassador.ts` | 178 request/response message types for RTI service calls |
31
- | `FederateAmbassador.ts` | 62 callback message types from RTI to federate |
32
-
33
- ## Installation
34
-
35
- ```bash
36
- bun add @hla4ts/proto
37
- ```
38
-
39
- ## Usage
40
-
41
- ### Importing Types
42
-
43
- ```typescript
44
- import {
45
- // Enums
46
- ResignAction,
47
- OrderType,
48
- CallbackModel,
49
-
50
- // Handle types
51
- type FederateHandle,
52
- type ObjectClassHandle,
53
- type AttributeHandle,
54
- type ObjectInstanceHandle,
55
-
56
- // Request/Response types
57
- type JoinFederationExecutionRequest,
58
- type JoinFederationExecutionResponse,
59
- type CallRequest,
60
- type CallResponse,
61
-
62
- // Callback types
63
- type CallbackRequest,
64
- type DiscoverObjectInstance,
65
- type ReflectAttributeValues,
66
- type TimeAdvanceGrant,
67
- } from '@hla4ts/proto';
68
- ```
69
-
70
- ### Creating Messages
71
-
72
- ```typescript
73
- import {
74
- type JoinFederationExecutionWithNameRequest,
75
- ResignAction,
76
- } from '@hla4ts/proto';
77
-
78
- // Create a join request
79
- const joinRequest: JoinFederationExecutionWithNameRequest = {
80
- federateName: 'MyFederate',
81
- federateType: 'SimulationType',
82
- federationName: 'TestFederation',
83
- };
84
-
85
- // Use enums
86
- const resignAction = ResignAction.DELETE_OBJECTS_THEN_DIVEST;
87
- ```
88
-
89
- ### Encoding/Decoding Messages
90
-
91
- The generated types include encode/decode methods using `protobufjs`:
92
-
93
- ```typescript
94
- import {
95
- CallRequest,
96
- JoinFederationExecutionRequest,
97
- } from '@hla4ts/proto/rti';
98
-
99
- // Encode a message to bytes
100
- const request: JoinFederationExecutionRequest = {
101
- federateType: 'MyType',
102
- federationName: 'MyFederation',
103
- };
104
-
105
- const encoded: Uint8Array = JoinFederationExecutionRequest.encode(request).finish();
106
-
107
- // Decode bytes to a message
108
- const decoded = JoinFederationExecutionRequest.decode(encoded);
109
- ```
110
-
111
- ## Message Categories
112
-
113
- ### RTI Ambassador Messages (Federate → RTI)
114
-
115
- These are service calls from the federate to the RTI:
116
-
117
- | Category | Examples |
118
- |----------|----------|
119
- | **Federation Management** | `CreateFederationExecution`, `JoinFederationExecution`, `ResignFederationExecution` |
120
- | **Declaration Management** | `PublishObjectClassAttributes`, `SubscribeObjectClassAttributes`, `PublishInteractionClass` |
121
- | **Object Management** | `RegisterObjectInstance`, `UpdateAttributeValues`, `SendInteraction`, `DeleteObjectInstance` |
122
- | **Time Management** | `EnableTimeRegulation`, `EnableTimeConstrained`, `TimeAdvanceRequest` |
123
- | **Ownership Management** | `AttributeOwnershipAcquisition`, `NegotiatedAttributeOwnershipDivestiture` |
124
- | **Support Services** | `GetObjectClassHandle`, `GetAttributeHandle`, `GetInteractionClassHandle` |
125
-
126
- ### Federate Ambassador Callbacks (RTI → Federate)
127
-
128
- These are callbacks from the RTI to the federate:
129
-
130
- | Category | Examples |
131
- |----------|----------|
132
- | **Object Discovery** | `DiscoverObjectInstance`, `RemoveObjectInstance` |
133
- | **Attribute Updates** | `ReflectAttributeValues`, `ProvideAttributeValueUpdate` |
134
- | **Interactions** | `ReceiveInteraction`, `ReceiveDirectedInteraction` |
135
- | **Time Grants** | `TimeAdvanceGrant`, `TimeRegulationEnabled`, `TimeConstrainedEnabled` |
136
- | **Ownership** | `RequestAttributeOwnershipAssumption`, `AttributeOwnershipAcquisitionNotification` |
137
- | **Synchronization** | `AnnounceSynchronizationPoint`, `FederationSynchronized` |
138
-
139
- ### Envelope Types
140
-
141
- All messages are wrapped in envelope types for the wire protocol:
142
-
143
- ```typescript
144
- // RTI calls use CallRequest/CallResponse
145
- type CallRequest = {
146
- callRequest:
147
- | { connectRequest: ConnectRequest }
148
- | { joinFederationExecutionRequest: JoinFederationExecutionRequest }
149
- | { updateAttributeValuesRequest: UpdateAttributeValuesRequest }
150
- // ... 175 more variants
151
- };
152
-
153
- // Callbacks use CallbackRequest/CallbackResponse
154
- type CallbackRequest = {
155
- callbackRequest:
156
- | { discoverObjectInstance: DiscoverObjectInstance }
157
- | { reflectAttributeValues: ReflectAttributeValues }
158
- | { timeAdvanceGrant: TimeAdvanceGrant }
159
- // ... 59 more variants
160
- };
161
- ```
162
-
163
- ## Key Types
164
-
165
- ### Handles
166
-
167
- HLA uses opaque handles to reference objects. These are represented as byte arrays:
168
-
169
- ```typescript
170
- interface FederateHandle { data: Uint8Array }
171
- interface ObjectClassHandle { data: Uint8Array }
172
- interface AttributeHandle { data: Uint8Array }
173
- interface InteractionClassHandle { data: Uint8Array }
174
- interface ParameterHandle { data: Uint8Array }
175
- interface ObjectInstanceHandle { data: Uint8Array }
176
- interface LogicalTime { data: Uint8Array }
177
- ```
178
-
179
- ### Enums
180
-
181
- ```typescript
182
- enum ResignAction {
183
- UNCONDITIONALLY_DIVEST_ATTRIBUTES = "UNCONDITIONALLY_DIVEST_ATTRIBUTES",
184
- DELETE_OBJECTS = "DELETE_OBJECTS",
185
- CANCEL_PENDING_OWNERSHIP_ACQUISITIONS = "CANCEL_PENDING_OWNERSHIP_ACQUISITIONS",
186
- DELETE_OBJECTS_THEN_DIVEST = "DELETE_OBJECTS_THEN_DIVEST",
187
- CANCEL_THEN_DELETE_THEN_DIVEST = "CANCEL_THEN_DELETE_THEN_DIVEST",
188
- NO_ACTION = "NO_ACTION",
189
- }
190
-
191
- enum OrderType {
192
- RECEIVE = "RECEIVE",
193
- TIMESTAMP = "TIMESTAMP",
194
- }
195
-
196
- enum CallbackModel {
197
- EVOKED = "EVOKED",
198
- IMMEDIATE = "IMMEDIATE",
199
- }
200
- ```
201
-
202
- ## Regenerating Types
203
-
204
- If you need to regenerate the TypeScript types from updated `.proto` files:
205
-
206
- 1. Place `.proto` files in `proto/` directory
207
- 2. Ensure `protoc` is installed
208
- 3. Run:
209
-
210
- ```bash
211
- bun run generate
212
- ```
213
-
214
- ### Prerequisites
215
-
216
- - **protoc** (Protocol Buffer Compiler)
217
- - Windows: `choco install protoc` or `scoop install protobuf`
218
- - macOS: `brew install protobuf`
219
- - Linux: `apt install protobuf-compiler`
220
-
221
- ## Source
222
-
223
- The `.proto` files are from the IEEE 1516.1-2025 standard:
224
-
225
- ```
226
- Reprinted with permission from IEEE 1516.1(TM)-2025
227
- ```
228
-
229
- ## Related Packages
230
-
231
- - [`@hla4ts/transport`](../transport) - Transport layer (TLS/TCP, message framing)
232
- - [`@hla4ts/session`](../session) - Session management
233
- - [`@hla4ts/hla-api`](../hla-api) - High-level HLA API facade
234
-
235
- ## License
236
-
237
- MIT
1
+ # @hla4ts/proto
2
+
3
+ **HLA 4 Federate Protocol TypeScript Types**
4
+
5
+ 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.
6
+
7
+ ## Overview
8
+
9
+ 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.
10
+
11
+ ## Sequence Diagram
12
+
13
+ ```mermaid
14
+ sequenceDiagram
15
+ participant App as Federate Code
16
+ participant Types as @hla4ts/proto
17
+ participant PB as protobufjs
18
+ App->>Types: Create CallRequest / CallbackRequest
19
+ Types->>PB: encode(...)
20
+ PB-->>App: Uint8Array payload
21
+ App->>Types: decode(bytes)
22
+ Types-->>App: Typed response/callback
23
+ ```
24
+
25
+ ### What's Included
26
+
27
+ | File | Description |
28
+ |------|-------------|
29
+ | `datatypes.ts` | Core HLA types: handles, enums, FOM modules, credentials |
30
+ | `RTIambassador.ts` | 178 request/response message types for RTI service calls |
31
+ | `FederateAmbassador.ts` | 62 callback message types from RTI to federate |
32
+
33
+ ## Installation
34
+
35
+ ```bash
36
+ bun add @hla4ts/proto
37
+ ```
38
+
39
+ ## Usage
40
+
41
+ ### Importing Types
42
+
43
+ ```typescript
44
+ import {
45
+ // Enums
46
+ ResignAction,
47
+ OrderType,
48
+ CallbackModel,
49
+
50
+ // Handle types
51
+ type FederateHandle,
52
+ type ObjectClassHandle,
53
+ type AttributeHandle,
54
+ type ObjectInstanceHandle,
55
+
56
+ // Request/Response types
57
+ type JoinFederationExecutionRequest,
58
+ type JoinFederationExecutionResponse,
59
+ type CallRequest,
60
+ type CallResponse,
61
+
62
+ // Callback types
63
+ type CallbackRequest,
64
+ type DiscoverObjectInstance,
65
+ type ReflectAttributeValues,
66
+ type TimeAdvanceGrant,
67
+ } from '@hla4ts/proto';
68
+ ```
69
+
70
+ ### Creating Messages
71
+
72
+ ```typescript
73
+ import {
74
+ type JoinFederationExecutionWithNameRequest,
75
+ ResignAction,
76
+ } from '@hla4ts/proto';
77
+
78
+ // Create a join request
79
+ const joinRequest: JoinFederationExecutionWithNameRequest = {
80
+ federateName: 'MyFederate',
81
+ federateType: 'SimulationType',
82
+ federationName: 'TestFederation',
83
+ };
84
+
85
+ // Use enums
86
+ const resignAction = ResignAction.DELETE_OBJECTS_THEN_DIVEST;
87
+ ```
88
+
89
+ ### Encoding/Decoding Messages
90
+
91
+ The generated types include encode/decode methods using `protobufjs`:
92
+
93
+ ```typescript
94
+ import {
95
+ CallRequest,
96
+ JoinFederationExecutionRequest,
97
+ } from '@hla4ts/proto/rti';
98
+
99
+ // Encode a message to bytes
100
+ const request: JoinFederationExecutionRequest = {
101
+ federateType: 'MyType',
102
+ federationName: 'MyFederation',
103
+ };
104
+
105
+ const encoded: Uint8Array = JoinFederationExecutionRequest.encode(request).finish();
106
+
107
+ // Decode bytes to a message
108
+ const decoded = JoinFederationExecutionRequest.decode(encoded);
109
+ ```
110
+
111
+ ## Message Categories
112
+
113
+ ### RTI Ambassador Messages (Federate → RTI)
114
+
115
+ These are service calls from the federate to the RTI:
116
+
117
+ | Category | Examples |
118
+ |----------|----------|
119
+ | **Federation Management** | `CreateFederationExecution`, `JoinFederationExecution`, `ResignFederationExecution` |
120
+ | **Declaration Management** | `PublishObjectClassAttributes`, `SubscribeObjectClassAttributes`, `PublishInteractionClass` |
121
+ | **Object Management** | `RegisterObjectInstance`, `UpdateAttributeValues`, `SendInteraction`, `DeleteObjectInstance` |
122
+ | **Time Management** | `EnableTimeRegulation`, `EnableTimeConstrained`, `TimeAdvanceRequest` |
123
+ | **Ownership Management** | `AttributeOwnershipAcquisition`, `NegotiatedAttributeOwnershipDivestiture` |
124
+ | **Support Services** | `GetObjectClassHandle`, `GetAttributeHandle`, `GetInteractionClassHandle` |
125
+
126
+ ### Federate Ambassador Callbacks (RTI → Federate)
127
+
128
+ These are callbacks from the RTI to the federate:
129
+
130
+ | Category | Examples |
131
+ |----------|----------|
132
+ | **Object Discovery** | `DiscoverObjectInstance`, `RemoveObjectInstance` |
133
+ | **Attribute Updates** | `ReflectAttributeValues`, `ProvideAttributeValueUpdate` |
134
+ | **Interactions** | `ReceiveInteraction`, `ReceiveDirectedInteraction` |
135
+ | **Time Grants** | `TimeAdvanceGrant`, `TimeRegulationEnabled`, `TimeConstrainedEnabled` |
136
+ | **Ownership** | `RequestAttributeOwnershipAssumption`, `AttributeOwnershipAcquisitionNotification` |
137
+ | **Synchronization** | `AnnounceSynchronizationPoint`, `FederationSynchronized` |
138
+
139
+ ### Envelope Types
140
+
141
+ All messages are wrapped in envelope types for the wire protocol:
142
+
143
+ ```typescript
144
+ // RTI calls use CallRequest/CallResponse
145
+ type CallRequest = {
146
+ callRequest:
147
+ | { connectRequest: ConnectRequest }
148
+ | { joinFederationExecutionRequest: JoinFederationExecutionRequest }
149
+ | { updateAttributeValuesRequest: UpdateAttributeValuesRequest }
150
+ // ... 175 more variants
151
+ };
152
+
153
+ // Callbacks use CallbackRequest/CallbackResponse
154
+ type CallbackRequest = {
155
+ callbackRequest:
156
+ | { discoverObjectInstance: DiscoverObjectInstance }
157
+ | { reflectAttributeValues: ReflectAttributeValues }
158
+ | { timeAdvanceGrant: TimeAdvanceGrant }
159
+ // ... 59 more variants
160
+ };
161
+ ```
162
+
163
+ ## Key Types
164
+
165
+ ### Handles
166
+
167
+ HLA uses opaque handles to reference objects. These are represented as byte arrays:
168
+
169
+ ```typescript
170
+ interface FederateHandle { data: Uint8Array }
171
+ interface ObjectClassHandle { data: Uint8Array }
172
+ interface AttributeHandle { data: Uint8Array }
173
+ interface InteractionClassHandle { data: Uint8Array }
174
+ interface ParameterHandle { data: Uint8Array }
175
+ interface ObjectInstanceHandle { data: Uint8Array }
176
+ interface LogicalTime { data: Uint8Array }
177
+ ```
178
+
179
+ ### Enums
180
+
181
+ ```typescript
182
+ enum ResignAction {
183
+ UNCONDITIONALLY_DIVEST_ATTRIBUTES = "UNCONDITIONALLY_DIVEST_ATTRIBUTES",
184
+ DELETE_OBJECTS = "DELETE_OBJECTS",
185
+ CANCEL_PENDING_OWNERSHIP_ACQUISITIONS = "CANCEL_PENDING_OWNERSHIP_ACQUISITIONS",
186
+ DELETE_OBJECTS_THEN_DIVEST = "DELETE_OBJECTS_THEN_DIVEST",
187
+ CANCEL_THEN_DELETE_THEN_DIVEST = "CANCEL_THEN_DELETE_THEN_DIVEST",
188
+ NO_ACTION = "NO_ACTION",
189
+ }
190
+
191
+ enum OrderType {
192
+ RECEIVE = "RECEIVE",
193
+ TIMESTAMP = "TIMESTAMP",
194
+ }
195
+
196
+ enum CallbackModel {
197
+ EVOKED = "EVOKED",
198
+ IMMEDIATE = "IMMEDIATE",
199
+ }
200
+ ```
201
+
202
+ ## Regenerating Types
203
+
204
+ If you need to regenerate the TypeScript types from updated `.proto` files:
205
+
206
+ 1. Place `.proto` files in `proto/` directory
207
+ 2. Ensure `protoc` is installed
208
+ 3. Run:
209
+
210
+ ```bash
211
+ bun run generate
212
+ ```
213
+
214
+ ### Prerequisites
215
+
216
+ - **protoc** (Protocol Buffer Compiler)
217
+ - Windows: `choco install protoc` or `scoop install protobuf`
218
+ - macOS: `brew install protobuf`
219
+ - Linux: `apt install protobuf-compiler`
220
+
221
+ ## Source
222
+
223
+ The `.proto` files are from the IEEE 1516.1-2025 standard:
224
+
225
+ ```
226
+ Reprinted with permission from IEEE 1516.1(TM)-2025
227
+ ```
228
+
229
+ ## Related Packages
230
+
231
+ - [`@hla4ts/transport`](../transport) - Transport layer (TLS/TCP, message framing)
232
+ - [`@hla4ts/session`](../session) - Session management
233
+ - [`@hla4ts/hla-api`](../hla-api) - High-level HLA API facade
234
+
235
+ ## License
236
+
237
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hla4ts/proto",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "HLA 4 Federate Protocol Protobuf definitions and generated TypeScript types",
5
5
  "type": "module",
6
6
  "main": "src/index.ts",