nuxt-openapi-hyperfetch 1.0.3 → 1.0.4

package/src/cli/config.ts

@@ -1,66 +1,50 @@
 import fs from 'fs-extra';
 import { join } from 'path';
+import { pathToFileURL } from 'url';
 import * as p from '@clack/prompts';
-import type { GeneratorBackend, ConfigGenerator } from './types.js';
+import type { GeneratorConfig, GeneratorType } from '../config/types.js';
 
 const { existsSync } = fs;
 
-/**
- * Configuration options for the generator
- */
-export interface GeneratorConfig {
-  /** Path or URL to OpenAPI specification */
-  input?: string;
-  /** Output directory for generated files */
-  output?: string;
-  /** Base URL for API requests */
-  baseUrl?: string;
-  /** Generation mode: client or server */
-  mode?: 'client' | 'server';
-  /** Generate only specific tags */
-  tags?: string[];
-  /** Exclude specific tags */
-  excludeTags?: string[];
-  /** Overwrite existing files without prompting */
-  overwrite?: boolean;
-  /** Preview changes without writing files */
-  dryRun?: boolean;
-  /** Enable verbose logging */
-  verbose?: boolean;
-  /** Watch mode - regenerate on file changes */
-  watch?: boolean;
-  /** Generator types to use */
-  generators?: ('useFetch' | 'useAsyncData' | 'nuxtServer' | 'connectors')[];
-  /** Server route path (for nuxtServer mode) */
-  serverRoutePath?: string;
-  /** Enable BFF pattern (for nuxtServer mode) */
-  enableBff?: boolean;
-  /** Generator backend: official (Java) or heyapi (Node.js) */
-  backend?: GeneratorBackend;
-  /**
-   * Generation engine to use.
-   * - 'openapi': @openapitools/openapi-generator-cli (requires Java 11+)
-   * - 'heyapi': @hey-api/openapi-ts (Node.js native, no Java required)
-   * When set, the CLI will not ask which engine to use.
-   */
-  generator?: ConfigGenerator;
-  /**
-   * Generate headless UI connector composables on top of useAsyncData.
-   * Connectors provide ready-made logic for tables, pagination, forms and delete actions.
-   * Requires useAsyncData to also be generated.
-   * @default false
-   */
-  createUseAsyncDataConnectors?: boolean;
+export type ComposableGeneratorType = 'useFetch' | 'useAsyncData' | 'nuxtServer';
+
+export interface NormalizedGenerators {
+  composables: ComposableGeneratorType[];
+  generateConnectors: boolean;
+}
+
+const COMPOSABLE_GENERATOR_ORDER: readonly ComposableGeneratorType[] = [
+  'useFetch',
+  'useAsyncData',
+  'nuxtServer',
+] as const;
+
+async function importConfigModule(configPath: string): Promise<unknown> {
+  try {
+    const module = await import(pathToFileURL(configPath).href);
+    return module.default || module;
+  } catch (error) {
+    if (!configPath.endsWith('.ts')) {
+      throw error;
+    }
+
+    const { createJiti } = await import('jiti');
+    const jiti = createJiti(import.meta.url, { interopDefault: true });
+    const module = jiti(configPath);
+    return module?.default || module;
+  }
 }
 
 /**
- * Load configuration from nxh.config.js, nuxt-openapi-generator.config.js, or package.json
+ * Load configuration from nxh.config.{ts,js,mjs}, nuxt-openapi-hyperfetch.{ts,js,mjs}, or package.json
  */
 export async function loadConfig(cwd: string = process.cwd()): Promise<GeneratorConfig | null> {
   // Try different config file names
   const configFiles = [
+    'nxh.config.ts',
     'nxh.config.js',
     'nxh.config.mjs',
+    'nuxt-openapi-hyperfetch.ts',
     'nuxt-openapi-hyperfetch.js',
     'nuxt-openapi-hyperfetch.mjs',
   ];
@@ -69,11 +53,8 @@ export async function loadConfig(cwd: string = process.cwd()): Promise<Generator
     const configPath = join(cwd, configFile);
     if (existsSync(configPath)) {
       try {
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-        const config = await import(`file://${configPath}`);
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment
-        const exportedConfig = config.default || config;
-        return exportedConfig as GeneratorConfig;
+        const config = await importConfigModule(configPath);
+        return config as GeneratorConfig;
       } catch (error) {
         p.log.warn(`Failed to load config from ${configFile}: ${String(error)}`);
       }
@@ -134,14 +115,37 @@ export function parseTags(tagsString?: string): string[] | undefined {
 /**
  * Parse generators string into array
  */
-export function parseGenerators(
-  generatorsString?: string
-): ('useFetch' | 'useAsyncData' | 'nuxtServer' | 'connectors')[] | undefined {
+export function parseGenerators(generatorsString?: string): GeneratorType[] | undefined {
   if (!generatorsString) {
     return undefined;
   }
   const parts = generatorsString.split(',').map((g) => g.trim());
-  return parts.filter((g): g is 'useFetch' | 'useAsyncData' | 'nuxtServer' | 'connectors' =>
+  return parts.filter((g): g is GeneratorType =>
     ['useFetch', 'useAsyncData', 'nuxtServer', 'connectors'].includes(g)
   );
 }
+
+/**
+ * Normalize generator selection so connectors can be requested declaratively.
+ * Rules:
+ * - If `connectors` is selected, `useAsyncData` is added automatically.
+ * - If `createUseAsyncDataConnectors` is true, connectors are enabled and
+ *   `useAsyncData` is added automatically.
+ */
+export function normalizeGenerators(
+  generators?: GeneratorType[],
+  createUseAsyncDataConnectors?: boolean
+): NormalizedGenerators {
+  const requested = new Set(generators ?? []);
+  const generateConnectors = requested.has('connectors') || createUseAsyncDataConnectors === true;
+
+  const composables: ComposableGeneratorType[] = COMPOSABLE_GENERATOR_ORDER.filter((generator) =>
+    requested.has(generator)
+  );
+
+  if (generateConnectors && !composables.includes('useAsyncData')) {
+    composables.push('useAsyncData');
+  }
+
+  return { composables, generateConnectors };
+}

package/src/config/connectors.ts

@@ -0,0 +1,48 @@
+import type { ConnectorsConfig, GeneratorConfig, GeneratorType } from './types.js';
+
+export type RuntimeComposableGenerator = 'useFetch' | 'useAsyncData' | 'nuxtServer';
+
+export function hasConnectorsConfig(connectors?: ConnectorsConfig): boolean {
+  if (!connectors) {
+    return false;
+  }
+
+  if (connectors.enabled === true) {
+    return true;
+  }
+
+  if (connectors.strategy !== undefined) {
+    return true;
+  }
+
+  return Object.keys(connectors.resources ?? {}).length > 0;
+}
+
+export function isConnectorsRequested(
+  config: Pick<GeneratorConfig, 'generators' | 'createUseAsyncDataConnectors' | 'connectors'>
+): boolean {
+  return (
+    config.createUseAsyncDataConnectors === true ||
+    (config.generators ?? []).includes('connectors') ||
+    hasConnectorsConfig(config.connectors)
+  );
+}
+
+export function toRuntimeComposableGenerators(
+  generators?: GeneratorType[]
+): RuntimeComposableGenerator[] {
+  return (generators ?? []).filter(
+    (g): g is RuntimeComposableGenerator =>
+      g === 'useFetch' || g === 'useAsyncData' || g === 'nuxtServer'
+  );
+}
+
+export function ensureUseAsyncDataForConnectors(
+  composables: RuntimeComposableGenerator[],
+  connectorsRequested: boolean
+): RuntimeComposableGenerator[] {
+  if (!connectorsRequested || composables.includes('useAsyncData')) {
+    return composables;
+  }
+  return [...composables, 'useAsyncData'];
+}

package/src/config/types.ts

@@ -0,0 +1,67 @@
+import type { GeneratorBackend, ConfigGenerator } from '../cli/types.js';
+
+export type GeneratorType = 'useFetch' | 'useAsyncData' | 'nuxtServer' | 'connectors';
+export type ConnectorStrategy = 'manual' | 'hybrid';
+export type ConnectorOperationName = 'getAll' | 'get' | 'create' | 'update' | 'delete';
+
+export interface ConnectorOperationConfig {
+  operationId?: string;
+  path?: string;
+}
+
+export interface ConnectorResourceConfig {
+  operations?: Partial<Record<ConnectorOperationName, ConnectorOperationConfig>>;
+}
+
+export interface ConnectorsConfig {
+  enabled?: boolean;
+  strategy?: ConnectorStrategy;
+  resources?: Record<string, ConnectorResourceConfig>;
+}
+
+/**
+ * Shared configuration contract used by both CLI (nxh.config.*) and Nuxt module (nuxt.config.ts).
+ */
+export interface GeneratorConfig {
+  /** Path or URL to OpenAPI specification */
+  input?: string;
+  /** Output directory for generated files */
+  output?: string;
+  /** Base URL for API requests */
+  baseUrl?: string;
+  /** Generation mode: client or server */
+  mode?: 'client' | 'server';
+  /** Generate only specific tags */
+  tags?: string[];
+  /** Exclude specific tags */
+  excludeTags?: string[];
+  /** Overwrite existing files without prompting */
+  overwrite?: boolean;
+  /** Preview changes without writing files */
+  dryRun?: boolean;
+  /** Enable verbose logging */
+  verbose?: boolean;
+  /** Watch mode - regenerate on file changes */
+  watch?: boolean;
+  /** Generator types to use */
+  generators?: GeneratorType[];
+  /** Server route path (for nuxtServer mode) */
+  serverRoutePath?: string;
+  /** Enable BFF pattern (for nuxtServer mode) */
+  enableBff?: boolean;
+  /** Generator backend: official (Java) or heyapi (Node.js) */
+  backend?: GeneratorBackend;
+  /**
+   * Generation engine to use.
+   * - 'openapi': @openapitools/openapi-generator-cli (requires Java 11+)
+   * - 'heyapi': @hey-api/openapi-ts (Node.js native, no Java required)
+   */
+  generator?: ConfigGenerator;
+  /**
+   * Generate headless UI connector composables on top of useAsyncData.
+   * Requires useAsyncData to also be generated.
+   */
+  createUseAsyncDataConnectors?: boolean;
+  /** Advanced connectors generation contract (manual/hybrid, custom resources, overloads). */
+  connectors?: ConnectorsConfig;
+}

package/src/generators/connectors/config-resolver.ts

@@ -0,0 +1,303 @@
+import { camelCase, pascalCase } from 'change-case';
+import type {
+  ConnectorsConfig,
+  ConnectorOperationConfig,
+  ConnectorOperationName,
+  ConnectorResourceConfig,
+} from '../../config/types.js';
+import type {
+  EndpointInfo,
+  OpenApiSchema,
+  ResourceInfo,
+  ResourceMap,
+} from '../components/schema-analyzer/types.js';
+import {
+  mapColumnsFromSchema,
+  mapFieldsFromSchema,
+  buildZodSchema,
+} from '../components/schema-analyzer/index.js';
+
+function toConnectorName(tag: string): string {
+  const pascal = pascalCase(tag);
+  const plural = /(?:s|x|z|ch|sh)$/i.test(pascal) ? `${pascal}es` : `${pascal}s`;
+  return `use${plural}Connector`;
+}
+
+function cloneResource(resource: ResourceInfo): ResourceInfo {
+  return {
+    ...resource,
+    endpoints: [...resource.endpoints],
+    columns: [...resource.columns],
+    formFields: {
+      ...(resource.formFields.create ? { create: [...resource.formFields.create] } : {}),
+      ...(resource.formFields.update ? { update: [...resource.formFields.update] } : {}),
+    },
+    zodSchemas: { ...resource.zodSchemas },
+  };
+}
+
+function getRefNameFromSchema(schema?: OpenApiSchema): string | undefined {
+  if (!schema) {
+    return undefined;
+  }
+
+  const directRef = schema['x-ref-name'];
+  if (typeof directRef === 'string') {
+    return directRef;
+  }
+
+  const items = schema.items;
+  if (items && typeof items === 'object') {
+    const itemRef = items['x-ref-name'];
+    if (typeof itemRef === 'string') {
+      return itemRef;
+    }
+  }
+
+  return undefined;
+}
+
+function rebuildDerived(resource: ResourceInfo): void {
+  const schemaForColumns =
+    resource.listEndpoint?.responseSchema ?? resource.detailEndpoint?.responseSchema;
+  resource.columns = schemaForColumns ? mapColumnsFromSchema(schemaForColumns) : [];
+
+  resource.formFields = {
+    ...(resource.createEndpoint?.requestBodySchema
+      ? { create: mapFieldsFromSchema(resource.createEndpoint.requestBodySchema) }
+      : {}),
+    ...(resource.updateEndpoint?.requestBodySchema
+      ? { update: mapFieldsFromSchema(resource.updateEndpoint.requestBodySchema) }
+      : {}),
+  };
+
+  resource.zodSchemas = {
+    ...(resource.createEndpoint?.requestBodySchema
+      ? { create: buildZodSchema(resource.createEndpoint.requestBodySchema) }
+      : {}),
+    ...(resource.updateEndpoint?.requestBodySchema
+      ? { update: buildZodSchema(resource.updateEndpoint.requestBodySchema) }
+      : {}),
+  };
+
+  resource.itemTypeName =
+    getRefNameFromSchema(resource.detailEndpoint?.responseSchema) ??
+    getRefNameFromSchema(resource.listEndpoint?.responseSchema) ??
+    undefined;
+}
+
+function expectedMethodsForOperation(
+  operationName: ConnectorOperationName
+): Array<EndpointInfo['method']> {
+  switch (operationName) {
+    case 'getAll':
+    case 'get':
+      return ['GET'];
+    case 'create':
+      return ['POST'];
+    case 'update':
+      return ['PUT', 'PATCH'];
+    case 'delete':
+      return ['DELETE'];
+  }
+}
+
+function selectByIntent(
+  operationName: ConnectorOperationName,
+  candidates: EndpointInfo[]
+): EndpointInfo[] {
+  if (operationName === 'getAll') {
+    const preferred = candidates.filter((c) => c.intent === 'list');
+    return preferred.length > 0 ? preferred : candidates;
+  }
+  if (operationName === 'get') {
+    const preferred = candidates.filter((c) => c.intent === 'detail');
+    return preferred.length > 0 ? preferred : candidates;
+  }
+  if (operationName === 'update') {
+    const put = candidates.filter((c) => c.method === 'PUT');
+    return put.length > 0 ? put : candidates;
+  }
+  return candidates;
+}
+
+function buildEndpointIndex(resourceMap: ResourceMap): {
+  byOperationId: Map<string, EndpointInfo>;
+  byPath: Map<string, EndpointInfo[]>;
+} {
+  const byOperationId = new Map<string, EndpointInfo>();
+  const byPath = new Map<string, EndpointInfo[]>();
+
+  for (const resource of resourceMap.values()) {
+    for (const endpoint of resource.endpoints) {
+      byOperationId.set(endpoint.operationId, endpoint);
+      const list = byPath.get(endpoint.path) ?? [];
+      list.push(endpoint);
+      byPath.set(endpoint.path, list);
+    }
+  }
+
+  return { byOperationId, byPath };
+}
+
+function resolveEndpoint(
+  operationName: ConnectorOperationName,
+  operationConfig: ConnectorOperationConfig,
+  endpointIndex: ReturnType<typeof buildEndpointIndex>,
+  resourceName: string
+): EndpointInfo {
+  if (operationConfig.operationId && operationConfig.path) {
+    throw new Error(
+      `[connectors] Resource "${resourceName}" operation "${operationName}" cannot define both operationId and path`
+    );
+  }
+
+  if (!operationConfig.operationId && !operationConfig.path) {
+    throw new Error(
+      `[connectors] Resource "${resourceName}" operation "${operationName}" must define operationId or path`
+    );
+  }
+
+  if (operationConfig.operationId) {
+    const endpoint = endpointIndex.byOperationId.get(operationConfig.operationId);
+    if (!endpoint) {
+      throw new Error(
+        `[connectors] Resource "${resourceName}" operation "${operationName}" references unknown operationId "${operationConfig.operationId}"`
+      );
+    }
+    return endpoint;
+  }
+
+  const candidates = endpointIndex.byPath.get(operationConfig.path!) ?? [];
+  if (candidates.length === 0) {
+    throw new Error(
+      `[connectors] Resource "${resourceName}" operation "${operationName}" references unknown path "${operationConfig.path}"`
+    );
+  }
+
+  const validMethods = expectedMethodsForOperation(operationName);
+  const byMethod = candidates.filter((c) => validMethods.includes(c.method));
+  if (byMethod.length === 0) {
+    throw new Error(
+      `[connectors] Resource "${resourceName}" operation "${operationName}" path "${operationConfig.path}" has no compatible method (${validMethods.join('/')})`
+    );
+  }
+
+  const prioritized = selectByIntent(operationName, byMethod);
+  return prioritized[0];
+}
+
+function setOperationEndpoint(
+  resource: ResourceInfo,
+  operationName: ConnectorOperationName,
+  endpoint: EndpointInfo
+): void {
+  switch (operationName) {
+    case 'getAll':
+      resource.listEndpoint = endpoint;
+      break;
+    case 'get':
+      resource.detailEndpoint = endpoint;
+      break;
+    case 'create':
+      resource.createEndpoint = endpoint;
+      break;
+    case 'update':
+      resource.updateEndpoint = endpoint;
+      break;
+    case 'delete':
+      resource.deleteEndpoint = endpoint;
+      break;
+  }
+
+  if (!resource.endpoints.some((ep) => ep.operationId === endpoint.operationId)) {
+    resource.endpoints.push(endpoint);
+  }
+}
+
+function createResourceSkeleton(resourceKey: string): ResourceInfo {
+  return {
+    name: pascalCase(resourceKey),
+    tag: resourceKey,
+    composableName: toConnectorName(resourceKey),
+    endpoints: [],
+    columns: [],
+    formFields: {},
+    zodSchemas: {},
+  };
+}
+
+function applyResourceOverrides(
+  target: ResourceInfo,
+  resourceName: string,
+  config: ConnectorResourceConfig,
+  endpointIndex: ReturnType<typeof buildEndpointIndex>
+): ResourceInfo {
+  const operations = config.operations ?? {};
+
+  for (const [operationName, operationConfig] of Object.entries(operations) as Array<
+    [ConnectorOperationName, ConnectorOperationConfig | undefined]
+  >) {
+    if (!operationConfig) {
+      continue;
+    }
+
+    const endpoint = resolveEndpoint(operationName, operationConfig, endpointIndex, resourceName);
+    setOperationEndpoint(target, operationName, endpoint);
+  }
+
+  rebuildDerived(target);
+  return target;
+}
+
+function normalizeConfig(
+  config?: ConnectorsConfig
+): Required<Pick<ConnectorsConfig, 'strategy'>> & ConnectorsConfig {
+  return {
+    strategy: config?.strategy ?? 'hybrid',
+    ...config,
+  };
+}
+
+export function resolveConnectorResourceMap(
+  baseResourceMap: ResourceMap,
+  connectorsConfig?: ConnectorsConfig
+): ResourceMap {
+  if (!connectorsConfig) {
+    return baseResourceMap;
+  }
+
+  const normalized = normalizeConfig(connectorsConfig);
+  const resourceConfigs = normalized.resources ?? {};
+  const endpointIndex = buildEndpointIndex(baseResourceMap);
+
+  if (normalized.strategy === 'manual') {
+    const manualMap: ResourceMap = new Map();
+
+    for (const [resourceName, resourceConfig] of Object.entries(resourceConfigs)) {
+      const resourceKey = camelCase(resourceName);
+      const baseResource = baseResourceMap.get(resourceKey);
+      const target = baseResource
+        ? cloneResource(baseResource)
+        : createResourceSkeleton(resourceName);
+
+      applyResourceOverrides(target, resourceName, resourceConfig, endpointIndex);
+      manualMap.set(resourceKey, target);
+    }
+
+    return manualMap;
+  }
+
+  const hybridMap: ResourceMap = new Map(
+    [...baseResourceMap.entries()].map(([key, value]) => [key, cloneResource(value)])
+  );
+
+  for (const [resourceName, resourceConfig] of Object.entries(resourceConfigs)) {
+    const resourceKey = camelCase(resourceName);
+    const target = hybridMap.get(resourceKey) ?? createResourceSkeleton(resourceName);
+    applyResourceOverrides(target, resourceName, resourceConfig, endpointIndex);
+    hybridMap.set(resourceKey, target);
+  }
+
+  return hybridMap;
+}

package/src/generators/connectors/generator.ts

@@ -9,6 +9,7 @@ import {
   generateConnectorIndexFile,
 } from './templates.js';
 import type { ConnectorGeneratorOptions } from './types.js';
+import { resolveConnectorResourceMap } from './config-resolver.js';
 import { type Logger, createClackLogger } from '../../cli/logger.js';
 
 // Runtime files that must be copied to the user's project
@@ -56,7 +57,8 @@ export async function generateConnectors(
 
   // ── 1. Analyze spec ───────────────────────────────────────────────────────
   spinner.start('Analyzing OpenAPI spec');
-  const resourceMap = analyzeSpec(options.inputSpec);
+  const baseResourceMap = analyzeSpec(options.inputSpec);
+  const resourceMap = resolveConnectorResourceMap(baseResourceMap, options.connectorsConfig);
   spinner.stop(`Found ${resourceMap.size} resource(s)`);
 
   if (resourceMap.size === 0) {

package/src/generators/connectors/templates.ts

@@ -181,6 +181,7 @@ function buildOptionsInterface(resource: ResourceInfo): string {
   if (resource.listEndpoint && hasColumns) {
     fields.push(`  columnLabels?: Record<string, string>;`);
     fields.push(`  columnLabel?: (key: string) => string;`);
+    fields.push(`  getAllRequestOptions?: Record<string, unknown>;`);
   }
   if (resource.createEndpoint && resource.zodSchemas.create) {
     const pascal = pascalCase(resource.name);
@@ -264,7 +265,9 @@ function buildFunctionBody(resource: ResourceInfo): string {
   // Options destructure
   const optionKeys: string[] = [];
   if (resource.listEndpoint && hasColumns) {
-    optionKeys.push('columnLabels', 'columnLabel');
+    optionKeys.push('columnLabels', 'columnLabel', 'getAllRequestOptions');
+  } else if (resource.listEndpoint) {
+    optionKeys.push('getAllRequestOptions');
   }
   if (resource.createEndpoint && resource.zodSchemas.create) {
     optionKeys.push('createSchema');
@@ -317,7 +320,7 @@ function buildFunctionBody(resource: ResourceInfo): string {
       `  const isFactory = typeof paramsOrSource === 'function';`,
       `  const listFactory = isFactory`,
       `    ? (paramsOrSource as () => unknown)`,
-      `    : () => ${fn}((paramsOrSource ?? {}) as ${listRequestTypeName});`,
+      `    : () => ${fn}((paramsOrSource ?? {}) as ${listRequestTypeName}, { paginated: true, ...(getAllRequestOptions ?? {}) });`,
       `  const getAll = useGetAllConnector(listFactory, ${opts}) as unknown as GetAllConnectorReturn<${pascal}>;`
     );
   } else {

package/src/generators/connectors/types.ts

@@ -5,6 +5,8 @@
  * and writes one `use{Resource}Connector.ts` file per resource using $fetch for mutations.
  */
 
+import type { ConnectorsConfig } from '../../config/types.js';
+
 export interface ConnectorGeneratorOptions {
   /** Absolute or relative path to the OpenAPI YAML/JSON spec */
   inputSpec: string;
@@ -25,6 +27,8 @@ export interface ConnectorGeneratorOptions {
    * useRuntimeConfig().public.apiBaseUrl at runtime.
    */
   baseUrl?: string;
+  /** Advanced connectors configuration (manual/hybrid, custom resources, overloads). */
+  connectorsConfig?: ConnectorsConfig;
 }
 
 export interface ConnectorFileInfo {