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

package/dist/generators/use-async-data/generator.js

@@ -66,6 +66,10 @@ export async function generateUseAsyncDataComposables(inputDir, outputDir, optio
     const sharedHelpersSource = path.resolve(__dirname, '../../../src/generators/shared/runtime/apiHelpers.ts');
     const sharedHelpersDest = path.join(sharedRuntimeDir, 'apiHelpers.ts');
     await fs.copyFile(sharedHelpersSource, sharedHelpersDest);
+    // Copy shared pagination.ts
+    const sharedPaginationSource = path.resolve(__dirname, '../../../src/generators/shared/runtime/pagination.ts');
+    const sharedPaginationDest = path.join(sharedRuntimeDir, 'pagination.ts');
+    await fs.copyFile(sharedPaginationSource, sharedPaginationDest);
     mainSpinner.stop('Runtime files copied');
     // 5. Calculate relative import path from composables to APIs
     const relativePath = calculateRelativeImportPath(composablesDir, inputDir);

package/dist/generators/use-async-data/runtime/useApiAsyncData.d.ts

@@ -1,12 +1,17 @@
 import type { UseFetchOptions } from '#app';
 import { type ApiRequestOptions as BaseApiRequestOptions } from '../../shared/runtime/apiHelpers.js';
+type PickInput = ReadonlyArray<string> | undefined;
+type HasNestedPath<K extends ReadonlyArray<string>> = Extract<K[number], `${string}.${string}`> extends never ? false : true;
+type PickedData<T, K extends PickInput> = K extends ReadonlyArray<string> ? HasNestedPath<K> extends true ? any : Pick<T, Extract<K[number], keyof T>> : T;
 /**
  * Options for useAsyncData API requests with lifecycle callbacks.
  * Extends all native Nuxt useFetch options plus our custom callbacks, transform, and pick.
  * Native options like baseURL, method, body, headers, query, lazy, server, immediate, dedupe, etc. are all available.
  * watch: boolean (true = auto-watch reactive params, false = disable auto-refresh)
  */
-export type ApiAsyncDataOptions<T> = BaseApiRequestOptions<T> & Omit<UseFetchOptions<T>, 'transform' | 'pick' | 'watch'> & {
+export type ApiAsyncDataOptions<T, DataT = T, PickT extends PickInput = undefined> = Omit<BaseApiRequestOptions<T>, 'transform' | 'pick'> & Omit<UseFetchOptions<T, DataT>, 'transform' | 'pick' | 'watch'> & {
+    pick?: PickT;
+    transform?: (data: PickedData<T, PickT>) => DataT;
     /**
      * Enable automatic refresh when reactive params/url change (default: true).
      * Set to false to disable auto-refresh entirely.
@@ -22,4 +27,5 @@ export type ApiAsyncDataOptions<T> = BaseApiRequestOptions<T> & Omit<UseFetchOpt
  * - Global headers from useApiHeaders or $getApiHeaders
  * - Watch pattern for reactive parameters
  */
-export declare function useApiAsyncData<T>(key: string, url: string | (() => string), options?: ApiAsyncDataOptions<T>): any;
+export declare function useApiAsyncData<T, Options extends ApiAsyncDataOptions<T, any, any> = ApiAsyncDataOptions<T>>(key: string, url: string | (() => string), options?: Options): any;
+export {};

package/dist/generators/use-async-data/runtime/useApiAsyncData.js

@@ -232,10 +232,10 @@ export function useApiAsyncData(key, url, options) {
             ...paginationState.value,
             hasNextPage: hasNextPage.value,
             hasPrevPage: hasPrevPage.value,
+            goToPage,
+            nextPage,
+            prevPage,
+            setPerPage,
         })),
-        goToPage,
-        nextPage,
-        prevPage,
-        setPerPage,
     };
 }

package/dist/generators/use-async-data/runtime/useApiAsyncDataRaw.d.ts

@@ -10,16 +10,21 @@ export interface RawResponse<T> {
     status: number;
     statusText: string;
 }
+type PickInput = ReadonlyArray<string> | undefined;
+type HasNestedPath<K extends ReadonlyArray<string>> = Extract<K[number], `${string}.${string}`> extends never ? false : true;
+type PickedData<T, K extends PickInput> = K extends ReadonlyArray<string> ? HasNestedPath<K> extends true ? any : Pick<T, Extract<K[number], keyof T>> : T;
 /**
  * Options for useAsyncData Raw API requests.
  * Extends all native Nuxt useFetch options plus our custom callbacks, transform, and pick.
  * onSuccess receives data AND the full response (headers, status, statusText).
  */
-export type ApiAsyncDataRawOptions<T> = Omit<BaseApiRequestOptions<T>, 'onSuccess'> & Omit<UseFetchOptions<T>, 'transform' | 'pick' | 'onSuccess'> & {
+export type ApiAsyncDataRawOptions<T, DataT = T, PickT extends PickInput = undefined> = Omit<BaseApiRequestOptions<T>, 'onSuccess' | 'transform' | 'pick'> & Omit<UseFetchOptions<T, DataT>, 'transform' | 'pick' | 'onSuccess'> & {
+    pick?: PickT;
+    transform?: (data: PickedData<T, PickT>) => DataT;
     /**
      * Called when the request succeeds — receives both data and the full response object.
      */
-    onSuccess?: (data: T, response: {
+    onSuccess?: (data: DataT, response: {
         headers: Headers;
         status: number;
         statusText: string;
@@ -38,4 +43,5 @@ export type ApiAsyncDataRawOptions<T> = Omit<BaseApiRequestOptions<T>, 'onSucces
  * - Global headers from useApiHeaders or $getApiHeaders
  * - Watch pattern for reactive parameters
  */
-export declare function useApiAsyncDataRaw<T>(key: string, url: string | (() => string), options?: ApiAsyncDataRawOptions<T>): any;
+export declare function useApiAsyncDataRaw<T, DataT = T, PickT extends PickInput = undefined, Options extends ApiAsyncDataRawOptions<T, DataT, PickT> = ApiAsyncDataRawOptions<T, DataT, PickT>>(key: string, url: string | (() => string), options?: Options): any;
+export {};

package/dist/generators/use-async-data/runtime/useApiAsyncDataRaw.js

@@ -213,10 +213,10 @@ export function useApiAsyncDataRaw(key, url, options) {
             ...paginationState.value,
             hasNextPage: hasNextPage.value,
             hasPrevPage: hasPrevPage.value,
+            goToPage,
+            nextPage,
+            prevPage,
+            setPerPage,
         })),
-        goToPage,
-        nextPage,
-        prevPage,
-        setPerPage,
     };
 }

package/dist/generators/use-async-data/templates.js

@@ -98,14 +98,16 @@ function generateImports(method, apiImportPath, isRaw) {
 function generateFunctionBody(method, isRaw, generateOptions) {
     const hasParams = !!method.requestType;
     const paramsArg = hasParams ? `params: ${method.requestType}` : '';
+    const responseType = method.responseType !== 'void' ? method.responseType : 'void';
     // Determine the options type based on isRaw
     const optionsType = isRaw
-        ? `ApiAsyncDataRawOptions<${method.responseType}>`
-        : `ApiAsyncDataOptions<${method.responseType}>`;
-    const optionsArg = `options?: ${optionsType}`;
+        ? `ApiAsyncDataRawOptions<${responseType}, DataT, PickT>`
+        : `ApiAsyncDataOptions<${responseType}, DataT, PickT>`;
+    const optionsDefaultType = isRaw
+        ? `ApiAsyncDataRawOptions<${responseType}, DataT, PickT>`
+        : `ApiAsyncDataOptions<${responseType}, DataT, PickT>`;
+    const optionsArg = `options?: Options`;
     const args = hasParams ? `${paramsArg}, ${optionsArg}` : optionsArg;
-    // Determine the response type generic
-    const responseTypeGeneric = method.responseType !== 'void' ? `<${method.responseType}>` : '';
     // Generate unique key for useAsyncData
     const composableName = isRaw && method.rawMethodName
         ? `useAsyncData${method.rawMethodName.replace(/Raw$/, '')}Raw`
@@ -116,15 +118,29 @@ function generateFunctionBody(method, isRaw, generateOptions) {
     const description = method.description ? `/**\n * ${method.description}\n */\n` : '';
     // Choose the correct wrapper function
     const wrapperFunction = isRaw ? 'useApiAsyncDataRaw' : 'useApiAsyncData';
+    const wrapperCall = isRaw
+        ? `${wrapperFunction}<${responseType}, DataT, PickT, Options>`
+        : `${wrapperFunction}<${responseType}, Options>`;
+    const returnType = isRaw
+        ? `ReturnType<typeof ${wrapperFunction}<${responseType}, DataT, PickT, Options>>`
+        : `ReturnType<typeof ${wrapperFunction}<${responseType}, Options>>`;
     const pInit = hasParams ? `\n  const p = shallowRef(params)` : '';
     const argsExtraction = hasParams
         ? `  const _hasKey = typeof args[0] === 'string'\n  const params = _hasKey ? args[1] : args[0]\n  const options = _hasKey ? { cacheKey: args[0], ...args[2] } : args[1]`
         : `  const _hasKey = typeof args[0] === 'string'\n  const options = _hasKey ? { cacheKey: args[0], ...args[1] } : args[0]`;
-    return `${description}export function ${composableName}(key: string, ${args})
-export function ${composableName}(${args})
+    return `${description}export function ${composableName}<
+  DataT = ${responseType},
+  PickT extends ReadonlyArray<string> | undefined = undefined,
+  Options extends ${optionsType} = ${optionsDefaultType}
+>(key: string, ${args}): ${returnType}
+export function ${composableName}<
+  DataT = ${responseType},
+  PickT extends ReadonlyArray<string> | undefined = undefined,
+  Options extends ${optionsType} = ${optionsDefaultType}
+>(${args}): ${returnType}
 export function ${composableName}(...args: any[]) {
 ${argsExtraction}${pInit}
-  return ${wrapperFunction}${responseTypeGeneric}(${key}, ${url}, ${fetchOptions})
+  return ${wrapperCall}(${key}, ${url}, ${fetchOptions})
 }`;
 }
 /**

package/dist/generators/use-fetch/generator.js

@@ -62,6 +62,10 @@ export async function generateUseFetchComposables(inputDir, outputDir, options,
     const sharedHelpersSource = path.resolve(__dirname, '../../../src/generators/shared/runtime/apiHelpers.ts');
     const sharedHelpersDest = path.join(sharedRuntimeDir, 'apiHelpers.ts');
     await fs.copyFile(sharedHelpersSource, sharedHelpersDest);
+    // Copy shared pagination.ts
+    const sharedPaginationSource = path.resolve(__dirname, '../../../src/generators/shared/runtime/pagination.ts');
+    const sharedPaginationDest = path.join(sharedRuntimeDir, 'pagination.ts');
+    await fs.copyFile(sharedPaginationSource, sharedPaginationDest);
     mainSpinner.stop('Runtime files copied');
     // 5. Calculate relative import path from composables to APIs
     const relativePath = calculateRelativeImportPath(composablesDir, inputDir);

package/dist/generators/use-fetch/runtime/useApiRequest.d.ts

@@ -1,11 +1,17 @@
 import type { UseFetchOptions } from '#app';
 import { type ApiRequestOptions as BaseApiRequestOptions } from '../../shared/runtime/apiHelpers.js';
+type PickInput = ReadonlyArray<string> | undefined;
+type HasNestedPath<K extends ReadonlyArray<string>> = Extract<K[number], `${string}.${string}`> extends never ? false : true;
+type PickedData<T, K extends PickInput> = K extends ReadonlyArray<string> ? HasNestedPath<K> extends true ? any : Pick<T, Extract<K[number], keyof T>> : T;
 /**
  * Options for useFetch API requests with lifecycle callbacks.
  * Extends all native Nuxt useFetch options plus our custom callbacks, transform, and pick.
  * Native options like baseURL, method, body, headers, query, lazy, server, immediate, etc. are all available.
  */
-export type ApiRequestOptions<T = any> = BaseApiRequestOptions<T> & Omit<UseFetchOptions<T>, 'transform' | 'pick'>;
+export type ApiRequestOptions<T = any, DataT = T, PickT extends PickInput = undefined> = Omit<BaseApiRequestOptions<T>, 'transform' | 'pick'> & Omit<UseFetchOptions<T, DataT>, 'transform' | 'pick'> & {
+    pick?: PickT;
+    transform?: (data: PickedData<T, PickT>) => DataT;
+};
 /**
  * Enhanced useFetch wrapper with lifecycle callbacks and request interception
  *
@@ -42,4 +48,5 @@ export type ApiRequestOptions<T = any> = BaseApiRequestOptions<T> & Omit<UseFetc
  * });
  * ```
  */
-export declare function useApiRequest<T = any, Options extends ApiRequestOptions<T> = ApiRequestOptions<T>>(url: string | (() => string), options?: Options): any;
+export declare function useApiRequest<T = any, Options extends ApiRequestOptions<T, any, any> = ApiRequestOptions<T>>(url: string | (() => string), options?: Options): any;
+export {};

package/dist/generators/use-fetch/templates.js

@@ -87,16 +87,20 @@ function generateImports(method, apiImportPath) {
 function generateFunctionBody(method, options) {
     const hasParams = !!method.requestType;
     const paramsArg = hasParams ? `params: ${method.requestType}` : '';
-    const optionsType = `ApiRequestOptions<${method.responseType}>`;
-    const optionsArg = `options?: ${optionsType}`;
+    const responseType = method.responseType !== 'void' ? method.responseType : 'void';
+    const optionsType = `ApiRequestOptions<${responseType}, DataT, PickT>`;
+    const optionsArg = `options?: Options`;
     const args = hasParams ? `${paramsArg}, ${optionsArg}` : optionsArg;
-    const responseTypeGeneric = method.responseType !== 'void' ? `<${method.responseType}>` : '';
     const url = generateUrl(method);
     const fetchOptions = generateFetchOptions(method, options);
     const description = method.description ? `/**\n * ${method.description}\n */\n` : '';
     const pInit = hasParams ? `\n  const p = shallowRef(params)` : '';
-    return `${description}export const ${method.composableName} = (${args}) => {${pInit}
-  return useApiRequest${responseTypeGeneric}(${url}, ${fetchOptions})
+    return `${description}export const ${method.composableName} = <
+  DataT = ${responseType},
+  PickT extends ReadonlyArray<string> | undefined = undefined,
+  Options extends ${optionsType} = ApiRequestOptions<${responseType}, DataT, PickT>
+>(${args}) => {${pInit}
+  return useApiRequest<${responseType}, Options>(${url}, ${fetchOptions})
 }`;
 }
 /**

package/dist/index.js

@@ -55,7 +55,8 @@ program
             backend: options.backend === 'official' || options.backend === 'heyapi'
                 ? options.backend
                 : undefined,
-            createUseAsyncDataConnectors: options.connectors,
+            // Only propagate if explicitly passed — undefined means "ask the user"
+            createUseAsyncDataConnectors: options.connectors === true ? true : undefined,
         });
         if (config.verbose) {
             console.log('Configuration:', config);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-openapi-hyperfetch",
-  "version": "0.2.8-alpha.1",
+  "version": "0.3.1-beta",
   "description": "Nuxt useFetch, useAsyncData and Nuxt server OpenAPI generator",
   "type": "module",
   "author": "",

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

@@ -13,6 +13,7 @@ import { type Logger, 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/src/generators/components/connector-generator/templates.ts

@@ -15,7 +15,6 @@ function generateFileHeader(): string {
  */
 
 /* eslint-disable */
-// @ts-nocheck
 `;
 }
 
@@ -42,18 +41,37 @@ function toFileName(composableName: string): string {
 /**
  * Build all `import` lines for a resource connector.
  */
-function buildImports(resource: ResourceInfo, composablesRelDir: string): string {
+function buildImports(resource: ResourceInfo, composablesRelDir: string, sdkRelDir: 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[] = [];
+  // connector-types — structural interfaces for return types
+  const connectorTypeImports: string[] = ['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: string[] = ['useListConnector'];
   if (resource.detailEndpoint) {
     runtimeHelpers.push('useDetailConnector');
   }
@@ -122,68 +140,184 @@ function buildZodSchemas(resource: ResourceInfo): string {
   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: ResourceInfo): string {
+  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: ResourceInfo): string {
+  const typeName = `${pascalCase(resource.composableName)}Options`;
+  const hasColumns = resource.columns && resource.columns.length > 0;
+  const fields: string[] = [];
+
+  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: ResourceInfo): string {
+  const pascal = pascalCase(resource.name);
+  const typeName = `${pascalCase(resource.composableName)}Return`;
+  const fields: string[] = [];
+
+  // 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: ResourceInfo): string {
   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: string[] = [];
 
+  // 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: string[] = [];
+  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;
+    const inputType = resource.zodSchemas.update ? `${pascal}UpdateInput` : `Record<string, unknown>`;
 
-    // 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 }`;
+      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});`);
+    subConnectors.push(`  const deleteAction = useDeleteConnector(${fn}) as unknown as DeleteConnectorReturn<${pascal}>;`);
   }
 
-  // Return object — only include what was built
-  const returnKeys: string[] = [];
-  if (resource.listEndpoint) {
-    returnKeys.push('table');
-  }
+  // Return object — always includes table (undefined when no list + no factory)
+  const returnKeys: string[] = ['table'];
   if (resource.detailEndpoint) {
     returnKeys.push('detail');
   }
@@ -197,14 +331,36 @@ function buildFunctionBody(resource: ResourceInfo): string {
     returnKeys.push('deleteAction');
   }
 
-  const returnStatement = `  return { ${returnKeys.join(', ')} };`;
+  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: string[] = [];
 
-  return [
-    `export function ${resource.composableName}() {`,
-    ...subConnectors,
-    returnStatement,
-    `}`,
-  ].join('\n');
+  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 ───────────────────────────────────────────────────────────────
@@ -216,19 +372,30 @@ function buildFunctionBody(resource: ResourceInfo): string {
  * @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 {
+export function generateConnectorFile(
+  resource: ResourceInfo,
+  composablesRelDir: string,
+  sdkRelDir = '../..'
+): string {
   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: string[] = [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';