@flighthq/types 0.1.0

package/src/Entity.test.ts

@@ -0,0 +1,66 @@
+import type { Entity, EntityRuntime, EntityWithoutRuntime, Kind } from './Entity';
+import { EntityRuntimeKey } from './Entity';
+
+describe('Entity', () => {
+  describe('EntityRuntimeKey', () => {
+    it('is a symbol', () => {
+      expect(typeof EntityRuntimeKey).toBe('symbol');
+    });
+
+    it('is registered as Symbol.for("EntityRuntime")', () => {
+      expect(EntityRuntimeKey).toBe(Symbol.for('EntityRuntime'));
+    });
+  });
+
+  describe('EntityWithoutRuntime', () => {
+    it('strips the runtime key from the entity type', () => {
+      type TestRuntime = EntityRuntime & { testField: string };
+      interface TestEntity extends Entity {
+        [EntityRuntimeKey]: TestRuntime | undefined;
+        value: number;
+        name: string;
+      }
+
+      type Stripped = EntityWithoutRuntime<TestEntity>;
+
+      // Verify Stripped has the plain data fields
+      expectTypeOf<Stripped>().toHaveProperty('value');
+      expectTypeOf<Stripped>().toHaveProperty('name');
+
+      // Verify the runtime symbol key is not present
+      // @ts-expect-error — EntityRuntimeKey should not exist on the stripped type
+      type _HasRuntimeKey = Stripped[typeof EntityRuntimeKey];
+    });
+
+    it('produces a type assignable from a plain object literal', () => {
+      interface TestEntity extends Entity {
+        [EntityRuntimeKey]: EntityRuntime | undefined;
+        count: number;
+      }
+
+      type Stripped = EntityWithoutRuntime<TestEntity>;
+
+      const literal: Stripped = { count: 42 };
+      expect(literal.count).toBe(42);
+    });
+
+    it('round-trips structurally — the entity without runtime is assignable to Stripped', () => {
+      interface TestEntity extends Entity {
+        [EntityRuntimeKey]: EntityRuntime | undefined;
+        label: string;
+      }
+
+      type Stripped = EntityWithoutRuntime<TestEntity>;
+      const obj: TestEntity = { [EntityRuntimeKey]: undefined, label: 'hello' };
+      const stripped: Stripped = obj;
+      expect(stripped.label).toBe('hello');
+    });
+  });
+
+  describe('Kind', () => {
+    it('is assignable from a plain string', () => {
+      const kind: Kind = 'MyKind';
+      expect(typeof kind).toBe('string');
+    });
+  });
+});

package/src/Material.test.ts

@@ -0,0 +1,90 @@
+import type { Entity } from './Entity';
+import { EntityRuntimeKey } from './Entity';
+import type { Material, MaterialData, MaterialLike } from './Material';
+import { DefaultMaterialKind } from './Material';
+
+describe('Material', () => {
+  describe('Material base contract', () => {
+    it('accepts a foreign custom material kind', () => {
+      interface AcmeMaterial extends Material {
+        readonly kind: 'acme.Shimmer';
+        intensity: number;
+      }
+
+      const acmeMaterial: AcmeMaterial = {
+        [EntityRuntimeKey]: undefined,
+        kind: 'acme.Shimmer',
+        intensity: 0.5,
+      };
+      // A custom material is assignable to the open base
+      const base: Material = acmeMaterial;
+      expect(base.kind).toBe('acme.Shimmer');
+    });
+
+    it('narrows on kind discriminant', () => {
+      interface RedMaterial extends Material {
+        readonly kind: 'Red';
+        hue: number;
+      }
+      interface BlueMaterial extends Material {
+        readonly kind: 'Blue';
+        shade: string;
+      }
+
+      function handle(mat: RedMaterial | BlueMaterial) {
+        if (mat.kind === 'Red') {
+          expectTypeOf(mat).toHaveProperty('hue');
+        } else {
+          expectTypeOf(mat).toHaveProperty('shade');
+        }
+      }
+
+      const red: RedMaterial = { [EntityRuntimeKey]: undefined, kind: 'Red', hue: 0 };
+      handle(red);
+      expect(red.kind).toBe('Red');
+    });
+  });
+
+  describe('MaterialLike', () => {
+    it('strips the EntityRuntimeKey from Material', () => {
+      const like: MaterialLike = { kind: 'SomeMaterial' };
+      expect(like.kind).toBe('SomeMaterial');
+    });
+
+    it('is assignable from a plain object without a runtime key', () => {
+      const plain = { kind: 'Plain' };
+      const like: MaterialLike = plain;
+      expect(like.kind).toBe('Plain');
+    });
+  });
+
+  describe('MaterialData', () => {
+    it('accepts any plain object', () => {
+      const data: MaterialData = { color: 0xff0000ff, opacity: 1 };
+      expect(data).toBeTruthy();
+    });
+  });
+
+  describe('DefaultMaterialKind', () => {
+    it('is the string DefaultMaterial', () => {
+      expect(DefaultMaterialKind).toBe('DefaultMaterial');
+    });
+
+    it('satisfies the Kind type constraint', () => {
+      // Compile-time assertion: DefaultMaterialKind is the literal type 'DefaultMaterial'
+      const kindLiteral: 'DefaultMaterial' = DefaultMaterialKind;
+      expect(kindLiteral).toBe('DefaultMaterial');
+    });
+  });
+});
+
+// Ensure Material is a proper Entity subtype (has the runtime key field)
+type _MaterialExtendsEntity = Material extends Entity ? true : false;
+const _materialIsEntity: _MaterialExtendsEntity = true;
+void _materialIsEntity;
+
+// Ensure MaterialLike does NOT have the EntityRuntimeKey field
+// (EntityWithoutRuntime removes it)
+type _MaterialLikeHasRuntimeKey = typeof EntityRuntimeKey extends keyof MaterialLike ? true : false;
+const _noRuntimeKey: _MaterialLikeHasRuntimeKey = false;
+void _noRuntimeKey;

package/src/MethodsOf.test.ts

@@ -0,0 +1,52 @@
+import type { MethodsOf } from './MethodsOf';
+
+describe('MethodsOf', () => {
+  it('extracts only method properties from an object type', () => {
+    interface Widget {
+      id: number;
+      label: string;
+      render(): void;
+      update(delta: number): boolean;
+    }
+
+    type WidgetMethods = MethodsOf<Widget>;
+
+    // Methods are preserved
+    expectTypeOf<WidgetMethods>().toHaveProperty('render');
+    expectTypeOf<WidgetMethods>().toHaveProperty('update');
+
+    // Data properties are excluded
+    // @ts-expect-error — 'id' is not in MethodsOf<Widget>
+    type _HasId = WidgetMethods['id'];
+
+    // @ts-expect-error — 'label' is not in MethodsOf<Widget>
+    type _HasLabel = WidgetMethods['label'];
+  });
+
+  it('produces an empty type for objects with no methods', () => {
+    interface DataOnly {
+      x: number;
+      y: number;
+    }
+
+    type DataMethods = MethodsOf<DataOnly>;
+
+    // No keys expected — DataMethods should be an empty object type
+    type Keys = keyof DataMethods;
+    const _noKeys: Keys extends never ? true : false = true;
+    void _noKeys;
+  });
+
+  it('preserves method signatures accurately', () => {
+    interface Calculator {
+      value: number;
+      add(a: number, b: number): number;
+      reset(): void;
+    }
+
+    type CalcMethods = MethodsOf<Calculator>;
+
+    expectTypeOf<CalcMethods['add']>().toEqualTypeOf<(a: number, b: number) => number>();
+    expectTypeOf<CalcMethods['reset']>().toEqualTypeOf<() => void>();
+  });
+});

package/src/Node.test.ts

@@ -0,0 +1,99 @@
+import type { Entity, EntityRuntime } from './Entity';
+import type { Node, NodeAny, NodeRuntime, NodeTraits } from './Node';
+import { NodeKind } from './Node';
+
+describe('Node', () => {
+  describe('NodeKind', () => {
+    it('is the string Node', () => {
+      expect(NodeKind).toBe('Node');
+    });
+  });
+
+  describe('NodeOf', () => {
+    it('intersects Node<Traits> with Traits', () => {
+      interface MyTraits extends NodeTraits {
+        data: { score: number } | null;
+        enabled: boolean;
+        kind: 'MyNode';
+        name: string | null;
+        myField: string;
+      }
+
+      // NodeOf<MyTraits> should have both Node and Traits properties
+      type MyNodeKind = MyTraits['kind'];
+      const kindCheck: MyNodeKind = 'MyNode';
+      expect(kindCheck).toBe('MyNode');
+    });
+  });
+
+  describe('NodeAny', () => {
+    it('accepts any Node regardless of Traits', () => {
+      interface TraitsA extends NodeTraits {
+        data: null;
+        enabled: boolean;
+        kind: 'A';
+        name: string | null;
+        fieldA: number;
+      }
+      interface TraitsB extends NodeTraits {
+        data: null;
+        enabled: boolean;
+        kind: 'B';
+        name: string | null;
+        fieldB: string;
+      }
+
+      function acceptsAny(_node: NodeAny): void {
+        // accepts any node kind
+      }
+
+      const nodeA = {
+        data: null,
+        enabled: true,
+        kind: 'A',
+        name: null,
+        fieldA: 1,
+      } as unknown as Node<TraitsA>;
+
+      const nodeB = {
+        data: null,
+        enabled: true,
+        kind: 'B',
+        name: null,
+        fieldB: 'hello',
+      } as unknown as Node<TraitsB>;
+
+      // Both can be passed as NodeAny
+      acceptsAny(nodeA);
+      acceptsAny(nodeB);
+      expect(true).toBe(true);
+    });
+  });
+
+  describe('NodeRuntime', () => {
+    it('has required numeric id fields', () => {
+      // Verify the structural shape of NodeRuntime at the type level
+      type RuntimeKeys = keyof NodeRuntime;
+
+      type _HasAppearanceId = 'appearanceId' extends RuntimeKeys ? true : false;
+      const _hasAppearance: _HasAppearanceId = true;
+      void _hasAppearance;
+
+      type _HasLocalTransformId = 'localTransformId' extends RuntimeKeys ? true : false;
+      const _hasLocalTransform: _HasLocalTransformId = true;
+      void _hasLocalTransform;
+
+      expect(true).toBe(true);
+    });
+  });
+});
+
+// Compile-time check: Node<Traits> extends Entity
+type _NodeExtendsEntity = Node extends Entity ? true : false;
+const _nodeIsEntity: _NodeExtendsEntity = true;
+void _nodeIsEntity;
+
+// Compile-time check: NodeRuntime extends EntityRuntime
+type _NodeRuntimeExtendsEntityRuntime = NodeRuntime extends EntityRuntime ? true : false;
+const _nodeRuntimeIsEntityRuntime: _NodeRuntimeExtendsEntityRuntime = true;
+void _nodeRuntimeIsEntityRuntime;

package/src/PartialNode.test.ts

@@ -0,0 +1,66 @@
+import type { PartialNode } from './PartialNode';
+
+describe('PartialNode', () => {
+  it('makes data fields partial within the data object', () => {
+    interface MyData {
+      x: number;
+      y: number;
+      label: string;
+    }
+    interface MyNode {
+      data: MyData;
+      kind: string;
+      name: string | null;
+    }
+
+    type Partial_ = PartialNode<MyNode>;
+
+    // data is optional and its inner fields are also partial
+    const withPartialData: Partial_ = { data: { x: 1 } };
+    expect(withPartialData.data?.x).toBe(1);
+    expect(withPartialData.data?.y).toBeUndefined();
+  });
+
+  it('makes top-level non-data fields optional', () => {
+    interface MyNode {
+      data: { count: number };
+      kind: string;
+      name: string | null;
+    }
+
+    type Partial_ = PartialNode<MyNode>;
+
+    // All top-level fields are optional (Partial applied to Omit<T, 'data'>)
+    const empty: Partial_ = {};
+    expect(empty.kind).toBeUndefined();
+    expect(empty.name).toBeUndefined();
+  });
+
+  it('accepts a fully specified node', () => {
+    interface MyNode {
+      data: { value: number };
+      kind: string;
+      enabled: boolean;
+    }
+
+    type Partial_ = PartialNode<MyNode>;
+
+    const full: Partial_ = { data: { value: 42 }, kind: 'MyNode', enabled: true };
+    expect(full.data?.value).toBe(42);
+    expect(full.kind).toBe('MyNode');
+    expect(full.enabled).toBe(true);
+  });
+
+  it('handles nodes with null data gracefully', () => {
+    interface MyNode {
+      data: null;
+      kind: string;
+    }
+
+    type Partial_ = PartialNode<MyNode>;
+
+    // data?: Partial<never> | undefined = data?: undefined
+    const minimal: Partial_ = {};
+    expect(minimal.data).toBeUndefined();
+  });
+});

package/src/ParticleForce.test.ts

@@ -0,0 +1,109 @@
+import type { AttractorForce } from './AttractorForce';
+import type { DragForce } from './DragForce';
+import type { ParticleForce } from './ParticleForce';
+import type { TurbulenceForce } from './TurbulenceForce';
+import type { VortexForce } from './VortexForce';
+import type { WindForce } from './WindForce';
+
+// ParticleForce is a closed discriminated union — verify exhaustiveness at the type level.
+// If a new member is added to the union, these exhaustiveness checks will produce a type error,
+// making the closed-by-design contract machine-verified.
+
+function assertNever(value: never): never {
+  throw new Error(`Unhandled ParticleForce kind: ${(value as ParticleForce).kind}`);
+}
+
+function handleParticleForce(force: ParticleForce): string {
+  switch (force.kind) {
+    case 'AttractorForce':
+      return 'attractor';
+    case 'DragForce':
+      return 'drag';
+    case 'TurbulenceForce':
+      return 'turbulence';
+    case 'VortexForce':
+      return 'vortex';
+    case 'WindForce':
+      return 'wind';
+    default:
+      // If ParticleForce gains a new member, this line becomes a type error.
+      return assertNever(force);
+  }
+}
+
+describe('ParticleForce', () => {
+  describe('closed discriminated union', () => {
+    it('handles AttractorForce', () => {
+      const force: AttractorForce = { kind: 'AttractorForce', x: 0, y: 0, strength: 1 };
+      expect(handleParticleForce(force)).toBe('attractor');
+    });
+
+    it('handles DragForce', () => {
+      const force: DragForce = { kind: 'DragForce', strength: 0.5 };
+      expect(handleParticleForce(force)).toBe('drag');
+    });
+
+    it('handles TurbulenceForce', () => {
+      const force: TurbulenceForce = { kind: 'TurbulenceForce', strength: 1, scale: 0.1 };
+      expect(handleParticleForce(force)).toBe('turbulence');
+    });
+
+    it('handles VortexForce', () => {
+      const force: VortexForce = { kind: 'VortexForce', x: 0, y: 0, strength: 1 };
+      expect(handleParticleForce(force)).toBe('vortex');
+    });
+
+    it('handles WindForce', () => {
+      const force: WindForce = { kind: 'WindForce', x: 1, y: 0 };
+      expect(handleParticleForce(force)).toBe('wind');
+    });
+  });
+
+  describe('union membership', () => {
+    it('AttractorForce is assignable to ParticleForce', () => {
+      const force: AttractorForce = { kind: 'AttractorForce', x: 0, y: 0, strength: 1 };
+      const asBase: ParticleForce = force;
+      expect(asBase.kind).toBe('AttractorForce');
+    });
+
+    it('DragForce is assignable to ParticleForce', () => {
+      const force: DragForce = { kind: 'DragForce', strength: 0.5 };
+      const asBase: ParticleForce = force;
+      expect(asBase.kind).toBe('DragForce');
+    });
+
+    it('TurbulenceForce is assignable to ParticleForce', () => {
+      const force: TurbulenceForce = { kind: 'TurbulenceForce', strength: 1, scale: 0.1 };
+      const asBase: ParticleForce = force;
+      expect(asBase.kind).toBe('TurbulenceForce');
+    });
+
+    it('VortexForce is assignable to ParticleForce', () => {
+      const force: VortexForce = { kind: 'VortexForce', x: 0, y: 0, strength: 1 };
+      const asBase: ParticleForce = force;
+      expect(asBase.kind).toBe('VortexForce');
+    });
+
+    it('WindForce is assignable to ParticleForce', () => {
+      const force: WindForce = { kind: 'WindForce', x: 1, y: 0 };
+      const asBase: ParticleForce = force;
+      expect(asBase.kind).toBe('WindForce');
+    });
+  });
+});
+
+// Exhaustiveness compile check: ParticleForce union equals the known members
+type _AllForceKinds = ParticleForce['kind'];
+type _ExpectedKinds =
+  | AttractorForce['kind']
+  | DragForce['kind']
+  | TurbulenceForce['kind']
+  | VortexForce['kind']
+  | WindForce['kind'];
+type _KindsMatch = _AllForceKinds extends _ExpectedKinds
+  ? _ExpectedKinds extends _AllForceKinds
+    ? true
+    : false
+  : false;
+const _kindsMatch: _KindsMatch = true;
+void _kindsMatch;

package/src/RenderEffect.test.ts

@@ -0,0 +1,39 @@
+import type { RenderEffect } from './RenderEffect';
+
+describe('RenderEffect', () => {
+  describe('open base contract', () => {
+    it('accepts a foreign custom effect kind', () => {
+      interface AcmeEffect extends RenderEffect {
+        kind: 'acme.Sparkle';
+        density: number;
+      }
+
+      const effect: AcmeEffect = { kind: 'acme.Sparkle', density: 10 };
+      // A custom effect is assignable to the open base
+      const base: RenderEffect = effect;
+      expect(base.kind).toBe('acme.Sparkle');
+    });
+
+    it('narrows on kind discriminant', () => {
+      interface RedEffect extends RenderEffect {
+        kind: 'RedEffect';
+        strength: number;
+      }
+      interface BlueEffect extends RenderEffect {
+        kind: 'BlueEffect';
+        amount: number;
+      }
+
+      const eff: RedEffect | BlueEffect = { kind: 'RedEffect', strength: 2 };
+      if (eff.kind === 'RedEffect') {
+        expectTypeOf(eff).toHaveProperty('strength');
+      }
+      expect(eff.kind).toBe('RedEffect');
+    });
+
+    it('accepts any string kind', () => {
+      const effect: RenderEffect = { kind: 'SomeEffect' };
+      expect(effect.kind).toBe('SomeEffect');
+    });
+  });
+});

package/src/Signal.test.ts

@@ -0,0 +1,60 @@
+import type { Signal, SignalData } from './Signal';
+
+describe('Signal', () => {
+  describe('Signal', () => {
+    it('parameterizes emit by the slot function type', () => {
+      type PointSlot = (x: number, y: number) => void;
+      const signal: Signal<PointSlot> = {
+        data: null,
+        emit: (_x, _y) => {},
+      };
+
+      // emit accepts exactly the slot signature
+      signal.emit(1, 2);
+      expect(signal.data).toBeNull();
+    });
+
+    it('carries a nullable SignalData payload', () => {
+      type Slot = (value: string) => void;
+      const data: SignalData<Slot> = {
+        slots: [(_value) => {}],
+        priorities: [0],
+        repeat: [true],
+        cancelled: false,
+      };
+      const signal: Signal<Slot> = { data, emit: (_value) => {} };
+      expect(signal.data?.slots.length).toBe(1);
+    });
+  });
+
+  describe('SignalData', () => {
+    it('carries parallel slot, priority, and repeat arrays plus a cancelled flag', () => {
+      type Slot = () => void;
+      const data: SignalData<Slot> = {
+        slots: [() => {}, () => {}],
+        priorities: [10, 0],
+        repeat: [true, false],
+        cancelled: false,
+      };
+
+      expect(data.slots.length).toBe(2);
+      expect(data.priorities).toEqual([10, 0]);
+      expect(data.repeat).toEqual([true, false]);
+      expect(data.cancelled).toBe(false);
+    });
+
+    it('types the slots array to the parameterized slot signature', () => {
+      type Slot = (n: number) => void;
+      const data: SignalData<Slot> = {
+        slots: [],
+        priorities: [],
+        repeat: [],
+        cancelled: false,
+      };
+      data.slots.push((n) => {
+        void n;
+      });
+      expect(data.slots.length).toBe(1);
+    });
+  });
+});