Add in-flight request deduplication for identical reads

[Lakes41]

Difficulty: Advanced

Type: Feature

Summary

Deduplicate concurrent identical read requests so the SDK does not issue multiple network calls for the same access, membership, role, or guild lookup at the same time.

Current Behaviour

Caching only helps after the first request has completed. If multiple callers request the same key concurrently, each call can still hit the network.

Expected Behaviour

When cache is enabled, concurrent identical reads should share the same in-flight promise and resolve to the same result.

Suggested Implementation

Add an internal in-flight request map keyed by the same cache key used for read caching. Remove entries after resolution or rejection. Ensure rejected requests do not poison future calls.

Files or Areas Likely Affected

• src/client/GuildPassClient.ts
• src/cache/cache.types.ts
• tests/client.test.ts
• tests/services.test.ts
• docs/sdk-guide.md

Acceptance Criteria

• Concurrent identical guild reads share one network request
• Concurrent identical membership reads share one network request
• Rejected in-flight requests are removed from the deduplication map
• Successful requests are still written to cache
• Deduplication is scoped by full cache key
• Tests prove only one raw service call occurs for concurrent identical reads

Additional Notes

This should be enabled only for safe read operations.

[gloskull]

Hello, I have 4 years of experience delivering solutions for projects like this, covering backend, frontend, and smart contract development. After carefully reviewing your requirements, I have a clear understanding of the task and am confident in my ability to deliver a clean, efficient, and thoroughly tested solution on time. I prioritize code quality, maintainability, and industry best practices throughout the development process.
My PR will be submitted in under 10hours.