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

package/src/generators/components/connector-generator/generator.ts

@@ -0,0 +1,138 @@
+import * as path from 'path';
+import fs from 'fs-extra';
+import { fileURLToPath } from 'url';
+import { format } from 'prettier';
+import { analyzeSpec } from '../schema-analyzer/index.js';
+import {
+  generateConnectorFile,
+  connectorFileName,
+  generateConnectorIndexFile,
+} from './templates.js';
+import type { ConnectorGeneratorOptions } from './types.js';
+import { type Logger, createClackLogger } from '../../../cli/logger.js';
+
+// Runtime files that must be copied to the user's project
+const RUNTIME_FILES = [
+  'useListConnector.ts',
+  'useDetailConnector.ts',
+  'useFormConnector.ts',
+  'useDeleteConnector.ts',
+  'zod-error-merger.ts',
+] as const;
+
+/**
+ * Format TypeScript source with Prettier.
+ * Falls back to unformatted code on error.
+ */
+async function formatCode(code: string, logger: Logger): Promise<string> {
+  try {
+    return await format(code, { parser: 'typescript' });
+  } catch (error) {
+    logger.log.warn(`Prettier formatting failed: ${String(error)}`);
+    return code;
+  }
+}
+
+/**
+ * Generate headless connector composables from an OpenAPI spec.
+ *
+ * Steps:
+ *  1. Analyze the spec → ResourceMap (Schema Analyzer)
+ *  2. For each resource: generate connector source, format, write
+ *  3. Write an index barrel file
+ *  4. Copy runtime helpers to the user's project
+ */
+export async function generateConnectors(
+  options: ConnectorGeneratorOptions,
+  logger: Logger = createClackLogger()
+): Promise<void> {
+  const spinner = logger.spinner();
+
+  const outputDir = path.resolve(options.outputDir);
+  const composablesRelDir = options.composablesRelDir ?? '../use-async-data';
+  const runtimeRelDir = options.runtimeRelDir ?? '../runtime';
+
+  // ── 1. Analyze spec ───────────────────────────────────────────────────────
+  spinner.start('Analyzing OpenAPI spec');
+  const resourceMap = analyzeSpec(options.inputSpec);
+  spinner.stop(`Found ${resourceMap.size} resource(s)`);
+
+  if (resourceMap.size === 0) {
+    logger.log.warn('No resources found in spec — nothing to generate');
+    return;
+  }
+
+  // ── 2. Prepare output directory ───────────────────────────────────────────
+  // emptyDir (not ensureDir) so stale connectors from previous runs are removed.
+  // If the resource got renamed in the spec the old file would otherwise linger.
+  spinner.start('Preparing output directory');
+  await fs.emptyDir(outputDir);
+  spinner.stop('Output directory ready');
+
+  // ── 3. Generate connector files ───────────────────────────────────────────
+  spinner.start('Generating connector composables');
+  let successCount = 0;
+  let errorCount = 0;
+  const generatedNames: string[] = [];
+
+  for (const resource of resourceMap.values()) {
+    try {
+      const code = generateConnectorFile(resource, composablesRelDir);
+      const formatted = await formatCode(code, logger);
+      const fileName = connectorFileName(resource.composableName);
+      const filePath = path.join(outputDir, fileName);
+
+      await fs.writeFile(filePath, formatted, 'utf-8');
+      generatedNames.push(resource.composableName);
+      successCount++;
+    } catch (error) {
+      logger.log.error(`Error generating ${resource.composableName}: ${String(error)}`);
+      errorCount++;
+    }
+  }
+
+  spinner.stop(`Generated ${successCount} connector(s)`);
+
+  // ── 4. Write barrel index ─────────────────────────────────────────────────
+  if (generatedNames.length > 0) {
+    try {
+      const indexCode = generateConnectorIndexFile(generatedNames);
+      const formattedIndex = await formatCode(indexCode, logger);
+      await fs.writeFile(path.join(outputDir, 'index.ts'), formattedIndex, 'utf-8');
+    } catch (error) {
+      logger.log.warn(`Could not write connector index: ${String(error)}`);
+    }
+  }
+
+  // ── 5. Copy runtime helpers ───────────────────────────────────────────────
+  // Runtime files (useListConnector, useFormConnector …) live in src/ and must
+  // be physical .ts files in the user's project so Nuxt/Vite can type-check them.
+  //
+  // Path resolution trick:
+  //   •  During development (ts-node / tsx):  __dirname ≈ src/generators/components/connector-generator/
+  //   •  After `tsc` build:                   __dirname ≈ dist/generators/components/connector-generator/
+  //
+  // In both cases we need to land in src/generators/shared/runtime/, so we step
+  // up 4 levels and then re-enter src/ explicitly.  This works because the repo
+  // always keeps src/ alongside dist/ in the published package (see "files" in package.json).
+  spinner.start('Copying runtime files');
+  const runtimeDir = path.resolve(outputDir, runtimeRelDir);
+  await fs.ensureDir(runtimeDir); // ensureDir (not emptyDir) — other runtime files may exist there
+
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  const runtimeSrcDir = path.resolve(__dirname, '../../../../src/generators/shared/runtime');
+
+  for (const file of RUNTIME_FILES) {
+    const src = path.join(runtimeSrcDir, file);
+    const dest = path.join(runtimeDir, file);
+    await fs.copyFile(src, dest);
+  }
+
+  spinner.stop('Runtime files copied');
+
+  // ── 6. Summary ────────────────────────────────────────────────────────────
+  if (errorCount > 0) {
+    logger.log.warn(`Completed with ${errorCount} error(s)`);
+  }
+  logger.log.success(`Generated ${successCount} connector(s) in ${outputDir}`);
+}

package/src/generators/components/connector-generator/templates.ts

@@ -0,0 +1,254 @@
+import { pascalCase, kebabCase } from 'change-case';
+import type { ResourceInfo } from '../schema-analyzer/types.js';
+
+// ─── File header ──────────────────────────────────────────────────────────────
+
+function generateFileHeader(): string {
+  return `/**
+ * ⚠️ AUTO-GENERATED FILE - DO NOT EDIT MANUALLY
+ *
+ * This file was automatically generated by nuxt-openapi-generator.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * @generated by nuxt-openapi-generator
+ * @see https://github.com/dmartindiaz/nuxt-openapi-hyperfetch
+ */
+
+/* eslint-disable */
+// @ts-nocheck
+`;
+}
+
+// ─── Naming helpers ───────────────────────────────────────────────────────────
+
+/**
+ * operationId → useAsyncData composable name.
+ * 'getPets' → 'useAsyncDataGetPets'
+ */
+function toAsyncDataName(operationId: string): string {
+  return `useAsyncData${pascalCase(operationId)}`;
+}
+
+/**
+ * composable name → kebab-case file name (without .ts).
+ * 'useAsyncDataGetPets' → 'use-async-data-get-pets'
+ */
+function toFileName(composableName: string): string {
+  return kebabCase(composableName);
+}
+
+// ─── Section builders ─────────────────────────────────────────────────────────
+
+/**
+ * Build all `import` lines for a resource connector.
+ */
+function buildImports(resource: ResourceInfo, composablesRelDir: string): string {
+  const lines: string[] = [];
+
+  // zod
+  lines.push(`import { z } from 'zod';`);
+  lines.push('');
+
+  // runtime helpers (Nuxt alias — set up by the Nuxt module)
+  const runtimeHelpers: string[] = [];
+  if (resource.listEndpoint) {
+    runtimeHelpers.push('useListConnector');
+  }
+  if (resource.detailEndpoint) {
+    runtimeHelpers.push('useDetailConnector');
+  }
+  if (resource.createEndpoint || resource.updateEndpoint) {
+    runtimeHelpers.push('useFormConnector');
+  }
+  if (resource.deleteEndpoint) {
+    runtimeHelpers.push('useDeleteConnector');
+  }
+
+  for (const helper of runtimeHelpers) {
+    lines.push(`import { ${helper} } from '#nxh/runtime/${helper}';`);
+  }
+  lines.push('');
+
+  // generated useAsyncData composables
+  const addImport = (operationId: string): void => {
+    const name = toAsyncDataName(operationId);
+    const file = toFileName(name);
+    lines.push(`import { ${name} } from '${composablesRelDir}/${file}';`);
+  };
+
+  if (resource.listEndpoint) {
+    addImport(resource.listEndpoint.operationId);
+  }
+  if (resource.detailEndpoint) {
+    addImport(resource.detailEndpoint.operationId);
+  }
+  if (resource.createEndpoint) {
+    addImport(resource.createEndpoint.operationId);
+  }
+  if (resource.updateEndpoint) {
+    addImport(resource.updateEndpoint.operationId);
+  }
+  if (resource.deleteEndpoint) {
+    addImport(resource.deleteEndpoint.operationId);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Build Zod schema const declarations.
+ */
+function buildZodSchemas(resource: ResourceInfo): string {
+  const lines: string[] = [];
+  const pascal = pascalCase(resource.name);
+
+  if (resource.zodSchemas.create) {
+    lines.push(`const ${pascal}CreateSchema = ${resource.zodSchemas.create};`);
+    lines.push('');
+  }
+  if (resource.zodSchemas.update) {
+    lines.push(`const ${pascal}UpdateSchema = ${resource.zodSchemas.update};`);
+    lines.push('');
+  }
+
+  // Derive TS types via z.infer
+  if (resource.zodSchemas.create) {
+    lines.push(`type ${pascal}CreateInput = z.infer<typeof ${pascal}CreateSchema>;`);
+  }
+  if (resource.zodSchemas.update) {
+    lines.push(`type ${pascal}UpdateInput = z.infer<typeof ${pascal}UpdateSchema>;`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Build the body of the exported connector function.
+ */
+function buildFunctionBody(resource: ResourceInfo): string {
+  const pascal = pascalCase(resource.name);
+  const subConnectors: string[] = [];
+
+  if (resource.listEndpoint) {
+    const fn = toAsyncDataName(resource.listEndpoint.operationId);
+    // paginated: true tells useListConnector to expose pagination helpers
+    // (goToPage, nextPage, prevPage, setPerPage, pagination ref).
+    // We set it whenever the spec declares a list endpoint that has a response schema,
+    // which is a reliable proxy for "this API returns structured data worth paginating".
+    const opts = resource.listEndpoint.responseSchema ? '{ paginated: true }' : '{}';
+    subConnectors.push(`  const table = useListConnector(${fn}, ${opts});`);
+  }
+
+  if (resource.detailEndpoint) {
+    const fn = toAsyncDataName(resource.detailEndpoint.operationId);
+    subConnectors.push(`  const detail = useDetailConnector(${fn});`);
+  }
+
+  if (resource.createEndpoint) {
+    const fn = toAsyncDataName(resource.createEndpoint.operationId);
+    const schemaArg = resource.zodSchemas.create ? `{ schema: ${pascal}CreateSchema }` : '{}';
+    subConnectors.push(`  const createForm = useFormConnector(${fn}, ${schemaArg});`);
+  }
+
+  if (resource.updateEndpoint) {
+    const fn = toAsyncDataName(resource.updateEndpoint.operationId);
+    const hasDetail = !!resource.detailEndpoint;
+
+    // Build the options argument for useFormConnector:
+    //   schema      → Zod schema for client-side validation before submission
+    //   loadWith    → reference to the detail connector so the form auto-fills
+    //                 when detail.item changes (user clicks "Edit" on a row)
+    //
+    // Four combinations are possible depending on what the spec provides:
+    let schemaArg = '{}';
+    if (resource.zodSchemas.update && hasDetail) {
+      // Best case: validate AND pre-fill from detail
+      schemaArg = `{ schema: ${pascal}UpdateSchema, loadWith: detail }`;
+    } else if (resource.zodSchemas.update) {
+      // Validate, but no detail endpoint to pre-fill from
+      schemaArg = `{ schema: ${pascal}UpdateSchema }`;
+    } else if (hasDetail) {
+      // No Zod schema (no request body in spec), but still pre-fill from detail
+      schemaArg = `{ loadWith: detail }`;
+    }
+    subConnectors.push(`  const updateForm = useFormConnector(${fn}, ${schemaArg});`);
+  }
+
+  if (resource.deleteEndpoint) {
+    const fn = toAsyncDataName(resource.deleteEndpoint.operationId);
+    subConnectors.push(`  const deleteAction = useDeleteConnector(${fn});`);
+  }
+
+  // Return object — only include what was built
+  const returnKeys: string[] = [];
+  if (resource.listEndpoint) {
+    returnKeys.push('table');
+  }
+  if (resource.detailEndpoint) {
+    returnKeys.push('detail');
+  }
+  if (resource.createEndpoint) {
+    returnKeys.push('createForm');
+  }
+  if (resource.updateEndpoint) {
+    returnKeys.push('updateForm');
+  }
+  if (resource.deleteEndpoint) {
+    returnKeys.push('deleteAction');
+  }
+
+  const returnStatement = `  return { ${returnKeys.join(', ')} };`;
+
+  return [
+    `export function ${resource.composableName}() {`,
+    ...subConnectors,
+    returnStatement,
+    `}`,
+  ].join('\n');
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Generate the full source of a `use{Resource}Connector.ts` file.
+ *
+ * @param resource     ResourceInfo produced by Schema Analyzer
+ * @param composablesRelDir  Relative path from the connector dir to the
+ *                           useAsyncData composables dir (e.g. '../use-async-data')
+ */
+export function generateConnectorFile(resource: ResourceInfo, composablesRelDir: string): string {
+  const header = generateFileHeader();
+  const imports = buildImports(resource, composablesRelDir);
+  const schemas = buildZodSchemas(resource);
+  const fn = buildFunctionBody(resource);
+
+  // Assemble file: header + imports + (optional) Zod blocks + function body.
+  // Each section ends with its own trailing newline; join with \n adds one blank
+  // line between sections, which matches Prettier's output for this structure.
+  const parts: string[] = [header, imports];
+  if (schemas.trim()) {
+    parts.push(schemas);
+  }
+  parts.push(fn);
+
+  return parts.join('\n') + '\n';
+}
+
+/**
+ * Derive the output filename for a connector.
+ * 'usePetsConnector' → 'use-pets-connector.ts'
+ */
+export function connectorFileName(composableName: string): string {
+  return `${kebabCase(composableName)}.ts`;
+}
+
+/**
+ * Generate an index barrel file that re-exports all connectors.
+ */
+export function generateConnectorIndexFile(composableNames: string[]): string {
+  const header = generateFileHeader();
+  const exports = composableNames
+    .map((name) => `export { ${name} } from './${kebabCase(name)}';`)
+    .join('\n');
+  return `${header}${exports}\n`;
+}

package/src/generators/components/connector-generator/types.ts

@@ -0,0 +1,34 @@
+/**
+ * Types for the Connector Generator — Fase 3.
+ *
+ * The Connector Generator reads the ResourceMap produced by the Schema Analyzer
+ * and writes one `use{Resource}Connector.ts` file per resource.
+ */
+
+export interface ConnectorGeneratorOptions {
+  /** Absolute or relative path to the OpenAPI YAML/JSON spec */
+  inputSpec: string;
+  /** Directory where connector files will be written. E.g. ./composables/connectors */
+  outputDir: string;
+  /**
+   * Directory where the useAsyncData composables live, expressed as a path
+   * relative to outputDir. Defaults to '../use-async-data'.
+   */
+  composablesRelDir?: string;
+  /**
+   * Directory where runtime helpers will be copied to, expressed relative to
+   * outputDir. Defaults to '../runtime'.
+   */
+  runtimeRelDir?: string;
+}
+
+export interface ConnectorFileInfo {
+  /** PascalCase resource name. E.g. 'Pet' */
+  resourceName: string;
+  /** Generated composable function name. E.g. 'usePetsConnector' */
+  composableName: string;
+  /** Output filename (kebab-case). E.g. 'use-pets-connector.ts' */
+  fileName: string;
+  /** Formatted TypeScript source ready to be written to disk */
+  content: string;
+}

package/src/generators/components/schema-analyzer/index.ts

@@ -0,0 +1,44 @@
+/**
+ * Schema Analyzer — entry point
+ *
+ * Usage:
+ *   import { analyzeSpec } from './schema-analyzer/index.js'
+ *   const resourceMap = analyzeSpec('./swagger.yaml')
+ */
+
+export { readOpenApiSpec } from './openapi-reader.js';
+export { detectIntent, extractEndpoints } from './intent-detector.js';
+export { buildResourceMap } from './resource-grouper.js';
+export {
+  mapFieldsFromSchema,
+  mapColumnsFromSchema,
+  buildZodSchema,
+  zodExpressionFromProp,
+} from './schema-field-mapper.js';
+export type {
+  OpenApiSpec,
+  OpenApiSchema,
+  OpenApiPropertySchema,
+  OpenApiOperation,
+  OpenApiParameter,
+  EndpointInfo,
+  ResourceInfo,
+  ResourceMap,
+  FormFieldDef,
+  ColumnDef,
+  Intent,
+  FieldType,
+  ColumnType,
+} from './types.js';
+
+import { readOpenApiSpec } from './openapi-reader.js';
+import { buildResourceMap } from './resource-grouper.js';
+import type { ResourceMap } from './types.js';
+
+/**
+ * Convenience function: read a spec file and return the full ResourceMap.
+ */
+export function analyzeSpec(specPath: string): ResourceMap {
+  const spec = readOpenApiSpec(specPath);
+  return buildResourceMap(spec);
+}

package/src/generators/components/schema-analyzer/intent-detector.ts

@@ -0,0 +1,187 @@
+import type { EndpointInfo, Intent, OpenApiOperation, OpenApiPropertySchema } from './types.js';
+
+// HTTP methods we care about
+const MUTATING_METHODS = new Set(['POST', 'PUT', 'PATCH']);
+const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] as const;
+type HttpMethod = (typeof HTTP_METHODS)[number];
+
+// ─── Path analysis helpers ────────────────────────────────────────────────────
+
+/** Returns path parameter names found in a path, e.g. '/pets/{id}' → ['id'] */
+function extractPathParams(path: string): string[] {
+  const matches = path.match(/\{([^}]+)\}/g) ?? [];
+  return matches.map((m) => m.slice(1, -1));
+}
+
+/** True when the path ends with a path parameter: /pets/{id} */
+function endsWithPathParam(path: string): boolean {
+  return /\/\{[^}]+\}$/.test(path);
+}
+
+// ─── Response schema analysis ─────────────────────────────────────────────────
+
+/**
+ * Return the resolved schema for the first 2xx response that has
+ * an application/json body, or undefined.
+ */
+function getSuccessResponseSchema(operation: OpenApiOperation): OpenApiPropertySchema | undefined {
+  if (!operation.responses) {
+    return undefined;
+  }
+
+  for (const [statusCode, response] of Object.entries(operation.responses)) {
+    const code = parseInt(statusCode, 10);
+    if (isNaN(code) || code < 200 || code >= 300) {
+      continue;
+    }
+
+    const jsonContent = response.content?.['application/json'];
+    if (jsonContent?.schema) {
+      return jsonContent.schema;
+    }
+  }
+
+  return undefined;
+}
+
+/** True when schema represents an array (type: array, or items present) */
+function isArraySchema(schema: OpenApiPropertySchema): boolean {
+  return schema.type === 'array' || schema.items !== undefined;
+}
+
+// ─── Request body schema ──────────────────────────────────────────────────────
+
+function getRequestBodySchema(operation: OpenApiOperation): OpenApiPropertySchema | undefined {
+  if (!operation.requestBody?.content) {
+    return undefined;
+  }
+
+  const jsonContent = operation.requestBody.content['application/json'];
+  if (jsonContent?.schema) {
+    return jsonContent.schema;
+  }
+
+  // Fallback to form-urlencoded
+  const formContent = operation.requestBody.content['application/x-www-form-urlencoded'];
+  return formContent?.schema;
+}
+
+// ─── Intent detection ─────────────────────────────────────────────────────────
+
+/**
+ * Detect the CRUD intent of a single endpoint.
+ *
+ * Priority:
+ * 1. x-nxh-intent extension on the operation (developer override)
+ * 2. HTTP method + path pattern + response schema
+ */
+export function detectIntent(
+  method: HttpMethod,
+  path: string,
+  operation: OpenApiOperation
+): Intent {
+  // 1. Developer override via OpenAPI extension
+  const override = operation['x-nxh-intent'];
+  if (override) {
+    return override;
+  }
+
+  const hasPathParam = extractPathParams(path).length > 0;
+  const responseSchema = getSuccessResponseSchema(operation);
+
+  switch (method) {
+    case 'DELETE':
+      return 'delete';
+
+    case 'POST':
+      // POST /resource  → create
+      // POST /resource/{id}/action → unknown (custom action, not CRUD)
+      return !endsWithPathParam(path) ? 'create' : 'unknown';
+
+    case 'PUT':
+    case 'PATCH':
+      return 'update';
+
+    case 'GET': {
+      // A GET without a JSON response (e.g. binary download) is not a CRUD intent
+      if (!responseSchema) {
+        return 'unknown';
+      }
+
+      // Array response ( type: 'array' OR has 'items' ) → always a list
+      if (isArraySchema(responseSchema)) {
+        return 'list';
+      }
+
+      // Object response — distinguish list vs detail by path structure:
+      //   GET /pets/{id}  → has path param → detail (single item fetch)
+      //   GET /pets       → no path param  → list (likely paginated envelope: { data: [], total: n })
+      if (hasPathParam) {
+        return 'detail';
+      }
+
+      return 'list';
+    }
+
+    default:
+      return 'unknown';
+  }
+}
+
+// ─── Endpoint extraction ──────────────────────────────────────────────────────
+
+/**
+ * Extract all endpoints from a single path item as EndpointInfo[].
+ * The spec must already be $ref-resolved before calling this.
+ */
+export function extractEndpoints(
+  path: string,
+  pathItem: Record<string, OpenApiOperation>
+): EndpointInfo[] {
+  const results: EndpointInfo[] = [];
+  const pathParams = extractPathParams(path);
+
+  for (const method of HTTP_METHODS) {
+    const operation: OpenApiOperation | undefined = pathItem[method.toLowerCase()];
+
+    if (!operation) {
+      continue;
+    }
+
+    const intent = detectIntent(method, path, operation);
+
+    const endpoint: EndpointInfo = {
+      // Fallback operationId when the spec omits it: 'get_/pets/{id}' → 'get__pets__id_'
+      // This rarely produces a ideal composable name, but avoids a crash.
+      operationId: operation.operationId ?? `${method.toLowerCase()}_${path.replace(/\//g, '_')}`,
+      method,
+      path,
+      tags: operation.tags ?? [],
+      summary: operation.summary,
+      description: operation.description,
+      intent,
+      hasPathParams: pathParams.length > 0,
+      pathParams,
+    };
+
+    // Attach response schema for GET intents
+    if (method === 'GET') {
+      const schema = getSuccessResponseSchema(operation);
+      if (schema) {
+        endpoint.responseSchema = schema as import('./types.js').OpenApiSchema;
+      }
+    }
+
+    // Attach request body schema for mutating methods
+    if (MUTATING_METHODS.has(method)) {
+      const schema = getRequestBodySchema(operation);
+      if (schema) {
+        endpoint.requestBodySchema = schema as import('./types.js').OpenApiSchema;
+      }
+    }
+
+    results.push(endpoint);
+  }
+
+  return results;
+}