@hla4ts/spacekit 0.1.0

package/src/decorators.ts

@@ -0,0 +1,514 @@
+import type {
+  AttributeSchema,
+  InteractionClassSchema,
+  ObjectClassSchema,
+  OrderType,
+  OwnershipType,
+  ParameterSchema,
+  SharingType,
+  UpdateType,
+} from "@hla4ts/fom-codegen";
+import type { DeclarativeAttribute, DeclarativeInteractionClass, DeclarativeObjectClass, DeclarativeParameter } from "./declarative.ts";
+import { DeclarativeFom } from "./declarative.ts";
+
+export type FomClassConstructor<T = object> = new (...args: never[]) => T;
+
+export interface FomCoder<T> {
+  encode(value: T): Uint8Array;
+  decode?(data: Uint8Array): T;
+}
+
+export interface FomObjectClassOptions {
+  name?: string;
+  parent?: string;
+  sharing?: SharingType;
+  semantics?: string;
+}
+
+export interface FomAttributeOptions<T> {
+  name?: string;
+  dataType: string;
+  updateType: UpdateType;
+  updateCondition: string;
+  ownership: OwnershipType;
+  sharing: SharingType;
+  transportation: string;
+  order: OrderType;
+  semantics?: string;
+  valueRequired?: boolean;
+  encode?: (value: T) => Uint8Array;
+  decode?: (data: Uint8Array) => T;
+  coder?: FomCoder<T>;
+}
+
+export interface FomInteractionClassOptions {
+  name?: string;
+  parent?: string;
+  sharing?: SharingType;
+  transportation?: string;
+  order?: OrderType;
+  semantics?: string;
+}
+
+export interface FomParameterOptions<T> {
+  name?: string;
+  dataType: string;
+  semantics?: string;
+  encode?: (value: T) => Uint8Array;
+  decode?: (data: Uint8Array) => T;
+  coder?: FomCoder<T>;
+}
+
+interface ObjectClassMetadata {
+  options?: FomObjectClassOptions;
+  attributes: Map<string, FomAttributeOptions<unknown>>;
+}
+
+interface InteractionClassMetadata {
+  options?: FomInteractionClassOptions;
+  parameters: Map<string, FomParameterOptions<unknown>>;
+}
+
+interface MetadataEntry<T> {
+  ctor: Function;
+  meta: T;
+}
+
+const objectClassMetadata = new Map<Function, ObjectClassMetadata>();
+const interactionClassMetadata = new Map<Function, InteractionClassMetadata>();
+
+export function FomObjectClass(options: FomObjectClassOptions = {}): ClassDecorator {
+  return (target) => {
+    const meta = getOrCreateObjectMetadata(target);
+    meta.options = options;
+    objectClassMetadata.set(target, meta);
+  };
+}
+
+export function FomAttribute<T>(options: FomAttributeOptions<T>): PropertyDecorator {
+  return (target, propertyKey) => {
+    const ctor = target.constructor as Function;
+    const meta = getOrCreateObjectMetadata(ctor);
+    meta.attributes.set(String(propertyKey), options as FomAttributeOptions<unknown>);
+    objectClassMetadata.set(ctor, meta);
+  };
+}
+
+export function FomInteractionClass(
+  options: FomInteractionClassOptions = {}
+): ClassDecorator {
+  return (target) => {
+    const meta = getOrCreateInteractionMetadata(target);
+    meta.options = options;
+    interactionClassMetadata.set(target, meta);
+  };
+}
+
+export function FomParameter<T>(options: FomParameterOptions<T>): PropertyDecorator {
+  return (target, propertyKey) => {
+    const ctor = target.constructor as Function;
+    const meta = getOrCreateInteractionMetadata(ctor);
+    meta.parameters.set(String(propertyKey), options as FomParameterOptions<unknown>);
+    interactionClassMetadata.set(ctor, meta);
+  };
+}
+
+export function getDecoratedObjectClassMetadata(
+  ctor: Function
+): ObjectClassSchema | undefined {
+  const chain = getObjectMetadataChain(ctor);
+  if (!chain.length) return undefined;
+  const meta = chain[chain.length - 1].meta;
+  if (!meta) return undefined;
+  const { name, parent } = resolveObjectNames(ctor, chain, meta.options);
+  return {
+    name,
+    parent,
+    sharing: meta.options?.sharing,
+    semantics: meta.options?.semantics,
+    attributes: Array.from(mergeObjectAttributes(chain).entries()).map(
+      ([key, attribute]) => toAttributeSchema(key, attribute)
+    ),
+  };
+}
+
+export function getDecoratedInteractionClassMetadata(
+  ctor: Function
+): InteractionClassSchema | undefined {
+  const chain = getInteractionMetadataChain(ctor);
+  if (!chain.length) return undefined;
+  const meta = chain[chain.length - 1].meta;
+  if (!meta) return undefined;
+  const { name, parent } = resolveInteractionNames(ctor, chain, meta.options);
+  return {
+    name,
+    parent,
+    sharing: meta.options?.sharing,
+    transportation: meta.options?.transportation,
+    order: meta.options?.order,
+    semantics: meta.options?.semantics,
+    parameters: Array.from(mergeInteractionParameters(chain).entries()).map(
+      ([key, parameter]) => toParameterSchema(key, parameter)
+    ),
+  };
+}
+
+export function registerDecoratedClasses(
+  declarative: DeclarativeFom,
+  options: {
+    objectClasses?: FomClassConstructor[];
+    interactionClasses?: FomClassConstructor[];
+    register?: boolean;
+  }
+): void {
+  for (const ctor of options.objectClasses ?? []) {
+    const schema = getDecoratedObjectSchema(ctor);
+    const shouldRegister = options.register ?? true;
+    declarative.defineObjectClass(schema, { register: false });
+    if (shouldRegister) {
+      declarative.registry.addObjectClass(getDecoratedObjectSchemaForFom(ctor));
+    }
+  }
+  for (const ctor of options.interactionClasses ?? []) {
+    const schema = getDecoratedInteractionSchema(ctor);
+    const shouldRegister = options.register ?? true;
+    declarative.defineInteractionClass(schema, { register: false });
+    if (shouldRegister) {
+      declarative.registry.addInteractionClass(getDecoratedInteractionSchemaForFom(ctor));
+    }
+  }
+}
+
+export function buildDeclarativeFomFromDecorators(options: {
+  objectClasses?: FomClassConstructor[];
+  interactionClasses?: FomClassConstructor[];
+  register?: boolean;
+}): DeclarativeFom {
+  const declarative = new DeclarativeFom();
+  registerDecoratedClasses(declarative, options);
+  return declarative;
+}
+
+export function getDecoratedObjectClassName(ctor: Function): string | undefined {
+  const meta = getDecoratedObjectClassMetadata(ctor);
+  if (!meta) return undefined;
+  return resolveDecoratedName(meta.name, meta.parent);
+}
+
+export function getDecoratedInteractionClassName(ctor: Function): string | undefined {
+  const meta = getDecoratedInteractionClassMetadata(ctor);
+  if (!meta) return undefined;
+  return resolveDecoratedName(meta.name, meta.parent);
+}
+
+function getDecoratedObjectSchema<T extends object>(
+  ctor: FomClassConstructor<T>
+): DeclarativeObjectClass<T> {
+  const chain = getObjectMetadataChain(ctor);
+  if (!chain.length) {
+    throw new Error(`Missing @FomObjectClass metadata for ${ctor.name}.`);
+  }
+  const meta = chain[chain.length - 1].meta;
+  const { name, parent } = resolveObjectNames(ctor, chain, meta.options);
+  const attributes = toDeclarativeAttributes(mergeObjectAttributes(chain));
+  return {
+    name,
+    parent,
+    sharing: meta.options?.sharing,
+    semantics: meta.options?.semantics,
+    attributes: attributes as DeclarativeObjectClass<T>["attributes"],
+  };
+}
+
+function getDecoratedObjectSchemaForFom(
+  ctor: FomClassConstructor
+): ObjectClassSchema {
+  const chain = getObjectMetadataChain(ctor);
+  if (!chain.length) {
+    throw new Error(`Missing @FomObjectClass metadata for ${ctor.name}.`);
+  }
+  const meta = chain[chain.length - 1].meta;
+  const { name, parent } = resolveObjectNames(ctor, chain, meta.options);
+  const attributes = toDeclarativeAttributes(meta.attributes);
+  return {
+    name,
+    parent,
+    sharing: meta.options?.sharing,
+    semantics: meta.options?.semantics,
+    attributes: Object.values(attributes).map((attribute) => ({
+      name: attribute.name,
+      dataType: attribute.dataType,
+      updateType: attribute.updateType,
+      updateCondition: attribute.updateCondition,
+      ownership: attribute.ownership,
+      sharing: attribute.sharing,
+      transportation: attribute.transportation,
+      order: attribute.order,
+      semantics: attribute.semantics,
+      valueRequired: attribute.valueRequired,
+    })),
+  };
+}
+
+function getDecoratedInteractionSchema<T extends object>(
+  ctor: FomClassConstructor<T>
+): DeclarativeInteractionClass<T> {
+  const chain = getInteractionMetadataChain(ctor);
+  if (!chain.length) {
+    throw new Error(`Missing @FomInteractionClass metadata for ${ctor.name}.`);
+  }
+  const meta = chain[chain.length - 1].meta;
+  const { name, parent } = resolveInteractionNames(ctor, chain, meta.options);
+  const parameters = toDeclarativeParameters(mergeInteractionParameters(chain));
+  return {
+    name,
+    parent,
+    sharing: meta.options?.sharing,
+    transportation: meta.options?.transportation,
+    order: meta.options?.order,
+    semantics: meta.options?.semantics,
+    parameters: parameters as DeclarativeInteractionClass<T>["parameters"],
+  };
+}
+
+function getDecoratedInteractionSchemaForFom(
+  ctor: FomClassConstructor
+): InteractionClassSchema {
+  const chain = getInteractionMetadataChain(ctor);
+  if (!chain.length) {
+    throw new Error(`Missing @FomInteractionClass metadata for ${ctor.name}.`);
+  }
+  const meta = chain[chain.length - 1].meta;
+  const { name, parent } = resolveInteractionNames(ctor, chain, meta.options);
+  const parameters = toDeclarativeParameters(meta.parameters);
+  return {
+    name,
+    parent,
+    sharing: meta.options?.sharing,
+    transportation: meta.options?.transportation,
+    order: meta.options?.order,
+    semantics: meta.options?.semantics,
+    parameters: Object.values(parameters).map((parameter) => ({
+      name: parameter.name,
+      dataType: parameter.dataType,
+      semantics: parameter.semantics,
+    })),
+  };
+}
+
+function toDeclarativeAttributes(
+  attributes: Map<string, FomAttributeOptions<unknown>>
+): Record<string, DeclarativeAttribute<unknown>> {
+  const result: Record<string, DeclarativeAttribute<unknown>> = {};
+  for (const [key, attribute] of attributes.entries()) {
+    const coder = resolveCoder(attribute, "attribute", key);
+    result[key] = {
+      name: attribute.name ?? key,
+      dataType: attribute.dataType,
+      updateType: attribute.updateType,
+      updateCondition: attribute.updateCondition,
+      ownership: attribute.ownership,
+      sharing: attribute.sharing,
+      transportation: attribute.transportation,
+      order: attribute.order,
+      semantics: attribute.semantics,
+      valueRequired: attribute.valueRequired,
+      encode: coder.encode,
+      decode: coder.decode,
+    };
+  }
+  return result;
+}
+
+function toDeclarativeParameters(
+  parameters: Map<string, FomParameterOptions<unknown>>
+): Record<string, DeclarativeParameter<unknown>> {
+  const result: Record<string, DeclarativeParameter<unknown>> = {};
+  for (const [key, parameter] of parameters.entries()) {
+    const coder = resolveCoder(parameter, "parameter", key);
+    result[key] = {
+      name: parameter.name ?? key,
+      dataType: parameter.dataType,
+      semantics: parameter.semantics,
+      encode: coder.encode,
+      decode: coder.decode,
+    };
+  }
+  return result;
+}
+
+function toAttributeSchema(key: string, attribute: FomAttributeOptions<unknown>): AttributeSchema {
+  return {
+    name: attribute.name ?? key,
+    dataType: attribute.dataType,
+    updateType: attribute.updateType,
+    updateCondition: attribute.updateCondition,
+    ownership: attribute.ownership,
+    sharing: attribute.sharing,
+    transportation: attribute.transportation,
+    order: attribute.order,
+    semantics: attribute.semantics,
+    valueRequired: attribute.valueRequired,
+  };
+}
+
+function toParameterSchema(key: string, parameter: FomParameterOptions<unknown>): ParameterSchema {
+  return {
+    name: parameter.name ?? key,
+    dataType: parameter.dataType,
+    semantics: parameter.semantics,
+  };
+}
+
+function getOrCreateObjectMetadata(target: Function): ObjectClassMetadata {
+  const existing = objectClassMetadata.get(target);
+  if (existing) return existing;
+  const created: ObjectClassMetadata = { attributes: new Map() };
+  objectClassMetadata.set(target, created);
+  return created;
+}
+
+function getOrCreateInteractionMetadata(target: Function): InteractionClassMetadata {
+  const existing = interactionClassMetadata.get(target);
+  if (existing) return existing;
+  const created: InteractionClassMetadata = { parameters: new Map() };
+  interactionClassMetadata.set(target, created);
+  return created;
+}
+
+function getObjectMetadataChain(target: Function): Array<MetadataEntry<ObjectClassMetadata>> {
+  const chain: Array<MetadataEntry<ObjectClassMetadata>> = [];
+  let current: Function | null = target;
+  while (current && current !== Function && current !== Object) {
+    const meta = objectClassMetadata.get(current);
+    if (meta) chain.unshift({ ctor: current, meta });
+    const proto = Object.getPrototypeOf(current.prototype);
+    current = proto?.constructor ?? null;
+  }
+  return chain;
+}
+
+function getInteractionMetadataChain(
+  target: Function
+): Array<MetadataEntry<InteractionClassMetadata>> {
+  const chain: Array<MetadataEntry<InteractionClassMetadata>> = [];
+  let current: Function | null = target;
+  while (current && current !== Function && current !== Object) {
+    const meta = interactionClassMetadata.get(current);
+    if (meta) chain.unshift({ ctor: current, meta });
+    const proto = Object.getPrototypeOf(current.prototype);
+    current = proto?.constructor ?? null;
+  }
+  return chain;
+}
+
+function mergeObjectAttributes(
+  chain: Array<MetadataEntry<ObjectClassMetadata>>
+): Map<string, FomAttributeOptions<unknown>> {
+  const merged = new Map<string, FomAttributeOptions<unknown>>();
+  for (const entry of chain) {
+    for (const [key, attribute] of entry.meta.attributes.entries()) {
+      merged.set(key, attribute);
+    }
+  }
+  return merged;
+}
+
+function mergeInteractionParameters(
+  chain: Array<MetadataEntry<InteractionClassMetadata>>
+): Map<string, FomParameterOptions<unknown>> {
+  const merged = new Map<string, FomParameterOptions<unknown>>();
+  for (const entry of chain) {
+    for (const [key, parameter] of entry.meta.parameters.entries()) {
+      merged.set(key, parameter);
+    }
+  }
+  return merged;
+}
+
+function getParentClassName(
+  chain: Array<MetadataEntry<ObjectClassMetadata>>
+): string | undefined {
+  if (chain.length < 2) return undefined;
+  const parentMeta = chain[chain.length - 2];
+  return (
+    (parentMeta.ctor as { className?: string }).className ??
+    getDecoratedObjectClassName(parentMeta.ctor) ??
+    parentMeta.meta.options?.name ??
+    parentMeta.ctor.name
+  );
+}
+
+function getParentInteractionName(
+  chain: Array<MetadataEntry<InteractionClassMetadata>>
+): string | undefined {
+  if (chain.length < 2) return undefined;
+  const parentMeta = chain[chain.length - 2];
+  return (
+    (parentMeta.ctor as { className?: string }).className ??
+    getDecoratedInteractionClassName(parentMeta.ctor) ??
+    parentMeta.meta.options?.name ??
+    parentMeta.ctor.name
+  );
+}
+
+function resolveDecoratedName(name?: string, parent?: string): string | undefined {
+  if (!name) return undefined;
+  if (name.includes(".")) return name;
+  if (!parent) return name;
+  return `${parent}.${name}`;
+}
+
+function resolveObjectNames(
+  ctor: Function,
+  chain: Array<MetadataEntry<ObjectClassMetadata>>,
+  options?: FomObjectClassOptions
+): { name: string; parent?: string } {
+  const name = options?.name ?? ctor.name;
+  const explicitParent = options?.parent;
+  if (explicitParent) {
+    return { name, parent: explicitParent };
+  }
+  if (name.includes(".")) {
+    return { name, parent: inferParentName(name) };
+  }
+  const parent = getParentClassName(chain) ?? "HLAobjectRoot";
+  return { name, parent };
+}
+
+function resolveInteractionNames(
+  ctor: Function,
+  chain: Array<MetadataEntry<InteractionClassMetadata>>,
+  options?: FomInteractionClassOptions
+): { name: string; parent?: string } {
+  const name = options?.name ?? ctor.name;
+  const explicitParent = options?.parent;
+  if (explicitParent) {
+    return { name, parent: explicitParent };
+  }
+  if (name.includes(".")) {
+    return { name, parent: inferParentName(name) };
+  }
+  const parent = getParentInteractionName(chain) ?? "HLAinteractionRoot";
+  return { name, parent };
+}
+
+function resolveCoder<T>(
+  options: { coder?: FomCoder<T>; encode?: (value: T) => Uint8Array; decode?: (data: Uint8Array) => T },
+  kind: "attribute" | "parameter",
+  key: string
+): FomCoder<T> {
+  if (options.coder) return options.coder;
+  if (!options.encode) {
+    throw new Error(`Missing encoder for ${kind} ${key}.`);
+  }
+  return {
+    encode: options.encode,
+    decode: options.decode,
+  };
+}
+
+function inferParentName(name: string): string | undefined {
+  if (!name.includes(".")) return undefined;
+  return name.slice(0, name.lastIndexOf("."));
+}

package/src/entity.ts

@@ -0,0 +1,103 @@
+import type { LogicalTime } from "@hla4ts/hla-api";
+import type { SpacekitApp } from "./app.ts";
+import type { ObjectClassAdapter, ObjectInstanceAdapter } from "./object-model.ts";
+
+const ENTITY_BINDING = Symbol.for("spacekit.entityBinding");
+
+export interface SpacekitEntityBinding<T extends object> {
+  app: SpacekitApp;
+  adapter: ObjectClassAdapter<T>;
+  instance: ObjectInstanceAdapter<T>;
+}
+
+export abstract class SpacekitEntity<T extends object> {
+  private _lastAttributes?: Record<string, unknown>;
+  private readonly _dirtyKeys = new Set<string>();
+  private _dirtyAll = true;
+
+  abstract toAttributes(): T;
+
+  markDirty(...keys: Array<keyof T & string>): void {
+    if (keys.length === 0) {
+      this._dirtyAll = true;
+      return;
+    }
+    for (const key of keys) {
+      this._dirtyKeys.add(String(key) as keyof T & string);
+    }
+  }
+
+  protected _consumeChangesInternal(): Partial<T> {
+    const current = this.toAttributes();
+    const currentRecord = current as Record<string, unknown>;
+    if (this._dirtyAll || !this._lastAttributes) {
+      this._dirtyAll = false;
+      this._dirtyKeys.clear();
+      this._lastAttributes = currentRecord;
+      return current;
+    }
+
+    const changes: Partial<T> = {};
+    for (const key of Object.keys(current) as Array<keyof T & string>) {
+      if (this._dirtyKeys.has(key)) {
+        changes[key] = current[key];
+        continue;
+      }
+      if (!Object.is(current[key], this._lastAttributes[key])) {
+        changes[key] = current[key];
+      }
+    }
+
+    this._dirtyKeys.clear();
+    this._lastAttributes = currentRecord;
+    return changes;
+  }
+
+  async sync(time?: LogicalTime, userSuppliedTag?: Uint8Array): Promise<void> {
+    const binding = requireEntityBinding(this);
+    await binding.app.syncEntity(this, time, userSuppliedTag);
+  }
+
+  async delete(time?: LogicalTime, userSuppliedTag?: Uint8Array): Promise<void> {
+    const binding = requireEntityBinding(this);
+    await binding.app.deleteObject(binding.instance, userSuppliedTag ?? new Uint8Array(), time);
+  }
+
+  get instanceName(): string | undefined {
+    return getEntityBinding(this)?.instance.objectInstanceName;
+  }
+
+  get className(): string | undefined {
+    return getEntityBinding(this)?.adapter.className;
+  }
+}
+
+export function bindEntity<T extends object>(
+  entity: SpacekitEntity<T>,
+  binding: SpacekitEntityBinding<T>
+): void {
+  (entity as unknown as Record<symbol, SpacekitEntityBinding<T>>)[ENTITY_BINDING] = binding;
+}
+
+export function getEntityBinding<T extends object>(
+  entity: SpacekitEntity<T>
+): SpacekitEntityBinding<T> | undefined {
+  return (entity as unknown as Record<symbol, SpacekitEntityBinding<T> | undefined>)[
+    ENTITY_BINDING
+  ];
+}
+
+export function requireEntityBinding<T extends object>(
+  entity: SpacekitEntity<T>
+): SpacekitEntityBinding<T> {
+  const binding = getEntityBinding(entity);
+  if (!binding) {
+    throw new Error("Entity is not registered with a SpacekitApp.");
+  }
+  return binding;
+}
+
+export function consumeEntityChanges<T extends object>(entity: SpacekitEntity<T>): Partial<T> {
+  return (entity as unknown as { _consumeChangesInternal: () => Partial<T> })
+    ._consumeChangesInternal();
+}