swaggie 1.9.0-dev.1 → 2.0.0

package/dist/gen/genMocks.js

@@ -0,0 +1,453 @@
+"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 = `\
+/* 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:
+ * - `createClientMocks()` — spyOn stubs for every `*Client` method (all templates)
+ * - `ClientMocks` type alias
+ * - `createApiHookMocks()` — spyOn stubs for every hook with ergonomic shorthand
+ *   helpers (`mockSWR`, `mockQuery`, etc.) — L2 templates only (swr/tsq)
+ * - `ApiHookMocks` type alias — L2 templates only
+ *
+ * @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;
+
+  if (template === 'ng1') {
+    throw new Error(
+      'Mock generation is not supported for the "ng1" template. ' +
+        'Use "ng2", "axios", "fetch", "xior", "swr", or "tsq" instead.'
+    );
+  }
+
+  const isNg2 = template === 'ng2';
+  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;
+
+  // Collect prepared operations per group up-front so we iterate once
+  const preparedGroups = groupNames
+    .map((name) => {
+      const fullName = servicePrefix + name;
+      const camelName = _case.camel.call(void 0, fullName);
+      const ops = _genOperations.prepareOperations.call(void 0, groups[name], options, spec.components);
+      return { name, camelName, ops };
+    })
+    .filter((g) => g.ops.length > 0);
+
+  let result = MOCK_FILE_HEADER;
+
+  // Framework import
+  result += buildFrameworkImport(fw);
+  if (l2 === 'swr') {
+    result += buildSwrTypeImport();
+  }
+  result += '\n';
+
+  if (isNg2) {
+    // ng2: type-only import (no Angular DI triggered), MockedService<T> utility, vi.fn()-based stubs
+    result += buildNg2TypeImport(preparedGroups, relativeApiImport);
+    result += '\n';
+    result += buildMockedServiceType();
+    result += '\n';
+    result += buildNg2CreateClientMocks(preparedGroups, fw);
+    result += '\n';
+    result += 'export type ClientMocks = ReturnType<typeof createClientMocks>;\n';
+    return result;
+  }
+
+  // ── Standard path (axios / fetch / xior / swr / tsq) ───────────────────────
+
+  // Real client import — needed for spyOn targets
+  result += `import * as realApi from '${relativeApiImport}';\n`;
+  result += '\n';
+
+  // SWR/TSQ helper functions and default return values (L2 only)
+  if (l2 === 'swr') {
+    result += buildSwrDefaults(fw);
+    result += '\n';
+    result += buildSwrHelpers(fw);
+    result += '\n';
+  } else if (l2 === 'tsq') {
+    result += buildTsqDefaults(fw);
+    result += '\n';
+    result += buildTsqHelpers(fw);
+    result += '\n';
+  }
+
+  // ── createClientMocks ───────────────────────────────────────────────────────
+  result += buildCreateClientMocks(preparedGroups, fw);
+  result += '\n';
+  result += 'export type ClientMocks = ReturnType<typeof createClientMocks>;\n';
+
+  // ── createApiHookMocks (L2 only) ────────────────────────────────────────────
+  if (l2 === 'swr') {
+    result += '\n';
+    result += buildCreateSwrHookMocks(preparedGroups, fw);
+    result += '\n';
+    result += 'export type ApiHookMocks = ReturnType<typeof createApiHookMocks>;\n';
+  } else if (l2 === 'tsq') {
+    result += '\n';
+    result += buildCreateTsqHookMocks(preparedGroups, fw);
+    result += '\n';
+    result += 'export type ApiHookMocks = ReturnType<typeof createApiHookMocks>;\n';
+  }
+
+  return result;
+} exports.default = generateMocks;
+
+function getL2Name(template) {
+  if (!Array.isArray(template)) return null;
+  const [l2] = template;
+  return _templateValidator.isL2Template.call(void 0, l2) ? (l2 ) : null;
+}
+
+/**
+ * Derives the Angular service class name from a camelCase group name.
+ * e.g. "pet" → "PetService", "petstorePet" → "PetstorePetService"
+ */
+function toServiceClassName(camelName) {
+  return camelName.charAt(0).toUpperCase() + camelName.slice(1) + 'Service';
+}
+
+function buildNg2TypeImport(groups, relativeApiImport) {
+  const names = groups.map((g) => toServiceClassName(g.camelName)).join(', ');
+  return `import type { ${names} } from '${relativeApiImport}';\n`;
+}
+
+function buildMockedServiceType() {
+  return `\
+export type MockedService<T> = {
+  [K in keyof T]: T[K] extends (...args: infer A) => infer R ? (...args: A) => R : T[K];
+};
+`;
+}
+
+function buildNg2CreateClientMocks(
+  groups,
+  fw
+) {
+  const lines = ['export function createClientMocks() {', '  return {'];
+
+  for (const { camelName, ops } of groups) {
+    const serviceClass = toServiceClassName(camelName);
+    lines.push(`    ${camelName}Client: {`);
+    for (const op of ops) {
+      if (fw === 'vitest') {
+        lines.push(`      ${op.name}: vi.fn<typeof ${serviceClass}.prototype.${op.name}>(),`);
+      } else {
+        // Jest: bare jest.fn() — no typed fn<F> overload available
+        lines.push(`      ${op.name}: jest.fn(),`);
+      }
+    }
+    if (fw === 'vitest') {
+      lines.push(`    } satisfies MockedService<${serviceClass}>,`);
+    } else {
+      lines.push('    },');
+    }
+  }
+
+  lines.push('  };');
+  lines.push('}');
+  return lines.join('\n') + '\n';
+}
+
+function buildFrameworkImport(fw) {
+  return fw === 'vitest'
+    ? "import { vi } from 'vitest';\n"
+    : "import { jest } from '@jest/globals';\n";
+}
+
+function buildSwrTypeImport() {
+  return "import type { KeyedMutator } from 'swr';\n";
+}
+
+/** Returns the spy function expression for the given framework. */
+function spyFn(fw) {
+  return fw === 'vitest' ? 'vi.spyOn' : 'jest.spyOn';
+}
+
+/** Returns a new fn() call for the given framework. */
+function fn(fw) {
+  return fw === 'vitest' ? 'vi.fn()' : 'jest.fn()';
+}
+
+/** Returns the framework object identifier (vi / jest). */
+function fwRef(fw) {
+  return fw === 'vitest' ? 'vi' : 'jest';
+}
+
+function buildSwrDefaults(fw) {
+  const ref = fwRef(fw);
+  return `\
+const defaultSWRReturn = {
+  data: undefined,
+  isLoading: false,
+  error: undefined,
+  mutate: ${fn(fw)} as unknown as KeyedMutator<any>,
+  isValidating: false,
+};
+
+const defaultSWRMutationReturn = {
+  trigger: ${ref}.fn(() => Promise.resolve(undefined)),
+  isMutating: false,
+  error: undefined,
+  data: undefined,
+  reset: ${fn(fw)},
+};
+`;
+}
+
+function buildSwrHelpers(fw) {
+  const ref = fwRef(fw);
+  return `\
+interface MockSWRReturn {
+  /** The data to return from the mock */
+  data: unknown;
+  /** Whether to return a loading state (default: false) */
+  isLoading?: boolean;
+  /** Whether to return an error (default: undefined) */
+  error?: Error | undefined | null;
+}
+
+interface MockSWRMutationReturn {
+  /** The data to return from the mock */
+  data: unknown;
+  /** Whether to return a mutating state (default: false) */
+  isMutating?: boolean;
+  /** Whether to return an error (default: undefined) */
+  error?: Error | undefined | null;
+}
+
+/** Augments a spy with a \`mockSWR\` shorthand for useSWR query hooks. */
+function withMockSWR<Fn extends (...args: never[]) => unknown>(spy: ${ref}.SpiedFunction<Fn>) {
+  return Object.assign(spy, {
+    mockSWR({ data, isLoading, error }: MockSWRReturn) {
+      spy.mockReturnValue({
+        ...defaultSWRReturn,
+        data,
+        isLoading: isLoading ?? false,
+        error: error ?? undefined,
+      } as ReturnType<Fn>);
+    },
+  });
+}
+
+/** Augments a spy with a \`mockSWRMutation\` shorthand for useSWRMutation hooks. */
+function withMockSWRMutation<Fn extends (...args: never[]) => unknown>(spy: ${ref}.SpiedFunction<Fn>) {
+  return Object.assign(spy, {
+    mockSWRMutation({
+      data,
+      isMutating,
+      error,
+    }: MockSWRMutationReturn) {
+      spy.mockReturnValue({
+        ...defaultSWRMutationReturn,
+        trigger: ${ref}.fn(() => Promise.resolve(undefined)),
+        isMutating: isMutating ?? false,
+        error: error ?? undefined,
+        data,
+      } as ReturnType<Fn>);
+    },
+  });
+}
+`;
+}
+
+function buildTsqDefaults(fw) {
+  return `\
+const defaultQueryReturn = {
+  data: undefined, isLoading: false, isPending: false, isFetching: false,
+  isSuccess: false, error: null, refetch: ${fn(fw)}, status: 'pending' as const,
+};
+
+const defaultMutationReturn = {
+  mutate: ${fn(fw)}, mutateAsync: ${fn(fw)}, isPending: false,
+  isSuccess: false, error: null, data: undefined, reset: ${fn(fw)},
+};
+`;
+}
+
+function buildTsqHelpers(fw) {
+  const ref = fwRef(fw);
+  return `\
+// ─── TanStack Query mock helpers ─────────────────────────────────────────────
+
+/** Augments a spy with a \`mockQuery\` shorthand for useQuery hooks. */
+function withMockQuery<T extends ReturnType<typeof ${ref}.spyOn>>(spy: T) {
+  return Object.assign(spy, {
+    mockQuery({ data, isLoading, error }: { data?: unknown; isLoading?: boolean; error?: Error }) {
+      const pending = isLoading ?? false;
+      spy.mockReturnValue({
+        ...defaultQueryReturn,
+        data,
+        isLoading: pending,
+        isPending: pending,
+        isSuccess: data !== undefined && !pending,
+        error: error ?? null,
+        status: pending ? 'pending' : ('success' as const),
+      });
+    },
+  });
+}
+
+/** Augments a spy with a \`mockMutation\` shorthand for useMutation hooks. */
+function withMockMutation<T extends ReturnType<typeof ${ref}.spyOn>>(spy: T) {
+  return Object.assign(spy, {
+    mockMutation({ data, isPending, error }: { data?: unknown; isPending?: boolean; error?: Error }) {
+      spy.mockReturnValue({
+        ...defaultMutationReturn,
+        mutate: ${fn(fw)},
+        mutateAsync: ${fn(fw)},
+        isPending: isPending ?? false,
+        error: error ?? null,
+        data,
+      });
+    },
+  });
+}
+`;
+}
+
+function buildCreateClientMocks(
+  groups,
+  fw
+) {
+  const spy = spyFn(fw);
+  const lines = ['export function createClientMocks() {', '  return {'];
+
+  for (const { camelName, ops } of groups) {
+    lines.push(`    ${camelName}Client: {`);
+    for (const op of ops) {
+      lines.push(
+        `      ${op.name}: ${spy}(realApi.${camelName}Client, '${op.name}').mockReturnValue(undefined as any),`
+      );
+    }
+    lines.push('    },');
+  }
+
+  lines.push('  };');
+  lines.push('}');
+  return lines.join('\n') + '\n';
+}
+
+function buildCreateSwrHookMocks(
+  groups,
+  fw
+) {
+  const spy = spyFn(fw);
+  const lines = ['export function createApiHookMocks() {', '  return {'];
+
+  for (const { camelName, ops } of groups) {
+    const getOps = ops.filter((o) => o.method === 'GET');
+    const mutOps = ops.filter((o) => o.method !== 'GET');
+
+    lines.push(`    ${camelName}: {`);
+    lines.push('      queries: {');
+    for (const op of getOps) {
+      const hookName = toHookName(op.name, 'use');
+      lines.push(
+        `        ${hookName}: withMockSWR(${spy}(realApi.${camelName}.queries, '${hookName}').mockReturnValue(defaultSWRReturn)),`
+      );
+    }
+    lines.push('      },');
+    lines.push('      mutations: {');
+    for (const op of mutOps) {
+      const hookName = 'use' + _case.pascal.call(void 0, op.name);
+      lines.push(
+        `        ${hookName}: withMockSWRMutation(${spy}(realApi.${camelName}.mutations, '${hookName}').mockReturnValue(defaultSWRMutationReturn as any)),`
+      );
+    }
+    lines.push('      },');
+    lines.push('    },');
+  }
+
+  lines.push('  };');
+  lines.push('}');
+  return lines.join('\n') + '\n';
+}
+
+function buildCreateTsqHookMocks(
+  groups,
+  fw
+) {
+  const spy = spyFn(fw);
+  const lines = ['export function createApiHookMocks() {', '  return {'];
+
+  for (const { camelName, ops } of groups) {
+    const getOps = ops.filter((o) => o.method === 'GET');
+    const mutOps = ops.filter((o) => o.method !== 'GET');
+
+    lines.push(`    ${camelName}: {`);
+    lines.push('      queries: {');
+    for (const op of getOps) {
+      const hookName = toHookName(op.name, 'use');
+      lines.push(
+        `        ${hookName}: withMockQuery(${spy}(realApi.${camelName}.queries, '${hookName}').mockReturnValue(defaultQueryReturn)),`
+      );
+    }
+    lines.push('      },');
+    lines.push('      mutations: {');
+    for (const op of mutOps) {
+      const hookName = 'use' + _case.pascal.call(void 0, op.name);
+      lines.push(
+        `        ${hookName}: withMockMutation(${spy}(realApi.${camelName}.mutations, '${hookName}').mockReturnValue(defaultMutationReturn)),`
+      );
+    }
+    lines.push('      },');
+    lines.push('    },');
+  }
+
+  lines.push('  };');
+  lines.push('}');
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Converts an operation name to a React hook name.
+ * Strips a leading "get" prefix (case-insensitive) then capitalises, then
+ * prepends the given prefix (e.g. "use").
+ *
+ * @example toHookName('getPetById', 'use')       → 'usePetById'
+ * @example toHookName('findPetsByStatus', 'use') → 'useFindPetsByStatus'
+ */
+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;
+}

package/dist/gen/genOperations.js

@@ -10,10 +10,17 @@ var _swagger = require('../swagger');
 
 var _utils = require('../utils/utils');
 var _templateEngine = require('../utils/templateEngine');
+var _templateValidator = require('../utils/templateValidator');
 var _createBarrel = require('./createBarrel');
 var _header = require('./header');
 
 
+
+
+
+
+
+
 var _jsDocs = require('./jsDocs');
 
 /**
@@ -26,11 +33,23 @@ var _jsDocs = require('./jsDocs');
   const operations = _swagger.getOperations.call(void 0, spec);
   const groups = _utils.groupOperationsByGroupName.call(void 0, operations);
   const servicePrefix = options.servicePrefix;
-  let result = _header.FILE_HEADER + _templateEngine.renderFile.call(void 0, 'baseClient.ejs', {
+  const baseClientData = {
     servicePrefix,
     baseUrl: options.baseUrl,
     ...options.queryParamsSerialization,
-  });
+  };
+
+  // When a composite [L2, L1] template is used, the L2 base client contains
+  // reactive library imports (e.g. useSWR, useQuery). These are placed first
+  // so all imports appear at the top of the file before the HTTP client setup.
+  let baseClients = '';
+  if (_templateEngine.hasTemplateFile.call(void 0, 'baseClientL2.ejs')) {
+    baseClients += _templateEngine.renderFile.call(void 0, 'baseClientL2.ejs', baseClientData);
+  }
+  baseClients += _templateEngine.renderFile.call(void 0, 'baseClient.ejs', baseClientData);
+
+  const clientDirective = options.useClient ? "'use client';\n" : '';
+  let result = clientDirective + _header.FILE_HEADER + baseClients;
 
   for (const name in groups) {
     const group = groups[name];
@@ -43,6 +62,7 @@ var _jsDocs = require('./jsDocs');
     const renderedFile = _templateEngine.renderFile.call(void 0, 'client.ejs', {
       ...clientData,
       servicePrefix,
+      httpConfigType: _templateValidator.getHttpConfigType.call(void 0, options.template),
     });
 
     result += renderedFile;
@@ -101,32 +121,44 @@ function prepareClient(
 
     try {
       const [respObject, responseContentType] = _utils.getBestResponse.call(void 0, op, components);
-      const returnType = _swagger.getParameterType.call(void 0, respObject, options);
+      const returnType = respObject
+        ? _swagger.getParameterType.call(void 0, respObject, options)
+        : options.preferAny
+          ? 'any'
+          : 'unknown';
 
-      const body = getRequestBody(op.requestBody, components, options);
+      const body = op.requestBody ? getRequestBody(op.requestBody, components, options) : null;
       const queryParams = getParams(op.parameters , options, ['query']);
-      const params = getParams(op.parameters , options);
+      let params = getParams(op.parameters , options);
+      let queryParamObject;
 
       if (body) {
         params.unshift(body);
       }
 
-    // If all parameters have 'x-position' defined, sort them by it
-      if (params.every((p) => p.original['x-position'])) {
-        params.sort((a, b) => a.original['x-position'] - b.original['x-position']);
+      // If all parameters have 'x-position' defined, sort them by it
+      if (params.every((p) => p.original && 'x-position' in p.original)) {
+        params.sort(
+          (a, b) =>
+            (a.original )['x-position'] -
+            (b.original )['x-position']
+        );
+      }
+
+      if (
+        shouldGroupQueryParams(queryParams, options.queryParamsSerialization.queryParamsAsObject)
+      ) {
+        queryParamObject = createQueryParamObject(queryParams);
+        params = replaceQueryParamsWithObject(params, queryParamObject);
       }
 
       markParametersAsSkippable(params);
 
-      const headers = getParams(
-        op.parameters ,
-        options,
-        ['header']
-      );
+      const headers = getParams(op.parameters , options, ['header']);
       // Some libraries need explicit Content-Type for request bodies.
       if (_optionalChain([body, 'optionalAccess', _2 => _2.contentType]) === 'urlencoded') {
         upsertFixedHeader(headers, 'Content-Type', 'application/x-www-form-urlencoded');
-      } else if (_optionalChain([body, 'optionalAccess', _3 => _3.contentType]) === 'json' && options.template === 'fetch') {
+      } else if (_optionalChain([body, 'optionalAccess', _3 => _3.contentType]) === 'json' && _templateValidator.getL1Template.call(void 0, options.template) === 'fetch') {
         upsertFixedHeader(headers, 'Content-Type', 'application/json');
       }
 
@@ -135,10 +167,11 @@ function prepareClient(
         returnType,
         responseContentType,
         method: op.method.toUpperCase(),
-        name: getOperationName(op.operationId, op.group),
+        name: getOperationName(_nullishCoalesce(op.operationId, () => ( null)), op.group),
         url: prepareUrl(op.path),
         parameters: params,
         query: queryParams,
+        queryParamObject,
         body,
         headers,
       };
@@ -157,6 +190,59 @@ function prepareClient(
   });
 } exports.prepareOperations = prepareOperations;
 
+function shouldGroupQueryParams(
+  queryParams,
+  setting
+) {
+  if (queryParams.length < 1 || setting === false) {
+    return false;
+  }
+
+  if (setting === true) {
+    return true;
+  }
+
+  return queryParams.length > setting;
+}
+
+function createQueryParamObject(queryParams) {
+  const properties = queryParams
+    .map((param) => {
+      const isOptional = param.optional ? '?' : '';
+      const nullableType = param.optional ? ' | null' : '';
+      return `${param.name}${isOptional}: ${param.type}${nullableType};`;
+    })
+    .join(' ');
+  const containsRequiredQueryParams = queryParams.some((param) => !param.optional);
+
+  return {
+    originalName: 'queryParams',
+    name: 'queryParams',
+    type: `{ ${properties} }`,
+    optional: !containsRequiredQueryParams,
+    jsDoc: `Grouped query parameters object (${queryParams
+      .map((param) => param.originalName)
+      .join(', ')})`,
+  };
+}
+
+function replaceQueryParamsWithObject(
+  params,
+  queryParamObject
+) {
+  const isQueryParam = (param) =>
+    !!param.original && 'in' in param.original && param.original.in === 'query';
+
+  const firstQueryParamIndex = params.findIndex(isQueryParam);
+  if (firstQueryParamIndex < 0) {
+    return params;
+  }
+
+  const paramsWithoutQuery = params.filter((param) => !isQueryParam(param));
+  paramsWithoutQuery.splice(firstQueryParamIndex, 0, queryParamObject);
+  return paramsWithoutQuery;
+}
+
 /**
  * Marks parameters as skippable based on their position relative to the last required parameter.
  *
@@ -202,7 +288,11 @@ function prepareUrl(path) {
  * it can happen very easily and we need to handle it gracefully.
  */
  function fixDuplicateOperations(operations) {
-  if (!operations || operations.length < 2) {
+  if (!operations) {
+    return [];
+  }
+
+  if (operations.length < 2) {
     return operations;
   }
 
@@ -287,7 +377,7 @@ function prepareUrl(path) {
  */
  function getParamName(name) {
   if (!name) {
-    return name;
+    return _nullishCoalesce(name, () => ( ''));
   }
 
   return _utils.escapeIdentifier.call(void 0, 
@@ -324,13 +414,15 @@ function getRequestBody(
   const isFormData = contentType === 'form-data';
 
   if (bodyContent) {
+    const reqBodyAny = reqBody ;
+    const xName = reqBodyAny['x-name'];
     return {
-      originalName: _nullishCoalesce(reqBody['x-name'], () => ( 'body')),
-      name: getParamName(_nullishCoalesce(reqBody['x-name'], () => ( 'body'))),
+      originalName: _nullishCoalesce(xName, () => ( 'body')),
+      name: getParamName(_nullishCoalesce(xName, () => ( 'body'))),
       type: isFormData ? 'FormData' : _swagger.getParameterType.call(void 0, bodyContent, options),
       optional: !reqBody.required,
       original: reqBody,
-      contentType,
+      contentType: _nullishCoalesce(contentType, () => ( undefined)),
     };
   }