nuxt-openapi-hyperfetch 0.1.7-alpha.1 → 0.2.7-alpha.1

package/src/generators/shared/templates/api-pagination-plugin.ts

@@ -0,0 +1,158 @@
+// @ts-nocheck
+/**
+ * Global API Pagination Plugin
+ *
+ * ⚠️ IMPORTANT: This file is NEVER regenerated - your changes are safe!
+ *
+ * Configure the global pagination convention for all paginated API requests.
+ * Each composable can override this config locally via `paginationConfig` option.
+ *
+ * ── HOW IT WORKS ──────────────────────────────────────────────────────────────
+ *
+ * When you call a composable with `paginated: true`, the wrapper will:
+ *   1. Inject page/perPage params into the request (query, body, or headers)
+ *   2. After the response, read total/totalPages/currentPage/perPage from the
+ *      response headers or JSON body, according to `metaSource`
+ *   3. Expose `pagination`, `goToPage()`, `nextPage()`, `prevPage()`, `setPerPage()`
+ *
+ * ── USAGE ─────────────────────────────────────────────────────────────────────
+ *
+ * // In your page/component:
+ * const { data, pagination, goToPage, nextPage, prevPage, setPerPage } =
+ *   useGetPets(params, { paginated: true })
+ *
+ * // pagination is a computed ref:
+ * pagination.value.currentPage  // current page
+ * pagination.value.totalPages   // total pages
+ * pagination.value.total        // total items
+ * pagination.value.perPage      // items per page
+ * pagination.value.hasNextPage  // boolean
+ * pagination.value.hasPrevPage  // boolean
+ *
+ * // Navigation helpers — automatically trigger re-fetch:
+ * goToPage(3)
+ * nextPage()
+ * prevPage()
+ * setPerPage(50)
+ *
+ * ── PRIORITY ──────────────────────────────────────────────────────────────────
+ *
+ * Per-call paginationConfig > this plugin's global config > built-in defaults
+ *
+ * Example of per-call override:
+ *   useGetPets(params, {
+ *     paginated: true,
+ *     paginationConfig: {
+ *       meta: { metaSource: 'headers', fields: { ... } },
+ *       request: { sendAs: 'query', params: { page: 'p', perPage: 'size' }, defaults: { page: 1, perPage: 10 } }
+ *     }
+ *   })
+ */
+
+export default defineNuxtPlugin(() => {
+  // Uncomment and configure ONE of the examples below that matches your backend.
+
+  // ============================================================================
+  // EXAMPLE 1 — Query params + response body (most common REST pattern)
+  //
+  // Request:  GET /pets?page=1&limit=20
+  // Response: { data: [...], total: 100, totalPages: 5, currentPage: 1, perPage: 20 }
+  // ============================================================================
+  // const paginationConfig = {
+  //   meta: {
+  //     metaSource: 'body',
+  //     fields: {
+  //       total: 'total',
+  //       totalPages: 'totalPages',
+  //       currentPage: 'currentPage',
+  //       perPage: 'perPage',
+  //       dataKey: 'data', // response.data contains the actual array
+  //     },
+  //   },
+  //   request: {
+  //     sendAs: 'query',
+  //     params: { page: 'page', perPage: 'limit' },
+  //     defaults: { page: 1, perPage: 20 },
+  //   },
+  // };
+
+  // ============================================================================
+  // EXAMPLE 2 — Laravel paginate() convention
+  //
+  // Request:  GET /pets?page=1&per_page=15
+  // Response: { data: [...], meta: { total: 100, last_page: 7, current_page: 1, per_page: 15 } }
+  // ============================================================================
+  // const paginationConfig = {
+  //   meta: {
+  //     metaSource: 'body',
+  //     fields: {
+  //       total: 'meta.total',
+  //       totalPages: 'meta.last_page',
+  //       currentPage: 'meta.current_page',
+  //       perPage: 'meta.per_page',
+  //       dataKey: 'data',
+  //     },
+  //   },
+  //   request: {
+  //     sendAs: 'query',
+  //     params: { page: 'page', perPage: 'per_page' },
+  //     defaults: { page: 1, perPage: 15 },
+  //   },
+  // };
+
+  // ============================================================================
+  // EXAMPLE 3 — HTTP response headers convention
+  //
+  // Request:  GET /pets?page=1&limit=20
+  // Response headers: X-Total-Count: 100, X-Total-Pages: 5, X-Page: 1, X-Per-Page: 20
+  // ============================================================================
+  // const paginationConfig = {
+  //   meta: {
+  //     metaSource: 'headers',
+  //     fields: {
+  //       total: 'X-Total-Count',
+  //       totalPages: 'X-Total-Pages',
+  //       currentPage: 'X-Page',
+  //       perPage: 'X-Per-Page',
+  //       // No dataKey needed — response body is the array directly
+  //     },
+  //   },
+  //   request: {
+  //     sendAs: 'query',
+  //     params: { page: 'page', perPage: 'limit' },
+  //     defaults: { page: 1, perPage: 20 },
+  //   },
+  // };
+
+  // ============================================================================
+  // EXAMPLE 4 — POST-as-search (body pagination)
+  //
+  // Request:  POST /pets/search  body: { filters: {...}, page: 1, pageSize: 20 }
+  // Response: { items: [...], total: 100, pages: 5 }
+  // ============================================================================
+  // const paginationConfig = {
+  //   meta: {
+  //     metaSource: 'body',
+  //     fields: {
+  //       total: 'total',
+  //       totalPages: 'pages',
+  //       currentPage: 'page',
+  //       perPage: 'pageSize',
+  //       dataKey: 'items',
+  //     },
+  //   },
+  //   request: {
+  //     sendAs: 'body',
+  //     params: { page: 'page', perPage: 'pageSize' },
+  //     defaults: { page: 1, perPage: 20 },
+  //   },
+  // };
+
+  return {
+    provide: {
+      // Expose the config so the runtime wrappers can read it.
+      // Uncomment this line once you've configured paginationConfig above:
+      // getGlobalApiPagination: () => paginationConfig,
+    },
+  };
+});

package/src/generators/use-async-data/generator.ts

@@ -1,204 +1,205 @@
-import * as path from 'path';
-import fs from 'fs-extra';
-import { fileURLToPath } from 'url';
-import { format } from 'prettier';
-import {
-  getApiFiles as getApiFilesOfficial,
-  parseApiFile as parseApiFileOfficial,
-} from './parser.js';
-import {
-  getApiFiles as getApiFilesHeyApi,
-  parseApiFile as parseApiFileHeyApi,
-} from '../shared/parsers/heyapi-parser.js';
-import {
-  generateComposableFile,
-  generateRawComposableFile,
-  generateIndexFile,
-  type GenerateOptions,
-} from './templates.js';
-import type { MethodInfo } from './types.js';
-import { p, logSuccess, logError } from '../../cli/logger.js';
-
-/**
- * Main function to generate useAsyncData composables
- */
-export async function generateUseAsyncDataComposables(
-  inputDir: string,
-  outputDir: string,
-  options?: GenerateOptions
-): Promise<void> {
-  const mainSpinner = p.spinner();
-
-  // Select parser based on chosen backend
-  const getApiFiles = options?.backend === 'heyapi' ? getApiFilesHeyApi : getApiFilesOfficial;
-  const parseApiFile = options?.backend === 'heyapi' ? parseApiFileHeyApi : parseApiFileOfficial;
-
-  // 1. Get all API files
-  mainSpinner.start('Scanning API files');
-  const apiFiles = getApiFiles(inputDir);
-  mainSpinner.stop(`Found ${apiFiles.length} API file(s)`);
-
-  if (apiFiles.length === 0) {
-    throw new Error('No API files found in the input directory');
-  }
-
-  // 2. Parse each API file
-  mainSpinner.start('Parsing API files');
-  const allMethods: MethodInfo[] = [];
-
-  for (const file of apiFiles) {
-    const fileName = path.basename(file);
-    try {
-      const apiInfo = parseApiFile(file);
-      allMethods.push(...apiInfo.methods);
-    } catch (error) {
-      logError(`Error parsing ${fileName}: ${error}`);
-    }
-  }
-
-  mainSpinner.stop(`Found ${allMethods.length} methods to generate`);
-
-  if (allMethods.length === 0) {
-    p.log.warn('No methods found to generate');
-    return;
-  }
-
-  // 3. Clean and create output directories
-  mainSpinner.start('Preparing output directories');
-  const composablesDir = path.join(outputDir, 'composables');
-  const runtimeDir = path.join(outputDir, 'runtime');
-  const sharedRuntimeDir = path.join(path.dirname(outputDir), 'shared', 'runtime');
-  await fs.emptyDir(composablesDir);
-  await fs.ensureDir(runtimeDir);
-  await fs.ensureDir(sharedRuntimeDir);
-  mainSpinner.stop('Output directories ready');
-
-  // 4. Copy runtime helpers
-  mainSpinner.start('Copying runtime files');
-  // Derive __dirname equivalent for ESM
-  const __dirname = path.dirname(fileURLToPath(import.meta.url));
-  // When compiled, __dirname points to dist/generators/use-async-data/
-  // We need to go back to src/ to get the original .ts files
-
-  // Copy useApiAsyncData.ts
-  const runtimeSource = path.resolve(
-    __dirname,
-    '../../../src/generators/use-async-data/runtime/useApiAsyncData.ts'
-  );
-  const runtimeDest = path.join(runtimeDir, 'useApiAsyncData.ts');
-  await fs.copyFile(runtimeSource, runtimeDest);
-
-  // Copy useApiAsyncDataRaw.ts
-  const runtimeRawSource = path.resolve(
-    __dirname,
-    '../../../src/generators/use-async-data/runtime/useApiAsyncDataRaw.ts'
-  );
-  const runtimeRawDest = path.join(runtimeDir, 'useApiAsyncDataRaw.ts');
-  await fs.copyFile(runtimeRawSource, runtimeRawDest);
-
-  // Copy shared apiHelpers.ts
-  const sharedHelpersSource = path.resolve(
-    __dirname,
-    '../../../src/generators/shared/runtime/apiHelpers.ts'
-  );
-  const sharedHelpersDest = path.join(sharedRuntimeDir, 'apiHelpers.ts');
-  await fs.copyFile(sharedHelpersSource, sharedHelpersDest);
-  mainSpinner.stop('Runtime files copied');
-
-  // 5. Calculate relative import path from composables to APIs
-  const relativePath = calculateRelativeImportPath(composablesDir, inputDir);
-
-  // 6. Generate each composable (normal + Raw if available)
-  mainSpinner.start('Generating composables');
-  let successCount = 0;
-  let errorCount = 0;
-  const generatedComposableNames: string[] = [];
-
-  for (const method of allMethods) {
-    // Generate normal version
-    try {
-      const code = generateComposableFile(method, relativePath, options);
-      const formattedCode = await formatCode(code);
-      const composableName = method.composableName.replace(/^useFetch/, 'useAsyncData');
-      const fileName = `${composableName}.ts`;
-      const filePath = path.join(composablesDir, fileName);
-
-      await fs.writeFile(filePath, formattedCode, 'utf-8');
-      generatedComposableNames.push(composableName);
-      successCount++;
-    } catch (error) {
-      logError(`Error generating ${method.composableName}: ${error}`);
-      errorCount++;
-    }
-
-    // Generate Raw version if available
-    if (method.hasRawMethod && method.rawMethodName) {
-      try {
-        const code = generateRawComposableFile(method, relativePath, options);
-        const formattedCode = await formatCode(code);
-        const composableName = `useAsyncData${method.rawMethodName.replace(/Raw$/, '')}Raw`;
-        const fileName = `${composableName}.ts`;
-        const filePath = path.join(composablesDir, fileName);
-
-        await fs.writeFile(filePath, formattedCode, 'utf-8');
-        generatedComposableNames.push(composableName);
-        successCount++;
-      } catch (error) {
-        logError(`Error generating ${method.composableName} (Raw): ${error}`);
-        errorCount++;
-      }
-    }
-  }
-
-  // 7. Generate index.ts
-  const indexCode = generateIndexFile(generatedComposableNames);
-  const formattedIndex = await formatCode(indexCode);
-  await fs.writeFile(path.join(outputDir, 'index.ts'), formattedIndex, 'utf-8');
-  mainSpinner.stop(`Generated ${successCount} composables`);
-
-  // 8. Summary
-  if (errorCount > 0) {
-    p.log.warn(`Completed with ${errorCount} error(s)`);
-  }
-  logSuccess(`Generated ${successCount} useAsyncData composable(s) in ${outputDir}`);
-}
-
-/**
- * Calculate relative import path from composables to APIs
- */
-function calculateRelativeImportPath(composablesDir: string, inputDir: string): string {
-  // Import from the root index.ts which exports apis, models, and runtime
-  let relativePath = path.relative(composablesDir, inputDir);
-
-  // Convert Windows paths to Unix-style
-  relativePath = relativePath.replace(/\\/g, '/');
-
-  // Ensure it starts with './' or '../'
-  if (!relativePath.startsWith('.')) {
-    relativePath = './' + relativePath;
-  }
-
-  // Remove .ts extension and trailing /
-  relativePath = relativePath.replace(/\.ts$/, '').replace(/\/$/, '');
-
-  return relativePath;
-}
-
-/**
- * Format code with Prettier
- */
-async function formatCode(code: string): Promise<string> {
-  try {
-    return await format(code, {
-      parser: 'typescript',
-      semi: true,
-      singleQuote: true,
-      trailingComma: 'es5',
-      printWidth: 80,
-      tabWidth: 2,
-    });
-  } catch {
-    p.log.warn('Could not format code with Prettier');
-    return code;
-  }
-}
+import * as path from 'path';
+import fs from 'fs-extra';
+import { fileURLToPath } from 'url';
+import { format } from 'prettier';
+import {
+  getApiFiles as getApiFilesOfficial,
+  parseApiFile as parseApiFileOfficial,
+} from './parser.js';
+import {
+  getApiFiles as getApiFilesHeyApi,
+  parseApiFile as parseApiFileHeyApi,
+} from '../shared/parsers/heyapi-parser.js';
+import {
+  generateComposableFile,
+  generateRawComposableFile,
+  generateIndexFile,
+  type GenerateOptions,
+} from './templates.js';
+import type { MethodInfo } from './types.js';
+import { type Logger, createClackLogger } from '../../cli/logger.js';
+
+/**
+ * Main function to generate useAsyncData composables
+ */
+export async function generateUseAsyncDataComposables(
+  inputDir: string,
+  outputDir: string,
+  options?: GenerateOptions,
+  logger: Logger = createClackLogger()
+): Promise<void> {
+  const mainSpinner = logger.spinner();
+
+  // Select parser based on chosen backend
+  const getApiFiles = options?.backend === 'heyapi' ? getApiFilesHeyApi : getApiFilesOfficial;
+  const parseApiFile = options?.backend === 'heyapi' ? parseApiFileHeyApi : parseApiFileOfficial;
+
+  // 1. Get all API files
+  mainSpinner.start('Scanning API files');
+  const apiFiles = getApiFiles(inputDir);
+  mainSpinner.stop(`Found ${apiFiles.length} API file(s)`);
+
+  if (apiFiles.length === 0) {
+    throw new Error('No API files found in the input directory');
+  }
+
+  // 2. Parse each API file
+  mainSpinner.start('Parsing API files');
+  const allMethods: MethodInfo[] = [];
+
+  for (const file of apiFiles) {
+    const fileName = path.basename(file);
+    try {
+      const apiInfo = parseApiFile(file);
+      allMethods.push(...apiInfo.methods);
+    } catch (error) {
+      logger.log.error(`Error parsing ${fileName}: ${String(error)}`);
+    }
+  }
+
+  mainSpinner.stop(`Found ${allMethods.length} methods to generate`);
+
+  if (allMethods.length === 0) {
+    logger.log.warn('No methods found to generate');
+    return;
+  }
+
+  // 3. Clean and create output directories
+  mainSpinner.start('Preparing output directories');
+  const composablesDir = path.join(outputDir, 'composables');
+  const runtimeDir = path.join(outputDir, 'runtime');
+  const sharedRuntimeDir = path.join(path.dirname(outputDir), 'shared', 'runtime');
+  await fs.emptyDir(composablesDir);
+  await fs.ensureDir(runtimeDir);
+  await fs.ensureDir(sharedRuntimeDir);
+  mainSpinner.stop('Output directories ready');
+
+  // 4. Copy runtime helpers
+  mainSpinner.start('Copying runtime files');
+  // Derive __dirname equivalent for ESM
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  // When compiled, __dirname points to dist/generators/use-async-data/
+  // We need to go back to src/ to get the original .ts files
+
+  // Copy useApiAsyncData.ts
+  const runtimeSource = path.resolve(
+    __dirname,
+    '../../../src/generators/use-async-data/runtime/useApiAsyncData.ts'
+  );
+  const runtimeDest = path.join(runtimeDir, 'useApiAsyncData.ts');
+  await fs.copyFile(runtimeSource, runtimeDest);
+
+  // Copy useApiAsyncDataRaw.ts
+  const runtimeRawSource = path.resolve(
+    __dirname,
+    '../../../src/generators/use-async-data/runtime/useApiAsyncDataRaw.ts'
+  );
+  const runtimeRawDest = path.join(runtimeDir, 'useApiAsyncDataRaw.ts');
+  await fs.copyFile(runtimeRawSource, runtimeRawDest);
+
+  // Copy shared apiHelpers.ts
+  const sharedHelpersSource = path.resolve(
+    __dirname,
+    '../../../src/generators/shared/runtime/apiHelpers.ts'
+  );
+  const sharedHelpersDest = path.join(sharedRuntimeDir, 'apiHelpers.ts');
+  await fs.copyFile(sharedHelpersSource, sharedHelpersDest);
+  mainSpinner.stop('Runtime files copied');
+
+  // 5. Calculate relative import path from composables to APIs
+  const relativePath = calculateRelativeImportPath(composablesDir, inputDir);
+
+  // 6. Generate each composable (normal + Raw if available)
+  mainSpinner.start('Generating composables');
+  let successCount = 0;
+  let errorCount = 0;
+  const generatedComposableNames: string[] = [];
+
+  for (const method of allMethods) {
+    // Generate normal version
+    try {
+      const code = generateComposableFile(method, relativePath, options);
+      const formattedCode = await formatCode(code, logger);
+      const composableName = method.composableName.replace(/^useFetch/, 'useAsyncData');
+      const fileName = `${composableName}.ts`;
+      const filePath = path.join(composablesDir, fileName);
+
+      await fs.writeFile(filePath, formattedCode, 'utf-8');
+      generatedComposableNames.push(composableName);
+      successCount++;
+    } catch (error) {
+      logger.log.error(`Error generating ${method.composableName}: ${String(error)}`);
+      errorCount++;
+    }
+
+    // Generate Raw version if available
+    if (method.hasRawMethod && method.rawMethodName) {
+      try {
+        const code = generateRawComposableFile(method, relativePath, options);
+        const formattedCode = await formatCode(code, logger);
+        const composableName = `useAsyncData${method.rawMethodName.replace(/Raw$/, '')}Raw`;
+        const fileName = `${composableName}.ts`;
+        const filePath = path.join(composablesDir, fileName);
+
+        await fs.writeFile(filePath, formattedCode, 'utf-8');
+        generatedComposableNames.push(composableName);
+        successCount++;
+      } catch (error) {
+        logger.log.error(`Error generating ${method.composableName} (Raw): ${String(error)}`);
+        errorCount++;
+      }
+    }
+  }
+
+  // 7. Generate index.ts
+  const indexCode = generateIndexFile(generatedComposableNames);
+  const formattedIndex = await formatCode(indexCode, logger);
+  await fs.writeFile(path.join(outputDir, 'index.ts'), formattedIndex, 'utf-8');
+  mainSpinner.stop(`Generated ${successCount} composables`);
+
+  // 8. Summary
+  if (errorCount > 0) {
+    logger.log.warn(`Completed with ${errorCount} error(s)`);
+  }
+  logger.log.success(`Generated ${successCount} useAsyncData composable(s) in ${outputDir}`);
+}
+
+/**
+ * Calculate relative import path from composables to APIs
+ */
+function calculateRelativeImportPath(composablesDir: string, inputDir: string): string {
+  // Import from the root index.ts which exports apis, models, and runtime
+  let relativePath = path.relative(composablesDir, inputDir);
+
+  // Convert Windows paths to Unix-style
+  relativePath = relativePath.replace(/\\/g, '/');
+
+  // Ensure it starts with './' or '../'
+  if (!relativePath.startsWith('.')) {
+    relativePath = './' + relativePath;
+  }
+
+  // Remove .ts extension and trailing /
+  relativePath = relativePath.replace(/\.ts$/, '').replace(/\/$/, '');
+
+  return relativePath;
+}
+
+/**
+ * Format code with Prettier
+ */
+async function formatCode(code: string, logger: Logger): Promise<string> {
+  try {
+    return await format(code, {
+      parser: 'typescript',
+      semi: true,
+      singleQuote: true,
+      trailingComma: 'es5',
+      printWidth: 80,
+      tabWidth: 2,
+    });
+  } catch {
+    logger.log.warn('Could not format code with Prettier');
+    return code;
+  }
+}