Introduce relationship queries.

[waynemwashuma]

Objective

Introduce a relationship query system that enables traversing entity relationships (e.g. parent–child trees or arbitrary graphs) in both breadth-first and depth-first order. This provides a generic and reusable foundation for hierarchical and graph-based entity systems, with strong type safety.

Solution

• Add VisitEntities interface: Provides a consistent contract for traversal across relationship types through the visit method.Must be implemented by relationship components e.g (e.g. Children, Parent, Neighbour)
• Added RelationshipQuery : Accepts a World, a relationship type (e.g. Children), an optional target type (e.g. Parent), and optional Data/Filter parameters.Can be used to traverse relationship edges in breadth first or depth first order.
• Added test suite for RelationshipQuery which verifies traversal correctness across multiple topologies:
  • Tree with nested children and grandchildren.
  • Grid-like graph of interconnected neighbours.

Tests assert that traversal order and coverage match expectations for BFS and DFS.

Showcase

A RelationshipQuery can be used to walk hierarchies and a graphs consistently:

// Traverse a parent–child tree
const query = new RelationshipQuery(world, Children, Parent, [Entity])
query.treebfs(rootEntity, ([child], [parent]) => {
  // Do something with (parent, child)
})

// Traverse a directed graph of neighbours
const graphQuery = new RelationshipQuery(world, Neighbour)
graphQuery.graphdfs(startEntity, ([neighbour], [self]) => {
  // Visit edges in depth-first order
})

This makes hierarchical propagation (e.g. transforms, constraints) and graph traversals (e.g. connectivity, influence spreading) straightforward and safe across entities.

Migration guide

These changes do not break existing code however:

• Relationship components (like Children and Parent) should now implement VisitEntities.
• For tree traversals, replace manual loops over queries with RelationshipQuery.treebfs or RelationshipQuery.treedfs.
• For graph traversals, replace ad-hoc neighbour iteration with RelationshipQuery.graphbfs or RelationshipQuery.graphdfs.

Checklist

• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.