refactor: improve type safety, reduce code duplication, and optimize error handling (Tasks 02, 03, 04)

## Task 02: Type Safety Improvements

### 2.1 Command Discriminated Union
- Converted `Command` interface to discriminated union type
- Enables TypeScript type narrowing for safer command processing
- Removed runtime checks for `componentType` existence in command processing

### 2.2 SerializedWorld Type
- Defined `SerializedEntityIdManager` interface for proper type safety
- Replaced `any` type in `SerializedWorld.entityManager`

### 2.3 Type Aliases
- Added `AnyComponentId` and `AnyEntityId` type aliases
- Documents intentional type erasure for internal runtime storage

### 2.4 Non-null Assertions
- Removed non-null assertions (!.) in favor of type-safe code
- Added explanatory comments where TypeScript type narrowing guarantees safety
- Applies to `serialization.ts` and `world.ts` relation handling

## Task 03: Code Duplication Elimination

### 3.1 Wildcard Relation Helpers
- Extracted `findWildcardRelations()` and `hasWildcardRelation()` helpers
- Added to `archetype-helpers.ts` for reuse across codebase
- Updated `world.ts` to use new helpers, eliminating ~15 lines of duplication

### 3.2 Utility Function Merge
- Merged identical `getOrComputeCache` and `getOrCreateWithSideEffect` functions
- Created unified `getOrCompute` function with backward-compatible aliases
- Reduced redundant code in `utils.ts`

## Task 04: Error Handling Optimization

### 4.1 Hook Try-Catch Removal
- Replaced try-catch in `entityHasAllComponents` with `getOptional()`
- Replaced try-catch in `entityHadAllComponentsBefore` with `getOptional()`
- Improves performance and code clarity

### 4.2 ID Type Functions
- Replaced try-catch in `getIdType()` with `decodeRelationRaw()`
- Replaced try-catch in `getDetailedIdType()` with `decodeRelationRaw()`
- Replaced try-catch in `inspectEntityId()` with `decodeRelationRaw()`
- Uses null-returning function instead of exception-based control flow

## Testing
- All 263 tests pass
- TypeScript compilation successful with `bunx tsc --noEmit`
- No breaking changes to public API

Author: codehz

src/commands/command-buffer.ts

@@ -7,13 +7,12 @@ const MAX_COMMAND_ITERATIONS = 100;
 
 /**
  * Command for deferred execution
+ * Uses discriminated union for type safety
  */
-export interface Command {
-  type: "set" | "delete" | "destroy";
-  entityId: EntityId;
-  componentType?: EntityId<any>;
-  component?: any;
-}
+export type Command =
+  | { type: "set"; entityId: EntityId; componentType: EntityId<any>; component: any }
+  | { type: "delete"; entityId: EntityId; componentType: EntityId<any> }
+  | { type: "destroy"; entityId: EntityId };
 
 /**
  * Command buffer for deferred structural changes

src/core/archetype-helpers.ts

@@ -1,6 +1,12 @@
 import { MISSING_COMPONENT } from "./archetype";
 import type { ComponentId, EntityId, WildcardRelationId } from "./entity";
-import { getComponentIdFromRelationId, getDetailedIdType, getIdType, getTargetIdFromRelationId } from "./entity";
+import {
+  getComponentIdFromRelationId,
+  getDetailedIdType,
+  getIdType,
+  getTargetIdFromRelationId,
+  isRelationId,
+} from "./entity";
 import { isOptionalEntityId, type ComponentType } from "./types";
 
 type DetailedIdType = ReturnType<typeof getDetailedIdType>;
@@ -9,6 +15,41 @@ type RelationDetailedType =
   | { type: "entity-relation"; componentId: ComponentId<any>; targetId: EntityId<any> }
   | { type: "component-relation"; componentId: ComponentId<any>; targetId: ComponentId<any> };
 
+/**
+ * Find all wildcard relations matching a specific component ID from a components map
+ * @param components - Component entity's components map
+ * @param wildcardComponentId - The component ID to match (relation part)
+ * @returns Array of matching relation IDs
+ */
+export function findWildcardRelations(components: Map<EntityId, any>, wildcardComponentId: EntityId): EntityId<any>[] {
+  const result: EntityId<any>[] = [];
+  for (const [relId] of components) {
+    if (isRelationId(relId)) {
+      const decoded = getComponentIdFromRelationId(relId);
+      if (decoded === wildcardComponentId) {
+        result.push(relId);
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Check if a components map has any wildcard relations matching a component ID
+ * @param components - Component entity's components map
+ * @param wildcardComponentId - The component ID to match
+ * @returns True if at least one matching relation exists
+ */
+export function hasWildcardRelation(components: Map<EntityId, any>, wildcardComponentId: EntityId): boolean {
+  for (const relId of components.keys()) {
+    if (isRelationId(relId)) {
+      const decoded = getComponentIdFromRelationId(relId);
+      if (decoded === wildcardComponentId) return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Check if a detailed type represents a relation (entity or component)
  */

src/core/entity-relation.ts

@@ -119,23 +119,23 @@ export function getIdType(
   if (isEntityId(id)) return "entity";
 
   if (id < 0) {
-    try {
-      const decoded = decodeRelationId(id as RelationId<any>);
-      // Validate that componentId and targetId are valid (decodeRelationId already checks componentId)
-      if (decoded.type !== "wildcard" && !isEntityId(decoded.targetId) && !isComponentId(decoded.targetId)) {
-        return "invalid";
-      }
-      switch (decoded.type) {
-        case "entity":
-          return "entity-relation";
-        case "component":
-          return "component-relation";
-        case "wildcard":
-          return "wildcard-relation";
-      }
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    } catch (_error) {
-      return "invalid"; // fallback for invalid relation IDs
+    const decoded = decodeRelationRaw(id as RelationId<any>);
+    if (decoded === null) return "invalid";
+
+    const { componentId: rawComponentId, targetId: rawTargetId } = decoded;
+
+    // Validate component ID
+    if (!isValidComponentId(rawComponentId)) return "invalid";
+
+    // Determine type based on targetId range
+    if (rawTargetId === WILDCARD_TARGET_ID) {
+      return "wildcard-relation";
+    } else if (isEntityId(rawTargetId as EntityId<any>)) {
+      return "entity-relation";
+    } else if (isComponentId(rawTargetId as ComponentId<any>)) {
+      return "component-relation";
+    } else {
+      return "invalid";
     }
   }
 
@@ -172,34 +172,29 @@ export function getDetailedIdType(id: EntityId<any>):
   }
 
   if (id < 0) {
-    try {
-      const decoded = decodeRelationId(id as RelationId<any>);
-      // Validate that targetId is valid (decodeRelationId already checks componentId)
-      if (decoded.type !== "wildcard" && !isEntityId(decoded.targetId) && !isComponentId(decoded.targetId)) {
-        return { type: "invalid" };
-      }
-      let type: "entity-relation" | "component-relation" | "wildcard-relation";
-
-      switch (decoded.type) {
-        case "entity":
-          type = "entity-relation";
-          break;
-        case "component":
-          type = "component-relation";
-          break;
-        case "wildcard":
-          type = "wildcard-relation";
-          break;
-      }
-
-      return {
-        type,
-        componentId: decoded.componentId,
-        targetId: decoded.targetId as any,
-      };
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    } catch (_error) {
-      // Invalid relation ID
+    const decoded = decodeRelationRaw(id as RelationId<any>);
+    if (decoded === null) {
+      return { type: "invalid" };
+    }
+
+    const { componentId: rawComponentId, targetId: rawTargetId } = decoded;
+
+    // Validate component ID
+    if (!isValidComponentId(rawComponentId)) {
+      return { type: "invalid" };
+    }
+
+    const componentId = rawComponentId as ComponentId<any>;
+    const targetId = rawTargetId as EntityId<any>;
+
+    // Determine type based on targetId range
+    if (targetId === WILDCARD_TARGET_ID) {
+      return { type: "wildcard-relation", componentId, targetId };
+    } else if (isEntityId(targetId)) {
+      return { type: "entity-relation", componentId, targetId };
+    } else if (isComponentId(targetId as any)) {
+      return { type: "component-relation", componentId, targetId: targetId as ComponentId<any> };
+    } else {
       return { type: "invalid" };
     }
   }
@@ -227,24 +222,33 @@ export function inspectEntityId(id: EntityId<any>): string {
   }
 
   if (id < 0) {
-    try {
-      const decoded = decodeRelationId(id as RelationId<any>);
-      // Validate that targetId is valid (decodeRelationId already checks componentId)
-      if (decoded.type !== "wildcard" && !isEntityId(decoded.targetId) && !isComponentId(decoded.targetId)) {
-        return `Invalid Relation ID (${id})`;
-      }
-      const componentStr = `Component ID (${decoded.componentId})`;
-      const targetStr =
-        decoded.type === "entity"
-          ? `Entity ID (${decoded.targetId})`
-          : decoded.type === "component"
-            ? `Component ID (${decoded.targetId})`
-            : "Wildcard (*)";
-      return `Relation ID: ${componentStr} -> ${targetStr}`;
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    } catch (_error) {
+    const decoded = decodeRelationRaw(id as RelationId<any>);
+    if (decoded === null) {
+      return `Invalid Relation ID (${id})`;
+    }
+
+    const { componentId: rawComponentId, targetId: rawTargetId } = decoded;
+
+    // Validate component ID
+    if (!isValidComponentId(rawComponentId)) {
       return `Invalid Relation ID (${id})`;
     }
+
+    // Determine target type and format output
+    const componentStr = `Component ID (${rawComponentId})`;
+    let targetStr: string;
+
+    if (rawTargetId === WILDCARD_TARGET_ID) {
+      targetStr = "Wildcard (*)";
+    } else if (isEntityId(rawTargetId as EntityId<any>)) {
+      targetStr = `Entity ID (${rawTargetId})`;
+    } else if (isComponentId(rawTargetId as ComponentId<any>)) {
+      targetStr = `Component ID (${rawTargetId})`;
+    } else {
+      return `Invalid Relation ID (${id})`;
+    }
+
+    return `Relation ID: ${componentStr} -> ${targetStr}`;
   }
 
   return `Unknown ID (${id})`;

src/core/serialization.ts

@@ -7,9 +7,17 @@ import { getComponentIdByName, getComponentNameById, getDetailedIdType, relation
 
 export type SerializedEntityId = number | string | { component: string; target: number | string | "*" };
 
+/**
+ * Serialized state of EntityIdManager
+ */
+export interface SerializedEntityIdManager {
+  nextId: number;
+  freelist?: number[];
+}
+
 export type SerializedWorld = {
   version: number;
-  entityManager: any;
+  entityManager: SerializedEntityIdManager;
   entities: SerializedEntity[];
   componentEntities?: SerializedEntity[];
 };
@@ -43,11 +51,13 @@ export function encodeEntityId(id: EntityId<any>): SerializedEntityId {
       if (!componentName) {
         console.warn(`Component ID ${detailed.componentId} in relation has no registered name`);
       }
-      return { component: componentName || (detailed.componentId as number).toString(), target: detailed.targetId! };
+      // Safe: targetId is guaranteed to exist for entity-relation type
+      return { component: componentName || (detailed.componentId as number).toString(), target: detailed.targetId };
     }
     case "component-relation": {
       const componentName = getComponentNameById(detailed.componentId);
-      const targetName = getComponentNameById(detailed.targetId! as ComponentId);
+      // Safe: targetId is guaranteed to exist for component-relation type
+      const targetName = getComponentNameById(detailed.targetId as ComponentId);
       if (!componentName) {
         console.warn(`Component ID ${detailed.componentId} in relation has no registered name`);
       }

src/core/types.ts

@@ -1,5 +1,17 @@
 import type { EntityId, WildcardRelationId } from "./entity";
 
+/**
+ * Type-erased component ID, used for runtime container storage
+ * @internal
+ */
+export type AnyComponentId = EntityId<any>;
+
+/**
+ * Type-erased entity ID, used for runtime container storage
+ * @internal
+ */
+export type AnyEntityId = EntityId<any>;
+
 /**
  * Hook types for component lifecycle events
  */

src/core/world-commands.ts

@@ -25,7 +25,8 @@ export function processCommands(
   handleExclusiveRelation: (entityId: EntityId, archetype: Archetype, componentId: ComponentId<any>) => void,
 ): void {
   for (const command of commands) {
-    if (command.type === "set" && command.componentType) {
+    if (command.type === "set") {
+      // TypeScript knows command.componentType and command.component exist
       processSetCommand(
         entityId,
         currentArchetype,
@@ -34,7 +35,8 @@ export function processCommands(
         changeset,
         handleExclusiveRelation,
       );
-    } else if (command.type === "delete" && command.componentType) {
+    } else if (command.type === "delete") {
+      // TypeScript knows command.componentType exists
       processDeleteCommand(entityId, currentArchetype, command.componentType, changeset);
     }
   }

src/core/world-hooks.ts

@@ -199,14 +199,11 @@ function triggerMultiComponentHooks(
 function entityHasAllComponents(ctx: HooksContext, entityId: EntityId, requiredComponents: EntityId<any>[]): boolean {
   return requiredComponents.every((c) => {
     // For wildcard relations, check if the entity has the wildcard relation data
-    // (ctx.get will return an array of matching relations, empty if none exist)
     if (isWildcardRelationId(c)) {
-      try {
-        const wildcardData = ctx.get(entityId, c);
-        return Array.isArray(wildcardData) && wildcardData.length > 0;
-      } catch {
-        return false;
-      }
+      const wildcardResult = ctx.getOptional(entityId, c);
+      if (!wildcardResult) return false;
+      const wildcardData = wildcardResult.value;
+      return Array.isArray(wildcardData) && wildcardData.length > 0;
     }
     return ctx.has(entityId, c);
   });
@@ -224,12 +221,10 @@ function entityHadAllComponentsBefore(
 
     // For wildcard relations, check if the entity still has matching relations
     if (isWildcardRelationId(c)) {
-      try {
-        const wildcardData = ctx.get(entityId, c);
-        return Array.isArray(wildcardData) && wildcardData.length > 0;
-      } catch {
-        return false;
-      }
+      const wildcardResult = ctx.getOptional(entityId, c);
+      if (!wildcardResult) return false;
+      const wildcardData = wildcardResult.value;
+      return Array.isArray(wildcardData) && wildcardData.length > 0;
     }
     return ctx.has(entityId, c);
   });

src/core/world.ts

@@ -4,6 +4,7 @@ import { serializeQueryFilter, type QueryFilter } from "../query/filter";
 import { Query } from "../query/query";
 import { getOrCreateWithSideEffect } from "../utils/utils";
 import { Archetype, MISSING_COMPONENT } from "./archetype";
+import { hasWildcardRelation } from "./archetype-helpers";
 import { EntityBuilder } from "./builder";
 import type { ComponentId, EntityId, WildcardRelationId } from "./entity";
 import {
@@ -129,7 +130,8 @@ export class World {
         for (const compType of componentTypes) {
           const detailedType = getDetailedIdType(compType);
           if (detailedType.type === "entity-relation") {
-            trackEntityReference(this.entityReferences, entityId, compType, detailedType.targetId!);
+            // Safe: targetId is guaranteed to exist for entity-relation type
+            trackEntityReference(this.entityReferences, entityId, compType, detailedType.targetId);
           } else if (detailedType.type === "entity") {
             trackEntityReference(this.entityReferences, entityId, compType, compType);
           }
@@ -456,10 +458,7 @@ export class World {
         const data = this.componentEntityComponents.get(entityId);
         if (!data) return false;
 
-        for (const key of data.keys()) {
-          if (getComponentIdFromRelationId(key) === componentId) return true;
-        }
-        return false;
+        return hasWildcardRelation(data, componentId);
       }
 
       return this.componentEntityComponents.get(entityId)?.has(componentType) ?? false;
@@ -516,7 +515,8 @@ export class World {
             if (getComponentIdFromRelationId(key) === componentId) {
               const detailed = getDetailedIdType(key);
               if (detailed.type === "entity-relation" || detailed.type === "component-relation") {
-                relations.push([detailed.targetId!, value]);
+                // Safe: targetId is guaranteed to exist for entity-relation and component-relation types
+                relations.push([detailed.targetId, value]);
               }
             }
           }
@@ -591,7 +591,8 @@ export class World {
           if (getComponentIdFromRelationId(key) === componentId) {
             const detailed = getDetailedIdType(key);
             if (detailed.type === "entity-relation" || detailed.type === "component-relation") {
-              relations.push([detailed.targetId!, value]);
+              // Safe: targetId is guaranteed to exist for entity-relation and component-relation types
+              relations.push([detailed.targetId, value]);
             }
           }
         }