@codehz/ecs 0.3.15 → 0.4.0

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@codehz/ecs",
-  "version": "0.3.15",
+  "version": "0.4.0",
   "type": "module",
   "main": "./index.mjs",
   "types": "./index.d.mts",
   "exports": {
-    ".": {
+    "./index": {
       "types": "./index.d.mts",
       "import": "./index.mjs"
+    },
+    "./testing": {
+      "types": "./testing.d.mts",
+      "import": "./testing.mjs"
     }
   },
   "peerDependencies": {

package/testing.d.mts

@@ -0,0 +1,305 @@
+import { S as relation, f as RelationId, m as component, n as World, o as LifecycleHook, p as WildcardRelationId, r as Query, s as ComponentId, u as EntityId } from "./world.mjs";
+
+//#region src/testing.d.ts
+
+/**
+ * A component definition for entity building, supporting both regular components and relations
+ */
+type ComponentDef<T = unknown> = {
+  type: "component";
+  id: EntityId<T>;
+  value: T;
+} | {
+  type: "relation";
+  componentId: ComponentId<T>;
+  targetId: EntityId<any>;
+  value: T;
+};
+/**
+ * Snapshot of a single entity's component state
+ */
+interface EntitySnapshot {
+  entity: EntityId;
+  components: Map<EntityId<any>, unknown>;
+}
+/**
+ * Snapshot of multiple entities' component state
+ */
+interface WorldSnapshot {
+  entities: EntitySnapshot[];
+}
+/**
+ * Result of comparing two snapshots
+ */
+interface SnapshotDiff {
+  /** Entities that exist in 'after' but not in 'before' */
+  addedEntities: EntityId[];
+  /** Entities that exist in 'before' but not in 'after' */
+  removedEntities: EntityId[];
+  /** Changes to components on existing entities */
+  componentChanges: Array<{
+    entity: EntityId;
+    componentId: EntityId<any>;
+    before: unknown | undefined;
+    after: unknown | undefined;
+    changeType: "added" | "removed" | "modified";
+  }>;
+}
+/**
+ * A test fixture that manages a World instance and provides convenient
+ * methods for setting up test scenarios.
+ *
+ * @example
+ * ```typescript
+ * const fixture = new WorldFixture();
+ *
+ * // Spawn entities with fluent API
+ * const player = fixture
+ *   .spawn()
+ *   .with(PositionId, { x: 0, y: 0 })
+ *   .with(HealthId, { current: 100, max: 100 })
+ *   .build();
+ *
+ * // Access the world for running systems
+ * movementSystem(fixture.world);
+ *
+ * // Clean up (optional - creates a fresh world)
+ * fixture.reset();
+ * ```
+ */
+declare class WorldFixture {
+  private _world;
+  private _queries;
+  constructor();
+  /**
+   * Get the underlying World instance
+   */
+  get world(): World;
+  /**
+   * Create a new EntityBuilder for spawning an entity with components
+   */
+  spawn(): EntityBuilder;
+  /**
+   * Spawn multiple entities with the same component configuration
+   * @param count Number of entities to spawn
+   * @param configure Function to configure each entity builder
+   * @returns Array of created entity IDs
+   */
+  spawnMany(count: number, configure: (builder: EntityBuilder, index: number) => EntityBuilder): EntityId[];
+  /**
+   * Create a query and track it for automatic cleanup
+   * @param componentTypes Component types to query for
+   * @returns Query instance
+   */
+  createQuery(componentTypes: EntityId<any>[]): Query;
+  /**
+   * Execute pending commands (alias for world.sync())
+   */
+  sync(): void;
+  /**
+   * Reset the fixture with a fresh World instance
+   * Disposes all tracked queries
+   */
+  reset(): void;
+  /**
+   * Capture a snapshot of specified entities and their components
+   * @param entities Entities to capture
+   * @param componentIds Components to include in the snapshot
+   */
+  captureSnapshot(entities: EntityId[], componentIds: EntityId<any>[]): WorldSnapshot;
+  /**
+   * Symbol.dispose implementation for automatic resource management
+   */
+  [Symbol.dispose](): void;
+}
+/**
+ * Fluent builder for creating entities with components.
+ * Supports both regular components and entity relations.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const entity = new EntityBuilder(world)
+ *   .with(PositionId, { x: 10, y: 20 })
+ *   .with(VelocityId, { x: 1, y: 0 })
+ *   .build();
+ *
+ * // With relations
+ * const child = new EntityBuilder(world)
+ *   .with(PositionId, { x: 0, y: 0 })
+ *   .withRelation(ParentId, parentEntity, { offset: { x: 5, y: 5 } })
+ *   .build();
+ *
+ * // Tag component (void type)
+ * const tagged = new EntityBuilder(world)
+ *   .withTag(PlayerTagId)
+ *   .build();
+ * ```
+ */
+declare class EntityBuilder {
+  private world;
+  private components;
+  constructor(world: World);
+  /**
+   * Add a component to the entity being built
+   * @param componentId The component ID
+   * @param value The component value
+   */
+  with<T>(componentId: EntityId<T>, value: T): this;
+  /**
+   * Add a tag component (void type) to the entity being built
+   * @param componentId The component ID (must be void type)
+   */
+  withTag(componentId: EntityId<void>): this;
+  /**
+   * Add a relation component targeting another entity
+   * @param componentId The base component ID for the relation
+   * @param targetEntity The target entity
+   * @param value The component value
+   */
+  withRelation<T>(componentId: ComponentId<T>, targetEntity: EntityId<any>, value: T): this;
+  /**
+   * Add a relation tag (void type) targeting another entity
+   * @param componentId The base component ID for the relation
+   * @param targetEntity The target entity
+   */
+  withRelationTag(componentId: ComponentId<void>, targetEntity: EntityId<any>): this;
+  /**
+   * Build the entity and return its ID.
+   * This creates the entity, sets all components, and calls sync().
+   */
+  build(): EntityId;
+  /**
+   * Build the entity without calling sync().
+   * Useful when batching multiple entity creations.
+   */
+  buildDeferred(): EntityId;
+}
+/**
+ * Test assertion utilities that return boolean values or throw descriptive errors.
+ * These work with any testing framework's expect() function.
+ *
+ * @example
+ * ```typescript
+ * // With bun:test or vitest
+ * expect(Assertions.hasComponent(world, entity, PositionId)).toBe(true);
+ * expect(Assertions.getComponent(world, entity, PositionId)).toEqual({ x: 10, y: 20 });
+ *
+ * // Direct assertion (throws on failure)
+ * Assertions.assertHasComponent(world, entity, PositionId);
+ * Assertions.assertComponentEquals(world, entity, PositionId, { x: 10, y: 20 });
+ * ```
+ */
+declare const Assertions: {
+  /**
+   * Check if an entity has a specific component
+   */
+  hasComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): boolean;
+  /**
+   * Check if an entity does not have a specific component
+   */
+  lacksComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): boolean;
+  /**
+   * Get a component value (returns undefined if entity doesn't exist or doesn't have the component)
+   */
+  getComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): T | undefined;
+  /**
+   * Get all relation instances for a wildcard relation
+   */
+  getRelations<T>(world: World, entity: EntityId, componentId: ComponentId<T>): [EntityId<unknown>, T][] | undefined;
+  /**
+   * Check if an entity has a relation to a specific target
+   */
+  hasRelation<T>(world: World, entity: EntityId, componentId: ComponentId<T>, targetEntity: EntityId<any>): boolean;
+  /**
+   * Check if an entity exists in the world
+   */
+  entityExists(world: World, entity: EntityId): boolean;
+  /**
+   * Check if a query contains specific entities
+   */
+  queryContains(query: Query, ...entities: EntityId[]): boolean;
+  /**
+   * Check if a query contains exactly the specified entities (no more, no less)
+   */
+  queryContainsExactly(query: Query, ...entities: EntityId[]): boolean;
+  /**
+   * Get the count of entities in a query
+   */
+  queryCount(query: Query): number;
+  /**
+   * Assert that an entity has a component (throws if not)
+   */
+  assertHasComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): void;
+  /**
+   * Assert that an entity lacks a component (throws if it has the component)
+   */
+  assertLacksComponent<T>(world: World, entity: EntityId, componentId: EntityId<T>): void;
+  /**
+   * Assert that a component equals an expected value (throws if not)
+   */
+  assertComponentEquals<T>(world: World, entity: EntityId, componentId: EntityId<T>, expected: T): void;
+  /**
+   * Assert that an entity exists (throws if not)
+   */
+  assertEntityExists(world: World, entity: EntityId): void;
+  /**
+   * Assert that an entity does not exist (throws if it exists)
+   */
+  assertEntityNotExists(world: World, entity: EntityId): void;
+  /**
+   * Assert that a query contains specific entities (throws if not)
+   */
+  assertQueryContains(query: Query, ...entities: EntityId[]): void;
+  /**
+   * Assert that a query does not contain specific entities (throws if it does)
+   */
+  assertQueryNotContains(query: Query, ...entities: EntityId[]): void;
+};
+/**
+ * Utilities for capturing and comparing world state snapshots.
+ * Useful for testing that systems produce expected state changes.
+ *
+ * @example
+ * ```typescript
+ * const before = Snapshot.capture(world, [entity], [PositionId, VelocityId]);
+ *
+ * // Run game logic
+ * movementSystem(world, deltaTime);
+ * world.sync();
+ *
+ * const after = Snapshot.capture(world, [entity], [PositionId, VelocityId]);
+ * const diff = Snapshot.compare(before, after);
+ *
+ * expect(diff.componentChanges).toHaveLength(1);
+ * expect(diff.componentChanges[0].changeType).toBe("modified");
+ * ```
+ */
+declare const Snapshot: {
+  /**
+   * Capture a snapshot of specified entities and their components
+   * @param world The world to capture from
+   * @param entities Entities to include in the snapshot
+   * @param componentIds Components to capture for each entity
+   */
+  capture(world: World, entities: EntityId[], componentIds: EntityId<any>[]): WorldSnapshot;
+  /**
+   * Compare two snapshots and return the differences
+   * @param before The 'before' snapshot
+   * @param after The 'after' snapshot
+   */
+  compare(before: WorldSnapshot, after: WorldSnapshot): SnapshotDiff;
+  /**
+   * Check if two snapshots are equal
+   */
+  equals(a: WorldSnapshot, b: WorldSnapshot): boolean;
+};
+/**
+ * Custom assertion error for testing utilities
+ */
+declare class AssertionError extends Error {
+  constructor(message: string);
+}
+//#endregion
+export { AssertionError, Assertions, ComponentDef, type ComponentId, EntityBuilder, type EntityId, EntitySnapshot, type LifecycleHook, type Query, type RelationId, Snapshot, SnapshotDiff, type WildcardRelationId, World, WorldFixture, WorldSnapshot, component, relation };
+//# sourceMappingURL=testing.d.mts.map