feat(world): add getOptional method for safe component access

Author: codehz

src/archetype.ts

@@ -107,7 +107,7 @@ export class Archetype {
     // Add component data for regular components (those in the archetype signature)
     for (const componentType of this.componentTypes) {
       const data = componentData.get(componentType);
-      this.getComponentData(componentType).push(data === undefined ? MISSING_COMPONENT : data);
+      this.getComponentData(componentType).push(!componentData.has(componentType) ? MISSING_COMPONENT : data);
     }
 
     // Add dontFragment relations separately
@@ -316,7 +316,10 @@ export class Archetype {
       // First check if it's in the archetype signature
       if (this.componentTypes.includes(componentType)) {
         const data = this.getComponentData(componentType)[index]!;
-        return data === MISSING_COMPONENT ? (undefined as T) : data;
+        if (data === MISSING_COMPONENT) {
+          throw new Error(`Component type ${componentType} not found for entity ${entityId}`);
+        }
+        return data as T;
       }
 
       // Check dontFragment relations
@@ -329,6 +332,36 @@ export class Archetype {
     }
   }
 
+  /**
+   * Get optional component data for a specific entity and component type
+   * @param entityId The entity
+   * @param componentType The component type
+   * @returns { value: T } if component exists, undefined otherwise
+   */
+  getOptional<T>(entityId: EntityId, componentType: EntityId<T>): { value: T } | undefined {
+    const index = this.entityToIndex.get(entityId);
+    if (index === undefined) {
+      throw new Error(`Entity ${entityId} is not in this archetype`);
+    }
+
+    // First check if it's in the archetype signature
+    if (this.componentTypes.includes(componentType)) {
+      const data = this.getComponentData(componentType)[index]!;
+      if (data === MISSING_COMPONENT) {
+        return undefined;
+      }
+      return { value: data as T };
+    }
+
+    // Check dontFragment relations
+    const dontFragmentData = this.dontFragmentRelations.get(entityId);
+    if (dontFragmentData && dontFragmentData.has(componentType)) {
+      return { value: dontFragmentData.get(componentType) };
+    }
+
+    return undefined;
+  }
+
   /**
    * Set component data for a specific entity and component type
    * @param entityId The entity

src/get-optional.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "bun:test";
+import { component, relation } from "./entity";
+import { World } from "./world";
+
+describe("World.getOptional", () => {
+  it("should return { value: T } when component exists", () => {
+    const world = new World();
+    const PositionId = component<{ x: number; y: number }>();
+    const entity = world.new();
+    world.set(entity, PositionId, { x: 10, y: 20 });
+    world.sync();
+
+    const result = world.getOptional(entity, PositionId);
+    expect(result).toEqual({ value: { x: 10, y: 20 } });
+  });
+
+  it("should return undefined when component does not exist", () => {
+    const world = new World();
+    const PositionId = component<{ x: number; y: number }>();
+    const VelocityId = component<{ x: number; y: number }>();
+    const entity = world.new();
+    world.set(entity, PositionId, { x: 10, y: 20 });
+    world.sync();
+
+    const result = world.getOptional(entity, VelocityId);
+    expect(result).toBeUndefined();
+  });
+
+  it("should distinguish between component value being undefined and component not existing", () => {
+    const world = new World();
+    const UndefinedComponent = component<undefined>();
+    const entity = world.new();
+    world.set(entity, UndefinedComponent, undefined);
+    world.sync();
+
+    // Exists with undefined value
+    expect(world.getOptional(entity, UndefinedComponent)).toEqual({ value: undefined });
+
+    // Not existing
+    const Other = component<number>();
+    expect(world.getOptional(entity, Other)).toBeUndefined();
+  });
+
+  it("should throw error when entity does not exist", () => {
+    const world = new World();
+    const PositionId = component<{ x: number; y: number }>();
+    const entity = 1234 as any; // non-existent entity
+
+    expect(() => world.getOptional(entity, PositionId)).toThrow("Entity 1234 does not exist");
+  });
+
+  it("should return undefined for wildcard relations", () => {
+    const world = new World();
+    const Rel = component<number>();
+    const target = world.new();
+    const entity = world.new();
+    world.set(entity, relation(Rel, target), 100);
+    world.sync();
+
+    const wildcard = relation(Rel, "*");
+    expect(world.getOptional(entity, wildcard as any)).toBeUndefined();
+  });
+
+  it("should work with dontFragment relations", () => {
+    const world = new World();
+    const DFRel = component<number>({ dontFragment: true });
+    const target = world.new();
+    const entity = world.new();
+    world.set(entity, relation(DFRel, target), 42);
+    world.sync();
+
+    const relId = relation(DFRel, target);
+    expect(world.getOptional(entity, relId)).toEqual({ value: 42 });
+
+    const otherTarget = world.new();
+    const otherRelId = relation(DFRel, otherTarget);
+    expect(world.getOptional(entity, otherRelId)).toBeUndefined();
+  });
+});

src/world.ts

@@ -401,6 +401,25 @@ export class World {
     return archetype.get(entityId, componentType);
   }
 
+  /**
+   * Get optional component data for a specific entity and component type
+   * @param entityId The entity
+   * @param componentType The component type
+   * @returns { value: T } if component exists, undefined otherwise
+   */
+  getOptional<T>(entityId: EntityId, componentType: EntityId<T>): { value: T } | undefined {
+    const archetype = this.entityToArchetype.get(entityId);
+    if (!archetype) {
+      throw new Error(`Entity ${entityId} does not exist`);
+    }
+
+    if (isWildcardRelationId(componentType)) {
+      return undefined;
+    }
+
+    return archetype.getOptional(entityId, componentType);
+  }
+
   /**
    * Register a lifecycle hook for component or wildcard relation events
    */