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

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

@@ -0,0 +1,168 @@
+/**
+ * Pagination Helpers - Used by both useFetch and useAsyncData wrappers
+ * Handles global pagination config, request param injection, and response meta extraction.
+ */
+/**
+ * Describes how to read pagination metadata from the backend response.
+ *
+ * - `metaSource: 'headers'` — metadata comes from HTTP response headers
+ * - `metaSource: 'body'`    — metadata is nested inside the response JSON
+ */
+export interface PaginationMetaConfig {
+    /**
+     * Where to read pagination metadata from.
+     * - 'headers': from HTTP response headers (requires raw fetch)
+     * - 'body': from the response JSON body (default)
+     */
+    metaSource: 'headers' | 'body';
+    /**
+     * Field names (header names or dot-notation body paths) for each pagination value.
+     *
+     * Examples for headers:   'X-Total-Count', 'X-Total-Pages', 'X-Page', 'X-Per-Page'
+     * Examples for body:      'meta.total', 'pagination.totalPages', 'page', 'perPage'
+     */
+    fields: {
+        /** Total number of items across all pages */
+        total: string;
+        /** Total number of pages */
+        totalPages: string;
+        /** Current page number */
+        currentPage: string;
+        /** Number of items per page */
+        perPage: string;
+        /**
+         * If the actual data array lives inside a nested key (e.g. response.data),
+         * set this to that key name so the composable unwraps it automatically.
+         * Leave undefined if the response root IS the array.
+         */
+        dataKey?: string;
+    };
+}
+/**
+ * Describes how to send pagination parameters to the backend.
+ */
+export interface PaginationRequestConfig {
+    /**
+     * Where to attach the pagination parameters.
+     * - 'query':   as URL query string params (GET default, recommended)
+     * - 'body':    merged into request body JSON (for POST-as-search APIs)
+     * - 'headers': as request headers
+     */
+    sendAs: 'query' | 'body' | 'headers';
+    /**
+     * Mapping from our internal names to your backend's parameter names.
+     * @example { page: 'page', perPage: 'limit' }   // ?page=1&limit=20
+     * @example { page: 'p', perPage: 'per_page' }   // ?p=1&per_page=20
+     * @example { page: 'offset', perPage: 'count' } // ?offset=1&count=20
+     */
+    params: {
+        page: string;
+        perPage: string;
+    };
+    /** Default values applied when none are passed by the composable caller */
+    defaults: {
+        page: number;
+        perPage: number;
+    };
+}
+/**
+ * Full pagination configuration object.
+ * Combine `meta` (how to read the response) and `request` (how to send params).
+ *
+ * @example
+ * // Headers-based API (e.g. many REST frameworks)
+ * {
+ *   meta: {
+ *     metaSource: 'headers',
+ *     fields: { total: 'X-Total-Count', totalPages: 'X-Total-Pages', currentPage: 'X-Page', perPage: 'X-Per-Page' }
+ *   },
+ *   request: {
+ *     sendAs: 'query',
+ *     params: { page: 'page', perPage: 'limit' },
+ *     defaults: { page: 1, perPage: 20 }
+ *   }
+ * }
+ *
+ * @example
+ * // Body-based API (e.g. Laravel paginate())
+ * {
+ *   meta: {
+ *     metaSource: 'body',
+ *     fields: { total: 'meta.total', totalPages: 'meta.last_page', currentPage: 'meta.current_page', perPage: 'meta.per_page', dataKey: 'data' }
+ *   },
+ *   request: {
+ *     sendAs: 'query',
+ *     params: { page: 'page', perPage: 'per_page' },
+ *     defaults: { page: 1, perPage: 15 }
+ *   }
+ * }
+ */
+export interface PaginationConfig {
+    meta: PaginationMetaConfig;
+    request: PaginationRequestConfig;
+}
+/**
+ * Reactive pagination state exposed to the composable caller.
+ */
+export interface PaginationState {
+    /** Current page number (reactive) */
+    currentPage: number;
+    /** Total pages as reported by the backend (reactive) */
+    totalPages: number;
+    /** Total item count as reported by the backend (reactive) */
+    total: number;
+    /** Current page size (reactive) */
+    perPage: number;
+}
+/**
+ * Register the global pagination configuration.
+ * Call this from your Nuxt plugin (plugins/api-pagination.ts).
+ *
+ * @example
+ * export default defineNuxtPlugin(() => {
+ *   provide('setGlobalApiPagination', setGlobalApiPagination);
+ *   setGlobalApiPagination({ meta: { ... }, request: { ... } });
+ * })
+ */
+export declare function setGlobalApiPagination(config: PaginationConfig): void;
+/**
+ * Retrieve the global pagination configuration, falling back to built-in defaults.
+ * Called internally by the runtime wrappers.
+ */
+export declare function getGlobalApiPagination(): PaginationConfig;
+/**
+ * Build the pagination parameters to inject into the outgoing request.
+ *
+ * Returns an object with at most one of: `query`, `body`, or `headers` populated,
+ * depending on `config.request.sendAs`.
+ */
+export declare function buildPaginationRequest(page: number, perPage: number, config: PaginationConfig): {
+    query?: Record<string, any>;
+    body?: Record<string, any>;
+    headers?: Record<string, string>;
+};
+/**
+ * Extract pagination metadata from a **body** response.
+ *
+ * @param responseData - The raw JSON returned by the backend
+ * @param config       - Active pagination config
+ * @returns Partial pagination state (only fields that were found)
+ */
+export declare function extractPaginationMetaFromBody(responseData: any, config: PaginationConfig): Partial<PaginationState>;
+/**
+ * Extract pagination metadata from HTTP **response headers**.
+ *
+ * @param headers - The `Headers` object from the fetch response
+ * @param config  - Active pagination config
+ * @returns Partial pagination state (only fields that were found)
+ */
+export declare function extractPaginationMetaFromHeaders(headers: Headers, config: PaginationConfig): Partial<PaginationState>;
+/**
+ * If `config.meta.fields.dataKey` is set, unwrap the actual data array from the body.
+ * Otherwise return the body as-is.
+ *
+ * @example
+ * // Laravel paginate() response: { data: [...], meta: { total: 100, ... } }
+ * unwrapDataKey(response, config) // → response.data
+ */
+export declare function unwrapDataKey<T>(responseData: any, config: PaginationConfig): T;

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

@@ -0,0 +1,179 @@
+// @ts-nocheck - This file runs in user's Nuxt project with different TypeScript config
+/**
+ * Pagination Helpers - Used by both useFetch and useAsyncData wrappers
+ * Handles global pagination config, request param injection, and response meta extraction.
+ */
+// ---------------------------------------------------------------------------
+// Internal defaults
+// ---------------------------------------------------------------------------
+const DEFAULT_PAGINATION_CONFIG = {
+    meta: {
+        metaSource: 'body',
+        fields: {
+            total: 'total',
+            totalPages: 'totalPages',
+            currentPage: 'currentPage',
+            perPage: 'perPage',
+        },
+    },
+    request: {
+        sendAs: 'query',
+        params: { page: 'page', perPage: 'perPage' },
+        defaults: { page: 1, perPage: 20 },
+    },
+};
+// ---------------------------------------------------------------------------
+// Global config store
+// ---------------------------------------------------------------------------
+let _globalPaginationConfig = null;
+/**
+ * Register the global pagination configuration.
+ * Call this from your Nuxt plugin (plugins/api-pagination.ts).
+ *
+ * @example
+ * export default defineNuxtPlugin(() => {
+ *   provide('setGlobalApiPagination', setGlobalApiPagination);
+ *   setGlobalApiPagination({ meta: { ... }, request: { ... } });
+ * })
+ */
+export function setGlobalApiPagination(config) {
+    _globalPaginationConfig = config;
+}
+/**
+ * Retrieve the global pagination configuration, falling back to built-in defaults.
+ * Called internally by the runtime wrappers.
+ */
+export function getGlobalApiPagination() {
+    // Try Nuxt plugin provide first (runtime usage inside components)
+    try {
+        const nuxtApp = useNuxtApp();
+        // @ts-ignore
+        if (nuxtApp.$getGlobalApiPagination) {
+            // @ts-ignore
+            const config = nuxtApp.$getGlobalApiPagination();
+            if (config && typeof config === 'object')
+                return config;
+        }
+    }
+    catch {
+        // outside Nuxt context — fall through
+    }
+    // Then the module-level variable (set via setGlobalApiPagination)
+    if (_globalPaginationConfig)
+        return _globalPaginationConfig;
+    return DEFAULT_PAGINATION_CONFIG;
+}
+// ---------------------------------------------------------------------------
+// Request helpers
+// ---------------------------------------------------------------------------
+/**
+ * Build the pagination parameters to inject into the outgoing request.
+ *
+ * Returns an object with at most one of: `query`, `body`, or `headers` populated,
+ * depending on `config.request.sendAs`.
+ */
+export function buildPaginationRequest(page, perPage, config) {
+    const { sendAs, params } = config.request;
+    const payload = {
+        [params.page]: page,
+        [params.perPage]: perPage,
+    };
+    if (sendAs === 'query')
+        return { query: payload };
+    if (sendAs === 'body')
+        return { body: payload };
+    if (sendAs === 'headers') {
+        // Header values must be strings
+        return {
+            headers: {
+                [params.page]: String(page),
+                [params.perPage]: String(perPage),
+            },
+        };
+    }
+    return { query: payload };
+}
+// ---------------------------------------------------------------------------
+// Response meta extraction helpers
+// ---------------------------------------------------------------------------
+/**
+ * Navigate a dot-notation path on a plain object.
+ * Returns `undefined` if any intermediate key is missing.
+ *
+ * @example resolveDotPath({ meta: { total: 42 } }, 'meta.total') // → 42
+ */
+function resolveDotPath(obj, path) {
+    if (!obj || typeof obj !== 'object')
+        return undefined;
+    const keys = path.split('.');
+    let current = obj;
+    for (const key of keys) {
+        if (current == null || typeof current !== 'object')
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+/**
+ * Extract pagination metadata from a **body** response.
+ *
+ * @param responseData - The raw JSON returned by the backend
+ * @param config       - Active pagination config
+ * @returns Partial pagination state (only fields that were found)
+ */
+export function extractPaginationMetaFromBody(responseData, config) {
+    const { fields } = config.meta;
+    const result = {};
+    const rawTotal = resolveDotPath(responseData, fields.total);
+    if (rawTotal !== undefined)
+        result.total = Number(rawTotal);
+    const rawTotalPages = resolveDotPath(responseData, fields.totalPages);
+    if (rawTotalPages !== undefined)
+        result.totalPages = Number(rawTotalPages);
+    const rawCurrentPage = resolveDotPath(responseData, fields.currentPage);
+    if (rawCurrentPage !== undefined)
+        result.currentPage = Number(rawCurrentPage);
+    const rawPerPage = resolveDotPath(responseData, fields.perPage);
+    if (rawPerPage !== undefined)
+        result.perPage = Number(rawPerPage);
+    return result;
+}
+/**
+ * Extract pagination metadata from HTTP **response headers**.
+ *
+ * @param headers - The `Headers` object from the fetch response
+ * @param config  - Active pagination config
+ * @returns Partial pagination state (only fields that were found)
+ */
+export function extractPaginationMetaFromHeaders(headers, config) {
+    const { fields } = config.meta;
+    const result = {};
+    const rawTotal = headers.get(fields.total);
+    if (rawTotal !== null)
+        result.total = Number(rawTotal);
+    const rawTotalPages = headers.get(fields.totalPages);
+    if (rawTotalPages !== null)
+        result.totalPages = Number(rawTotalPages);
+    const rawCurrentPage = headers.get(fields.currentPage);
+    if (rawCurrentPage !== null)
+        result.currentPage = Number(rawCurrentPage);
+    const rawPerPage = headers.get(fields.perPage);
+    if (rawPerPage !== null)
+        result.perPage = Number(rawPerPage);
+    return result;
+}
+/**
+ * If `config.meta.fields.dataKey` is set, unwrap the actual data array from the body.
+ * Otherwise return the body as-is.
+ *
+ * @example
+ * // Laravel paginate() response: { data: [...], meta: { total: 100, ... } }
+ * unwrapDataKey(response, config) // → response.data
+ */
+export function unwrapDataKey(responseData, config) {
+    const key = config.meta.fields.dataKey;
+    if (key && responseData && typeof responseData === 'object' && key in responseData) {
+        return responseData[key];
+    }
+    return responseData;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * @param composableFn  The generated delete composable, e.g. useAsyncDataDeletePet
+ * @param options       Optional configuration
+ */
+export declare function useDeleteConnector(composableFn: any, options?: {}): {
+    target: any;
+    isOpen: any;
+    loading: any;
+    error: any;
+    hasTarget: any;
+    onSuccess: any;
+    onError: any;
+    setTarget: (item: any) => void;
+    cancel: () => void;
+    confirm: () => Promise<void>;
+};

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

@@ -0,0 +1,93 @@
+// @ts-nocheck - This file runs in user's Nuxt project with different TypeScript config
+/**
+ * useDeleteConnector — Runtime connector for DELETE endpoints.
+ *
+ * Manages:
+ * - The target item to delete (set from the table via openDelete)
+ * - Modal open/close state
+ * - Confirmation logic
+ * - Callbacks onSuccess / onError
+ *
+ * Copied to the user's project alongside the generated connectors.
+ */
+import { ref, computed } from 'vue';
+/**
+ * @param composableFn  The generated delete composable, e.g. useAsyncDataDeletePet
+ * @param options       Optional configuration
+ */
+export function useDeleteConnector(composableFn, options = {}) {
+    // ── State ──────────────────────────────────────────────────────────────────
+    const target = ref(null);
+    const isOpen = ref(false);
+    const loading = ref(false);
+    const error = ref(null);
+    // Callbacks — set by the developer or the generated component
+    const onSuccess = ref(null);
+    const onError = ref(null);
+    // ── Actions ────────────────────────────────────────────────────────────────
+    /**
+     * Set the item to delete and open the confirmation modal.
+     * Called by useListConnector.openDelete(row).
+     */
+    function setTarget(item) {
+        target.value = item;
+        isOpen.value = true;
+    }
+    /**
+     * Cancel the delete operation — close modal and clear target.
+     */
+    function cancel() {
+        isOpen.value = false;
+        target.value = null;
+        error.value = null;
+    }
+    /**
+     * Confirm the delete — call the underlying composable with the target item.
+     */
+    async function confirm() {
+        if (!target.value) {
+            return;
+        }
+        loading.value = true;
+        error.value = null;
+        try {
+            // Pass the full target item; the generated composable extracts the id it needs
+            const composable = composableFn(target.value);
+            if (composable.execute) {
+                await composable.execute();
+            }
+            const err = composable.error?.value;
+            if (err) {
+                throw err;
+            }
+            const deletedItem = target.value;
+            isOpen.value = false;
+            target.value = null;
+            onSuccess.value?.(deletedItem);
+        }
+        catch (err) {
+            error.value = err;
+            onError.value?.(err);
+        }
+        finally {
+            loading.value = false;
+        }
+    }
+    // ── Derived ────────────────────────────────────────────────────────────────
+    const hasTarget = computed(() => target.value !== null);
+    return {
+        // State
+        target,
+        isOpen,
+        loading,
+        error,
+        hasTarget,
+        // Callbacks (developer-assignable)
+        onSuccess,
+        onError,
+        // Actions
+        setTarget,
+        cancel,
+        confirm,
+    };
+}

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

@@ -0,0 +1,14 @@
+/**
+ * @param composableFn  The generated useAsyncData composable, e.g. useAsyncDataGetPetById
+ * @param options       Optional configuration
+ */
+export declare function useDetailConnector(composableFn: any, options?: {}): {
+    item: any;
+    loading: any;
+    error: any;
+    fields: any;
+    load: (id: any) => Promise<void>;
+    clear: () => void;
+    _composable: any;
+    _currentId: any;
+};

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

@@ -0,0 +1,50 @@
+// @ts-nocheck - This file runs in user's Nuxt project with different TypeScript config
+/**
+ * useDetailConnector — Runtime connector for single-item GET endpoints.
+ *
+ * Wraps a useAsyncData composable that returns a single object and exposes:
+ * - item, loading, error state
+ * - load(id) to fetch a specific item on demand
+ * - fields derived from the response (used by detail view components)
+ *
+ * Copied to the user's project alongside the generated connectors.
+ */
+import { ref, computed } from 'vue';
+/**
+ * @param composableFn  The generated useAsyncData composable, e.g. useAsyncDataGetPetById
+ * @param options       Optional configuration
+ */
+export function useDetailConnector(composableFn, options = {}) {
+    const { fields = [] } = options;
+    // The item ID to load — reactive. null = not loaded yet.
+    const currentId = ref(null);
+    // ── Execute the underlying composable lazily (only when currentId changes) ─
+    // We call the composable with lazy: true so it doesn't auto-fetch on mount.
+    // load(id) sets currentId which triggers the watch inside the composable.
+    const composable = composableFn(computed(() => (currentId.value !== null ? { id: currentId.value } : null)), { lazy: true, immediate: false });
+    // ── Derived state ──────────────────────────────────────────────────────────
+    const item = computed(() => composable.data?.value ?? null);
+    const loading = computed(() => composable.pending?.value ?? false);
+    const error = computed(() => composable.error?.value ?? null);
+    // ── Actions ────────────────────────────────────────────────────────────────
+    async function load(id) {
+        currentId.value = id;
+        await composable.refresh?.();
+    }
+    function clear() {
+        currentId.value = null;
+    }
+    return {
+        // State
+        item,
+        loading,
+        error,
+        fields: computed(() => fields),
+        // Actions
+        load,
+        clear,
+        // Expose composable for advanced use (e.g. useFormConnector loadWith)
+        _composable: composable,
+        _currentId: currentId,
+    };
+}

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

@@ -0,0 +1,19 @@
+/**
+ * @param composableFn   The generated mutation composable, e.g. useAsyncDataCreatePet
+ * @param options        { schema, fields, loadWith?, errorConfig? }
+ */
+export declare function useFormConnector(composableFn: any, options?: {}): {
+    model: any;
+    errors: any;
+    loading: any;
+    submitError: any;
+    submitted: any;
+    isValid: any;
+    hasErrors: any;
+    fields: any;
+    onSuccess: any;
+    onError: any;
+    submit: () => Promise<void>;
+    reset: () => void;
+    setValues: (data: any) => void;
+};

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

@@ -0,0 +1,113 @@
+// @ts-nocheck - This file runs in user's Nuxt project with different TypeScript config
+/**
+ * useFormConnector — Runtime connector for create/update form endpoints.
+ *
+ * Responsibilities:
+ * - Hold the reactive form model
+ * - Validate with a Zod schema (generated at code-gen time) on submit
+ * - Merge Zod error messages with per-field overrides from config
+ * - Submit the validated data via the provided useAsyncData composable
+ * - Optionally pre-fill from a useDetailConnector (loadWith option)
+ *
+ * Copied to the user's project alongside the generated connectors.
+ */
+import { ref, computed, watch } from 'vue';
+import { mergeZodErrors } from './zod-error-merger.js';
+/**
+ * @param composableFn   The generated mutation composable, e.g. useAsyncDataCreatePet
+ * @param options        { schema, fields, loadWith?, errorConfig? }
+ */
+export function useFormConnector(composableFn, options = {}) {
+    const { schema, fields = [], loadWith = null, errorConfig = {} } = options;
+    // ── Form state ─────────────────────────────────────────────────────────────
+    const model = ref({});
+    const errors = ref({});
+    const loading = ref(false);
+    const submitError = ref(null);
+    const submitted = ref(false);
+    // Callbacks — set by the developer or the generated component
+    const onSuccess = ref(null);
+    const onError = ref(null);
+    // ── Pre-fill from detail connector ────────────────────────────────────────
+    if (loadWith) {
+        // When the detail item changes (e.g. user clicks "Edit"), pre-fill the model
+        watch(() => loadWith.item?.value, (newItem) => {
+            if (newItem) {
+                setValues(newItem);
+            }
+        }, { immediate: true });
+    }
+    // ── Actions ────────────────────────────────────────────────────────────────
+    function setValues(data) {
+        model.value = { ...model.value, ...data };
+    }
+    function reset() {
+        model.value = {};
+        errors.value = {};
+        submitError.value = null;
+        submitted.value = false;
+    }
+    async function submit() {
+        submitted.value = true;
+        // 1. Zod validation (if schema provided)
+        if (schema) {
+            const result = schema.safeParse(model.value);
+            if (!result.success) {
+                const fieldErrors = result.error.flatten().fieldErrors;
+                errors.value = mergeZodErrors(fieldErrors, errorConfig);
+                return;
+            }
+            // Clear previous errors on successful validation
+            errors.value = {};
+        }
+        // 2. Call the underlying composable
+        loading.value = true;
+        submitError.value = null;
+        try {
+            // The mutation composable accepts the model as its payload
+            const composable = composableFn(model.value);
+            // Wait for the async data to resolve
+            if (composable.execute) {
+                await composable.execute();
+            }
+            const data = composable.data?.value;
+            const err = composable.error?.value;
+            if (err) {
+                throw err;
+            }
+            onSuccess.value?.(data);
+        }
+        catch (err) {
+            submitError.value = err;
+            onError.value?.(err);
+        }
+        finally {
+            loading.value = false;
+        }
+    }
+    // ── Derived ────────────────────────────────────────────────────────────────
+    const isValid = computed(() => {
+        if (!schema)
+            return true;
+        return schema.safeParse(model.value).success;
+    });
+    const hasErrors = computed(() => Object.keys(errors.value).length > 0);
+    return {
+        // State
+        model,
+        errors,
+        loading,
+        submitError,
+        submitted,
+        isValid,
+        hasErrors,
+        fields: computed(() => fields),
+        // Callbacks (developer-assignable)
+        onSuccess,
+        onError,
+        // Actions
+        submit,
+        reset,
+        setValues,
+    };
+}

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

@@ -0,0 +1,25 @@
+/**
+ * @param composableFn  The generated useAsyncData composable, e.g. useAsyncDataGetPets
+ * @param options       Configuration for the list connector
+ */
+export declare function useListConnector(composableFn: any, options?: {}): {
+    rows: any;
+    columns: any;
+    loading: any;
+    error: any;
+    pagination: any;
+    goToPage: (page: any) => void;
+    nextPage: () => void;
+    prevPage: () => void;
+    setPerPage: (n: any) => void;
+    selected: any;
+    onRowSelect: (row: any) => void;
+    clearSelection: () => void;
+    refresh: () => void;
+    create: () => void;
+    update: (row: any) => void;
+    remove: (row: any) => void;
+    _createTrigger: any;
+    _updateTarget: any;
+    _deleteTarget: any;
+};