nuxt-openapi-hyperfetch 0.3.81-beta → 1.0.1

package/src/generators/connectors/runtime/useGetAllConnector.ts

@@ -0,0 +1,151 @@
+// @ts-nocheck - This file runs in user's Nuxt project with different TypeScript config
+/**
+ * useGetAllConnector — Runtime connector for list/collection GET endpoints.
+ *
+ * Wraps a useAsyncData composable (reactive, SSR-compatible, supports pagination).
+ * The factory pattern means the composable is initialized in setup() context.
+ *
+ * Key differences from the old useListConnector:
+ * - items instead of rows
+ * - select/deselect/toggleSelect instead of onRowSelect
+ * - load(params?) instead of refresh()
+ * - No CRUD coordination methods (create/update/remove/_createTrigger etc.)
+ *   — coordination is the component's responsibility via callbacks
+ *
+ * Copied to the user's project alongside the generated connectors.
+ */
+import { ref, computed } from 'vue';
+
+/**
+ * @param factory   A zero-argument function that calls and returns the underlying
+ *                  useAsyncData composable, e.g. () => useAsyncDataGetPets(params)
+ *                  Called once during connector setup (inside setup()).
+ * @param options   Configuration for the connector
+ */
+export function useGetAllConnector(factory, options = {}) {
+  const { columns = [], columnLabels = {}, columnLabel = null } = options;
+
+  // ── Execute the underlying composable once (in setup context) ─────────────
+  const composable = factory();
+
+  // ── Derived state ──────────────────────────────────────────────────────────
+
+  const items = computed(() => {
+    const data = composable.data?.value;
+    if (!data) return [];
+    // Support both direct arrays and { data: [...] } shapes (paginated APIs)
+    if (Array.isArray(data)) return data;
+    if (Array.isArray(data.data)) return data.data;
+    return [];
+  });
+
+  const loading = computed(() => composable.pending?.value ?? false);
+  const error = computed(() => composable.error?.value ?? null);
+
+  // Pagination — passthrough from the underlying composable when paginated: true
+  const pagination = computed(() => composable.pagination?.value ?? null);
+
+  function goToPage(page) {
+    composable.pagination?.value?.goToPage?.(page);
+  }
+
+  function nextPage() {
+    composable.pagination?.value?.nextPage?.();
+  }
+
+  function prevPage() {
+    composable.pagination?.value?.prevPage?.();
+  }
+
+  function setPerPage(n) {
+    composable.pagination?.value?.setPerPage?.(n);
+  }
+
+  // ── Selection ──────────────────────────────────────────────────────────────
+
+  const selected = ref([]);
+
+  function select(item) {
+    if (!selected.value.includes(item)) {
+      selected.value = [...selected.value, item];
+    }
+  }
+
+  function deselect(item) {
+    selected.value = selected.value.filter((r) => r !== item);
+  }
+
+  function toggleSelect(item) {
+    if (selected.value.includes(item)) {
+      deselect(item);
+    } else {
+      select(item);
+    }
+  }
+
+  function clearSelection() {
+    selected.value = [];
+  }
+
+  // ── Callbacks — developer-assignable ──────────────────────────────────────
+  const onSuccess = ref(null);
+  const onError = ref(null);
+
+  // ── Load / refresh ─────────────────────────────────────────────────────────
+
+  /**
+   * Reload the list. Equivalent to refresh() on the underlying composable.
+   * @param _params Reserved for future use (reactive params are handled by
+   *                the underlying useAsyncData watch sources).
+   */
+  async function load(_params) {
+    await composable.refresh?.();
+    if (!composable.error?.value) {
+      onSuccess.value?.(items.value);
+    } else {
+      onError.value?.(composable.error.value);
+    }
+  }
+
+  // ── Column label resolution ────────────────────────────────────────────────
+
+  const resolvedColumns = computed(() =>
+    columns.map((col) => ({
+      ...col,
+      label: columnLabel
+        ? columnLabel(col.key)
+        : (columnLabels[col.key] ?? col.label),
+    }))
+  );
+
+  // ── Return ─────────────────────────────────────────────────────────────────
+
+  return {
+    // State
+    items,
+    columns: resolvedColumns,
+    loading,
+    error,
+
+    // Pagination
+    pagination,
+    goToPage,
+    nextPage,
+    prevPage,
+    setPerPage,
+
+    // Selection
+    selected,
+    select,
+    deselect,
+    toggleSelect,
+    clearSelection,
+
+    // Actions
+    load,
+
+    // Callbacks
+    onSuccess,
+    onError,
+  };
+}

package/src/generators/connectors/runtime/useGetConnector.ts

@@ -0,0 +1,120 @@
+// @ts-nocheck - This file runs in user's Nuxt project with different TypeScript config
+/**
+ * useGetConnector — Runtime connector for single-item GET endpoints.
+ *
+ * Uses $fetch directly (no useAsyncData) so:
+ * - load(id) is truly imperative and awaitable
+ * - Returns the fetched item from load()
+ * - No SSR key registration, no cache interference
+ *
+ * Copied to the user's project alongside the generated connectors.
+ */
+import { ref, computed } from 'vue';
+import { getGlobalBaseUrl, mergeCallbacks } from '../composables/shared/runtime/apiHelpers.js';
+
+/**
+ * @param urlFn   URL string or function that receives an id and returns the URL string.
+ *                e.g. '/pet/me' or (id) => `/pet/${id}`
+ * @param options Optional configuration
+ */
+export function useGetConnector(urlFn, options = {}) {
+  const resolveUrl = (id) => (typeof urlFn === 'function' ? urlFn(id) : urlFn);
+  const {
+    fields = [],
+    baseURL: baseURLOpt,
+    onRequest: onRequestOpt,
+    onSuccess: onSuccessOpt,
+    onError: onErrorOpt,
+    skipGlobalCallbacks,
+  } = options;
+  const baseURL = baseURLOpt || getGlobalBaseUrl();
+  if (!baseURL) {
+    console.warn('[useGetConnector] No baseURL configured. Set runtimeConfig.public.apiBaseUrl in nuxt.config.ts or pass baseURL in options.');
+  }
+
+  // Callbacks — developer-assignable (can also be passed as options)
+  // Both the connector-level option and the per-operation registration are called.
+  let _localOnSuccess = null;
+  let _localOnError = null;
+
+  // ── State ──────────────────────────────────────────────────────────────────
+
+  const data = ref(null);
+  const loading = ref(false);
+  const error = ref(null);
+
+
+  // ── Actions ────────────────────────────────────────────────────────────────
+
+  /**
+   * Fetch a single item by ID.
+   * Returns the fetched item so it can be awaited imperatively:
+   *   const pet = await get.load(5)
+   */
+  async function load(id) {
+    if (id === undefined || id === null) {
+      console.warn('[useGetConnector] load() called with undefined/null id — request was not sent.');
+      return;
+    }
+    loading.value = true;
+    error.value = null;
+
+    // Merge global + local callbacks (onRequest modifications, rule-based suppression)
+    const url = resolveUrl(id);
+    const merged = mergeCallbacks(url, 'GET', {
+      onRequest: onRequestOpt,
+      onSuccess: onSuccessOpt,
+      onError: onErrorOpt,
+    }, skipGlobalCallbacks);
+
+    // onRequest hook — collects header/query modifications
+    const requestMods = await merged.onRequest({ url, method: 'GET' });
+
+    try {
+      const result = await $fetch(url, {
+        method: 'GET',
+        ...(requestMods?.headers ? { headers: requestMods.headers } : {}),
+        ...(requestMods?.query ? { query: requestMods.query } : {}),
+        ...(baseURL ? { baseURL } : {}),
+      });
+
+      data.value = result;
+      await merged.onSuccess(result, { operation: 'get' });
+      _localOnSuccess?.(result);
+      return result;
+    } catch (err) {
+      error.value = err;
+      await merged.onError(err, { operation: 'get' });
+      _localOnError?.(err);
+      throw err;
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  /**
+   * Clear the current item from state.
+   */
+  function clear() {
+    data.value = null;
+    error.value = null;
+  }
+
+  // ── Return ─────────────────────────────────────────────────────────────────
+
+  return {
+    // State
+    data,
+    loading,
+    error,
+    fields: computed(() => fields),
+
+    // Actions
+    load,
+    clear,
+
+    // Callbacks
+    onSuccess: (fn) => { _localOnSuccess = fn; },
+    onError: (fn) => { _localOnError = fn; },
+  };
+}

package/src/generators/connectors/runtime/useUpdateConnector.ts

@@ -0,0 +1,257 @@
+// @ts-nocheck - This file runs in user's Nuxt project with different TypeScript config
+/**
+ * useUpdateConnector — Runtime connector for PUT/PATCH endpoints.
+ *
+ * Uses $fetch directly (no useAsyncData) so:
+ * - execute() always fires a real network request, no SSR cache interference
+ * - load(id) fetches the current item to pre-fill the form
+ * - ui.open(item) pre-fills from an existing row without an extra fetch
+ *
+ * Copied to the user's project alongside the generated connectors.
+ */
+import { ref, computed } from 'vue';
+import { mergeZodErrors } from './zod-error-merger.js';
+import { getGlobalBaseUrl, mergeCallbacks } from '../composables/shared/runtime/apiHelpers.js';
+
+/**
+ * @param urlFn   URL string or function that receives an id and returns the URL string.
+ *                e.g. '/pet' (when ID is sent via body) or (id) => `/pet/${id}`
+ * @param options Configuration: schema, fields, method, baseURL, callbacks, etc.
+ */
+export function useUpdateConnector(urlFn, options = {}) {
+  const resolveUrl = (id) => (typeof urlFn === 'function' ? urlFn(id) : urlFn);
+  const {
+    schema: baseSchema,
+    schemaOverride,
+    fields = [],
+    method = 'PUT',
+    baseURL: baseURLOpt,
+    errorConfig = {},
+    onRequest: onRequestOpt,
+    onSuccess: onSuccessOpt,
+    onError: onErrorOpt,
+    onFinish: onFinishOpt,
+    autoClose = true,
+    skipGlobalCallbacks,
+  } = options;
+
+  const baseURL = baseURLOpt || getGlobalBaseUrl();
+  if (!baseURL) {
+    console.warn('[useUpdateConnector] No baseURL configured. Set runtimeConfig.public.apiBaseUrl in nuxt.config.ts or pass baseURL in options.');
+  }
+
+  // Resolve active schema: schemaOverride(base) / schemaOverride / base / none
+  const schema = schemaOverride
+    ? typeof schemaOverride === 'function'
+      ? schemaOverride(baseSchema)
+      : schemaOverride
+    : baseSchema;
+
+  if (schemaOverride && !schema) {
+    console.warn('[useUpdateConnector] schemaOverride resolved to undefined — validation will be skipped. Check your schemaOverride function returns a valid Zod schema.');
+  }
+
+  // ── Form state ─────────────────────────────────────────────────────────────
+
+  const model = ref({});
+  const errors = ref({});
+  const loading = ref(false);
+  const error = ref(null);
+  const submitted = ref(false);
+  const targetId = ref(null);
+
+  // Callbacks — developer-assignable (can also be passed as options)
+  // Both the connector-level option and the per-operation registration are called.
+  let _localOnSuccess = null;
+  let _localOnError = null;
+
+  // ── UI state ───────────────────────────────────────────────────────────────
+
+  const isOpen = ref(false);
+
+  const ui = {
+    isOpen,
+    /**
+     * Open the update form.
+     * @param item If provided, pre-fills the model immediately (no extra fetch needed).
+     *             Typically pass the row object from the table.
+     */
+    open(item) {
+      if (item) {
+        setValues(item);
+      }
+      isOpen.value = true;
+    },
+    close() {
+      isOpen.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);
+
+  // ── Actions ────────────────────────────────────────────────────────────────
+
+  function setValues(data) {
+    model.value = { ...model.value, ...data };
+  }
+
+  function setField(key, value) {
+    model.value = { ...model.value, [key]: value };
+  }
+
+  function reset() {
+    model.value = {};
+    errors.value = {};
+    error.value = null;
+    submitted.value = false;
+    targetId.value = null;
+  }
+
+  /**
+   * Fetch the current item by ID and pre-fill the form model.
+   * Use this when you need fresh data from the server before editing.
+   * If the row data from the table is sufficient, use ui.open(item) instead.
+   */
+  async function load(id) {
+    if (id === undefined || id === null) {
+      console.warn('[useUpdateConnector] load() called with undefined/null id — request was not sent.');
+      return;
+    }
+    loading.value = true;
+    error.value = null;
+
+    const loadUrl = resolveUrl(id);
+    const mergedGet = mergeCallbacks(loadUrl, 'GET', {
+      onError: onErrorOpt,
+    }, skipGlobalCallbacks);
+    const loadMods = await mergedGet.onRequest({ url: loadUrl, method: 'GET' });
+
+    try {
+      const result = await $fetch(loadUrl, {
+        method: 'GET',
+        ...(loadMods?.headers ? { headers: loadMods.headers } : {}),
+        ...(loadMods?.query ? { query: loadMods.query } : {}),
+        ...(baseURL ? { baseURL } : {}),
+      });
+
+      targetId.value = id;
+      setValues(result);
+    } catch (err) {
+      error.value = err;
+      await mergedGet.onError(err, { operation: 'update' });
+      _localOnError?.(err);
+      throw err;
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  /**
+   * Validate with Zod (if schema provided) then PUT/PATCH via $fetch.
+   * @param id   The resource ID to update.
+   * @param data Optional payload override. Falls back to model.value.
+   * @returns The response data, or undefined if validation failed.
+   */
+  async function execute(id, data) {
+    submitted.value = true;
+    const payload = data ?? model.value;
+
+    // 1. Zod validation
+    if (schema) {
+      const result = schema.safeParse(payload);
+      if (!result.success) {
+        errors.value = mergeZodErrors(result.error.flatten().fieldErrors, errorConfig);
+        console.error('[useUpdateConnector] Validation failed — request was not sent.', errors.value);
+        return undefined;
+      }
+      errors.value = {};
+    }
+
+    // 2. $fetch PUT/PATCH
+    if (id === undefined || id === null) {
+      console.warn('[useUpdateConnector] execute() called with undefined/null id — request was not sent.');
+      return undefined;
+    }
+    loading.value = true;
+    error.value = null;
+
+    const url = resolveUrl(id);
+
+    // Merge global + local callbacks (onRequest modifications, rule-based suppression)
+    const merged = mergeCallbacks(url, method, {
+      onRequest: onRequestOpt,
+      onSuccess: onSuccessOpt,
+      onError: onErrorOpt,
+      onFinish: onFinishOpt,
+    }, skipGlobalCallbacks);
+
+    // onRequest hook — collects header/body/query modifications from global rules and local option
+    const requestMods = await merged.onRequest({ url, method, body: payload });
+
+    try {
+      const result = await $fetch(url, {
+        method,
+        body: requestMods?.body ?? payload,
+        ...(requestMods?.headers ? { headers: requestMods.headers } : {}),
+        ...(requestMods?.query ? { query: requestMods.query } : {}),
+        ...(baseURL ? { baseURL } : {}),
+      });
+
+      await merged.onSuccess(result, { operation: 'update' });
+      _localOnSuccess?.(result);
+
+      if (autoClose) ui.close();
+
+      await merged.onFinish({ url, method, data: result, success: true });
+
+      return result;
+    } catch (err) {
+      error.value = err;
+      await merged.onError(err, { operation: 'update' });
+      _localOnError?.(err);
+
+      await merged.onFinish({ url, method, error: err, success: false });
+
+      throw err;
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  // ── Return ─────────────────────────────────────────────────────────────────
+
+  return {
+    // Form state
+    model,
+    errors,
+    loading,
+    error,
+    submitted,
+    isValid,
+    hasErrors,
+    fields: computed(() => fields),
+    targetId,
+
+    // Actions
+    load,
+    execute,
+    refresh: execute,
+    reset,
+    setValues,
+    setField,
+
+    // Callbacks
+    onSuccess: (fn) => { _localOnSuccess = fn; },
+    onError: (fn) => { _localOnError = fn; },
+
+    // UI
+    ui,
+  };
+}

package/src/generators/connectors/runtime/zod-error-merger.ts

@@ -0,0 +1,119 @@
+// @ts-nocheck - This file runs in user's Nuxt project with different TypeScript config
+/**
+ * zod-error-merger — Merge Zod fieldErrors with per-field error message overrides.
+ *
+ * Priority (highest → lowest):
+ *   3. config.fields[fieldName].errors[zodCode]   — per-field, per-code override
+ *   2. z.setErrorMap()                            — global translation (set by the developer)
+ *   1. Zod defaults                               — built-in English messages
+ *
+ * This function handles priority 3 only. Priority 2 is handled automatically by Zod
+ * when the developer sets z.setErrorMap() in their plugins/zod-i18n.ts.
+ *
+ * Copied to the user's project alongside the generated connectors.
+ */
+
+/**
+ * Map Zod issue codes to friendlier config key names.
+ * The developer uses these keys in config.fields[name].errors:
+ *
+ *   errors: {
+ *     required: 'Name is required',
+ *     min:      'At least 1 character',
+ *     max:      'Max 100 characters',
+ *     email:    'Invalid email',
+ *     enum:     'Select a valid option',
+ *   }
+ */
+const ZOD_CODE_TO_CONFIG_KEY = {
+  too_small: 'min',
+  too_big: 'max',
+  invalid_type: 'required', // most common: field is undefined/null
+  invalid_enum_value: 'enum',
+  invalid_string: 'format',
+};
+
+/**
+ * Convert Zod's flatten().fieldErrors to Record<string, string>,
+ * merging optional per-field message overrides from the component config.
+ *
+ * @param fieldErrors  Output of zodResult.error.flatten().fieldErrors
+ *                     Shape: { fieldName: string[] }
+ * @param errorConfig  Optional per-field error config from index.ts
+ *                     Shape: { fieldName: { required?: string, min?: string, ... } }
+ */
+export function mergeZodErrors(fieldErrors, errorConfig = {}) {
+  const result = {};
+
+  for (const [field, messages] of Object.entries(fieldErrors)) {
+    if (!messages || messages.length === 0) {
+      continue;
+    }
+
+    // The first message is the most relevant one
+    const defaultMessage = messages[0];
+
+    // Check if there's a config override for this field
+    const fieldConfig = errorConfig[field];
+    if (!fieldConfig) {
+      result[field] = defaultMessage;
+      continue;
+    }
+
+    // Try to map the Zod message to a config key.
+    // We check for simple substrings in the Zod message to identify the code.
+    const configMessage = resolveConfigMessage(defaultMessage, fieldConfig);
+    result[field] = configMessage ?? defaultMessage;
+  }
+
+  return result;
+}
+
+/**
+ * Try to find a matching override in fieldConfig based on the Zod message content.
+ * Returns the override string, or null if no match found.
+ */
+function resolveConfigMessage(zodMessage, fieldConfig) {
+  if (!fieldConfig || typeof fieldConfig !== 'object') {
+    return null;
+  }
+
+  // Direct key match: developer can use zod code names directly
+  // e.g. errors.too_small, errors.invalid_type
+  for (const [zodCode, configKey] of Object.entries(ZOD_CODE_TO_CONFIG_KEY)) {
+    if (fieldConfig[zodCode]) {
+      // Check if Zod message suggests this error type
+      if (messageMatchesCode(zodMessage, zodCode)) {
+        return fieldConfig[zodCode];
+      }
+    }
+    // Also support friendly key names: errors.min, errors.required, etc.
+    if (fieldConfig[configKey]) {
+      if (messageMatchesCode(zodMessage, zodCode)) {
+        return fieldConfig[configKey];
+      }
+    }
+  }
+
+  // Fallback: if developer set errors.required and Zod says "Required"
+  if (fieldConfig.required && /required|undefined|null/i.test(zodMessage)) {
+    return fieldConfig.required;
+  }
+
+  return null;
+}
+
+/**
+ * Heuristic: does the Zod default message suggest a certain error code?
+ */
+function messageMatchesCode(message, zodCode) {
+  const patterns = {
+    too_small: /at least|minimum|must contain at least|min/i,
+    too_big: /at most|maximum|must contain at most|max/i,
+    invalid_type: /required|expected|received undefined|null/i,
+    invalid_enum_value: /invalid enum|expected one of/i,
+    invalid_string: /invalid|email|url|uuid|datetime/i,
+  };
+
+  return patterns[zodCode]?.test(message) ?? false;
+}