@wpnuxt/core 2.0.0-alpha.4 → 2.0.0-alpha.6

package/dist/module.json

@@ -1,7 +1,10 @@
 {
-  "name": "wpnuxt",
+  "name": "@wpnuxt/core",
   "configKey": "wpNuxt",
-  "version": "2.0.0-alpha.3",
+  "compatibility": {
+    "nuxt": ">=3.0.0"
+  },
+  "version": "2.0.0-alpha.5",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -8,6 +8,13 @@ import { ref } from 'vue';
 import { parse, GraphQLError } from 'graphql';
 import { execSync } from 'node:child_process';
 
+function createModuleError(module, message) {
+  return new Error(formatErrorMessage(module, message));
+}
+function formatErrorMessage(module, message) {
+  return `[wpnuxt:${module}] ${message}`;
+}
+
 function randHashGenerator(length = 12) {
   return Math.random().toString(36).substring(2, 2 + length).toUpperCase().padEnd(length, "0");
 }
@@ -38,14 +45,14 @@ async function mergeQueries(nuxt, wpNuxtConfig, resolver) {
 
 const _parseDoc = async (doc) => {
   if (!doc || typeof doc !== "string" || doc.trim().length === 0) {
-    throw new Error("WPNuxt: Invalid GraphQL document - document is empty or not a string");
+    throw createModuleError("core", "Invalid GraphQL document - document is empty or not a string");
   }
   try {
     const { definitions } = parse(doc);
     const operations = definitions.filter(({ kind }) => kind === "OperationDefinition").map((definition) => {
       const operationDefinition = definition;
       if (!operationDefinition.name?.value) {
-        throw new Error("WPNuxt: GraphQL operation is missing a name. All queries and mutations must have a name.");
+        throw createModuleError("core", "GraphQL operation is missing a name. All queries and mutations must have a name.");
       }
       const query = {
         name: operationDefinition.name.value.trim(),
@@ -60,7 +67,7 @@ const _parseDoc = async (doc) => {
     return operations;
   } catch (error) {
     if (error instanceof GraphQLError) {
-      throw new TypeError(`WPNuxt: Failed to parse GraphQL document - ${error.message}`);
+      throw createModuleError("core", `Failed to parse GraphQL document - ${error.message}`);
     }
     throw error;
   }
@@ -83,6 +90,31 @@ function processSelections(selections, level, query, canExtract = true) {
 const parseDoc = _parseDoc;
 
 const SCHEMA_PATTERN = /schema\.(?:gql|graphql)$/i;
+const COMPLEXITY_THRESHOLDS = {
+  /** Maximum recommended extraction depth */
+  maxDepth: 5,
+  /** Maximum recommended number of fragments */
+  maxFragments: 4
+};
+function analyzeQueryComplexity(queries) {
+  const logger = getLogger();
+  for (const query of queries) {
+    const warnings = [];
+    const depth = query.nodes?.length ?? 0;
+    if (depth > COMPLEXITY_THRESHOLDS.maxDepth) {
+      warnings.push(`deep extraction path (${depth} levels)`);
+    }
+    const fragmentCount = query.fragments?.length ?? 0;
+    if (fragmentCount > COMPLEXITY_THRESHOLDS.maxFragments) {
+      warnings.push(`many fragments (${fragmentCount})`);
+    }
+    if (warnings.length > 0) {
+      logger.warn(
+        `Query "${query.name}" may be expensive: ${warnings.join(", ")}. Consider splitting into smaller queries or reducing data fetched.`
+      );
+    }
+  }
+}
 const allowDocument = (f, resolver) => {
   if (SCHEMA_PATTERN.test(f)) return false;
   try {
@@ -106,6 +138,7 @@ async function prepareContext(ctx) {
   }
   const queries = ctx.fns.filter((f) => f.operation === "query");
   const mutations = ctx.fns.filter((f) => f.operation === "mutation");
+  analyzeQueryComplexity(queries);
   const fnName = (fn) => ctx.composablesPrefix + upperFirst(fn);
   const mutationFnName = (fn) => `useMutation${upperFirst(fn)}`;
   const formatNodes = (nodes) => nodes?.map((n) => `'${n}'`).join(",") ?? "";
@@ -246,7 +279,7 @@ async function validateWordPressEndpoint(wordpressUrl, graphqlEndpoint = "/graph
     clearTimeout(timeout);
     if (!response.ok) {
       throw new Error(
-        `[WPNuxt] WordPress GraphQL endpoint returned HTTP ${response.status}.
+        `[wpnuxt:core] WordPress GraphQL endpoint returned HTTP ${response.status}.
 
 URL: ${fullUrl}
 
@@ -261,7 +294,7 @@ Check your wpNuxt.wordpressUrl configuration in nuxt.config.ts`
     const data = await response.json();
     if (!data || typeof data !== "object") {
       throw new Error(
-        `[WPNuxt] WordPress GraphQL endpoint returned invalid response.
+        `[wpnuxt:core] WordPress GraphQL endpoint returned invalid response.
 
 URL: ${fullUrl}
 
@@ -271,7 +304,7 @@ The endpoint did not return valid JSON. Make sure WPGraphQL plugin is installed
     if (data.errors && !data.data) {
       const errorMessage = data.errors[0]?.message || "Unknown error";
       throw new Error(
-        `[WPNuxt] WordPress GraphQL endpoint returned an error: ${errorMessage}
+        `[wpnuxt:core] WordPress GraphQL endpoint returned an error: ${errorMessage}
 
 URL: ${fullUrl}
 
@@ -289,7 +322,7 @@ Make sure WPGraphQL plugin is installed and activated on your WordPress site.`
       } catch (err) {
         const error = err;
         throw new Error(
-          `[WPNuxt] Failed to download GraphQL schema.
+          `[wpnuxt:core] Failed to download GraphQL schema.
 
 URL: ${fullUrl}
 Error: ${error.stderr?.toString() || error.message}
@@ -299,14 +332,14 @@ Make sure WPGraphQL plugin is installed and activated on your WordPress site.`
       }
     }
   } catch (error) {
-    if (error instanceof Error && error.message.startsWith("[WPNuxt]")) {
+    if (error instanceof Error && error.message.startsWith("[wpnuxt:core]")) {
       throw error;
     }
     const err = error;
     const errorCode = err.code || err.cause?.code || "";
     if (err.name === "AbortError") {
       throw new Error(
-        `[WPNuxt] WordPress GraphQL endpoint timed out after 10 seconds.
+        `[wpnuxt:core] WordPress GraphQL endpoint timed out after 10 seconds.
 
 URL: ${fullUrl}
 
@@ -315,7 +348,7 @@ The server did not respond in time. Check if the WordPress site is accessible.`
     }
     if (errorCode === "ENOTFOUND" || err.message?.includes("getaddrinfo")) {
       throw new Error(
-        `[WPNuxt] WordPress site not found - DNS lookup failed.
+        `[wpnuxt:core] WordPress site not found - DNS lookup failed.
 
 URL: ${fullUrl}
 
@@ -329,7 +362,7 @@ Check your wpNuxt.wordpressUrl configuration in nuxt.config.ts`
     }
     if (errorCode === "ECONNREFUSED") {
       throw new Error(
-        `[WPNuxt] Connection refused to WordPress site.
+        `[wpnuxt:core] Connection refused to WordPress site.
 
 URL: ${fullUrl}
 
@@ -337,7 +370,7 @@ The server is not accepting connections. Check if the WordPress site is running.
       );
     }
     throw new Error(
-      `[WPNuxt] Failed to connect to WordPress GraphQL endpoint.
+      `[wpnuxt:core] Failed to connect to WordPress GraphQL endpoint.
 
 URL: ${fullUrl}
 Error: ${err.message || "Unknown error"}
@@ -373,8 +406,11 @@ function patchWPGraphQLSchema(schemaPath) {
 
 const module$1 = defineNuxtModule({
   meta: {
-    name: "wpnuxt",
-    configKey: "wpNuxt"
+    name: "@wpnuxt/core",
+    configKey: "wpNuxt",
+    compatibility: {
+      nuxt: ">=3.0.0"
+    }
   },
   defaults: {
     wordpressUrl: void 0,
@@ -404,15 +440,32 @@ const module$1 = defineNuxtModule({
     const mergedQueriesFolder = await mergeQueries(nuxt, wpNuxtConfig, resolver);
     await setupServerOptions(nuxt, resolver, logger);
     await setupClientOptions(nuxt, resolver, logger);
+    const schemaPath = join(nuxt.options.rootDir, "schema.graphql");
+    const schemaExists = existsSync(schemaPath);
     if (wpNuxtConfig.downloadSchema) {
-      const schemaPath = join(nuxt.options.rootDir, "schema.graphql");
-      logger.debug(`Validating WordPress endpoint: ${wpNuxtConfig.wordpressUrl}${wpNuxtConfig.graphqlEndpoint}`);
-      await validateWordPressEndpoint(
-        wpNuxtConfig.wordpressUrl,
-        wpNuxtConfig.graphqlEndpoint,
-        { schemaPath }
-      );
-      logger.debug("WordPress endpoint validation passed");
+      if (!schemaExists) {
+        logger.debug(`Downloading schema from: ${wpNuxtConfig.wordpressUrl}${wpNuxtConfig.graphqlEndpoint}`);
+        await validateWordPressEndpoint(
+          wpNuxtConfig.wordpressUrl,
+          wpNuxtConfig.graphqlEndpoint,
+          { schemaPath }
+        );
+        logger.debug("Schema downloaded successfully");
+      } else {
+        nuxt.hook("ready", async () => {
+          try {
+            await validateWordPressEndpoint(
+              wpNuxtConfig.wordpressUrl,
+              wpNuxtConfig.graphqlEndpoint
+            );
+            logger.debug("WordPress endpoint validation passed");
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.warn(`WordPress endpoint validation failed: ${message.split("\n")[0]}`);
+            logger.warn("App will continue with existing schema.graphql file");
+          }
+        });
+      }
     }
     await registerModules(nuxt, resolver, wpNuxtConfig, mergedQueriesFolder);
     nuxt.hook("devtools:customTabs", (tabs) => {
@@ -500,10 +553,10 @@ function loadConfig(options, nuxt) {
     }
   };
   if (!config.wordpressUrl?.trim()) {
-    throw new Error("WPNuxt error: WordPress url is missing");
+    throw createModuleError("core", "WordPress URL is required. Set it in nuxt.config.ts or via WPNUXT_WORDPRESS_URL environment variable.");
   }
   if (config.wordpressUrl.endsWith("/")) {
-    throw new Error(`WPNuxt error: WordPress url should not have a trailing slash: ${config.wordpressUrl}`);
+    throw createModuleError("core", `WordPress URL should not have a trailing slash: ${config.wordpressUrl}`);
   }
   return config;
 }

package/dist/runtime/composables/useWPContent.js

@@ -1,36 +1,102 @@
 import { getRelativeImagePath } from "../util/images.js";
-import { computed, useAsyncGraphqlQuery } from "#imports";
-function defaultGetCachedData(key, nuxtApp, ctx) {
-  if (nuxtApp.isHydrating) {
-    return nuxtApp.payload.data[key];
-  }
-  if (ctx.cause === "refresh:manual" || ctx.cause === "refresh:hook") {
-    return void 0;
-  }
-  return nuxtApp.payload.data[key] ?? nuxtApp.static.data[key];
-}
+import { computed, ref, watch as vueWatch, useAsyncGraphqlQuery } from "#imports";
 export const useWPContent = (queryName, nodes, fixImagePaths, params, options) => {
-  const { clientCache, cacheKey, getCachedData: userGetCachedData, ...restOptions } = options ?? {};
+  const {
+    clientCache,
+    cacheKey,
+    getCachedData: userGetCachedData,
+    retry: retryOption,
+    retryDelay: retryDelayOption,
+    timeout: timeoutOption,
+    ...restOptions
+  } = options ?? {};
+  const maxRetries = retryOption === false ? 0 : retryOption ?? 0;
+  const baseRetryDelay = retryDelayOption ?? 1e3;
+  const retryCount = ref(0);
+  const isRetrying = ref(false);
+  const timeoutMs = timeoutOption ?? 0;
   const graphqlCaching = clientCache === false ? { client: false } : restOptions.graphqlCaching ?? { client: true };
   const paramsKey = params ? JSON.stringify(params) : "{}";
   const baseKey = `wpnuxt-${String(queryName)}-${paramsKey}`;
   const finalKey = cacheKey ? `${baseKey}-${cacheKey}` : baseKey;
-  const effectiveGetCachedData = userGetCachedData ?? (clientCache === false ? () => void 0 : defaultGetCachedData);
+  const effectiveGetCachedData = userGetCachedData ?? (clientCache === false ? () => void 0 : void 0);
+  let abortController;
+  let timeoutId;
+  if (timeoutMs > 0) {
+    abortController = new AbortController();
+    timeoutId = setTimeout(() => {
+      abortController?.abort();
+      if (import.meta.dev) {
+        console.warn(`[wpnuxt] Query "${String(queryName)}" timed out after ${timeoutMs}ms`);
+      }
+    }, timeoutMs);
+  }
   const mergedOptions = {
     ...restOptions,
     graphqlCaching,
     // Explicit key ensures consistent cache lookups
     key: finalKey,
-    getCachedData: effectiveGetCachedData
+    // Only set getCachedData if user provided one or wants to disable caching
+    // Otherwise let nuxt-graphql-middleware handle it with $graphqlCache
+    ...effectiveGetCachedData && { getCachedData: effectiveGetCachedData },
+    // Pass abort signal for timeout support
+    ...abortController && {
+      fetchOptions: {
+        ...restOptions.fetchOptions ?? {},
+        signal: abortController.signal
+      }
+    }
   };
   const { data, pending, refresh, execute, clear, error, status } = useAsyncGraphqlQuery(
     queryName,
     params ?? {},
     mergedOptions
   );
+  const transformError = ref(null);
+  if (timeoutId !== void 0) {
+    vueWatch(pending, (isPending) => {
+      if (!isPending && timeoutId !== void 0) {
+        clearTimeout(timeoutId);
+        timeoutId = void 0;
+      }
+    }, { immediate: true });
+  }
+  if (maxRetries > 0) {
+    vueWatch(error, async (newError) => {
+      if (newError && !isRetrying.value && retryCount.value < maxRetries && import.meta.client) {
+        isRetrying.value = true;
+        retryCount.value++;
+        const delay = baseRetryDelay * Math.pow(2, retryCount.value - 1);
+        if (import.meta.dev) {
+          console.warn(`[wpnuxt] Query "${String(queryName)}" failed, retrying in ${delay}ms (attempt ${retryCount.value}/${maxRetries})`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        try {
+          await refresh();
+        } finally {
+          isRetrying.value = false;
+        }
+      }
+    });
+    vueWatch(data, (newData) => {
+      if (newData && retryCount.value > 0) {
+        retryCount.value = 0;
+      }
+    });
+  }
   const transformedData = computed(() => {
-    const queryResult = data.value && typeof data.value === "object" && data.value !== null && "data" in data.value ? data.value.data : void 0;
-    return queryResult ? transformData(queryResult, nodes, fixImagePaths) : void 0;
+    transformError.value = null;
+    try {
+      const queryResult = data.value && typeof data.value === "object" && data.value !== null && "data" in data.value ? data.value.data : void 0;
+      if (!queryResult) return void 0;
+      return transformData(queryResult, nodes, fixImagePaths);
+    } catch (err) {
+      if (import.meta.dev) {
+        console.warn(`[wpnuxt] Data transformation error for "${String(queryName)}":`, err);
+      }
+      transformError.value = err instanceof Error ? err : new Error("Failed to transform query response");
+      return void 0;
+    }
   });
   return {
     data: transformedData,
@@ -39,7 +105,13 @@ export const useWPContent = (queryName, nodes, fixImagePaths, params, options) =
     execute,
     clear,
     error,
-    status
+    status,
+    /** Error from data transformation (separate from fetch error) */
+    transformError,
+    /** Current retry attempt count (0 if no retries or retries disabled) */
+    retryCount,
+    /** Whether a retry is currently in progress */
+    isRetrying
   };
 };
 const transformData = (data, nodes, fixImagePaths) => {

package/dist/runtime/types/errors.js

@@ -0,0 +1,32 @@
+export function createWPNuxtError(code, message, options) {
+  return {
+    code,
+    message,
+    details: options?.details,
+    query: options?.query,
+    timestamp: Date.now()
+  };
+}
+export function isWPNuxtError(error) {
+  return typeof error === "object" && error !== null && "code" in error && "message" in error && "timestamp" in error && typeof error.code === "string" && typeof error.message === "string" && typeof error.timestamp === "number";
+}
+export function success(data) {
+  return { success: true, data, error: null };
+}
+export function failure(error) {
+  return { success: false, data: null, error };
+}
+export function fromError(error, code = "NETWORK_ERROR", query) {
+  let errorCode = code;
+  if (error.name === "AbortError") {
+    errorCode = "TIMEOUT_ERROR";
+  } else if (error.message?.includes("GraphQL")) {
+    errorCode = "GRAPHQL_ERROR";
+  } else if (error.message?.includes("401") || error.message?.includes("403")) {
+    errorCode = "AUTH_ERROR";
+  }
+  return createWPNuxtError(errorCode, error.message, {
+    details: error.stack,
+    query
+  });
+}

package/dist/runtime/types/stub.d.ts

@@ -8,6 +8,8 @@
 
 // Stub for #imports
 export const computed: any
+export const ref: any
+export const watch: any
 export const defineNuxtPlugin: any
 export const useAsyncGraphqlQuery: any
 export const useGraphqlState: any

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wpnuxt/core",
-  "version": "2.0.0-alpha.4",
+  "version": "2.0.0-alpha.6",
   "description": "Nuxt module for WordPress integration via GraphQL (WPGraphQL)",
   "keywords": [
     "nuxt",
@@ -47,18 +47,18 @@
     "@radya/nuxt-dompurify": "^1.0.5",
     "defu": "^6.1.4",
     "graphql": "^16.12.0",
-    "nuxt-graphql-middleware": "5.3.1",
+    "nuxt-graphql-middleware": "5.3.2",
     "scule": "^1.3.0"
   },
   "devDependencies": {
     "@nuxt/devtools": "^3.1.1",
     "@nuxt/module-builder": "^1.0.2",
     "@nuxt/schema": "4.2.2",
-    "@nuxt/test-utils": "^3.21.0",
-    "@types/node": "^25.0.3",
+    "@nuxt/test-utils": "^3.23.0",
+    "@types/node": "^25.0.9",
     "nuxt": "4.2.2",
-    "vitest": "^4.0.16",
-    "vue-tsc": "^3.2.1"
+    "vitest": "^4.0.17",
+    "vue-tsc": "^3.2.2"
   },
   "peerDependencies": {
     "nuxt": "^4.0.0"