feat(query): add literal param syntax for mutationInvalidates

[zeriong]

Summary

• Add InvalidateTargetParam type (string | { literal: string }) to @orval/core
• { literal: "@me" } emits "@me" as a string literal in generated code
• Plain string params still resolve to variables.<name> (backward-compatible)

Usage

mutationInvalidates: [
  {
    onMutations: ['updateProfile'],
    invalidates: [
      { query: 'showPetById', params: ['petId'] },          // → variables.petId
      { query: 'getProfile', params: [{ literal: '@me' }] }, // → "@me"
    ],
  },
],

Test plan

• Snapshot test: 3593 passed
• Unit test: 2227 passed (3 pre-existing failures unrelated)
• Typecheck: all 12 packages pass
• ESLint: all 12 packages pass

Closes #3152

Summary by CodeRabbit

New Features

• Added support for literal parameter values in cache invalidation rules. You can now specify fixed values using { literal: 'value' } syntax alongside variable references in mutationInvalidates configuration.

Documentation

• Updated configuration reference documentation with clarification on parameter options, including a syntax-to-generated-code mapping table and practical examples using literal values.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 5e6fe27c-5319-4589-8e40-bec24a454872

📥 Commits

Reviewing files that changed from the base of the PR and between 0099e13 and 7cb234d.

📒 Files selected for processing (1)

• packages/core/src/types.ts

---

📝 Walkthrough

Walkthrough

This PR adds support for literal parameter values in mutationInvalidates configuration. Parameters can now be either string variable references (existing) or { literal: string } objects to emit quoted string literals in generated invalidation code. Type definitions, generation logic, tests, and documentation were updated accordingly.

Changes

Cohort / File(s)	Summary
Type definitions packages/core/src/types.ts, packages/query/src/framework-adapter.ts	Added new InvalidateTargetParam type supporting string | { literal: string }. Updated InvalidateTarget.params to use the new type across array and record forms.
Code generation packages/query/src/mutation-generator.ts	Replaced generateVariableRef with generateParamArg to handle both string variable references (emitting variables.<path>) and literal objects (emitting JSON.stringify(param.literal)). Updated parameter handling for both array and record shapes.
Tests and configuration tests/configs/react-query.config.ts, tests/__snapshots__/react-query/invalidates/endpoints.ts	Added test configuration using { literal: '@me' } syntax in mutation invalidation rules. Updated snapshot to reflect generated invalidation calls using literal parameter values.
Documentation docs/content/docs/reference/configuration/output.mdx	Added clarification showing parameter syntax forms and their mapping to generated getQueryKey(...) invocations with new example demonstrating literal value usage.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A literal hop through the param-space so grand,
No more twisty variables, @me takes a stand!
Type-safe and string-quoted, our queries now glow,
Cache invalidates sweetly—watch mutations go! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(query): add literal param syntax for mutationInvalidates' accurately describes the main change: introducing a new literal param syntax for mutation invalidation configuration.
Linked Issues check	✅ Passed	The PR fully implements the requirements from issue #3152: adds InvalidateTargetParam type supporting both string and { literal: string } syntax, updates code generation to emit literals correctly, maintains backward compatibility, and includes comprehensive test coverage.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the literal param syntax feature: type definitions, code generation logic, documentation, configuration, and snapshot tests. No unrelated modifications were introduced.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In
`@tests/__snapshots__/fetch/mixed-content-responses-force-success/endpoints.ts`:
- Around line 86-93: The error-path unconditionally calls JSON.parse on body
which throws for non-JSON responses; wrap the parse in a try/catch inside the
res.ok false branch (where err is created) and set err.info to the parsed object
on success or to the raw body (or a safe text fallback like body || '') on
failure, preserving res.status in err.status; apply the same safe-parse pattern
to the other identical blocks that reference body, err, and res.status so
non-JSON payloads do not throw SyntaxError and mask the original HTTP error.

In `@tests/__snapshots__/fetch/mixed-content-responses/endpoints.ts`:
- Around line 44-47: The code unconditionally JSON.parse's any non-null body
when building getDataResponse, which will throw for the plain-text 429 payload;
update the getData construction (the body/data assignment logic around the body
variable and getDataResponse typing) to handle 429 specially — e.g., if
res.status === 429 set data to the plain string (or to the getDataResponse429
shape) instead of JSON.parse, or attempt JSON.parse in a try/catch and fall back
to the raw text for non-JSON 429 responses so getDataResponse and
getDataResponse429 are returned without runtime errors.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 909921a6-9a64-4c98-b98c-ef7f306f148a

📥 Commits

Reviewing files that changed from the base of the PR and between 97d1ce2 and 25dcdda.

📒 Files selected for processing (14)

• docs/content/docs/reference/configuration/output.mdx
• packages/core/src/types.ts
• packages/query/src/framework-adapter.ts
• packages/query/src/mutation-generator.ts
• tests/__snapshots__/fetch/mixed-content-responses-force-success/endpoints.ts
• tests/__snapshots__/fetch/mixed-content-responses-force-success/model/getData200.ts
• tests/__snapshots__/fetch/mixed-content-responses-force-success/model/getMixedSuccess200.ts
• tests/__snapshots__/fetch/mixed-content-responses-force-success/model/index.ts
• tests/__snapshots__/fetch/mixed-content-responses/endpoints.ts
• tests/__snapshots__/fetch/mixed-content-responses/model/getData200.ts
• tests/__snapshots__/fetch/mixed-content-responses/model/getMixedSuccess200.ts
• tests/__snapshots__/fetch/mixed-content-responses/model/index.ts
• tests/__snapshots__/react-query/invalidates/endpoints.ts
• tests/configs/react-query.config.ts

[coderabbitai]

♻️ Duplicate comments (1)

tests/__snapshots__/fetch/mixed-content-responses-force-success/endpoints.ts (1)

86-93: ⚠️ Potential issue | 🟠 Major

Error parsing still assumes JSON in three non-JSON error paths.

Line 89, Line 132, and Line 183 unconditionally call JSON.parse(...). If the server returns text/HTML, this throws SyntaxError and masks the original HTTP failure.

💡 Proposed fix (safe parse shared helper)

+const parseErrorInfo = (body: string | null, contentType?: string | null) => {
+  if (body === null) return {};
+  const ct = (contentType ?? '').toLowerCase();
+  if (!ct.includes('json')) return body;
+  try {
+    return JSON.parse(body);
+  } catch {
+    return body;
+  }
+};
...
-    const data = body !== null ? JSON.parse(body) : {};
+    const data = parseErrorInfo(body, res.headers.get('content-type'));
...
-    const data = errorBody !== null ? JSON.parse(errorBody) : {};
+    const data = parseErrorInfo(errorBody, res.headers.get('content-type'));
...
-    const data = body !== null ? JSON.parse(body) : {};
+    const data = parseErrorInfo(body, res.headers.get('content-type'));

#!/bin/bash
# Verify all unconditional JSON.parse error-body sites in this snapshot file.
rg -n --type=ts -C2 'JSON\.parse\((body|errorBody)\)' tests/__snapshots__/fetch/mixed-content-responses-force-success/endpoints.ts

Also applies to: 125-135, 180-187

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@tests/__snapshots__/fetch/mixed-content-responses-force-success/endpoints.ts`
around lines 86 - 93, The error handling unconditionally calls JSON.parse on
body/errorBody (seen around the res.ok check creating err), which throws on
non-JSON responses; update the three sites that parse response bodies (uses of
JSON.parse(body) and JSON.parse(errorBody)) to safely parse: either check
Content-Type for application/json before parsing or wrap JSON.parse in a
try/catch and on failure set err.info to the raw body string (or an empty
object) so the original HTTP error (err.status and message) is preserved; look
for the res, body, err and errorBody variables and replace the direct JSON.parse
calls with a safe-parse helper or inline try/catch to avoid throwing
SyntaxError.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In
`@tests/__snapshots__/fetch/mixed-content-responses-force-success/endpoints.ts`:
- Around line 86-93: The error handling unconditionally calls JSON.parse on
body/errorBody (seen around the res.ok check creating err), which throws on
non-JSON responses; update the three sites that parse response bodies (uses of
JSON.parse(body) and JSON.parse(errorBody)) to safely parse: either check
Content-Type for application/json before parsing or wrap JSON.parse in a
try/catch and on failure set err.info to the raw body string (or an empty
object) so the original HTTP error (err.status and message) is preserved; look
for the res, body, err and errorBody variables and replace the direct JSON.parse
calls with a safe-parse helper or inline try/catch to avoid throwing
SyntaxError.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 9b563c85-614b-4d85-89fb-012219c03f91

📥 Commits

Reviewing files that changed from the base of the PR and between 25dcdda and 0099e13.

📒 Files selected for processing (14)

• docs/content/docs/reference/configuration/output.mdx
• packages/core/src/types.ts
• packages/query/src/framework-adapter.ts
• packages/query/src/mutation-generator.ts
• tests/__snapshots__/fetch/mixed-content-responses-force-success/endpoints.ts
• tests/__snapshots__/fetch/mixed-content-responses-force-success/model/getData200.ts
• tests/__snapshots__/fetch/mixed-content-responses-force-success/model/getMixedSuccess200.ts
• tests/__snapshots__/fetch/mixed-content-responses-force-success/model/index.ts
• tests/__snapshots__/fetch/mixed-content-responses/endpoints.ts
• tests/__snapshots__/fetch/mixed-content-responses/model/getData200.ts
• tests/__snapshots__/fetch/mixed-content-responses/model/getMixedSuccess200.ts
• tests/__snapshots__/fetch/mixed-content-responses/model/index.ts
• tests/__snapshots__/react-query/invalidates/endpoints.ts
• tests/configs/react-query.config.ts

✅ Files skipped from review due to trivial changes (8)

• tests/snapshots/fetch/mixed-content-responses/model/getMixedSuccess200.ts
• tests/snapshots/react-query/invalidates/endpoints.ts
• tests/snapshots/fetch/mixed-content-responses-force-success/model/index.ts
• tests/snapshots/fetch/mixed-content-responses-force-success/model/getMixedSuccess200.ts
• tests/snapshots/fetch/mixed-content-responses/model/index.ts
• tests/snapshots/fetch/mixed-content-responses-force-success/model/getData200.ts
• tests/snapshots/fetch/mixed-content-responses/endpoints.ts
• tests/snapshots/fetch/mixed-content-responses/model/getData200.ts

🚧 Files skipped from review as they are similar to previous changes (4)

• docs/content/docs/reference/configuration/output.mdx
• tests/configs/react-query.config.ts
• packages/query/src/mutation-generator.ts
• packages/core/src/types.ts