Support relationship direction and bidirectional relationships

[kornelrabczak]

Summary

Add support for specifying relationship direction (OUTGOING, INCOMING) and bidirectional relationships in the @RelationshipEntity annotation and related metadata classes.

Current Behavior

Currently, the @RelationshipEntity annotation only defines:

• type - relationship type name
• nodeType - single type for both source and target (requires same type)
• sourceField / targetField - field names for endpoints

There is no concept of:

1. Direction - relationships are implicitly directional but direction cannot be specified or controlled
2. Bidirectional - no way to mark a relationship as traversable in both directions
3. Heterogeneous node types - source and target must be the same type

Proposed Solution

1. Add Direction Enum

public enum RelationshipDirection {
    OUTGOING,   // (source)-[rel]->(target)
    INCOMING,   // (source)<-[rel]-(target)
    BIDIRECTIONAL  // traversable in both directions
}

2. Extend @RelationshipEntity Annotation

@RelationshipEntity(
    type = "FRIEND_OF",
    sourceType = Person.class,
    targetType = Person.class,
    sourceField = "from",
    targetField = "to",
    direction = RelationshipDirection.BIDIRECTIONAL
)
public class FriendRelationship {
    @Id
    private String id;
    private Person from;
    private Person to;
    private LocalDate since;
}

3. Update RelationshipMetadata

• Add direction field
• Support different source and target types
• Generate direction-aware Cypher patterns

Use Cases

1. Social Graph: Friendships are bidirectional - if A is friends with B, B is friends with A
2. Hierarchical Data: Parent-child relationships where direction matters
3. Mixed Entity Types: Person WORKS_AT Company where source and target are different types

Impact

• Breaking change: nodeType() could be deprecated in favor of sourceType()/targetType()
• Requires updates to RelationshipMetadata and query generation logic
• Consider backward compatibility for existing single-type relationships