Skip to content

Document cache key format and TTL precedence rules - #413

Merged
Lakes41 merged 1 commit into
Adamantine-guild:mainfrom
Joyful12-tech:docs/cache-key-format-and-ttl-precedence
Jul 28, 2026
Merged

Document cache key format and TTL precedence rules#413
Lakes41 merged 1 commit into
Adamantine-guild:mainfrom
Joyful12-tech:docs/cache-key-format-and-ttl-precedence

Conversation

@Joyful12-tech

Copy link
Copy Markdown
Contributor

Summary

This PR adds documentation for exact cache key formats and TTL precedence rules, as requested in #392.

Changes

docs/cache-adapters.md

  • Key Composition (new section): Lists the exact cache key template for every cached service method (checkAccess, checkRoleAccess, getMembership, getRoles, getUserRoles, getGuild, getGuildConfig), verified against the actual source in src/client/GuildPassClient.ts.
  • TTL Precedence (new subsection): Clarifies that only the client-level cacheTtl applies, with a concrete worked example.
  • Fixed inaccurate claim: The previous docs stated that "methods that accept a per-call override subtract elapsed time from the deadline before storing." This is incorrect — there is no per-call TTL override in the current implementation (withCache always passes this.cacheTtl). The text now accurately reflects the source.
  • Added a note that the wallet: prefix is an invalidation-only namespace.

docs/sdk-guide.md

  • Added cross-link to the new Key Composition section.

docs/architecture.md

  • Added cross-links to the Key Composition and TTL Precedence sections under the Caching Layer bullet.

Discrepancy noted

The issue's acceptance criteria asked for a worked example with a per-call TTL override. No such override exists in the current implementation — RequestOptions carries timeoutMs, retry, and signal but no cacheTtl field, and withCache() always uses the client-level cacheTtl. The documentation reflects this accurately rather than inventing a feature.

Closes #392

@Lakes41

Lakes41 commented Jul 28, 2026

Copy link
Copy Markdown
Contributor

This PR cannot be merged automatically because it has merge conflicts.

Please update the branch with the latest base branch and resolve the conflicts.

After the conflicts are resolved and checks pass, the automation can review it again.

- Add Key Composition subsection listing exact key templates per service method
- Add TTL Precedence subsection with worked example
- Fix inaccurate per-call TTL override claim in existing docs
- Add cross-links from sdk-guide.md and architecture.md

Closes Adamantine-guild#392
@Joyful12-tech
Joyful12-tech force-pushed the docs/cache-key-format-and-ttl-precedence branch from 1c1e3ab to 75ae166 Compare July 28, 2026 11:35
@Lakes41
Lakes41 merged commit c67635b into Adamantine-guild:main Jul 28, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document cache key format and TTL precedence rules

2 participants