swaggie 1.8.8 → 1.9.0-alpha.10

package/README.md

@@ -21,7 +21,8 @@ See the [Example section](#example) for a quick demo, or visit the full document
 ## Features
 
 - Generates TypeScript code from OpenAPI 3.0, 3.1, and 3.2 specs
-- Supports multiple HTTP client libraries out of the box: `fetch`, `axios`, `xior`, `SWR + axios`, `Angular 1`, `Angular 2+`, and `TanStack Query`
+- Supports multiple HTTP client libraries out of the box: `fetch`, `axios`, `xior`, `Angular 1`, `Angular 2+`; with optional reactive layers (`swr`, `tsq`) that compose with any compatible HTTP client
+- **Auto-generated mock/stub files** for Vitest and Jest — typed spies for every client method and hook, with ergonomic helpers like `mockSWR()` and `mockQuery()`
 - Custom templates — bring your own to fit your existing codebase
 - Supports `allOf`, `oneOf`, `anyOf`, `$ref`, nullable types, and various enum definitions
 - Handles multiple content types: JSON, plain text, multipart/form-data, URL-encoded, and binary
@@ -72,24 +73,27 @@ swaggie -s https://petstore3.swagger.io/api/v3/openapi.json -o ./client/petstore
 **Available options:**
 
 ```
--V, --version              Output the version number
--c, --config <path>        Path to a JSON configuration file
--s, --src <url|path>       URL or file path to the OpenAPI spec
--o, --out <filePath>       Output file path (omit to print to stdout)
--b, --baseUrl <string>     Default base URL for the generated client (default: "")
--t, --template <string>    Template to use for code generation (default: "axios")
--m, --mode <mode>          Generation mode: "full" or "schemas" (default: "full")
--d, --schemaStyle <style>  Schema object style: "interface" or "type" (default: "interface")
-    --enumStyle <style>    Enum style for plain string enums: "union" or "enum" (default: "union")
-    --enumNamesStyle <s>   Enum member name casing: "original" or "PascalCase" (default: "original")
-    --dateFormat <format>  Date handling in schemas: "Date" or "string"
-    --nullables <strategy> Nullable handling: "include", "nullableAsOptional", or "ignore"
-    --preferAny            Use "any" instead of "unknown" for untyped values (default: false)
-    --skipDeprecated       Exclude deprecated operations from the output (default: false)
-    --servicePrefix        Prefix for service names — useful when generating multiple APIs
-    --allowDots            Use dot notation to serialize nested object query params
-    --arrayFormat          How arrays are serialized: "indices", "repeat", or "brackets"
--h, --help                 Show help
+-V, --version                  Output the version number
+-c, --config <path>            Path to a JSON configuration file
+-s, --src <url|path>           URL or file path to the OpenAPI spec
+-o, --out <filePath>           Output file path (omit to print to stdout)
+-b, --baseUrl <string>         Base URL that will be used as a default value in the clients
+-t, --template <string>        Template to use. Single name: "axios", "fetch", "xior", "ng1", "ng2", "swr", "tsq". Reactive pair: "swr,axios" / "tsq,xior" / etc. (default: "axios")
+-m, --mode <mode>              Generation mode: "full" or "schemas" (default: "full")
+-d, --schemaStyle <style>      Schema object style: "interface" or "type" (default: "interface")
+    --enumStyle <style>        Enum style for plain string enums: "union" or "enum" (default: "union")
+    --enumNamesStyle <s>       Enum member name casing: "original" or "PascalCase" (default: "original")
+    --dateFormat <format>      How date fields are emitted in generated types
+    --nullables <strategy>     Nullable handling: "include", "nullableAsOptional", or "ignore"
+    --preferAny                Use "any" instead of "unknown" for untyped values (default: false)
+    --skipDeprecated           Exclude deprecated operations from the output (default: false)
+    --servicePrefix            Prefix for service names — useful when generating multiple APIs
+    --allowDots                Use dot notation to serialize nested object query params
+    --arrayFormat              How arrays are serialized: "indices", "repeat", or "brackets"
+-C, --useClient                Prepend 'use client'; directive (Next.js App Router + SWR/TSQ)
+    --mocks <path>             Output path for a generated mock/stub file (requires --testingFramework and --out)
+-T, --testingFramework <name>  Framework for generated mocks: "vitest" or "jest" (requires --mocks and --out)
+-h, --help                     Show help
 ```
 
 ### Formatting the Output
@@ -142,24 +146,72 @@ The `$schema` field enables autocompletion and inline documentation in most edit
 
 ## Templates
 
-Swaggie ships with the following built-in templates:
+Swaggie's templates are split into two independent layers that you can combine freely.
 
-| Template    | Description                                                                               |
-| ----------- | ----------------------------------------------------------------------------------------- |
-| `axios`     | Default. Recommended for React, Vue, and similar frameworks                               |
-| `xior`      | Lightweight modern alternative to axios ([xior](https://github.com/suhaotian/xior#intro)) |
-| `swr-axios` | SWR hooks for GET requests, backed by axios                                               |
-| `tsq-xior`  | TanStack Query hooks for GET requests, backed by xior                                     |
-| `fetch`     | Uses the native browser Fetch API                                                         |
-| `ng1`       | Angular 1 client                                                                          |
-| `ng2`       | Angular 2+ client (uses HttpClient and InjectionTokens)                                   |
+### HTTP client templates (L1)
 
-To use a custom template, pass the path to your template directory:
+These are standalone and cover the most common client libraries:
+
+| Template | Description |
+| -------- | ----------- |
+| `axios`  | Default. Recommended for React, Vue, and most Node.js projects |
+| `fetch`  | Native browser/Node 18+ Fetch API — zero runtime dependencies |
+| `xior`   | Lightweight Axios-compatible alternative ([xior](https://github.com/suhaotian/xior#intro)) |
+| `ng1`    | Angular 1 client |
+| `ng2`    | Angular 2+ client (uses `HttpClient` and `InjectionToken`) |
+
+### Reactive query layer templates (L2)
+
+These add a reactive data-fetching layer (SWR or TanStack Query hooks) on top of any compatible L1 client. They cannot be used alone — pair them with an L1 template using a 2-element array:
+
+| Template | Description |
+| -------- | ----------- |
+| `swr`    | [SWR](https://swr.vercel.app) hooks for queries and mutations |
+| `tsq`    | [TanStack Query](https://tanstack.com/query) hooks for queries and mutations |
+
+Compatible L1 templates for L2: `axios`, `fetch`, `xior`. Angular clients are not compatible with reactive layers.
+
+### Usage examples
+
+**Single L1 template (existing behaviour):**
+
+```json
+{ "template": "axios" }
+```
+
+```bash
+swaggie -s ./openapi.json -o ./client.ts -t axios
+```
+
+**L2 + L1 combination — in config:**
+
+```json
+{ "template": ["swr", "axios"] }
+```
+
+```bash
+# CLI: comma-separated pair
+swaggie -s ./openapi.json -o ./client.ts -t swr,axios
+swaggie -s ./openapi.json -o ./client.ts -t tsq,xior
+swaggie -s ./openapi.json -o ./client.ts -t swr,fetch
+```
+
+**L2 alone — defaults to `fetch` as the L1:**
+
+```json
+{ "template": "swr" }
+```
+
+### Custom templates
+
+Pass the path to your own template directory as the template value:
 
 ```bash
 swaggie -s https://petstore3.swagger.io/api/v3/openapi.json -o ./client/petstore.ts --template ./my-swaggie-template/
 ```
 
+Custom paths also work as part of a composite pair: `["./my-l2", "axios"]`.
+
 ---
 
 ## Example
@@ -179,7 +231,7 @@ import Axios, { AxiosPromise } from 'axios';
 
 const axios = Axios.create({
   baseURL: '/api',
-  paramsSerializer: (params) =>
+  paramsSerializer: (params: any) =>
     encodeParams(params, null, {
       allowDots: true,
       arrayFormat: 'repeat',
@@ -359,6 +411,39 @@ Either tool needs to be installed separately and configured for your project.
 
 ---
 
+## Generating Mocks
+
+Swaggie can generate a companion mock file alongside your client — a set of typed spy stubs for every method and hook, ready to drop into your tests.
+
+```bash
+swaggie -s ./spec.json -o ./src/api/client.ts -t swr,axios \
+  --mocks ./src/__mocks__/api.ts --testingFramework vitest
+```
+
+Or in a config file:
+
+```json
+{
+  "src": "./openapi.json",
+  "out": "./src/api/client.ts",
+  "template": ["swr", "axios"],
+  "mocks": "./src/__mocks__/api.ts",
+  "testingFramework": "vitest"
+}
+```
+
+The generated mock file exports the same names as the real client, so `vi.mock('./api', () => import('./__mocks__/api'))` is all you need in tests. For L2 (SWR/TSQ) templates, hook stubs come with shorthand helpers:
+
+```ts
+pet.queries.usePetById.mockSWR({ data: { id: 1, name: 'Rex' } });
+pet.mutations.useAddPet.mockSWRMutation({ isMutating: false });
+// TanStack Query equivalents: mockQuery() / mockMutation()
+```
+
+See the [Mocking guide](https://yhnavein.github.io/swaggie/guide/mocking) for full details.
+
+---
+
 ## Using Swaggie Programmatically
 
 You can also call Swaggie directly from Node.js/bun/deno/etc:

package/dist/browser.js

@@ -9,6 +9,8 @@ var _bundledTemplates = require('./generated/bundledTemplates');
 var _utils = require('./utils/utils');
 var _documentLoaderbrowser = require('./utils/documentLoader.browser');
 var _templateEngine = require('./utils/templateEngine');
+var _templateValidator = require('./utils/templateValidator');
+var _templateManager = require('./utils/templateManager');
 
 /**
  * Browser-friendly code generation entrypoint.
@@ -52,12 +54,27 @@ async function generateCode(spec, options) {
     return _header.FILE_HEADER + _genTypes2.default.call(void 0, spec, options, false);
   }
 
-  const templateFiles = _bundledTemplates.BUNDLED_TEMPLATES[options.template];
-  if (!templateFiles) {
-    throw new Error(`Bundled templates for '${options.template}' are not available`);
+  _templateValidator.validateTemplate.call(void 0, options.template);
+
+  if (Array.isArray(options.template)) {
+    const [l2, l1] = options.template;
+    const l1Files = _bundledTemplates.BUNDLED_TEMPLATES[l1 ];
+    const l2Files = _bundledTemplates.BUNDLED_TEMPLATES[l2 ];
+    if (!l1Files) {
+      throw new Error(`Bundled templates for L1 '${l1}' are not available`);
+    }
+    if (!l2Files) {
+      throw new Error(`Bundled templates for L2 '${l2}' are not available`);
+    }
+    _templateEngine.initTemplateEngineFromBundled.call(void 0, _templateManager.mergeTemplateFiles.call(void 0, l1Files, l2Files));
+  } else {
+    const templateFiles = _bundledTemplates.BUNDLED_TEMPLATES[options.template ];
+    if (!templateFiles) {
+      throw new Error(`Bundled templates for '${options.template}' are not available`);
+    }
+    _templateEngine.initTemplateEngineFromBundled.call(void 0, templateFiles);
   }
 
-  _templateEngine.initTemplateEngineFromBundled.call(void 0, templateFiles);
   const operationsCode = await _genOperations2.default.call(void 0, spec, options);
 
   return operationsCode + _genTypes2.default.call(void 0, spec, options);
@@ -70,6 +87,7 @@ async function generateCode(spec, options) {
   const {
     allowDots,
     arrayFormat,
+    queryParamsAsObject,
     mode,
     schemaStyle,
     enumStyle,
@@ -86,11 +104,12 @@ async function generateCode(spec, options) {
     ),
     ...(allowDots !== undefined ? { allowDots } : {}),
     ...(arrayFormat !== undefined ? { arrayFormat } : {}),
+    ...(queryParamsAsObject !== undefined ? { queryParamsAsObject } : {}),
   };
 
   return {
     ...rest,
-    template: _nullishCoalesce(template, () => ( _swagger.APP_DEFAULTS.template)),
+    template: _templateValidator.normalizeTemplate.call(void 0, _nullishCoalesce(template, () => ( _swagger.APP_DEFAULTS.template))),
     servicePrefix: _nullishCoalesce(rest.servicePrefix, () => ( _swagger.APP_DEFAULTS.servicePrefix)),
     nullableStrategy: _nullishCoalesce(_nullishCoalesce(nullables, () => ( rest.nullableStrategy)), () => ( _swagger.APP_DEFAULTS.nullableStrategy)),
     generationMode: _nullishCoalesce(_nullishCoalesce(mode, () => ( rest.generationMode)), () => ( _swagger.APP_DEFAULTS.generationMode)),

package/dist/cli.js

@@ -13,6 +13,11 @@ const arrayFormatOption = new (0, _commander.Option)(
   'Determines how arrays should be serialized'
 ).choices(['indices', 'repeat', 'brackets']);
 
+const testingFrameworkOption = new (0, _commander.Option)(
+  '-T, --testingFramework <framework>',
+  'Test framework for generated mock stubs (requires --mocks and --out)'
+).choices(['vitest', 'jest']);
+
 const packageJson = readPackageJson();
 
 const modeOption = new (0, _commander.Option)('-m, --mode <mode>', 'Generation mode').choices([
@@ -39,6 +44,10 @@ const nullableStrategyOption = new (0, _commander.Option)(
   '--nullables <strategy>',
   "Controls how OpenAPI 'nullable' is translated into TypeScript types"
 ).choices(['include', 'nullableAsOptional', 'ignore']);
+const queryParamsAsObjectOption = new (0, _commander.Option)(
+  '--queryParamsAsObject [threshold]',
+  'Group query params into a single object; pass a number to group only when query params count is greater than threshold'
+).argParser(parseQueryParamsAsObjectArg);
 
 const program = new (0, _commander.Command)();
 program
@@ -63,9 +72,18 @@ program
   .option('-b, --baseUrl <string>', 'Base URL that will be used as a default value in the clients')
   .option(
     '-t, --template <string>',
-    'Template used for generating API client. Default: "axios". Other: "fetch", "ng1", "ng2", "swr-axios", "xior", "tsq-xior"'
+    'Template used for generating API client. ' +
+      'L1 (HTTP client) templates: "axios" (default), "fetch", "xior", "ng1", "ng2". ' +
+      'L2 (reactive layer) templates must be paired with an L1 using a comma-separated value: ' +
+      '"swr,axios", "swr,fetch", "tsq,xior", "tsq,fetch", etc. ' +
+      'Providing only an L2 name (e.g. "swr") defaults to "fetch" as the L1.',
+    parseTemplateArg
   )
   .option('--preferAny', 'Use "any" type instead of "unknown"')
+  .option(
+    '-C, --useClient',
+    "Prepend 'use client'; to the generated file. Required for Next.js App Router with SWR or TanStack Query hooks"
+  )
   .option(
     '--skipDeprecated',
     'Skip deprecated operations. When enabled, deprecated operations will be skipped from the generated code'
@@ -84,13 +102,19 @@ program
   .addOption(enumStyleOption)
   .addOption(enumNamesStyleOption)
   .addOption(dateFormatOption)
-  .addOption(nullableStrategyOption);
+  .addOption(nullableStrategyOption)
+  .addOption(queryParamsAsObjectOption)
+  .option(
+    '--mocks <path>',
+    'Output path for the generated mock/stub file (requires --testingFramework and --out)'
+  )
+  .addOption(testingFrameworkOption);
 
 program.parse(process.argv);
 
 const options = program.opts();
 
-_index.runCodeGenerator.call(void 0, options).then(complete, error);
+_index.runCodeGenerator.call(void 0, options ).then(complete, error);
 
 function complete([code, opts]) {
   if (opts.out) {
@@ -116,3 +140,29 @@ function readPackageJson() {
     throw new Error('Could not read package.json file');
   }
 }
+
+function parseTemplateArg(value) {
+  const parts = value.split(',').map((s) => s.trim());
+  if (parts.length === 1) {
+    return parts[0];
+  }
+  if (parts.length === 2) {
+    return [parts[0], parts[1]];
+  }
+  throw new Error(
+    `--template accepts at most 2 comma-separated values (e.g. "swr,axios"). Got ${parts.length}.`
+  );
+}
+
+function parseQueryParamsAsObjectArg(value) {
+  if (value === undefined) {
+    return true;
+  }
+
+  const threshold = Number(value);
+  if (!Number.isInteger(threshold) || threshold < 0) {
+    throw new Error('--queryParamsAsObject threshold must be a non-negative integer');
+  }
+
+  return threshold;
+}

package/dist/gen/genMocks.js

@@ -0,0 +1,316 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _case = require('case');
+
+
+var _swagger = require('../swagger');
+var _utils = require('../utils/utils');
+var _templateValidator = require('../utils/templateValidator');
+var _genOperations = require('./genOperations');
+
+
+
+const MOCK_FILE_HEADER = `\
+/* istanbul ignore file -- auto-generated test helper */
+/* tslint:disable */
+/* eslint-disable */
+//----------------------
+// <auto-generated>
+//   Generated using Swaggie (https://github.com/yhnavein/swaggie)
+//   Please avoid doing any manual changes in this file
+// </auto-generated>
+//----------------------
+// biome-ignore-all lint: auto-generated code
+// deno-lint-ignore-file
+`;
+
+/**
+ * Generates a companion mock/stub file for a generated API client.
+ *
+ * The mock file exports:
+ * - Typed spy stubs for every `*Client` object method
+ * - When an L2 template (swr/tsq) is active: hook stubs wrapped with
+ *   `withMockSWR` / `withMockQuery` / `withMockMutation` helpers
+ * - `queryKeys` passthrough (re-exported from the real client — not mocked)
+ *
+ * @param spec              The OpenAPI document
+ * @param options           Generator options (must have `testingFramework` set)
+ * @param relativeApiImport Relative import path from the mock file to the real client file
+ */
+ function generateMocks(
+  spec,
+  options,
+  relativeApiImport
+) {
+  const fw = options.testingFramework;
+  const template = options.template;
+  const l2 = getL2Name(template);
+
+  const operations = _swagger.getOperations.call(void 0, spec);
+  const groups = _utils.groupOperationsByGroupName.call(void 0, operations);
+
+  const groupNames = Object.keys(groups);
+  const servicePrefix = options.servicePrefix;
+
+  let result = MOCK_FILE_HEADER;
+
+  // Framework import
+  result += buildFrameworkImport(fw);
+  result += '\n';
+
+  // Real client import — needed for queryKeys passthrough (value import).
+  // Only emitted when there is an L2 (hooks layer).
+  if (l2) {
+    result += `import * as realApi from '${relativeApiImport}';\n`;
+    result += '\n';
+  }
+
+  // Helper functions (only when L2 is present)
+  if (l2 === 'swr') {
+    result += buildSwrHelpers(fw);
+    result += '\n';
+  } else if (l2 === 'tsq') {
+    result += buildTsqHelpers(fw);
+    result += '\n';
+  }
+
+  // Per-group stubs
+  for (const name of groupNames) {
+    const group = groups[name];
+    const fullName = servicePrefix + name;
+    const camelName = _case.camel.call(void 0, fullName);
+    const preparedOps = _genOperations.prepareOperations.call(void 0, group, options, spec.components);
+
+    if (preparedOps.length === 0) {
+      continue;
+    }
+
+    // *Client stub object
+    result += buildClientStub(camelName, preparedOps, fw);
+    result += '\n';
+
+    // Hooks stub object (L2 only)
+    if (l2 === 'swr') {
+      result += buildSwrHooksStub(camelName, preparedOps, fw);
+      result += '\n';
+    } else if (l2 === 'tsq') {
+      result += buildTsqHooksStub(camelName, preparedOps, fw);
+      result += '\n';
+    }
+  }
+
+  return result;
+} exports.default = generateMocks;
+
+// ---------------------------------------------------------------------------
+// Helpers: L2 detection
+// ---------------------------------------------------------------------------
+
+function getL2Name(template) {
+  if (!Array.isArray(template)) {
+    return null;
+  }
+  const [l2] = template;
+  if (_templateValidator.isL2Template.call(void 0, l2)) {
+    return l2 ;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Framework import line
+// ---------------------------------------------------------------------------
+
+function buildFrameworkImport(fw) {
+  if (fw === 'vitest') {
+    return "import { vi } from 'vitest';\n";
+  }
+  return "import { jest } from '@jest/globals';\n";
+}
+
+function fn(fw) {
+  return fw === 'vitest' ? 'vi.fn()' : 'jest.fn()';
+}
+
+// ---------------------------------------------------------------------------
+// SWR helper functions
+// ---------------------------------------------------------------------------
+
+function buildSwrHelpers(fw) {
+  const fnRef = fw === 'vitest' ? 'vi' : 'jest';
+  return `\
+// ─── SWR mock helpers ────────────────────────────────────────────────────────
+
+/** Augments a spy with a \`mockSWR\` shorthand for useSWR query hooks. */
+function withMockSWR<T extends ReturnType<typeof ${fnRef}.fn>>(spy: T) {
+  return Object.assign(spy, {
+    mockSWR({ data, isLoading, error }: { data?: unknown; isLoading?: boolean; error?: Error }) {
+      spy.mockReturnValue({ data, isLoading: isLoading ?? false, error: error ?? null, mutate: ${fn(fw)} });
+    },
+  });
+}
+
+/** Augments a spy with a \`mockSWRMutation\` shorthand for useSWRMutation hooks. */
+function withMockSWRMutation<T extends ReturnType<typeof ${fnRef}.fn>>(spy: T) {
+  return Object.assign(spy, {
+    mockSWRMutation({ data, isMutating, error }: { data?: unknown; isMutating?: boolean; error?: Error }) {
+      spy.mockReturnValue({ trigger: ${fn(fw)}, isMutating: isMutating ?? false, error: error ?? null, data });
+    },
+  });
+}
+`;
+}
+
+// ---------------------------------------------------------------------------
+// TanStack Query helper functions
+// ---------------------------------------------------------------------------
+
+function buildTsqHelpers(fw) {
+  const fnRef = fw === 'vitest' ? 'vi' : 'jest';
+  return `\
+// ─── TanStack Query mock helpers ─────────────────────────────────────────────
+
+/** Augments a spy with a \`mockQuery\` shorthand for useQuery hooks. */
+function withMockQuery<T extends ReturnType<typeof ${fnRef}.fn>>(spy: T) {
+  return Object.assign(spy, {
+    mockQuery({ data, isLoading, error }: { data?: unknown; isLoading?: boolean; error?: Error }) {
+      const pending = isLoading ?? false;
+      spy.mockReturnValue({
+        data,
+        isLoading: pending,
+        isPending: pending,
+        isFetching: false,
+        isSuccess: data !== undefined && !pending,
+        error: error ?? null,
+        refetch: ${fn(fw)},
+        status: pending ? 'pending' : 'success',
+      });
+    },
+  });
+}
+
+/** Augments a spy with a \`mockMutation\` shorthand for useMutation hooks. */
+function withMockMutation<T extends ReturnType<typeof ${fnRef}.fn>>(spy: T) {
+  return Object.assign(spy, {
+    mockMutation({ data, isPending, error }: { data?: unknown; isPending?: boolean; error?: Error }) {
+      spy.mockReturnValue({
+        mutate: ${fn(fw)},
+        mutateAsync: ${fn(fw)},
+        isPending: isPending ?? false,
+        isSuccess: false,
+        error: error ?? null,
+        data,
+        reset: ${fn(fw)},
+      });
+    },
+  });
+}
+`;
+}
+
+// ---------------------------------------------------------------------------
+// *Client stub object
+// ---------------------------------------------------------------------------
+
+function buildClientStub(
+  camelName,
+  operations,
+  fw
+) {
+  const lines = operations.map((op) => `  ${op.name}: ${fn(fw)},`);
+  return `export const ${camelName}Client = {\n${lines.join('\n')}\n};\n`;
+}
+
+// ---------------------------------------------------------------------------
+// SWR hooks stub object
+// ---------------------------------------------------------------------------
+
+function buildSwrHooksStub(
+  camelName,
+  operations,
+  fw
+) {
+  const getOps = operations.filter((o) => o.method === 'GET');
+  const mutOps = operations.filter((o) => o.method !== 'GET');
+
+  const queryLines = getOps.map((op) => {
+    const hookName = toHookName(op.name, 'use');
+    return `    ${hookName}: withMockSWR(${fn(fw)}),`;
+  });
+
+  const mutationLines = mutOps.map((op) => {
+    const hookName = 'use' + _case.pascal.call(void 0, op.name);
+    return `    ${hookName}: withMockSWRMutation(${fn(fw)}),`;
+  });
+
+  return [
+    `export const ${camelName} = {`,
+    `  queries: {`,
+    ...queryLines,
+    `  },`,
+    ``,
+    `  mutations: {`,
+    ...mutationLines,
+    `  },`,
+    ``,
+    `  // queryKeys are pure functions — no mocking needed`,
+    `  queryKeys: realApi.${camelName}.queryKeys,`,
+    `};\n`,
+  ].join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// TanStack Query hooks stub object
+// ---------------------------------------------------------------------------
+
+function buildTsqHooksStub(
+  camelName,
+  operations,
+  fw
+) {
+  const getOps = operations.filter((o) => o.method === 'GET');
+  const mutOps = operations.filter((o) => o.method !== 'GET');
+
+  const queryLines = getOps.map((op) => {
+    const hookName = toHookName(op.name, 'use');
+    return `    ${hookName}: withMockQuery(${fn(fw)}),`;
+  });
+
+  const mutationLines = mutOps.map((op) => {
+    const hookName = 'use' + _case.pascal.call(void 0, op.name);
+    return `    ${hookName}: withMockMutation(${fn(fw)}),`;
+  });
+
+  return [
+    `export const ${camelName} = {`,
+    `  queries: {`,
+    ...queryLines,
+    `  },`,
+    ``,
+    `  mutations: {`,
+    ...mutationLines,
+    `  },`,
+    ``,
+    `  // queryKeys are pure functions — no mocking needed`,
+    `  queryKeys: realApi.${camelName}.queryKeys,`,
+    `};\n`,
+  ].join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Shared name helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Converts an operation name to a React hook name.
+ * Strips a leading "get" prefix (case-insensitive) and capitalises, then
+ * prepends the given prefix (e.g. "use").
+ *
+ * @example toHookName('findPetsByStatus', 'use') → 'useFindPetsByStatus'
+ * @example toHookName('getPetById', 'use')       → 'usePetById'
+ */
+function toHookName(operationName, prefix) {
+  const stripped = operationName.toLowerCase().startsWith('get')
+    ? operationName.slice(3)
+    : operationName;
+  const capitalised = stripped.charAt(0).toUpperCase() + stripped.slice(1);
+  return prefix + capitalised;
+}