@hla4ts/spacekit 0.1.0

package/src/object-model.ts

@@ -0,0 +1,275 @@
+import type {
+  AttributeHandle,
+  AttributeHandleValueMap,
+  InteractionClassHandle,
+  LogicalTime,
+  MessageRetractionReturn,
+  ObjectClassHandle,
+  ObjectInstanceHandle,
+  ParameterHandle,
+  ParameterHandleValueMap,
+  RTIAmbassador,
+  UserSuppliedTag,
+} from "@hla4ts/hla-api";
+import { handleToHex } from "@hla4ts/hla-api";
+
+export interface AttributeSpec<T> {
+  name: string;
+  encode: (value: T) => Uint8Array;
+  decode?: (data: Uint8Array) => T;
+}
+
+export type AttributeSpecMap<T extends object> = {
+  [K in keyof T]: AttributeSpec<T[K]>;
+};
+
+export class ObjectClassAdapter<T extends object> {
+  private _classHandle: ObjectClassHandle | null = null;
+  private readonly _attributeKeys: Array<keyof T & string>;
+  private readonly _attributeHandles = new Map<keyof T & string, AttributeHandle>();
+  private readonly _attributeNamesByHandle = new Map<string, keyof T & string>();
+
+  constructor(
+    public readonly className: string,
+    public readonly attributes: AttributeSpecMap<T>
+  ) {
+    this._attributeKeys = Object.keys(attributes) as Array<keyof T & string>;
+  }
+
+  get isResolved(): boolean {
+    return this._classHandle !== null;
+  }
+
+  get classHandle(): ObjectClassHandle {
+    if (!this._classHandle) {
+      throw new Error(`ObjectClassAdapter(${this.className}) is not resolved.`);
+    }
+    return this._classHandle;
+  }
+
+  get attributeHandleSet(): AttributeHandle[] {
+    return Array.from(this._attributeHandles.values());
+  }
+
+  getAttributeHandle(name: keyof T & string): AttributeHandle {
+    const handle = this._attributeHandles.get(name);
+    if (!handle) {
+      throw new Error(`Attribute handle not resolved: ${String(name)}`);
+    }
+    return handle;
+  }
+
+  async resolve(rti: RTIAmbassador): Promise<void> {
+    this._classHandle = await rti.getObjectClassHandle(this.className);
+    this._attributeHandles.clear();
+    this._attributeNamesByHandle.clear();
+
+    for (const key of this._attributeKeys) {
+      const spec = this.attributes[key];
+      const handle = await rti.getAttributeHandle(this._classHandle, spec.name);
+      this._attributeHandles.set(key, handle);
+      this._attributeNamesByHandle.set(handleToHex(handle), key);
+    }
+  }
+
+  async publish(rti: RTIAmbassador): Promise<void> {
+    await rti.publishObjectClassAttributes(this.classHandle, this.attributeHandleSet);
+  }
+
+  async subscribe(rti: RTIAmbassador): Promise<void> {
+    await rti.subscribeObjectClassAttributes(this.classHandle, this.attributeHandleSet);
+  }
+
+  async registerInstance(
+    rti: RTIAmbassador,
+    name?: string
+  ): Promise<ObjectInstanceAdapter<T>> {
+    const objectInstance = name
+      ? await rti.registerObjectInstanceWithName(this.classHandle, name)
+      : await rti.registerObjectInstance(this.classHandle);
+    return new ObjectInstanceAdapter<T>(this, objectInstance, name);
+  }
+
+  encode(values: Partial<T>): AttributeHandleValueMap {
+    if (!this._classHandle) {
+      throw new Error(`ObjectClassAdapter(${this.className}) is not resolved.`);
+    }
+    const entries: AttributeHandleValueMap = [];
+    for (const key of this._attributeKeys) {
+      if (!(key in values)) continue;
+      const value = values[key];
+      if (value === undefined) continue;
+      const spec = this.attributes[key];
+      const handle = this._attributeHandles.get(key);
+      if (!handle) {
+        throw new Error(`Attribute handle not resolved: ${String(key)}`);
+      }
+      entries.push({ attributeHandle: handle, value: spec.encode(value) });
+    }
+    return entries;
+  }
+
+  decode(values: AttributeHandleValueMap): Partial<T> {
+    const result: Partial<T> = {};
+    for (const entry of values) {
+      const key = this._attributeNamesByHandle.get(handleToHex(entry.attributeHandle));
+      if (!key) continue;
+      const spec = this.attributes[key];
+      if (!spec.decode) continue;
+      result[key] = spec.decode(entry.value);
+    }
+    return result;
+  }
+}
+
+export class ObjectInstanceAdapter<T extends object> {
+  constructor(
+    public readonly objectClass: ObjectClassAdapter<T>,
+    public readonly objectInstance: ObjectInstanceHandle,
+    public objectInstanceName?: string
+  ) {}
+
+  get className(): string {
+    return this.objectClass.className;
+  }
+
+  encode(values: Partial<T>): AttributeHandleValueMap {
+    return this.objectClass.encode(values);
+  }
+
+  decode(values: AttributeHandleValueMap): Partial<T> {
+    return this.objectClass.decode(values);
+  }
+
+  async updateAttributes(
+    rti: RTIAmbassador,
+    values: Partial<T>,
+    userSuppliedTag: UserSuppliedTag = new Uint8Array(),
+    time?: LogicalTime
+  ): Promise<MessageRetractionReturn | void> {
+    const payload = this.objectClass.encode(values);
+    if (time) {
+      return rti.updateAttributeValuesWithTime(
+        this.objectInstance,
+        payload,
+        userSuppliedTag,
+        time
+      );
+    }
+    await rti.updateAttributeValues(this.objectInstance, payload, userSuppliedTag);
+    return undefined;
+  }
+
+  async deleteInstance(
+    rti: RTIAmbassador,
+    userSuppliedTag: UserSuppliedTag = new Uint8Array(),
+    time?: LogicalTime
+  ): Promise<MessageRetractionReturn | void> {
+    if (time) {
+      return rti.deleteObjectInstanceWithTime(this.objectInstance, userSuppliedTag, time);
+    }
+    await rti.deleteObjectInstance(this.objectInstance, userSuppliedTag);
+    return undefined;
+  }
+}
+
+export interface ParameterSpec<T> {
+  name: string;
+  encode: (value: T) => Uint8Array;
+  decode?: (data: Uint8Array) => T;
+}
+
+export type ParameterSpecMap<T extends object> = {
+  [K in keyof T]: ParameterSpec<T[K]>;
+};
+
+export class InteractionClassAdapter<T extends object> {
+  private _interactionHandle: InteractionClassHandle | null = null;
+  private readonly _parameterKeys: Array<keyof T & string>;
+  private readonly _parameterHandles = new Map<keyof T & string, ParameterHandle>();
+  private readonly _parameterNamesByHandle = new Map<string, keyof T & string>();
+
+  constructor(
+    public readonly className: string,
+    public readonly parameters: ParameterSpecMap<T>
+  ) {
+    this._parameterKeys = Object.keys(parameters) as Array<keyof T & string>;
+  }
+
+  get isResolved(): boolean {
+    return this._interactionHandle !== null;
+  }
+
+  get interactionHandle(): InteractionClassHandle {
+    if (!this._interactionHandle) {
+      throw new Error(`InteractionClassAdapter(${this.className}) is not resolved.`);
+    }
+    return this._interactionHandle;
+  }
+
+  async resolve(rti: RTIAmbassador): Promise<void> {
+    this._interactionHandle = await rti.getInteractionClassHandle(this.className);
+    this._parameterHandles.clear();
+    this._parameterNamesByHandle.clear();
+
+    for (const key of this._parameterKeys) {
+      const spec = this.parameters[key];
+      const handle = await rti.getParameterHandle(this._interactionHandle, spec.name);
+      this._parameterHandles.set(key, handle);
+      this._parameterNamesByHandle.set(handleToHex(handle), key);
+    }
+  }
+
+  async publish(rti: RTIAmbassador): Promise<void> {
+    await rti.publishInteractionClass(this.interactionHandle);
+  }
+
+  async subscribe(rti: RTIAmbassador): Promise<void> {
+    await rti.subscribeInteractionClass(this.interactionHandle);
+  }
+
+  encode(values: Partial<T>): ParameterHandleValueMap {
+    if (!this._interactionHandle) {
+      throw new Error(`InteractionClassAdapter(${this.className}) is not resolved.`);
+    }
+    const entries: ParameterHandleValueMap = [];
+    for (const key of this._parameterKeys) {
+      if (!(key in values)) continue;
+      const value = values[key];
+      if (value === undefined) continue;
+      const spec = this.parameters[key];
+      const handle = this._parameterHandles.get(key);
+      if (!handle) {
+        throw new Error(`Parameter handle not resolved: ${String(key)}`);
+      }
+      entries.push({ parameterHandle: handle, value: spec.encode(value) });
+    }
+    return entries;
+  }
+
+  decode(values: ParameterHandleValueMap): Partial<T> {
+    const result: Partial<T> = {};
+    for (const entry of values) {
+      const key = this._parameterNamesByHandle.get(handleToHex(entry.parameterHandle));
+      if (!key) continue;
+      const spec = this.parameters[key];
+      if (!spec.decode) continue;
+      result[key] = spec.decode(entry.value);
+    }
+    return result;
+  }
+
+  async send(
+    rti: RTIAmbassador,
+    values: Partial<T>,
+    userSuppliedTag: UserSuppliedTag = new Uint8Array(),
+    time?: LogicalTime
+  ): Promise<void> {
+    const payload = this.encode(values);
+    if (time) {
+      await rti.sendInteractionWithTime(this.interactionHandle, payload, userSuppliedTag, time);
+    } else {
+      await rti.sendInteraction(this.interactionHandle, payload, userSuppliedTag);
+    }
+  }
+}

package/src/see-app.test.ts

@@ -0,0 +1,62 @@
+import { expect, test } from "bun:test";
+import { SpacekitApp } from "./see-app.ts";
+
+test("SpacekitApp exposes SEE timing helpers", () => {
+  const app = new SpacekitApp({
+    federationName: "SpaceFederation",
+    federateName: "TestFederate",
+    federateType: "TestFederate",
+    lookaheadMicros: 500_000n,
+    updatePeriodMicros: 1_000_000n,
+  });
+
+  expect(app.lookaheadMicros).toBe(500_000n);
+  expect(app.updatePeriodMicros).toBe(1_000_000n);
+  expect(app.getSendTimeMicros(10_000_000n)).toBe(10_500_000n);
+  expect(app.shouldLogTick(1)).toBe(true);
+});
+
+test("SpacekitApp can continue when a reference frame is missing", async () => {
+  const warnings: Array<{ message: string; data?: Record<string, unknown> }> = [];
+  const app = new SpacekitApp({
+    federationName: "SpaceFederation",
+    federateName: "TestFederate",
+    federateType: "TestFederate",
+    referenceFrameTimeoutMs: 1,
+    missingReferenceFrameMode: "continue",
+    logger: {
+      debug() {},
+      info() {},
+      warn(message, data) {
+        warnings.push({ message, data });
+      },
+      error() {},
+    },
+  });
+
+  (app as unknown as { _bootstrapState: unknown })._bootstrapState = {
+    referenceFrames: [],
+  };
+
+  await expect(app.waitForReferenceFrame("MissingFrame", 1)).resolves.toBeUndefined();
+  expect(
+    warnings.some((entry) => entry.message === "Proceeding without discovered reference frame.")
+  ).toBe(true);
+});
+
+test("SpacekitApp still errors by default when a reference frame is missing", async () => {
+  const app = new SpacekitApp({
+    federationName: "SpaceFederation",
+    federateName: "TestFederate",
+    federateType: "TestFederate",
+    referenceFrameTimeoutMs: 1,
+  });
+
+  (app as unknown as { _bootstrapState: unknown })._bootstrapState = {
+    referenceFrames: [],
+  };
+
+  await expect(app.waitForReferenceFrame("MissingFrame", 1)).rejects.toThrow(
+    "Reference frame not discovered: MissingFrame"
+  );
+});