docs: document AppSync per-item cache eviction (evictFromApiCache)#720
Conversation
evictFromApiCache is a runtime AppSync extension called from within a resolver's mapping template or JS code, not a config/CloudFormation property — the plugin already passes templates/code through and already supports per-resolver caching keys, so eviction works today. Document it in the caching guide with VTL and JS examples, covering the mutation-only and key-order constraints. Closes #502
📝 WalkthroughWalkthroughThis PR adds a new documentation section to ChangesCache Eviction Documentation
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
|
doc update. merging, low risk |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@doc/caching.md`:
- Around line 56-58: The VTL and JS eviction examples use "context.arguments.id"
but must include the leading $ to match caching.keys exactly; update the VTL
snippet that sets $keys (and any usage of $util.qr or
$extensions.evictFromApiCache) to use "$context.arguments.id" as the key name,
and likewise update the JS example to use '$context.arguments.id' so the
eviction keys exactly match the resolver cachingKeys strings.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| #set($keys = {}) | ||
| $util.qr($keys.put("context.arguments.id", $ctx.args.id)) | ||
| $extensions.evictFromApiCache("Query", "getNote", $keys) |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
AWS AppSync evictFromApiCache key name format - should the key map use the exact string from the resolver's caching keys configuration including dollar sign prefix?
💡 Result:
When using the evictFromApiCache extension in AWS AppSync, the keys in your mapping object must exactly match the strings defined in your resolver's cachingKeys configuration [1][2][3]. If your cachingKeys configuration includes the dollar sign prefix (e.g., "$context.arguments.id"), you must include that exact string as the key in the mapping object provided to the evictFromApiCache function [2][3]. Key requirements for successful cache eviction include: 1. Exact Match: The map keys must match the configuration exactly, including the dollar sign [2][3]. 2. Order: If you are using multiple caching keys, the entries must be added to the mapping object in the same order they are defined in the resolver's cachingKeys list [1][3][4]. 3. Mapping: Each value in your mapping object should be the actual value you wish to use to identify the specific cache entry (e.g., the specific ID or username) [1][3]. For example, if your caching configuration is: cachingKeys: ['$context.arguments.id'] Your eviction call should look like this: extensions.evictFromApiCache('Query', 'getNote', { '$context.arguments.id': ctx.args.id });
Citations:
- 1: https://docs.aws.amazon.com/appsync/latest/devguide/extensions-js.html
- 2: https://dev.to/aws-builders/appsync-cache-eviction-with-lambda-data-sources-2ne5
- 3: https://aws.amazon.com/blogs/mobile/introducing-server-side-caching-item-eviction-for-aws-appsync/
- 4: https://docs.aws.amazon.com/appsync/latest/devguide/enabling-caching.html
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Show the relevant section around the reported lines
nl -ba doc/caching.md | sed -n '35,70p'Repository: sid88in/serverless-appsync-plugin
Length of output: 120
🏁 Script executed:
#!/bin/bash
set -euo pipefail
awk 'NR>=35 && NR<=70 {printf "%d:%s\n", NR, $0}' doc/caching.mdRepository: sid88in/serverless-appsync-plugin
Length of output: 1258
Fix cache eviction key mapping to exactly match caching.keys (include the $ prefix).
doc/caching.md defines the caching key as '$context.arguments.id' (line 50), but the VTL eviction example uses "context.arguments.id" (line 57), and the JS example similarly uses 'context.arguments.id' (line 69). AppSync eviction keys must match the resolver’s cachingKeys strings exactly (including $), so the examples should use "$context.arguments.id" / '$context.arguments.id'.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@doc/caching.md` around lines 56 - 58, The VTL and JS eviction examples use
"context.arguments.id" but must include the leading $ to match caching.keys
exactly; update the VTL snippet that sets $keys (and any usage of $util.qr or
$extensions.evictFromApiCache) to use "$context.arguments.id" as the key name,
and likewise update the JS example to use '$context.arguments.id' so the
eviction keys exactly match the resolver cachingKeys strings.
1 participant
What
Document AWS AppSync's per-item cache eviction (
evictFromApiCache) indoc/caching.md, with VTL and JavaScript examples.Closes #502.
Why
#502 asks the plugin to "support cache eviction" (AWS item-eviction feature).
There's nothing for the plugin to implement:
$extensions.evictFromApiCache(...)(VTL) /extensions.evictFromApiCache(...)(JS, from@aws-appsync/utils) is a runtime AppSync utility called from within a resolver's mapping template or JS code. It is not a CloudFormation/config property — AppSync evaluates it at request time. The plugin already passes resolver templates and JS code through to AppSync verbatim, and already supports the one prerequisite (per-resolver caching withkeys). So eviction has effectively been usable all along; it just wasn't discoverable from the plugin's docs.This PR closes that gap by adding an "Evicting items from the cache" section to the caching guide.
What's in it
A new section in
doc/caching.md(between "Per resolver caching" and "Flushing the cache") that:keysin the same order.Out of scope (intentional)
No code change. There is no sensible plugin abstraction to add here — eviction is inherently per-resolver runtime logic that lives in the user's template/code, which the plugin already passes through. Whole-cache flushing already exists via the
flush-cachecommand and is cross-referenced from the same page.Testing
Docs-only;
prettier --check doc/caching.mdpasses. No source/tests touched, sobuild/lint/test/test:e2eare unaffected. The VTL and JS snippets mirror AWS's own published examples.Confidence
Summary by CodeRabbit