nuxt-openapi-hyperfetch 1.0.2 → 1.0.4

package/README.md

@@ -1,6 +1,4 @@
-# nuxt-openapi-hyperfetch
-
-<p align="center">
+<p align="center">
   <img src="https://raw.githubusercontent.com/dmartindiaz/nuxt-openapi-hyperfetch/main/public/nuxt-openapi-hyperfetch-logo.png" alt="Nuxt OpenAPI Hyperfetch logo" width="260" />
 </p>
 
@@ -51,10 +49,10 @@ One composable per endpoint, for when you need direct control:
 
 ```ts
 // useFetch — reactive, bound to template lifecycle
-const { data: pet, pending, error } = useFetchGetPetById({ petId: 123 })
+const { data: pet, pending, error } = useFetchGetPetById({ petId: 123 });
 
 // useAsyncData — SSR-compatible, awaitable
-const { data: pets } = await useAsyncDataFindPets({ status: 'available' })
+const { data: pets } = await useAsyncDataFindPets({ status: 'available' });
 ```
 
 With callbacks and request modification:
@@ -66,13 +64,13 @@ const { data } = useFetchFindPets(
   {
     onRequest: (ctx) => {
       // ctx: { url, method, headers, query, body }
-      return { headers: { 'X-Source': 'pets-page' } }
+      return { headers: { 'X-Source': 'pets-page' } };
     },
     onSuccess: (pets) => console.log(`${pets.length} pets loaded`),
     onError: (err) => console.error(err.message),
     onFinish: ({ success }) => console.log('Done:', success),
   }
-)
+);
 
 // useAsyncData — onSuccess and onError receive a second context argument
 const { data: pets } = await useAsyncDataFindPets(
@@ -82,7 +80,7 @@ const { data: pets } = await useAsyncDataFindPets(
     onSuccess: (pets, ctx) => console.log(`${pets.length} from ${ctx.url}`),
     onError: (err, ctx) => console.error(err.message, ctx.url),
   }
-)
+);
 ```
 
 ---
@@ -97,7 +95,7 @@ Client → Nuxt Server Route (generated) → External API
 
 ```ts
 // Works automatically after generation
-const { data } = useFetch('/api/pet/123')
+const { data } = useFetch('/api/pet/123');
 ```
 
 ---
@@ -107,19 +105,19 @@ const { data } = useFetch('/api/pet/123')
 A connector exposes five sub-composables for one resource. For a `pet` tag in your spec:
 
 ```ts
-const { getAll, get, create, update, del } = usePetsConnector()
+const { getAll, get, create, update, del } = usePetsConnector();
 ```
 
 ### Full CRUD page in one component
 
 ```vue
 <script setup lang="ts">
-const { getAll, create, update, del } = usePetsConnector()
+const { getAll, create, update, del } = usePetsConnector();
 
 // Reload the list after every mutation
-create.onSuccess(() => getAll.load())
-update.onSuccess(() => getAll.load())
-del.onSuccess(()    => getAll.load())
+create.onSuccess(() => getAll.load());
+update.onSuccess(() => getAll.load());
+del.onSuccess(() => getAll.load());
 </script>
 
 <template>
@@ -143,8 +141,7 @@ del.onSuccess(()    => getAll.load())
         <UInput v-model="create.model.value.name" />
       </UFormField>
       <UFormField label="Status">
-        <USelect v-model="create.model.value.status"
-          :options="['available','pending','sold']" />
+        <USelect v-model="create.model.value.status" :options="['available', 'pending', 'sold']" />
       </UFormField>
       <template #footer>
         <UButton :loading="create.loading.value" @click="create.execute()">Save</UButton>
@@ -157,8 +154,9 @@ del.onSuccess(()    => getAll.load())
     <UCard>
       <UInput v-model="update.model.value.name" />
       <template #footer>
-        <UButton :loading="update.loading.value"
-          @click="update.execute(update.model.value.id)">Save changes</UButton>
+        <UButton :loading="update.loading.value" @click="update.execute(update.model.value.id)"
+          >Save changes</UButton
+        >
       </template>
     </UCard>
   </UModal>
@@ -166,7 +164,10 @@ del.onSuccess(()    => getAll.load())
   <!-- Delete confirmation -->
   <UModal v-model:open="del.ui.isOpen.value">
     <UCard>
-      <p>Delete <strong>{{ del.staged.value?.name }}</strong>?</p>
+      <p>
+        Delete <strong>{{ del.staged.value?.name }}</strong
+        >?
+      </p>
       <template #footer>
         <UButton color="red" :loading="del.loading.value" @click="del.execute()">Delete</UButton>
         <UButton variant="outline" @click="del.ui.close()">Cancel</UButton>
@@ -178,21 +179,21 @@ del.onSuccess(()    => getAll.load())
 
 ### What each sub-connector provides
 
-| Key | Transport | What you get |
-|---|---|---|
+| Key      | Transport      | What you get                                                               |
+| -------- | -------------- | -------------------------------------------------------------------------- |
 | `getAll` | `useAsyncData` | `items`, `columns`, `loading`, `error`, `pagination`, `selected`, `load()` |
-| `get` | `$fetch` | `data`, `loading`, `error`, `load(id)`, `clear()` |
-| `create` | `$fetch` | `model`, `errors`, `isValid`, `execute()`, `reset()`, `ui.open/close` |
-| `update` | `$fetch` | Same as create + `load(id)`, `ui.open(row)`, `targetId` |
-| `del` | `$fetch` | `staged`, `hasStaged`, `execute()`, `ui.open(item)/close` |
+| `get`    | `$fetch`       | `data`, `loading`, `error`, `load(id)`, `clear()`                          |
+| `create` | `$fetch`       | `model`, `errors`, `isValid`, `execute()`, `reset()`, `ui.open/close`      |
+| `update` | `$fetch`       | Same as create + `load(id)`, `ui.open(row)`, `targetId`                    |
+| `del`    | `$fetch`       | `staged`, `hasStaged`, `execute()`, `ui.open(item)/close`                  |
 
 ### Reactive list parameters
 
 ```ts
-const status = ref('available')
+const status = ref('available');
 
 // Re-fetches automatically when status changes
-const { getAll } = usePetsConnector(() => ({ status: status.value }))
+const { getAll } = usePetsConnector(() => ({ status: status.value }));
 ```
 
 ### Zod validation, out of the box
@@ -201,11 +202,15 @@ Schemas are generated from your OpenAPI `requestBody`. `create.execute()` valida
 
 ```ts
 // Extend the generated schema for extra rules
-const { create } = usePetsConnector({}, {
-  createSchema: (base) => base.extend({
-    name: z.string().min(2, 'At least 2 characters'),
-  })
-})
+const { create } = usePetsConnector(
+  {},
+  {
+    createSchema: (base) =>
+      base.extend({
+        name: z.string().min(2, 'At least 2 characters'),
+      }),
+  }
+);
 ```
 
 ### Global callbacks
@@ -217,11 +222,11 @@ Register once, applies to every API call in the app:
 defineGlobalApiCallbacks([
   {
     onRequest: (ctx) => ({
-      headers: { Authorization: `Bearer ${useAuthStore().token}` }
+      headers: { Authorization: `Bearer ${useAuthStore().token}` },
     }),
     onError: (err) => useToast().add({ title: err.message, color: 'red' }),
-  }
-])
+  },
+]);
 ```
 
 Connector-level and per-operation callbacks are also available — see [Callbacks docs](./docs/connectors/callbacks.md).
@@ -244,6 +249,55 @@ nxh generate -i ./swagger.yaml -o ./composables/api
 
 The CLI asks for your spec path, output folder, engine (`heyapi` or `official`), and which generators to run.
 
+### Generators semantics (CLI + config)
+
+`generators` now supports `connectors` as a declarative option.
+
+- `['connectors']` → generates `useAsyncData` + `connectors`
+- `['useAsyncData']` → generates only `useAsyncData`
+- `['useAsyncData', 'connectors']` → generates both
+
+`createUseAsyncDataConnectors` is still supported for backward compatibility, but `generators: ['connectors']` is the recommended setup.
+
+### Typed `nxh.config.ts`
+
+The CLI now supports `nxh.config.ts` (besides `.js`/`.mjs`).
+
+```ts
+// nxh.config.ts
+import type { GeneratorConfig } from 'nuxt-openapi-hyperfetch';
+
+const config: GeneratorConfig = {
+  input: './swagger.yaml',
+  output: './composables/api',
+  generators: ['useAsyncData', 'connectors'],
+  connectors: {
+    strategy: 'hybrid',
+    resources: {
+      pets: {
+        operations: {
+          getAll: { operationId: 'findPetsByStatus' },
+          get: { path: '/pet/{petId}' },
+        },
+      },
+      featuredPets: {
+        operations: {
+          getAll: { operationId: 'findPetsByTags' },
+          get: { operationId: 'getPetById' },
+        },
+      },
+    },
+  },
+};
+
+export default config;
+```
+
+`connectors.strategy` supports:
+
+- `manual`: generate only resources defined by the user
+- `hybrid`: start from inferred resources and apply user overrides/custom resources
+
 ### Nuxt module
 
 ```ts
@@ -254,11 +308,11 @@ export default defineNuxtConfig({
   openApiHyperFetch: {
     input: './swagger.yaml',
     output: './composables/api',
-    generators: ['useFetch', 'useAsyncData', 'nuxtServer'],
+    generators: ['useFetch', 'connectors', 'nuxtServer'],
     backend: 'heyapi',
     enableAutoImport: true,
   },
-})
+});
 ```
 
 ### Configure the base URL
@@ -266,7 +320,9 @@ export default defineNuxtConfig({
 ```ts
 // nuxt.config.ts
 runtimeConfig: {
-  public: { apiBaseUrl: process.env.NUXT_PUBLIC_API_BASE_URL || 'https://api.example.com' }
+  public: {
+    apiBaseUrl: process.env.NUXT_PUBLIC_API_BASE_URL || 'https://api.example.com';
+  }
 }
 ```
 
@@ -276,28 +332,28 @@ All generated composables and connectors pick up `apiBaseUrl` automatically.
 
 ## Two generation engines
 
-| Engine | Requires | Best for |
-|---|---|---|
-| `heyapi` | Node only | Quick setup, CI/CD |
-| `official` | Java 11+ | Maximum spec compatibility |
+| Engine     | Requires  | Best for                   |
+| ---------- | --------- | -------------------------- |
+| `heyapi`   | Node only | Quick setup, CI/CD         |
+| `official` | Java 11+  | Maximum spec compatibility |
 
 Pre-select in `nxh.config.js` to skip the prompt:
 
 ```js
-export default { generator: 'heyapi', input: './swagger.yaml', output: './api' }
+export default { generator: 'heyapi', input: './swagger.yaml', output: './api' };
 ```
 
 ---
 
 ## Documentation
 
-| | |
-|---|---|
-| [Connectors](./docs/connectors/index.md) | Full connector API reference and examples |
-| [Quick Start](./docs/QUICK-START.md) | From zero to working composables in 5 minutes |
-| [API Reference](./docs/API-REFERENCE.md) | All options and TypeScript types |
-| [Architecture](./docs/ARCHITECTURE.md) | How the generator works internally |
-| [Troubleshooting](./docs/TROUBLESHOOTING.md) | Common errors and solutions |
+|                                              |                                               |
+| -------------------------------------------- | --------------------------------------------- |
+| [Connectors](./docs/connectors/index.md)     | Full connector API reference and examples     |
+| [Quick Start](./docs/QUICK-START.md)         | From zero to working composables in 5 minutes |
+| [API Reference](./docs/API-REFERENCE.md)     | All options and TypeScript types              |
+| [Architecture](./docs/ARCHITECTURE.md)       | How the generator works internally            |
+| [Troubleshooting](./docs/TROUBLESHOOTING.md) | Common errors and solutions                   |
 
 ---
 
@@ -311,7 +367,6 @@ npm run validate   # lint + type check
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md).
 
-
 ---
 
 ## License

package/dist/cli/config.d.ts

@@ -1,53 +1,11 @@
-import type { GeneratorBackend, ConfigGenerator } from './types.js';
-/**
- * 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;
+import type { GeneratorConfig, GeneratorType } from '../config/types.js';
+export type ComposableGeneratorType = 'useFetch' | 'useAsyncData' | 'nuxtServer';
+export interface NormalizedGenerators {
+    composables: ComposableGeneratorType[];
+    generateConnectors: boolean;
 }
 /**
- * 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 declare function loadConfig(cwd?: string): Promise<GeneratorConfig | null>;
 /**
@@ -61,4 +19,12 @@ export declare function parseTags(tagsString?: string): string[] | undefined;
 /**
  * Parse generators string into array
  */
-export declare function parseGenerators(generatorsString?: string): ('useFetch' | 'useAsyncData' | 'nuxtServer' | 'connectors')[] | undefined;
+export declare function parseGenerators(generatorsString?: string): GeneratorType[] | undefined;
+/**
+ * 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 declare function normalizeGenerators(generators?: GeneratorType[], createUseAsyncDataConnectors?: boolean): NormalizedGenerators;

package/dist/cli/config.js

@@ -1,15 +1,38 @@
 import fs from 'fs-extra';
 import { join } from 'path';
+import { pathToFileURL } from 'url';
 import * as p from '@clack/prompts';
 const { existsSync } = fs;
+const COMPOSABLE_GENERATOR_ORDER = [
+    'useFetch',
+    'useAsyncData',
+    'nuxtServer',
+];
+async function importConfigModule(configPath) {
+    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 = process.cwd()) {
     // 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',
     ];
@@ -17,11 +40,8 @@ export async function loadConfig(cwd = process.cwd()) {
         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;
+                const config = await importConfigModule(configPath);
+                return config;
             }
             catch (error) {
                 p.log.warn(`Failed to load config from ${configFile}: ${String(error)}`);
@@ -83,3 +103,19 @@ export function parseGenerators(generatorsString) {
     const parts = generatorsString.split(',').map((g) => g.trim());
     return parts.filter((g) => ['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, createUseAsyncDataConnectors) {
+    const requested = new Set(generators ?? []);
+    const generateConnectors = requested.has('connectors') || createUseAsyncDataConnectors === true;
+    const composables = COMPOSABLE_GENERATOR_ORDER.filter((generator) => requested.has(generator));
+    if (generateConnectors && !composables.includes('useAsyncData')) {
+        composables.push('useAsyncData');
+    }
+    return { composables, generateConnectors };
+}

package/dist/config/connectors.d.ts

@@ -0,0 +1,6 @@
+import type { ConnectorsConfig, GeneratorConfig, GeneratorType } from './types.js';
+export type RuntimeComposableGenerator = 'useFetch' | 'useAsyncData' | 'nuxtServer';
+export declare function hasConnectorsConfig(connectors?: ConnectorsConfig): boolean;
+export declare function isConnectorsRequested(config: Pick<GeneratorConfig, 'generators' | 'createUseAsyncDataConnectors' | 'connectors'>): boolean;
+export declare function toRuntimeComposableGenerators(generators?: GeneratorType[]): RuntimeComposableGenerator[];
+export declare function ensureUseAsyncDataForConnectors(composables: RuntimeComposableGenerator[], connectorsRequested: boolean): RuntimeComposableGenerator[];

package/dist/config/connectors.js

@@ -0,0 +1,26 @@
+export function hasConnectorsConfig(connectors) {
+    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) {
+    return (config.createUseAsyncDataConnectors === true ||
+        (config.generators ?? []).includes('connectors') ||
+        hasConnectorsConfig(config.connectors));
+}
+export function toRuntimeComposableGenerators(generators) {
+    return (generators ?? []).filter((g) => g === 'useFetch' || g === 'useAsyncData' || g === 'nuxtServer');
+}
+export function ensureUseAsyncDataForConnectors(composables, connectorsRequested) {
+    if (!connectorsRequested || composables.includes('useAsyncData')) {
+        return composables;
+    }
+    return [...composables, 'useAsyncData'];
+}

package/dist/config/types.d.ts

@@ -0,0 +1,62 @@
+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/dist/config/types.js

@@ -0,0 +1 @@
+export {};

package/dist/generators/connectors/config-resolver.d.ts

@@ -0,0 +1,3 @@
+import type { ConnectorsConfig } from '../../config/types.js';
+import type { ResourceMap } from '../components/schema-analyzer/types.js';
+export declare function resolveConnectorResourceMap(baseResourceMap: ResourceMap, connectorsConfig?: ConnectorsConfig): ResourceMap;