nuxt-openapi-hyperfetch 0.2.8-alpha.1 → 0.3.1-beta

package/README.md

@@ -1,4 +1,8 @@
-# 🚀 Nuxt OpenAPI Generator
+<p align="center">
+  <img src="./public/nuxt-openapi-hyperfetch-logo.png" alt="Nuxt OpenAPI Hyperfetch logo" width="260" />
+</p>
+
+# 🚀 Nuxt OpenAPI Generator
 
 **Generate type-safe, SSR-compatible Nuxt composables from OpenAPI/Swagger specifications.**
 
@@ -6,7 +10,7 @@
 
 ---
 
-Transform your API documentation into production-ready **100% Nuxt-native** code—`useFetch` composables, `useAsyncData` composables, and Nuxt Server Routes—with full TypeScript support, lifecycle callbacks, and request interception. No third-party runtime, no wrappers: just Nuxt.
+Transform your API documentation into production-ready **100% Nuxt-native** code—`useFetch` composables, `useAsyncData` composables, and Nuxt Server Routes—with full TypeScript support, lifecycle callbacks, and request interception. Use it either as a CLI with `nxh generate` or as a Nuxt module wired directly from `nuxt.config.ts`.
 
 ---
 
@@ -52,6 +56,8 @@ export default {
 
 ## 📦 Installation
 
+### Use as CLI
+
 ```bash
 npm install -g nuxt-openapi-hyperfetch
 # or
@@ -66,11 +72,49 @@ Or use directly with npx:
 npx nuxt-openapi-hyperfetch generate
 ```
 
+### Use as Nuxt module
+
+Install it in your Nuxt project:
+
+```bash
+npm install -D nuxt-openapi-hyperfetch
+# or
+pnpm add -D nuxt-openapi-hyperfetch
+# or
+yarn add -D nuxt-openapi-hyperfetch
+```
+
+Then register the module in `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  modules: ['nuxt-openapi-hyperfetch'],
+
+  openApiHyperFetch: {
+    input: './swagger.yaml',
+    output: './composables/api',
+    generators: ['useFetch', 'useAsyncData'],
+    backend: 'heyapi',
+    enableDevBuild: true,
+    enableProductionBuild: true,
+    enableAutoGeneration: false,
+    enableAutoImport: true,
+    createUseAsyncDataConnectors: false,
+  },
+})
+```
+
+The module uses `openApiHyperFetch` as its Nuxt config key and runs generation during Nuxt build hooks. If you include `nuxtServer` in `generators`, you can also configure `serverRoutePath` and `enableBff` here.
+
 ---
 
 ## 🚀 Quick Start
 
-### 1. Run the generator
+### 1. Run the generator with the CLI
+
+<p align="center">
+  <img src="./public/nuxt-openapi-hyperfetch-cli.png" alt="Nuxt OpenAPI Hyperfetch CLI" width="720" />
+</p>
 
 ```bash
 nxh generate
@@ -89,7 +133,41 @@ Or pass arguments directly:
 nxh generate -i ./swagger.yaml -o ./api
 ```
 
-### 2. Generated output
+### 2. Or generate through the Nuxt module
+
+If you prefer generation to run from Nuxt itself, add the module and configure it in `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  modules: ['nuxt-openapi-hyperfetch'],
+
+  openApiHyperFetch: {
+    input: './swagger.yaml',
+    output: './composables/api',
+    generators: ['useFetch', 'useAsyncData', 'nuxtServer'],
+    backend: 'heyapi',
+    serverRoutePath: 'server/routes/api',
+    enableBff: false,
+    enableAutoImport: true,
+    enableAutoGeneration: true,
+  },
+})
+```
+
+Useful module options:
+
+- `input`: OpenAPI file path relative to the Nuxt root.
+- `output`: Directory where the generated SDK/composables are written.
+- `generators`: Any combination of `useFetch`, `useAsyncData`, and `nuxtServer`.
+- `backend`: `heyapi` or `official`.
+- `enableDevBuild` / `enableProductionBuild`: Control generation before dev/build.
+- `enableAutoGeneration`: Regenerate when the input spec changes in dev mode.
+- `enableAutoImport`: Auto-register generated composables for Nuxt auto-imports.
+- `createUseAsyncDataConnectors`: Generate headless connectors on top of `useAsyncData`.
+- `serverRoutePath`: Output path for generated Nuxt server routes.
+- `enableBff`: Enable the BFF transformer layer for server routes.
+
+### 3. Generated output
 
 ```
 api/
@@ -110,7 +188,7 @@ api/
         +-- index.ts
 ```
 
-### 3. Configure the API base URL
+### 4. Configure the API base URL
 
 Add to `nuxt.config.ts`:
 
@@ -132,7 +210,7 @@ NUXT_PUBLIC_API_BASE_URL=https://api.example.com
 
 All generated `useFetch` and `useAsyncData` composables will automatically use this as `baseURL`. You can still override it per-composable via `options.baseURL`.
 
-### 4. Use in your Nuxt app
+### 5. Use in your Nuxt app
 
 ```vue
 <script setup lang="ts">

package/dist/generators/components/connector-generator/generator.js

@@ -7,6 +7,7 @@ import { generateConnectorFile, connectorFileName, generateConnectorIndexFile, }
 import { createClackLogger } from '../../../cli/logger.js';
 // Runtime files that must be copied to the user's project
 const RUNTIME_FILES = [
+    'connector-types.ts',
     'useListConnector.ts',
     'useDetailConnector.ts',
     'useFormConnector.ts',

package/dist/generators/components/connector-generator/templates.d.ts

@@ -6,7 +6,7 @@ import type { ResourceInfo } from '../schema-analyzer/types.js';
  * @param composablesRelDir  Relative path from the connector dir to the
  *                           useAsyncData composables dir (e.g. '../use-async-data')
  */
-export declare function generateConnectorFile(resource: ResourceInfo, composablesRelDir: string): string;
+export declare function generateConnectorFile(resource: ResourceInfo, composablesRelDir: string, sdkRelDir?: string): string;
 /**
  * Derive the output filename for a connector.
  * 'usePetsConnector' → 'use-pets-connector.ts'

package/dist/generators/components/connector-generator/templates.js

@@ -12,7 +12,6 @@ function generateFileHeader() {
  */
 
 /* eslint-disable */
-// @ts-nocheck
 `;
 }
 // ─── Naming helpers ───────────────────────────────────────────────────────────
@@ -34,16 +33,33 @@ function toFileName(composableName) {
 /**
  * Build all `import` lines for a resource connector.
  */
-function buildImports(resource, composablesRelDir) {
+function buildImports(resource, composablesRelDir, sdkRelDir) {
     const lines = [];
     // zod
     lines.push(`import { z } from 'zod';`);
     lines.push('');
-    // runtime helpers (Nuxt alias — set up by the Nuxt module)
-    const runtimeHelpers = [];
+    // connector-types — structural interfaces for return types
+    const connectorTypeImports = ['ListConnectorReturn'];
+    if (resource.detailEndpoint) {
+        connectorTypeImports.push('DetailConnectorReturn');
+    }
+    if (resource.createEndpoint || resource.updateEndpoint) {
+        connectorTypeImports.push('FormConnectorReturn');
+    }
+    if (resource.deleteEndpoint) {
+        connectorTypeImports.push('DeleteConnectorReturn');
+    }
+    lines.push(`import type { ${connectorTypeImports.join(', ')} } from '#nxh/runtime/connector-types';`);
+    lines.push('');
+    // SDK request/response types (for the params overload signature)
     if (resource.listEndpoint) {
-        runtimeHelpers.push('useListConnector');
+        const requestTypeName = `${pascalCase(resource.listEndpoint.operationId)}Request`;
+        lines.push(`import type { ${requestTypeName} } from '${sdkRelDir}';`);
+        lines.push('');
     }
+    // runtime helpers (Nuxt alias — set up by the Nuxt module)
+    // useListConnector is always imported to support the optional factory pattern
+    const runtimeHelpers = ['useListConnector'];
     if (resource.detailEndpoint) {
         runtimeHelpers.push('useDetailConnector');
     }
@@ -103,63 +119,157 @@ function buildZodSchemas(resource) {
     }
     return lines.join('\n');
 }
+/**
+ * Build a const array with the column definitions inferred from the resource.
+ * Returns an empty string if the resource has no columns.
+ */
+function buildColumns(resource) {
+    if (!resource.columns || resource.columns.length === 0) {
+        return '';
+    }
+    const camel = resource.composableName
+        .replace(/^use/, '')
+        .replace(/Connector$/, '')
+        .replace(/^./, (c) => c.toLowerCase());
+    const varName = `${camel}Columns`;
+    const entries = resource.columns
+        .map((col) => `  { key: '${col.key}', label: '${col.label}', type: '${col.type}' }`)
+        .join(',\n');
+    return `const ${varName} = [\n${entries},\n];`;
+}
+/**
+ * Build the TypeScript options interface for a connector.
+ * Only includes fields relevant to the endpoints present on the resource.
+ */
+function buildOptionsInterface(resource) {
+    const typeName = `${pascalCase(resource.composableName)}Options`;
+    const hasColumns = resource.columns && resource.columns.length > 0;
+    const fields = [];
+    if (resource.listEndpoint && hasColumns) {
+        fields.push(`  columnLabels?: Record<string, string>;`);
+        fields.push(`  columnLabel?: (key: string) => string;`);
+    }
+    if (resource.createEndpoint && resource.zodSchemas.create) {
+        fields.push(`  createSchema?: z.ZodTypeAny | ((base: z.ZodTypeAny) => z.ZodTypeAny);`);
+    }
+    if (resource.updateEndpoint && resource.zodSchemas.update) {
+        fields.push(`  updateSchema?: z.ZodTypeAny | ((base: z.ZodTypeAny) => z.ZodTypeAny);`);
+    }
+    if (fields.length === 0) {
+        return `type ${typeName} = Record<string, never>;`;
+    }
+    return [`interface ${typeName} {`, ...fields, `}`].join('\n');
+}
+/**
+ * Build the TypeScript return type for a connector.
+ */
+function buildReturnType(resource) {
+    const pascal = pascalCase(resource.name);
+    const typeName = `${pascalCase(resource.composableName)}Return`;
+    const fields = [];
+    // table is always present in the return type:
+    //   - if listEndpoint exists → ListConnectorReturn<T> (always defined)
+    //   - if no listEndpoint      → ListConnectorReturn<unknown> | undefined (only when factory passed)
+    if (resource.listEndpoint) {
+        fields.push(`  table: ListConnectorReturn<${pascal}>;`);
+    }
+    else {
+        fields.push(`  table: ListConnectorReturn<unknown> | undefined;`);
+    }
+    if (resource.detailEndpoint) {
+        fields.push(`  detail: DetailConnectorReturn<${pascal}>;`);
+    }
+    if (resource.createEndpoint) {
+        const inputType = resource.zodSchemas.create ? `${pascal}CreateInput` : `Record<string, unknown>`;
+        fields.push(`  createForm: FormConnectorReturn<${inputType}>;`);
+    }
+    if (resource.updateEndpoint) {
+        const inputType = resource.zodSchemas.update ? `${pascal}UpdateInput` : `Record<string, unknown>`;
+        fields.push(`  updateForm: FormConnectorReturn<${inputType}>;`);
+    }
+    if (resource.deleteEndpoint) {
+        fields.push(`  deleteAction: DeleteConnectorReturn<${pascal}>;`);
+    }
+    return [`type ${typeName} = {`, ...fields, `};`].join('\n');
+}
 /**
  * Build the body of the exported connector function.
  */
 function buildFunctionBody(resource) {
     const pascal = pascalCase(resource.name);
+    const hasColumns = resource.columns && resource.columns.length > 0;
+    const camel = resource.composableName
+        .replace(/^use/, '')
+        .replace(/Connector$/, '')
+        .replace(/^./, (c) => c.toLowerCase());
+    const columnsVar = `${camel}Columns`;
     const subConnectors = [];
+    // Derived type names — must match buildOptionsInterface / buildReturnType
+    const optionsTypeName = `${pascalCase(resource.composableName)}Options`;
+    const returnTypeName = `${pascalCase(resource.composableName)}Return`;
+    // Destructure options param — only what's relevant for this resource
+    const optionKeys = [];
+    if (resource.listEndpoint && hasColumns) {
+        optionKeys.push('columnLabels', 'columnLabel');
+    }
+    if (resource.createEndpoint && resource.zodSchemas.create) {
+        optionKeys.push('createSchema');
+    }
+    if (resource.updateEndpoint && resource.zodSchemas.update) {
+        optionKeys.push('updateSchema');
+    }
+    const optionsDestructure = optionKeys.length > 0 ? `  const { ${optionKeys.join(', ')} } = options;\n` : '';
+    // ── List / table sub-connector ─────────────────────────────────────────────
     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});`);
+        const listRequestTypeName = `${pascalCase(resource.listEndpoint.operationId)}Request`;
+        const paginatedFlag = resource.listEndpoint.responseSchema ? 'paginated: true' : '';
+        const columnsArg = hasColumns ? `columns: ${columnsVar}` : '';
+        const labelArgs = hasColumns ? 'columnLabels, columnLabel' : '';
+        const allArgs = [paginatedFlag, columnsArg, labelArgs].filter(Boolean).join(', ');
+        const opts = allArgs ? `{ ${allArgs} }` : '{}';
+        // Factory: if the first arg is a function the user provided their own composable;
+        // otherwise build a default factory from the plain params object.
+        subConnectors.push(`  const isFactory = typeof paramsOrSource === 'function';`, `  const listFactory = isFactory`, `    ? (paramsOrSource as () => unknown)`, `    : () => ${fn}((paramsOrSource ?? {}) as ${listRequestTypeName});`, `  const table = useListConnector(listFactory, ${opts}) as unknown as ListConnectorReturn<${pascal}>;`);
+    }
+    else {
+        // No list endpoint — support optional factory for developer-provided list
+        subConnectors.push(`  const table = paramsOrSource`, `    ? (useListConnector(paramsOrSource as () => unknown, {}) as unknown as ListConnectorReturn<unknown>)`, `    : undefined;`);
     }
     if (resource.detailEndpoint) {
         const fn = toAsyncDataName(resource.detailEndpoint.operationId);
-        subConnectors.push(`  const detail = useDetailConnector(${fn});`);
+        subConnectors.push(`  const detail = useDetailConnector(${fn}) as unknown as DetailConnectorReturn<${pascal}>;`);
     }
     if (resource.createEndpoint) {
         const fn = toAsyncDataName(resource.createEndpoint.operationId);
-        const schemaArg = resource.zodSchemas.create ? `{ schema: ${pascal}CreateSchema }` : '{}';
-        subConnectors.push(`  const createForm = useFormConnector(${fn}, ${schemaArg});`);
+        const inputType = resource.zodSchemas.create ? `${pascal}CreateInput` : `Record<string, unknown>`;
+        const schemaArg = resource.zodSchemas.create
+            ? `{ schema: ${pascal}CreateSchema, schemaOverride: createSchema }`
+            : '{}';
+        subConnectors.push(`  const createForm = useFormConnector(${fn}, ${schemaArg}) as unknown as FormConnectorReturn<${inputType}>;`);
     }
     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:
+        const inputType = resource.zodSchemas.update ? `${pascal}UpdateInput` : `Record<string, unknown>`;
         let schemaArg = '{}';
         if (resource.zodSchemas.update && hasDetail) {
-            // Best case: validate AND pre-fill from detail
-            schemaArg = `{ schema: ${pascal}UpdateSchema, loadWith: detail }`;
+            schemaArg = `{ schema: ${pascal}UpdateSchema, schemaOverride: updateSchema, loadWith: detail }`;
         }
         else if (resource.zodSchemas.update) {
-            // Validate, but no detail endpoint to pre-fill from
-            schemaArg = `{ schema: ${pascal}UpdateSchema }`;
+            schemaArg = `{ schema: ${pascal}UpdateSchema, schemaOverride: 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});`);
+        subConnectors.push(`  const updateForm = useFormConnector(${fn}, ${schemaArg}) as unknown as FormConnectorReturn<${inputType}>;`);
     }
     if (resource.deleteEndpoint) {
         const fn = toAsyncDataName(resource.deleteEndpoint.operationId);
-        subConnectors.push(`  const deleteAction = useDeleteConnector(${fn});`);
-    }
-    // Return object — only include what was built
-    const returnKeys = [];
-    if (resource.listEndpoint) {
-        returnKeys.push('table');
+        subConnectors.push(`  const deleteAction = useDeleteConnector(${fn}) as unknown as DeleteConnectorReturn<${pascal}>;`);
     }
+    // Return object — always includes table (undefined when no list + no factory)
+    const returnKeys = ['table'];
     if (resource.detailEndpoint) {
         returnKeys.push('detail');
     }
@@ -172,13 +282,27 @@ function buildFunctionBody(resource) {
     if (resource.deleteEndpoint) {
         returnKeys.push('deleteAction');
     }
-    const returnStatement = `  return { ${returnKeys.join(', ')} };`;
-    return [
-        `export function ${resource.composableName}() {`,
-        ...subConnectors,
-        returnStatement,
-        `}`,
-    ].join('\n');
+    const returnStatement = `  return { ${returnKeys.join(', ')} } as ${returnTypeName};`;
+    // ── Function signature ─────────────────────────────────────────────────────
+    // Resources WITH a list endpoint: two overloads (factory | params).
+    // Resources WITHOUT a list endpoint: single signature with optional factory.
+    const lines = [];
+    if (resource.listEndpoint) {
+        const listRequestTypeName = `${pascalCase(resource.listEndpoint.operationId)}Request`;
+        lines.push(`export function ${resource.composableName}(source: () => unknown, options?: ${optionsTypeName}): ${returnTypeName};`, `export function ${resource.composableName}(params?: ${listRequestTypeName}, options?: ${optionsTypeName}): ${returnTypeName};`, `export function ${resource.composableName}(paramsOrSource?: ${listRequestTypeName} | (() => unknown), options: ${optionsTypeName} = {}): ${returnTypeName} {`);
+    }
+    else {
+        lines.push(`export function ${resource.composableName}(source?: () => unknown, options: ${optionsTypeName} = {}): ${returnTypeName} {`);
+        // Alias so the body can use paramsOrSource uniformly
+        lines.push(`  const paramsOrSource = source;`);
+    }
+    if (optionsDestructure.trim()) {
+        lines.push(optionsDestructure.trimEnd());
+    }
+    lines.push(...subConnectors);
+    lines.push(returnStatement);
+    lines.push(`}`);
+    return lines.join('\n');
 }
 // ─── Public API ───────────────────────────────────────────────────────────────
 /**
@@ -188,18 +312,25 @@ function buildFunctionBody(resource) {
  * @param composablesRelDir  Relative path from the connector dir to the
  *                           useAsyncData composables dir (e.g. '../use-async-data')
  */
-export function generateConnectorFile(resource, composablesRelDir) {
+export function generateConnectorFile(resource, composablesRelDir, sdkRelDir = '../..') {
     const header = generateFileHeader();
-    const imports = buildImports(resource, composablesRelDir);
+    const imports = buildImports(resource, composablesRelDir, sdkRelDir);
     const schemas = buildZodSchemas(resource);
+    const columns = buildColumns(resource);
+    const optionsInterface = buildOptionsInterface(resource);
+    const returnType = buildReturnType(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.
+    // Assemble file: header + imports + (optional) Zod blocks + columns const +
+    // options interface + return type + function body.
     const parts = [header, imports];
     if (schemas.trim()) {
         parts.push(schemas);
     }
+    if (columns.trim()) {
+        parts.push(columns);
+    }
+    parts.push(optionsInterface);
+    parts.push(returnType);
     parts.push(fn);
     return parts.join('\n') + '\n';
 }

package/dist/generators/shared/runtime/connector-types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * connector-types.ts — Structural return type interfaces for the 4 runtime connectors.
+ *
+ * Uses locally-defined minimal type aliases for Ref/ComputedRef/ShallowRef so this
+ * file compiles in the CLI context (where Vue is not installed) and remains
+ * structurally compatible with Vue's actual types in the user's Nuxt project.
+ *
+ * Copied to the user's project alongside the generated connectors and runtime helpers.
+ */
+type Ref<T> = {
+    value: T;
+};
+type ShallowRef<T> = {
+    value: T;
+};
+type ComputedRef<T> = {
+    readonly value: T;
+};
+export interface ColumnDef {
+    key: string;
+    label: string;
+    type: string;
+}
+export interface FormFieldDef {
+    key: string;
+    label: string;
+    type: string;
+    required: boolean;
+    options?: {
+        label: string;
+        value: string;
+    }[];
+    placeholder?: string;
+    hidden?: boolean;
+}
+export interface PaginationState {
+    page: number;
+    perPage: number;
+    total: number;
+    totalPages: number;
+    goToPage: (page: number) => void;
+    nextPage: () => void;
+    prevPage: () => void;
+    setPerPage: (n: number) => void;
+}
+export interface ListConnectorReturn<TRow = unknown> {
+    rows: ComputedRef<TRow[]>;
+    columns: ComputedRef<ColumnDef[]>;
+    loading: ComputedRef<boolean>;
+    error: ComputedRef<unknown>;
+    pagination: ComputedRef<PaginationState | null>;
+    goToPage: (page: number) => void;
+    nextPage: () => void;
+    prevPage: () => void;
+    setPerPage: (n: number) => void;
+    selected: Ref<TRow[]>;
+    onRowSelect: (row: TRow) => void;
+    clearSelection: () => void;
+    refresh: () => void;
+    create: () => void;
+    update: (row: TRow) => void;
+    remove: (row: TRow) => void;
+    _createTrigger: Ref<number>;
+    _updateTarget: ShallowRef<TRow | null>;
+    _deleteTarget: ShallowRef<TRow | null>;
+}
+export interface DetailConnectorReturn<TItem = unknown> {
+    item: ComputedRef<TItem | null>;
+    loading: ComputedRef<boolean>;
+    error: ComputedRef<unknown>;
+    fields: ComputedRef<FormFieldDef[]>;
+    load: (id: string | number) => Promise<void>;
+    clear: () => void;
+    _composable: unknown;
+    _currentId: Ref<string | number | null>;
+}
+export interface FormConnectorReturn<TInput = Record<string, unknown>> {
+    model: Ref<Partial<TInput>>;
+    errors: Ref<Record<string, string[]>>;
+    loading: Ref<boolean>;
+    submitError: Ref<unknown>;
+    submitted: Ref<boolean>;
+    isValid: ComputedRef<boolean>;
+    hasErrors: ComputedRef<boolean>;
+    fields: ComputedRef<FormFieldDef[]>;
+    onSuccess: Ref<((data: unknown) => void) | null>;
+    onError: Ref<((err: unknown) => void) | null>;
+    submit: () => Promise<void>;
+    reset: () => void;
+    setValues: (data: Partial<TInput>) => void;
+}
+export interface DeleteConnectorReturn<TItem = unknown> {
+    target: Ref<TItem | null>;
+    isOpen: Ref<boolean>;
+    loading: Ref<boolean>;
+    error: Ref<unknown>;
+    hasTarget: ComputedRef<boolean>;
+    onSuccess: Ref<((item: TItem) => void) | null>;
+    onError: Ref<((err: unknown) => void) | null>;
+    setTarget: (item: TItem) => void;
+    cancel: () => void;
+    confirm: () => Promise<void>;
+}
+export {};

package/dist/generators/shared/runtime/connector-types.js

@@ -0,0 +1,10 @@
+/**
+ * connector-types.ts — Structural return type interfaces for the 4 runtime connectors.
+ *
+ * Uses locally-defined minimal type aliases for Ref/ComputedRef/ShallowRef so this
+ * file compiles in the CLI context (where Vue is not installed) and remains
+ * structurally compatible with Vue's actual types in the user's Nuxt project.
+ *
+ * Copied to the user's project alongside the generated connectors and runtime helpers.
+ */
+export {};

package/dist/generators/shared/runtime/useFormConnector.js

@@ -18,7 +18,14 @@ import { mergeZodErrors } from './zod-error-merger.js';
  * @param options        { schema, fields, loadWith?, errorConfig? }
  */
 export function useFormConnector(composableFn, options = {}) {
-    const { schema, fields = [], loadWith = null, errorConfig = {} } = options;
+    const { schema: baseSchema, schemaOverride, fields = [], loadWith = null, errorConfig = {} } = options;
+    // Resolve the active schema:
+    //   schemaOverride(base) — extend or refine the generated schema
+    //   schemaOverride        — replace the generated schema entirely
+    //   baseSchema            — the generated schema unchanged (default)
+    const schema = schemaOverride
+        ? (typeof schemaOverride === 'function' ? schemaOverride(baseSchema) : schemaOverride)
+        : baseSchema;
     // ── Form state ─────────────────────────────────────────────────────────────
     const model = ref({});
     const errors = ref({});

package/dist/generators/shared/runtime/useListConnector.d.ts

@@ -1,8 +1,10 @@
 /**
- * @param composableFn  The generated useAsyncData composable, e.g. useAsyncDataGetPets
- * @param options       Configuration for the list connector
+ * @param factory   A zero-argument function that calls and returns the underlying
+ *                  useAsyncData composable, e.g. () => useAsyncDataGetPets(params)
+ *                  The factory is called once during connector setup (inside setup()).
+ * @param options   Configuration for the list connector
  */
-export declare function useListConnector(composableFn: any, options?: {}): {
+export declare function useListConnector(factory: any, options?: {}): {
     rows: any;
     columns: any;
     loading: any;

package/dist/generators/shared/runtime/useListConnector.js

@@ -12,13 +12,15 @@
  */
 import { ref, computed, shallowRef } from 'vue';
 /**
- * @param composableFn  The generated useAsyncData composable, e.g. useAsyncDataGetPets
- * @param options       Configuration for the list connector
+ * @param factory   A zero-argument function that calls and returns the underlying
+ *                  useAsyncData composable, e.g. () => useAsyncDataGetPets(params)
+ *                  The factory is called once during connector setup (inside setup()).
+ * @param options   Configuration for the list connector
  */
-export function useListConnector(composableFn, options = {}) {
-    const { paginated = false, columns = [] } = options;
+export function useListConnector(factory, options = {}) {
+    const { paginated = false, columns = [], columnLabels = {}, columnLabel = null } = options;
     // ── Execute the underlying composable ──────────────────────────────────────
-    const composable = composableFn({ paginated });
+    const composable = factory();
     // ── Derived state ──────────────────────────────────────────────────────────
     const rows = computed(() => {
         const data = composable.data?.value;
@@ -36,16 +38,16 @@ export function useListConnector(composableFn, options = {}) {
     // Pagination — passthrough from the underlying composable when paginated: true
     const pagination = computed(() => composable.pagination?.value ?? null);
     function goToPage(page) {
-        composable.goToPage?.(page);
+        composable.pagination?.value?.goToPage?.(page);
     }
     function nextPage() {
-        composable.nextPage?.();
+        composable.pagination?.value?.nextPage?.();
     }
     function prevPage() {
-        composable.prevPage?.();
+        composable.pagination?.value?.prevPage?.();
     }
     function setPerPage(n) {
-        composable.setPerPage?.(n);
+        composable.pagination?.value?.setPerPage?.(n);
     }
     // ── Row selection ──────────────────────────────────────────────────────────
     const selected = ref([]);
@@ -95,10 +97,17 @@ export function useListConnector(composableFn, options = {}) {
     function remove(row) {
         _deleteTarget.value = row;
     }
+    // Apply label overrides: columnLabel function takes priority over columnLabels map
+    const resolvedColumns = computed(() => columns.map((col) => ({
+        ...col,
+        label: columnLabel
+            ? columnLabel(col.key)
+            : (columnLabels[col.key] ?? col.label),
+    })));
     return {
         // State
         rows,
-        columns: computed(() => columns),
+        columns: resolvedColumns,
         loading,
         error,
         // Pagination