feat: add serialize mutation option for queued (serialised) mutations

[zedrdave]

Summary

Adds first-class support for serialised (queued) mutations via a new serialize option on MutationOptions, wrapping TanStack Query v5 mutation scope with an ergonomic, typed, auto-keyed API. Replaces consumer-side hacks (e.g. manual save queues) for auto-save / last-write-wins flows.

Changes

• serialize?: boolean | string on MutationOptions:
  • true derives the scope id from the operation's method + resolved path (e.g. serialize:PATCH:/api/contract/123), so mutations of the same resource queue automatically while different resources stay concurrent
  • a string is used verbatim as the scope id for cross-operation grouping
• Explicit scope passed by the caller wins over serialize (warning emitted once)
• Deferred path params (supplied at mutateAsync) fall back to the path-template scope id: coarser but correct, documented in typedoc and README
• serialize is stripped before options reach useMutation (does not leak)
• Per-call serialize on mutation vars deliberately omitted: TanStack scope is static per observer, so a per-call override would be a silent no-op

Tests

• tests/unit/mutation-serialize.test.ts (7 tests): sequential execution with deferred-promise mocks, concurrency guard without serialize, cross-operation string scope, explicit-scope-wins + single warning, order preservation, error in first does not block queued second, no leak into axios config
• tests/typing/mutation-serialize.ts: boolean | string accepted, number rejected

Release

• Version bump 0.22.0 → 0.23.0 (minor, new feature)
• CHANGELOG entry, README 'Serialised mutations' section

Validation

• npm run check (types, types:test, lint, format:check) ✅
• npx vitest run tests/unit/mutation-serialize.test.ts → 7/7 ✅

Implements the plan in OPENAPI_SERIAL.md via a reviewed subagent chain (implement → test → review → finalize → quality gate).

[Copilot]

Pull request overview

Adds first-class support for serialised (queued) mutations via a new serialize?: boolean | string option on mutation options, mapping to TanStack Query v5 mutation scope and documenting/testing the behavior.

Changes:

• Introduces serialize on MutationOptions and derives a TanStack scope.id automatically from method + resolved path (or uses a caller-provided string scope).
• Implements serialization scope handling in useEndpointMutation, including “explicit scope wins” warning behavior and ensuring serialize doesn’t leak to axios.
• Adds unit + typing tests, plus README/CHANGELOG updates and a version bump.

Reviewed changes

Copilot reviewed 8 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/unit/mutation-serialize.test.ts	New unit tests covering queued execution, precedence rules, and non-leakage.
tests/typing/mutation-serialize.ts	New compile-time checks for serialize’s accepted/rejected types.
src/types.ts	Adds serialize?: boolean | string to MutationOptions with detailed docs.
src/openapi-mutation.ts	Derives/passes TanStack mutation scope from serialize and handles precedence + warning.
README.md	Documents “Serialised mutations” usage and caveats.
package.json	Bumps version to 0.23.0.
package-lock.json	Updates lockfile version metadata to 0.23.0.
CHANGELOG.md	Adds 0.23.0 entry documenting the new feature.
.prettierignore	Ignores subagent artifact directory.
.gitignore	Ignores subagent artifact directory.