perf: optimize ACL role lookups with Map indexes and caching

[msotnikov]

Replace O(n) linear scans in getRole(), getRoleByName(), and expandRoles() with Map-based lookups. Add WeakMap caches keyed by introspection object for role-by-id, role-by-name,
auth_members-by-member-id indexes, and expandRoles results. This significantly improves performance for schemas with many roles, where these functions are called repeatedly during introspection.

Description

During PostGraphile introspection, getRole(), getRoleByName(), and expandRoles() are called repeatedly for every entity's ACL resolution. The original implementation uses Array.find() and
Array.includes() which are O(n) per call, and expandRoles() iterates the full auth_members array for each role. For schemas with many roles this becomes a significant bottleneck.

This PR introduces:

• Map-based indexes for role-by-id and role-by-name lookups (O(1) instead of O(n))
• Map-based index for auth_members grouped by member id (avoids full array scan in expandRoles)
• Set-based visited tracking in expandRoles (O(1) membership check instead of Array.includes)
• Per-introspection result caching for single-role expandRoles calls (the common path) via WeakMap

All caches use WeakMap<Introspection, ...> so they are automatically garbage-collected when the introspection object is no longer referenced. The public API is unchanged.

Performance impact

Significant improvement for schemas with many roles. Role lookups go from O(n) to O(1). expandRoles avoids redundant full scans of auth_members and caches results for repeated calls with the same role.
The overhead of building indexes is amortized over the many calls that use them during a single introspection cycle.

Security impact

None. This is a purely internal optimization with no changes to the public API or behavior.

Checklist

• My code matches the project's code style and yarn lint:fix passes.
• I've added tests for the new feature, and yarn test passes.
• I have detailed the new feature in the relevant documentation.
• I have added this feature to 'Pending' in the RELEASE_NOTES.md file (if one exists).
• If this is a breaking change I've explained why.

Notes on checklist:

• Tests added for expandRoles, aclContainsRole, and resolvePermissions (37/37 pass), covering role inheritance, NOINHERIT, caching, and circular membership.
• No documentation changes needed — this is an internal optimization with no API changes.
• RELEASE_NOTES.md does not exist for pg-introspection.
• No breaking changes.

[changeset-bot]

🦋 Changeset detected

Latest commit: 86aab72

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages

Name	Type
pg-introspection	Patch
graphile-build-pg	Patch
pgl	Patch
graphile-utils	Patch
postgraphile	Patch
graphile	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR