nuxt-openapi-hyperfetch 0.3.81-beta → 1.0.0

package/src/generators/connectors/runtime/connector-types.ts

@@ -0,0 +1,207 @@
+/**
+ * connector-types.ts — Structural return type interfaces for the new connector system.
+ *
+ * Uses locally-defined minimal type aliases for Ref/ComputedRef 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.
+ */
+
+// Minimal structural aliases — compatible with Vue's Ref<T> and ComputedRef<T>.
+type Ref<T> = { value: T };
+type ComputedRef<T> = { readonly value: T };
+
+/** Operation name passed as context to connector-level callbacks. */
+export type ConnectorOperation = 'create' | 'update' | 'delete' | 'get' | 'getAll';
+
+export interface ConnectorCallbackContext {
+  operation: ConnectorOperation;
+}
+
+// ─── Column / field defs (mirrors schema-analyzer output) ────────────────────
+
+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;
+}
+
+// ─── Pagination ───────────────────────────────────────────────────────────────
+
+export interface PaginationState {
+  currentPage: number;
+  perPage: number;
+  total: number;
+  totalPages: number;
+  hasNextPage: boolean;
+  hasPrevPage: boolean;
+  goToPage: (page: number) => void;
+  nextPage: () => void;
+  prevPage: () => void;
+  setPerPage: (n: number) => void;
+}
+
+// ─── UI state (shared sub-object in create / update / del) ───────────────────
+
+export interface ConnectorUi {
+  isOpen: Ref<boolean>;
+  open: (...args: any[]) => void;
+  close: () => void;
+}
+
+// ─── GetAllConnectorReturn ────────────────────────────────────────────────────
+
+export interface GetAllConnectorReturn<TRow = unknown> {
+  // State
+  items: ComputedRef<TRow[]>;
+  columns: ComputedRef<ColumnDef[]>;
+  loading: ComputedRef<boolean>;
+  error: ComputedRef<unknown>;
+
+  // Pagination
+  pagination: ComputedRef<PaginationState | null>;
+  goToPage: (page: number) => void;
+  nextPage: () => void;
+  prevPage: () => void;
+  setPerPage: (n: number) => void;
+
+  // Selection
+  selected: Ref<TRow[]>;
+  select: (item: TRow) => void;
+  deselect: (item: TRow) => void;
+  toggleSelect: (item: TRow) => void;
+  clearSelection: () => void;
+
+  // Actions
+  load: (params?: unknown) => Promise<void>;
+
+  // Callbacks (developer-assignable)
+  onSuccess: Ref<((items: TRow[]) => void) | null>;
+  onError: Ref<((err: unknown) => void) | null>;
+}
+
+// ─── GetConnectorReturn ───────────────────────────────────────────────────────
+
+export interface GetConnectorReturn<TItem = unknown> {
+  // State
+  data: Ref<TItem | null>;
+  loading: Ref<boolean>;
+  error: Ref<unknown>;
+  fields: ComputedRef<FormFieldDef[]>;
+
+  // Actions
+  load: (id: string | number) => Promise<TItem>;
+  clear: () => void;
+
+  // Callbacks (developer-assignable via get.onSuccess(fn))
+  // The per-operation callback complements the connector-level onSuccess option.
+  onSuccess: (fn: (item: TItem) => void) => void;
+  onError: (fn: (err: unknown) => void) => void;
+}
+
+// ─── CreateConnectorReturn ────────────────────────────────────────────────────
+
+export interface CreateConnectorReturn<TInput = Record<string, unknown>, TOutput = TInput> {
+  // Form state
+  model: Ref<Partial<TInput>>;
+  errors: Ref<Record<string, string[]>>;
+  loading: Ref<boolean>;
+  error: Ref<unknown>;
+  submitted: Ref<boolean>;
+  isValid: ComputedRef<boolean>;
+  hasErrors: ComputedRef<boolean>;
+  fields: ComputedRef<FormFieldDef[]>;
+
+  // Actions
+  execute: (data?: Partial<TInput>) => Promise<TOutput | undefined>;
+  refresh: (data?: Partial<TInput>) => Promise<TOutput | undefined>;
+  reset: () => void;
+  setValues: (data: Partial<TInput>) => void;
+  setField: (key: keyof TInput, value: unknown) => void;
+
+  // Callbacks (developer-assignable via create.onSuccess(fn))
+  // The per-operation callback complements the connector-level onSuccess option.
+  onSuccess: (fn: (data: TOutput) => void) => void;
+  onError: (fn: (err: unknown) => void) => void;
+
+  // UI coordination
+  ui: {
+    isOpen: Ref<boolean>;
+    open: () => void;
+    close: () => void;
+  };
+}
+
+// ─── UpdateConnectorReturn ────────────────────────────────────────────────────
+
+export interface UpdateConnectorReturn<TInput = Record<string, unknown>, TOutput = TInput> {
+  // Form state
+  model: Ref<Partial<TInput>>;
+  errors: Ref<Record<string, string[]>>;
+  loading: Ref<boolean>;
+  error: Ref<unknown>;
+  submitted: Ref<boolean>;
+  isValid: ComputedRef<boolean>;
+  hasErrors: ComputedRef<boolean>;
+  fields: ComputedRef<FormFieldDef[]>;
+  targetId: Ref<string | number | null>;
+
+  // Actions
+  load: (id: string | number) => Promise<void>;
+  execute: (id: string | number, data?: Partial<TInput>) => Promise<TOutput | undefined>;
+  refresh: (id: string | number, data?: Partial<TInput>) => Promise<TOutput | undefined>;
+  reset: () => void;
+  setValues: (data: Partial<TInput>) => void;
+  setField: (key: keyof TInput, value: unknown) => void;
+
+  // Callbacks (developer-assignable via update.onSuccess(fn))
+  // The per-operation callback complements the connector-level onSuccess option.
+  onSuccess: (fn: (data: TOutput) => void) => void;
+  onError: (fn: (err: unknown) => void) => void;
+
+  // UI coordination
+  ui: {
+    isOpen: Ref<boolean>;
+    open: (item?: Partial<TInput> & Record<string, unknown>) => void;
+    close: () => void;
+  };
+}
+
+// ─── DeleteConnectorReturn ────────────────────────────────────────────────────
+
+export interface DeleteConnectorReturn<TItem = unknown> {
+  // State
+  staged: Ref<TItem | null>;
+  hasStaged: ComputedRef<boolean>;
+  loading: Ref<boolean>;
+  error: Ref<unknown>;
+
+  // Actions
+  stage: (item: TItem) => void;
+  cancel: () => void;
+  execute: (item?: TItem) => Promise<void>;
+  refresh: (item?: TItem) => Promise<void>;
+
+  // Callbacks (developer-assignable via remove.onSuccess(fn))
+  // The per-operation callback complements the connector-level onSuccess option.
+  onSuccess: (fn: (item: TItem) => void) => void;
+  onError: (fn: (err: unknown) => void) => void;
+
+  // UI coordination
+  ui: {
+    isOpen: Ref<boolean>;
+    open: (item: TItem) => void;
+    close: () => void;
+  };
+}

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

@@ -0,0 +1,199 @@
+// @ts-nocheck - This file runs in user's Nuxt project with different TypeScript config
+/**
+ * useCreateConnector — Runtime connector for POST endpoints.
+ *
+ * Uses $fetch directly (no useAsyncData) so:
+ * - execute() always fires a real network request, no SSR cache interference
+ * - Can be called multiple times (create multiple items)
+ * - Validates with Zod before sending
+ *
+ * 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 url     The endpoint URL string. e.g. '/pet'
+ * @param options Configuration: schema, fields, method, baseURL, callbacks, etc.
+ */
+export function useCreateConnector(url, options = {}) {
+  const {
+    schema: baseSchema,
+    schemaOverride,
+    fields = [],
+    method = 'POST',
+    baseURL: baseURLOpt,
+    errorConfig = {},
+    onRequest: onRequestOpt,
+    onSuccess: onSuccessOpt,
+    onError: onErrorOpt,
+    onFinish: onFinishOpt,
+    autoClose = true,
+    autoReset = false,
+    skipGlobalCallbacks,
+  } = options;
+
+  const baseURL = baseURLOpt || getGlobalBaseUrl();
+  if (!baseURL) {
+    console.warn('[useCreateConnector] 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('[useCreateConnector] 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);
+
+  // 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() {
+      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;
+  }
+
+  /**
+   * Validate with Zod (if schema provided) then POST via $fetch.
+   * @param data Optional payload override. Falls back to model.value.
+   * @returns The response data, or undefined if validation failed.
+   */
+  async function execute(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('[useCreateConnector] Validation failed — request was not sent.', errors.value);
+        return undefined;
+      }
+      errors.value = {};
+    }
+
+    // 2. $fetch POST
+    loading.value = true;
+    error.value = null;
+
+    // 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: 'create' });
+      _localOnSuccess?.(result);
+
+      if (autoClose) ui.close();
+      if (autoReset) reset();
+
+      await merged.onFinish({ url, method, data: result, success: true });
+
+      return result;
+    } catch (err) {
+      error.value = err;
+      await merged.onError(err, { operation: 'create' });
+      _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),
+
+    // Actions
+    execute,
+    refresh: execute,
+    reset,
+    setValues,
+    setField,
+
+    // Callbacks
+    onSuccess: (fn) => { _localOnSuccess = fn; },
+    onError: (fn) => { _localOnError = fn; },
+
+    // UI
+    ui,
+  };
+}

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

@@ -0,0 +1,179 @@
+// @ts-nocheck - This file runs in user's Nuxt project with different TypeScript config
+/**
+ * useDeleteConnector — Runtime connector for DELETE endpoints.
+ *
+ * Uses $fetch directly (no useAsyncData) so:
+ * - execute() always fires a real network request, no SSR cache interference
+ * - Supports staging pattern (stage → confirm via ui) or direct execution
+ *
+ * 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 idFn    Function that extracts the resource ID from a staged item.
+ *                e.g. (item) => item.petId ?? item.id
+ * @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 Optional configuration
+ */
+export function useDeleteConnector(idFn, urlFn, options = {}) {
+  const resolveUrl = (id) => (typeof urlFn === 'function' ? urlFn(id) : urlFn);
+  const {
+    baseURL: baseURLOpt,
+    onRequest: onRequestOpt,
+    onSuccess: onSuccessOpt,
+    onError: onErrorOpt,
+    onFinish: onFinishOpt,
+    autoClose = true,
+    skipGlobalCallbacks,
+  } = options;
+
+  const baseURL = baseURLOpt || getGlobalBaseUrl();
+  if (!baseURL) {
+    console.warn('[useDeleteConnector] No baseURL configured. Set runtimeConfig.public.apiBaseUrl in nuxt.config.ts or pass baseURL in options.');
+  }
+
+  // ── State ──────────────────────────────────────────────────────────────────
+
+  const staged = ref(null);
+  const loading = ref(false);
+  const error = 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,
+    /**
+     * Stage the item and open the confirmation UI (modal/drawer/etc).
+     */
+    open(item) {
+      stage(item);
+      isOpen.value = true;
+    },
+    /**
+     * Cancel and close the confirmation UI.
+     */
+    close() {
+      cancel();
+      isOpen.value = false;
+    },
+  };
+
+  // ── Derived ────────────────────────────────────────────────────────────────
+
+  const hasStaged = computed(() => staged.value !== null);
+
+  // ── Actions ────────────────────────────────────────────────────────────────
+
+  /**
+   * Stage an item for deletion without opening any UI.
+   * Useful when you want to control the UI yourself.
+   */
+  function stage(item) {
+    staged.value = item;
+  }
+
+  /**
+   * Clear the staged item and reset error state.
+   */
+  function cancel() {
+    staged.value = null;
+    error.value = null;
+  }
+
+  /**
+   * Execute the DELETE request.
+   * @param item Optional — if provided, uses this item instead of staged.
+   *             Allows direct deletion without staging: await del.execute(row)
+   */
+  async function execute(item) {
+    const target = item ?? staged.value;
+
+    if (!target) {
+      console.warn('[useDeleteConnector] execute() called with no item and nothing staged — request was not sent. Call stage(item) or pass the item directly to execute(item).');
+      return;
+    }
+
+    const id = idFn(target);
+    if (id === undefined || id === null) {
+      console.warn('[useDeleteConnector] idFn returned undefined/null — could not resolve resource ID. Request was not sent.', { target });
+      return;
+    }
+    const url = resolveUrl(id);
+
+    loading.value = true;
+    error.value = null;
+
+    // Merge global + local callbacks (onRequest modifications, rule-based suppression)
+    const merged = mergeCallbacks(url, 'DELETE', {
+      onRequest: onRequestOpt,
+      onSuccess: onSuccessOpt,
+      onError: onErrorOpt,
+      onFinish: onFinishOpt,
+    }, skipGlobalCallbacks);
+
+    // onRequest hook — collects header/body/query modifications
+    const requestMods = await merged.onRequest({ url, method: 'DELETE' });
+
+    try {
+      await $fetch(url, {
+        method: 'DELETE',
+        ...(requestMods?.headers ? { headers: requestMods.headers } : {}),
+        ...(requestMods?.query ? { query: requestMods.query } : {}),
+        ...(baseURL ? { baseURL } : {}),
+      });
+
+      const deletedItem = target;
+
+      await merged.onSuccess(deletedItem, { operation: 'delete' });
+      _localOnSuccess?.(deletedItem);
+      cancel();
+
+      if (autoClose) ui.close();
+
+      await merged.onFinish({ url, method: 'DELETE', success: true });
+    } catch (err) {
+      error.value = err;
+      await merged.onError(err, { operation: 'delete' });
+      _localOnError?.(err);
+
+      await merged.onFinish({ url, method: 'DELETE', error: err, success: false });
+
+      throw err;
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  // ── Return ─────────────────────────────────────────────────────────────────
+
+  return {
+    // State
+    staged,
+    hasStaged,
+    loading,
+    error,
+
+    // Actions
+    stage,
+    cancel,
+    execute,
+    refresh: execute,
+
+    // Callbacks
+    onSuccess: (fn) => { _localOnSuccess = fn; },
+    onError: (fn) => { _localOnError = fn; },
+
+    // UI
+    ui,
+  };
+}