Add dedicated Cache for Members with Role Index

[lajczik]

📝 Motivation

Currently, retrieving members associated with a specific role (e.g., using Role#getMembers() or internally via MemberCacheView#getElementsWithRoles) requires JDA to iterate over the entire guild member cache. This operation is $\mathbf{O(N)}$, where $N$ is the total number of members in the guild.

For bots serving large guilds (e.g., $>10,000$ members) that frequently perform role-based operations (like admin list generation, moderation tasks, or role-specific statistics), this continuous full cache scanning leads to significant CPU overhead and slow execution times. Developers often resort to building custom, external role-to-member maps, which adds complexity and potential for data inconsistency.

💡 Proposed Solution

Implement an optional, dedicated reverse index cache that maps Role IDs to a collection of Member IDs:

$$\text{Map<Long, TLongSet> (Role ID -> Set of Member IDs)}$$

This index would be:

1. Optional: Enabled only when needed, to avoid unnecessary memory consumption for smaller guilds.
2. Configurable: Managed through a new CacheFlag.

Proposed Implementation Details

1. New CacheFlag: Introduce a new flag to the JDABuilder:

   public enum CacheFlag {
       // ... existing flags ...
       MEMBER_ROLES_INDEX
   }

2. Usage: Users would enable it like so:

   JDABuilder.createDefault(TOKEN)
       .enableCache(CacheFlag.MEMBER_ROLES_INDEX)
       .build();

3. Performance Impact:

   • Lookup: Operations like Role#getMembers() would become $\mathbf{O(K)}$ (where $K$ is the number of members in the role) or $\mathbf{O(1)}$ (lookup time) instead of $\mathbf{O(N)}$ (full scan).
   • Update Overhead: The cache would need to be updated upon role changes (GuildMemberRoleAddEvent, GuildMemberRoleRemoveEvent), member joins/removes, and cache updates. This is a necessary trade-off for the performance gain.

✅ Benefits

• Massive Performance Gain: Eliminates full cache scans for common role-based queries.
• Standardization: Provides an official, robust, and consistent way to handle this common use case.
• Ease of Use: Simplifies application code by removing the need for manual, custom role indexing logic.