@hla4ts/spacekit 0.1.0

package/src/declarative-runtime.ts

@@ -0,0 +1,541 @@
+import type {
+  AttributeHandle,
+  AttributeHandleValueMap,
+  ConveyedRegionSet,
+  FederateHandle,
+  InteractionClassHandle,
+  LogicalTime,
+  MessageRetractionHandle,
+  ObjectClassHandle,
+  ObjectInstanceHandle,
+  OrderType,
+  ParameterHandleValueMap,
+  RTIAmbassador,
+  TransportationTypeHandle,
+  UserSuppliedTag,
+} from "@hla4ts/hla-api";
+import { handleToHex } from "@hla4ts/hla-api";
+import type { SharingType } from "@hla4ts/fom-codegen";
+import type { DeclarativeFom, DeclarativeObjectClass } from "./declarative.ts";
+import { InteractionClassAdapter, ObjectClassAdapter, ObjectInstanceAdapter } from "./object-model.ts";
+import type { FederateHandlers } from "./types.ts";
+
+export interface DeclarativeRuntimeOptions {
+  autoPublish?: boolean;
+  autoSubscribe?: boolean;
+  defaultInteractionSharing?: SharingType;
+}
+
+export interface DeclarativePublicationSummary {
+  objectClasses: {
+    publish: string[];
+    subscribe: string[];
+  };
+  interactions: {
+    publish: string[];
+    subscribe: string[];
+  };
+}
+
+export interface DeclarativeObjectDiscoverContext<T extends object> {
+  instance: ObjectInstanceAdapter<T>;
+  objectClass: ObjectClassHandle;
+  objectInstanceName: string;
+  producingFederate: FederateHandle;
+}
+
+export interface DeclarativeObjectUpdateContext<T extends object> {
+  instance: ObjectInstanceAdapter<T>;
+  values: Partial<T>;
+  rawValues: AttributeHandleValueMap;
+  userSuppliedTag: UserSuppliedTag;
+  transportationType?: TransportationTypeHandle;
+  producingFederate: FederateHandle;
+  sentRegions?: ConveyedRegionSet;
+  time?: LogicalTime;
+  sentOrderType?: OrderType;
+  receivedOrderType?: OrderType;
+  retractionHandle?: MessageRetractionHandle;
+}
+
+export interface DeclarativeObjectRemoveContext<T extends object> {
+  instance: ObjectInstanceAdapter<T>;
+  userSuppliedTag: UserSuppliedTag;
+  producingFederate: FederateHandle;
+  time?: LogicalTime;
+  sentOrderType?: OrderType;
+  receivedOrderType?: OrderType;
+  retractionHandle?: MessageRetractionHandle;
+}
+
+export interface DeclarativeInteractionContext<T extends object> {
+  interactionClass: InteractionClassHandle;
+  values: Partial<T>;
+  rawValues: ParameterHandleValueMap;
+  userSuppliedTag: UserSuppliedTag;
+  transportationType?: TransportationTypeHandle;
+  producingFederate: FederateHandle;
+  sentRegions?: ConveyedRegionSet;
+  time?: LogicalTime;
+  sentOrderType?: OrderType;
+  receivedOrderType?: OrderType;
+  retractionHandle?: MessageRetractionHandle;
+}
+
+export interface DeclarativeObjectHandlers<T extends object> {
+  discover?: (context: DeclarativeObjectDiscoverContext<T>) => void;
+  update?: (context: DeclarativeObjectUpdateContext<T>) => void;
+  remove?: (context: DeclarativeObjectRemoveContext<T>) => void;
+}
+
+export interface DeclarativeInteractionHandlers<T extends object> {
+  receive?: (context: DeclarativeInteractionContext<T>) => void;
+}
+
+const DEFAULT_INTERACTION_SHARING: SharingType = "PublishSubscribe";
+
+function canPublish(sharing?: SharingType, defaultSharing: SharingType = DEFAULT_INTERACTION_SHARING): boolean {
+  const resolved = sharing ?? defaultSharing;
+  return resolved === "Publish" || resolved === "PublishSubscribe";
+}
+
+function canSubscribe(sharing?: SharingType, defaultSharing: SharingType = DEFAULT_INTERACTION_SHARING): boolean {
+  const resolved = sharing ?? defaultSharing;
+  return resolved === "Subscribe" || resolved === "PublishSubscribe";
+}
+
+export class DeclarativeRuntime {
+  readonly handlers: FederateHandlers;
+  private readonly _fom: DeclarativeFom;
+  private readonly _options: Required<DeclarativeRuntimeOptions>;
+  private readonly _objectHandlers = new Map<
+    string,
+    Array<DeclarativeObjectHandlers<Record<string, unknown>>>
+  >();
+  private readonly _interactionHandlers = new Map<
+    string,
+    Array<DeclarativeInteractionHandlers<Record<string, unknown>>>
+  >();
+  private readonly _objectInstances = new Map<string, ObjectInstanceAdapter<Record<string, unknown>>>();
+  private readonly _objectClassByHandle = new Map<string, string>();
+  private readonly _interactionClassByHandle = new Map<string, string>();
+
+  constructor(fom: DeclarativeFom, options: DeclarativeRuntimeOptions = {}) {
+    this._fom = fom;
+    this._options = {
+      autoPublish: options.autoPublish ?? true,
+      autoSubscribe: options.autoSubscribe ?? true,
+      defaultInteractionSharing: options.defaultInteractionSharing ?? DEFAULT_INTERACTION_SHARING,
+    };
+
+    this.handlers = {
+      discoverObjectInstance: (objectInstance, objectClass, objectInstanceName, producingFederate) => {
+        const className = this._objectClassByHandle.get(handleToHex(objectClass));
+        if (!className) return;
+        const adapter = this._fom.getObjectAdapter<Record<string, unknown>>(className);
+        if (!adapter) return;
+        const key = handleToHex(objectInstance);
+        const existing = this._objectInstances.get(key);
+        const instance =
+          existing ?? new ObjectInstanceAdapter<Record<string, unknown>>(adapter, objectInstance);
+        instance.objectInstanceName = objectInstanceName;
+        this._objectInstances.set(key, instance);
+        const handlers = this._objectHandlers.get(className);
+        if (!handlers) return;
+        for (const handler of handlers) {
+          handler.discover?.({
+            instance: instance as ObjectInstanceAdapter<Record<string, unknown>>,
+            objectClass,
+            objectInstanceName,
+            producingFederate,
+          });
+        }
+      },
+      reflectAttributeValues: (
+        objectInstance,
+        attributeValues,
+        userSuppliedTag,
+        transportationType,
+        producingFederate,
+        sentRegions
+      ) => {
+        this._handleAttributeUpdate({
+          objectInstance,
+          attributeValues,
+          userSuppliedTag,
+          transportationType,
+          producingFederate,
+          sentRegions,
+        });
+      },
+      reflectAttributeValuesWithTime: (
+        objectInstance,
+        attributeValues,
+        userSuppliedTag,
+        transportationType,
+        producingFederate,
+        sentRegions,
+        time,
+        sentOrderType,
+        receivedOrderType,
+        retractionHandle
+      ) => {
+        this._handleAttributeUpdate({
+          objectInstance,
+          attributeValues,
+          userSuppliedTag,
+          transportationType,
+          producingFederate,
+          sentRegions,
+          time,
+          sentOrderType,
+          receivedOrderType,
+          retractionHandle,
+        });
+      },
+      removeObjectInstance: (objectInstance, userSuppliedTag, producingFederate) => {
+        this._handleObjectRemoval({
+          objectInstance,
+          userSuppliedTag,
+          producingFederate,
+        });
+      },
+      removeObjectInstanceWithTime: (
+        objectInstance,
+        userSuppliedTag,
+        producingFederate,
+        time,
+        sentOrderType,
+        receivedOrderType,
+        retractionHandle
+      ) => {
+        this._handleObjectRemoval({
+          objectInstance,
+          userSuppliedTag,
+          producingFederate,
+          time,
+          sentOrderType,
+          receivedOrderType,
+          retractionHandle,
+        });
+      },
+      receiveInteraction: (
+        interactionClass,
+        parameterValues,
+        userSuppliedTag,
+        transportationType,
+        producingFederate,
+        sentRegions
+      ) => {
+        this._handleInteraction({
+          interactionClass,
+          parameterValues,
+          userSuppliedTag,
+          transportationType,
+          producingFederate,
+          sentRegions,
+        });
+      },
+      receiveInteractionWithTime: (
+        interactionClass,
+        parameterValues,
+        userSuppliedTag,
+        transportationType,
+        producingFederate,
+        sentRegions,
+        time,
+        sentOrderType,
+        receivedOrderType,
+        retractionHandle
+      ) => {
+        this._handleInteraction({
+          interactionClass,
+          parameterValues,
+          userSuppliedTag,
+          transportationType,
+          producingFederate,
+          sentRegions,
+          time,
+          sentOrderType,
+          receivedOrderType,
+          retractionHandle,
+        });
+      },
+    };
+  }
+
+  registerObjectHandlers<T extends object>(
+    adapter: ObjectClassAdapter<T>,
+    handlers: DeclarativeObjectHandlers<T>
+  ): void {
+    this._objectHandlers.set(adapter.className, [
+      handlers as DeclarativeObjectHandlers<Record<string, unknown>>,
+    ]);
+  }
+
+  registerInteractionHandlers<T extends object>(
+    adapter: InteractionClassAdapter<T>,
+    handlers: DeclarativeInteractionHandlers<T>
+  ): void {
+    this._interactionHandlers.set(adapter.className, [
+      handlers as DeclarativeInteractionHandlers<Record<string, unknown>>,
+    ]);
+  }
+
+  addObjectHandlers<T extends object>(
+    adapter: ObjectClassAdapter<T>,
+    handlers: DeclarativeObjectHandlers<T>
+  ): void {
+    const existing = this._objectHandlers.get(adapter.className) ?? [];
+    existing.push(handlers as DeclarativeObjectHandlers<Record<string, unknown>>);
+    this._objectHandlers.set(adapter.className, existing);
+  }
+
+  addInteractionHandlers<T extends object>(
+    adapter: InteractionClassAdapter<T>,
+    handlers: DeclarativeInteractionHandlers<T>
+  ): void {
+    const existing = this._interactionHandlers.get(adapter.className) ?? [];
+    existing.push(handlers as DeclarativeInteractionHandlers<Record<string, unknown>>);
+    this._interactionHandlers.set(adapter.className, existing);
+  }
+
+  getObjectInstance<T extends object>(
+    objectInstance: ObjectInstanceHandle
+  ): ObjectInstanceAdapter<T> | undefined {
+    return this._objectInstances.get(handleToHex(objectInstance)) as
+      | ObjectInstanceAdapter<T>
+      | undefined;
+  }
+
+  async resolve(rti: RTIAmbassador): Promise<void> {
+    await this._fom.resolveAll(rti);
+    this._refreshHandleMaps();
+  }
+
+  async publish(rti: RTIAmbassador): Promise<void> {
+    for (const [name, adapter] of this._fom.objectAdapters) {
+      const schema = this._fom.getObjectSchema<Record<string, unknown>>(name);
+      if (!schema) continue;
+      if (!adapter.isResolved) {
+        await adapter.resolve(rti);
+      }
+      const handles = collectAttributeHandles(schema, adapter, (sharing) =>
+        canPublish(sharing)
+      );
+      if (handles.length === 0) continue;
+      await rti.publishObjectClassAttributes(adapter.classHandle, handles);
+    }
+
+    for (const [name, adapter] of this._fom.interactionAdapters) {
+      const schema = this._fom.getInteractionSchema<Record<string, unknown>>(name);
+      if (!schema) continue;
+      if (!adapter.isResolved) {
+        await adapter.resolve(rti);
+      }
+      if (!canPublish(schema.sharing, this._options.defaultInteractionSharing)) continue;
+      await rti.publishInteractionClass(adapter.interactionHandle);
+    }
+    this._refreshHandleMaps();
+  }
+
+  async subscribe(rti: RTIAmbassador): Promise<void> {
+    for (const [name, adapter] of this._fom.objectAdapters) {
+      const schema = this._fom.getObjectSchema<Record<string, unknown>>(name);
+      if (!schema) continue;
+      if (!adapter.isResolved) {
+        await adapter.resolve(rti);
+      }
+      const handles = collectAttributeHandles(schema, adapter, (sharing) =>
+        canSubscribe(sharing)
+      );
+      if (handles.length === 0) continue;
+      await rti.subscribeObjectClassAttributes(adapter.classHandle, handles);
+    }
+
+    for (const [name, adapter] of this._fom.interactionAdapters) {
+      const schema = this._fom.getInteractionSchema<Record<string, unknown>>(name);
+      if (!schema) continue;
+      if (!adapter.isResolved) {
+        await adapter.resolve(rti);
+      }
+      if (!canSubscribe(schema.sharing, this._options.defaultInteractionSharing)) continue;
+      await rti.subscribeInteractionClass(adapter.interactionHandle);
+    }
+    this._refreshHandleMaps();
+  }
+
+  async prepare(rti: RTIAmbassador): Promise<void> {
+    await this.resolve(rti);
+    if (this._options.autoPublish) {
+      await this.publish(rti);
+    }
+    if (this._options.autoSubscribe) {
+      await this.subscribe(rti);
+    }
+  }
+
+  getPublicationSummary(): DeclarativePublicationSummary {
+    const objectPublish: string[] = [];
+    const objectSubscribe: string[] = [];
+    const interactionPublish: string[] = [];
+    const interactionSubscribe: string[] = [];
+
+    for (const [name] of this._fom.objectAdapters) {
+      const schema = this._fom.getObjectSchema<Record<string, unknown>>(name);
+      if (!schema) continue;
+      const attributes = Object.values(schema.attributes ?? {});
+      const canPub = attributes.some((attribute) => canPublish(attribute.sharing));
+      const canSub = attributes.some((attribute) => canSubscribe(attribute.sharing));
+      if (canPub) objectPublish.push(name);
+      if (canSub) objectSubscribe.push(name);
+    }
+
+    for (const [name] of this._fom.interactionAdapters) {
+      const schema = this._fom.getInteractionSchema<Record<string, unknown>>(name);
+      if (!schema) continue;
+      if (canPublish(schema.sharing, this._options.defaultInteractionSharing)) {
+        interactionPublish.push(name);
+      }
+      if (canSubscribe(schema.sharing, this._options.defaultInteractionSharing)) {
+        interactionSubscribe.push(name);
+      }
+    }
+
+    return {
+      objectClasses: { publish: objectPublish, subscribe: objectSubscribe },
+      interactions: { publish: interactionPublish, subscribe: interactionSubscribe },
+    };
+  }
+
+  private _refreshHandleMaps(): void {
+    this._objectClassByHandle.clear();
+    this._interactionClassByHandle.clear();
+
+    for (const [name, adapter] of this._fom.objectAdapters) {
+      if (!adapter.isResolved) continue;
+      this._objectClassByHandle.set(handleToHex(adapter.classHandle), name);
+    }
+    for (const [name, adapter] of this._fom.interactionAdapters) {
+      if (!adapter.isResolved) continue;
+      this._interactionClassByHandle.set(handleToHex(adapter.interactionHandle), name);
+    }
+  }
+
+  private _handleAttributeUpdate(params: {
+    objectInstance: ObjectInstanceHandle;
+    attributeValues: AttributeHandleValueMap;
+    userSuppliedTag: UserSuppliedTag;
+    transportationType?: TransportationTypeHandle;
+    producingFederate: FederateHandle;
+    sentRegions?: ConveyedRegionSet;
+    time?: LogicalTime;
+    sentOrderType?: OrderType;
+    receivedOrderType?: OrderType;
+    retractionHandle?: MessageRetractionHandle;
+  }): void {
+    const key = handleToHex(params.objectInstance);
+    const instance = this._objectInstances.get(key);
+    if (!instance) return;
+    const adapter = instance.objectClass;
+    const values = adapter.decode(params.attributeValues);
+    const handlers = this._objectHandlers.get(adapter.className);
+    if (!handlers) return;
+    for (const handler of handlers) {
+      handler.update?.({
+        instance: instance as ObjectInstanceAdapter<Record<string, unknown>>,
+        values: values as Partial<Record<string, unknown>>,
+        rawValues: params.attributeValues,
+        userSuppliedTag: params.userSuppliedTag,
+        transportationType: params.transportationType,
+        producingFederate: params.producingFederate,
+        sentRegions: params.sentRegions,
+        time: params.time,
+        sentOrderType: params.sentOrderType,
+        receivedOrderType: params.receivedOrderType,
+        retractionHandle: params.retractionHandle,
+      });
+    }
+  }
+
+  private _handleObjectRemoval(params: {
+    objectInstance: ObjectInstanceHandle;
+    userSuppliedTag: UserSuppliedTag;
+    producingFederate: FederateHandle;
+    time?: LogicalTime;
+    sentOrderType?: OrderType;
+    receivedOrderType?: OrderType;
+    retractionHandle?: MessageRetractionHandle;
+  }): void {
+    const key = handleToHex(params.objectInstance);
+    const instance = this._objectInstances.get(key);
+    if (!instance) return;
+    const handlers = this._objectHandlers.get(instance.className);
+    if (handlers) {
+      for (const handler of handlers) {
+        handler.remove?.({
+          instance: instance as ObjectInstanceAdapter<Record<string, unknown>>,
+          userSuppliedTag: params.userSuppliedTag,
+          producingFederate: params.producingFederate,
+          time: params.time,
+          sentOrderType: params.sentOrderType,
+          receivedOrderType: params.receivedOrderType,
+          retractionHandle: params.retractionHandle,
+        });
+      }
+    }
+    this._objectInstances.delete(key);
+  }
+
+  private _handleInteraction(params: {
+    interactionClass: InteractionClassHandle;
+    parameterValues: ParameterHandleValueMap;
+    userSuppliedTag: UserSuppliedTag;
+    transportationType?: TransportationTypeHandle;
+    producingFederate: FederateHandle;
+    sentRegions?: ConveyedRegionSet;
+    time?: LogicalTime;
+    sentOrderType?: OrderType;
+    receivedOrderType?: OrderType;
+    retractionHandle?: MessageRetractionHandle;
+  }): void {
+    const className = this._interactionClassByHandle.get(handleToHex(params.interactionClass));
+    if (!className) return;
+    const adapter = this._fom.getInteractionAdapter<Record<string, unknown>>(className);
+    if (!adapter) return;
+    const values = adapter.decode(params.parameterValues);
+    const handlers = this._interactionHandlers.get(className);
+    if (!handlers) return;
+    for (const handler of handlers) {
+      handler.receive?.({
+        interactionClass: params.interactionClass,
+        values: values as Partial<Record<string, unknown>>,
+        rawValues: params.parameterValues,
+        userSuppliedTag: params.userSuppliedTag,
+        transportationType: params.transportationType,
+        producingFederate: params.producingFederate,
+        sentRegions: params.sentRegions,
+        time: params.time,
+        sentOrderType: params.sentOrderType,
+        receivedOrderType: params.receivedOrderType,
+        retractionHandle: params.retractionHandle,
+      });
+    }
+  }
+}
+
+function collectAttributeHandles<T extends object>(
+  schema: DeclarativeObjectClass<T>,
+  adapter: ObjectClassAdapter<T>,
+  predicate: (sharing: SharingType) => boolean
+): AttributeHandle[] {
+  const handles: AttributeHandle[] = [];
+  const entries = Object.entries(schema.attributes) as Array<
+    [keyof T & string, DeclarativeObjectClass<T>["attributes"][keyof T]]
+  >;
+  for (const [key, attribute] of entries) {
+    if (!predicate(attribute.sharing)) continue;
+    handles.push(adapter.getAttributeHandle(key));
+  }
+  return handles;
+}

package/src/declarative.test.ts

@@ -0,0 +1,49 @@
+import { expect, test } from "bun:test";
+import { DeclarativeFom } from "./declarative.ts";
+
+test("DeclarativeFom registers object and interaction schemas", () => {
+  const declarative = new DeclarativeFom();
+
+  declarative.defineObjectClass<{ name: string }>({
+    name: "HLAobjectRoot.TestEntity",
+    sharing: "PublishSubscribe",
+    attributes: {
+      name: {
+        name: "name",
+        dataType: "HLAunicodeString",
+        updateType: "Static",
+        updateCondition: "during initialization",
+        ownership: "NoTransfer",
+        sharing: "PublishSubscribe",
+        transportation: "HLAreliable",
+        order: "TimeStamp",
+        encode: (value) => new TextEncoder().encode(value),
+      },
+    },
+  });
+
+  declarative.defineInteractionClass<{ count: number }>({
+    name: "HLAinteractionRoot.TestInteraction",
+    sharing: "PublishSubscribe",
+    transportation: "HLAreliable",
+    order: "Receive",
+    parameters: {
+      count: {
+        name: "count",
+        dataType: "HLAinteger32BE",
+        encode: (value) => {
+          const buffer = new ArrayBuffer(4);
+          const view = new DataView(buffer);
+          view.setInt32(0, value, false);
+          return new Uint8Array(buffer);
+        },
+      },
+    },
+  });
+
+  const model = declarative.registry.buildModel();
+  expect(model.objectClasses[0]?.name).toBe("HLAobjectRoot.TestEntity");
+  expect(model.objectClasses[0]?.attributes?.[0]?.name).toBe("name");
+  expect(model.interactionClasses[0]?.name).toBe("HLAinteractionRoot.TestInteraction");
+  expect(model.interactionClasses[0]?.parameters?.[0]?.name).toBe("count");
+});