@lewebsimple/nuxt-graphql 0.6.11 → 0.6.12

package/README.md

@@ -287,21 +287,75 @@ const { data } = await useAsyncGraphQLQuery("HelloWorld", undefined, {
 });
 ```
 
-#### Manual invalidation
+#### Cache manipulation
 
-On the client, `useGraphQLCache()` can invalidate in-memory and persisted entries:
+On the client, `useGraphQLCache()` provides helpers to read, write, update, and invalidate cache entries:
 
 ```ts
-const { invalidate } = useGraphQLCache();
+const cache = useGraphQLCache();
 
-// Invalidate a single entry (operation + variables)
-await invalidate({ operation: "HelloWorld", variables: {} });
+// Read cached query (in-memory only)
+const films = cache.read("AllFilms", {});
 
-// Invalidate all entries for an operation
-await invalidate({ operation: "HelloWorld" });
+// Write cached query synchronously (in-memory only, useful for rollbacks)
+cache.write("AllFilms", {}, newValue);
+cache.write("AllFilms", {}, (current) => ({ ...current, films: [...current.films, newFilm] }));
 
-// Invalidate all entries
-await invalidate();
+// Update cached query asynchronously (in-memory + persisted)
+await cache.update("AllFilms", {}, newValue);
+await cache.update("AllFilms", {}, (current) => ({ ...current, films: [...current.films, newFilm] }));
+
+// Invalidate cache entries
+await cache.invalidate("HelloWorld", {});  // Exact match (operation + variables)
+await cache.invalidate("HelloWorld");      // All entries for operation
+await cache.invalidate();                  // All entries
+```
+
+> **⚠️ Important:** Cache manipulation methods (`read`, `write`, `update`, `invalidate`) are incompatible with the `transform` option on `useAsyncGraphQLQuery`. If you need to use cache invalidation or manipulation, do not use the `transform` option. Instead, transform the data after retrieving it from the composable.
+
+#### Optimistic updates
+
+`useGraphQLMutation` supports optimistic updates via lifecycle hooks:
+
+```ts
+const { mutate } = useGraphQLMutation("AddFilm", {
+  onMutate: async (variables) => {
+    const cache = useGraphQLCache();
+    
+    // Snapshot current value for rollback
+    const snapshot = cache.read("AllFilms", {});
+    
+    // Optimistically update cache
+    await cache.update("AllFilms", {}, (current) => ({
+      films: [...(current?.films ?? []), { id: 'temp', title: variables.title }]
+    }));
+    
+    return { snapshot };
+  },
+  
+  onError: (error, variables, context) => {
+    const cache = useGraphQLCache();
+    // Rollback on error (sync for instant UI update)
+    if (context?.snapshot) {
+      cache.write("AllFilms", {}, context.snapshot);
+    }
+  },
+  
+  onSuccess: (data, variables, context) => {
+    // Replace optimistic temp ID with real ID from server
+    const cache = useGraphQLCache();
+    cache.update("AllFilms", {}, (current) => ({
+      films: current?.films.map(f => f.id === 'temp' ? data.addFilm : f) ?? []
+    }));
+  },
+  
+  onSettled: (result, variables, context) => {
+    // Always runs after mutation (success or error)
+    console.log('Mutation completed');
+  }
+});
+
+const result = await mutate({ title: "New Film" });
 ```
 
 

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@lewebsimple/nuxt-graphql",
   "configKey": "graphql",
-  "version": "0.6.11",
+  "version": "0.6.12",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -203,7 +203,7 @@ function addUniversalTemplate({ filename, getContents, emitTs }) {
   return modulePath;
 }
 
-const version = "0.6.11";
+const version = "0.6.12";
 
 async function getDocuments(documentsGlob) {
   try {

package/dist/runtime/app/composables/useGraphQLCache.client.d.ts

@@ -1,13 +1,14 @@
-import type { QueryName } from "#graphql/registry";
+import type { QueryName, ResultOf, VariablesOf } from "#graphql/registry";
+import type { IsEmptyObject } from "../../shared/lib/types.js";
 /**
  * GraphQL cache helper composable.
  *
- * @returns Cache config and invalidation helper.
+ * @returns Cache manipulation helpers.
  */
 export declare function useGraphQLCache(): {
-    readonly cacheConfig: any;
-    readonly invalidate: (options?: {
-        operation: QueryName;
-        variables?: unknown;
-    }) => Promise<void>;
+    readonly cacheConfig: import("../../shared/lib/types.js").CacheConfig;
+    readonly read: <TName extends QueryName>(operation: TName, ...args: IsEmptyObject<VariablesOf<TName>> extends true ? [variables?: VariablesOf<TName>] : [variables: VariablesOf<TName>]) => ResultOf<TName> | undefined;
+    readonly write: <TName extends QueryName>(operation: TName, variables: VariablesOf<TName>, value: ResultOf<TName> | ((current: ResultOf<TName> | undefined) => ResultOf<TName>)) => void;
+    readonly update: <TName extends QueryName>(operation: TName, variables: VariablesOf<TName>, value: ResultOf<TName> | ((current: ResultOf<TName> | undefined) => ResultOf<TName>)) => Promise<void>;
+    readonly invalidate: <TName extends QueryName>(operation?: TName | undefined, variables?: VariablesOf<TName> | undefined) => Promise<void>;
 };

package/dist/runtime/app/composables/useGraphQLCache.client.js

@@ -1,17 +1,40 @@
-import { clearNuxtData, useRuntimeConfig } from "#imports";
+import { clearNuxtData, useNuxtData, useRuntimeConfig } from "#imports";
 import { getCacheKeyParts } from "../lib/cache.js";
-import { deletePersistedByPrefix, deletePersistedEntry } from "../lib/persisted.js";
+import { deletePersistedByPrefix, deletePersistedEntry, getPersistedEntry, setPersistedEntry } from "../lib/persisted.js";
 export function useGraphQLCache() {
   const { public: { graphql: { cacheConfig } } } = useRuntimeConfig();
-  async function invalidate(options) {
-    if (!options) {
+  function read(operation, ...args) {
+    const [variables] = args;
+    const { key } = getCacheKeyParts(cacheConfig, operation, variables ?? {});
+    const nuxtData = useNuxtData(key);
+    return nuxtData.data.value;
+  }
+  function write(operation, variables, value) {
+    const { key } = getCacheKeyParts(cacheConfig, operation, variables);
+    const nuxtData = useNuxtData(key);
+    nuxtData.data.value = typeof value === "function" ? value(nuxtData.data.value) : value;
+  }
+  async function update(operation, variables, value) {
+    const { key } = getCacheKeyParts(cacheConfig, operation, variables);
+    const nuxtData = useNuxtData(key);
+    let current = nuxtData.data.value;
+    if (current === void 0 && cacheConfig.ttl !== void 0) {
+      current = await getPersistedEntry(key);
+    }
+    const updated = typeof value === "function" ? value(current) : value;
+    nuxtData.data.value = updated;
+    if (cacheConfig.ttl !== void 0) {
+      await setPersistedEntry(key, updated, cacheConfig.ttl);
+    }
+  }
+  async function invalidate(operation, variables) {
+    if (operation === void 0) {
       const { keyPrefix, keyVersion } = cacheConfig;
       const prefix = `${keyPrefix}:${keyVersion}:`;
       clearNuxtData((k) => k.startsWith(prefix));
       await deletePersistedByPrefix(prefix);
       return;
     }
-    const { operation, variables } = options;
     if (variables === void 0) {
       const { opPrefix } = getCacheKeyParts(cacheConfig, operation, {});
       clearNuxtData((k) => k.startsWith(opPrefix));
@@ -22,5 +45,5 @@ export function useGraphQLCache() {
     clearNuxtData(key);
     await deletePersistedEntry(key);
   }
-  return { cacheConfig, invalidate };
+  return { cacheConfig, read, write, update, invalidate };
 }

package/dist/runtime/app/composables/useGraphQLLoadMore.d.ts

@@ -10,8 +10,8 @@ type Connection<TItem> = {
 };
 export declare function useGraphQLLoadMore<TQueryName extends QueryName, TConnection extends Connection<unknown>>(queryName: TQueryName, inputVars: MaybeRef<Omit<VariablesOf<TQueryName>, "after">>, getConnection: (data?: ResultOf<TQueryName>) => TConnection | undefined): Promise<{
     items: Ref<TConnection["nodes"][number][], TConnection["nodes"][number][]>;
-    pending: any;
-    error: any;
+    pending: Ref<boolean, boolean>;
+    error: Ref<import("../../shared/lib/error.js").NormalizedError | undefined, import("../../shared/lib/error.js").NormalizedError | undefined>;
     reset: (clearProducts?: boolean) => void;
     hasNextPage: ComputedRef<boolean>;
     isLoadingMore: Ref<boolean, boolean>;

package/dist/runtime/app/composables/useGraphQLMutation.d.ts

@@ -1,6 +1,57 @@
 import type { MutationName, ResultOf, VariablesOf } from "#graphql/registry";
 import type { ExecuteGraphQLResult, IsEmptyObject } from "../../shared/lib/types.js";
-export declare function useGraphQLMutation<TName extends MutationName>(operationName: TName): {
+import { type NormalizedError } from "../../shared/lib/error.js";
+/**
+ * Mutation lifecycle hooks for optimistic updates and cache manipulation.
+ *
+ * @template TName Mutation operation name.
+ * @template TContext Type of context returned by onMutate and passed to other hooks.
+ */
+export type MutationOptions<TName extends MutationName, TContext = unknown> = {
+    /**
+     * Callback invoked before the mutation executes.
+     * Use for optimistic updates. Return value is passed as context to other hooks.
+     *
+     * @param variables Mutation variables.
+     * @returns Context object for onSuccess/onError/onSettled hooks.
+     */
+    onMutate?: (variables: VariablesOf<TName>) => TContext | Promise<TContext>;
+    /**
+     * Callback invoked when the mutation succeeds.
+     *
+     * @param data Mutation result data.
+     * @param variables Mutation variables.
+     * @param context Context returned from onMutate (undefined if onMutate not provided or threw).
+     */
+    onSuccess?: (data: ResultOf<TName>, variables: VariablesOf<TName>, context: TContext | undefined) => void;
+    /**
+     * Callback invoked when the mutation fails.
+     * Use for rolling back optimistic updates.
+     *
+     * @param error Normalized error.
+     * @param variables Mutation variables.
+     * @param context Context returned from onMutate (undefined if onMutate not provided or threw).
+     */
+    onError?: (error: NormalizedError, variables: VariablesOf<TName>, context: TContext | undefined) => void;
+    /**
+     * Callback invoked when the mutation completes (success or error).
+     *
+     * @param result Mutation result (data or error).
+     * @param variables Mutation variables.
+     * @param context Context returned from onMutate (undefined if onMutate not provided or threw).
+     */
+    onSettled?: (result: ExecuteGraphQLResult<ResultOf<TName>>, variables: VariablesOf<TName>, context: TContext | undefined) => void;
+};
+/**
+ * GraphQL mutation composable with lifecycle hooks for optimistic updates.
+ *
+ * @template TName Mutation operation name.
+ * @template TContext Type of context returned by onMutate and passed to other hooks.
+ * @param operationName Mutation operation name.
+ * @param options Optional mutation lifecycle hooks.
+ * @returns Mutation state and mutate function.
+ */
+export declare function useGraphQLMutation<TName extends MutationName, TContext = unknown>(operationName: TName, options?: MutationOptions<TName, TContext>): {
     pending: import("vue").Ref<boolean, boolean>;
     mutate: (...args: IsEmptyObject<VariablesOf<TName>> extends true ? [variables?: VariablesOf<TName>] : [variables: VariablesOf<TName>]) => Promise<ExecuteGraphQLResult<ResultOf<TName>>>;
 };

package/dist/runtime/app/composables/useGraphQLMutation.js

@@ -1,20 +1,42 @@
 import { useNuxtApp } from "#app";
 import { ref } from "vue";
 import { getOperationDocument } from "../../shared/lib/registry.js";
-export function useGraphQLMutation(operationName) {
+import { normalizeError } from "../../shared/lib/error.js";
+export function useGraphQLMutation(operationName, options) {
   const { $executeGraphQL } = useNuxtApp();
   const document = getOperationDocument(operationName);
   const pending = ref(false);
   async function mutate(...args) {
     const [variables] = args;
+    let context;
+    if (options?.onMutate) {
+      try {
+        context = await options.onMutate(variables);
+      } catch (error) {
+        const normalizedError = normalizeError(error);
+        options?.onError?.(normalizedError, variables, context);
+        return { data: null, error: normalizedError };
+      }
+    }
     pending.value = true;
     try {
-      return await $executeGraphQL({ query: document, variables, operationName });
+      const result = await $executeGraphQL({ query: document, variables, operationName });
+      if (result.error) {
+        options?.onError?.(result.error, variables, context);
+      } else if (result.data) {
+        options?.onSuccess?.(result.data, variables, context);
+      }
+      options?.onSettled?.(result, variables, context);
+      return result;
+    } catch (error) {
+      const normalizedError = normalizeError(error);
+      const errorResult = { data: null, error: normalizedError };
+      options?.onError?.(normalizedError, variables, context);
+      options?.onSettled?.(errorResult, variables, context);
+      return errorResult;
     } finally {
       pending.value = false;
     }
   }
-  ;
   return { pending, mutate };
 }
-;

package/dist/runtime/app/plugins/execute-graphql.d.ts

@@ -1,5 +1,9 @@
 import type { ExecuteGraphQLInput, ExecuteGraphQLResult, GraphQLVariables } from "../../shared/lib/types.js";
-declare const _default: any;
+declare const _default: import("#app").Plugin<{
+    executeGraphQL: <TResult = unknown, TVariables extends GraphQLVariables = GraphQLVariables>({ query, variables, operationName }: ExecuteGraphQLInput<TVariables>) => Promise<ExecuteGraphQLResult<TResult>>;
+}> & import("#app").ObjectPlugin<{
+    executeGraphQL: <TResult = unknown, TVariables extends GraphQLVariables = GraphQLVariables>({ query, variables, operationName }: ExecuteGraphQLInput<TVariables>) => Promise<ExecuteGraphQLResult<TResult>>;
+}>;
 export default _default;
 type ExecuteGraphQL = <TResult = unknown, TVariables extends GraphQLVariables = GraphQLVariables>(input: ExecuteGraphQLInput<TVariables>) => Promise<ExecuteGraphQLResult<TResult>>;
 declare module "#app/nuxt" {

package/dist/runtime/app/plugins/graphql-sse.client.d.ts

@@ -4,7 +4,11 @@ import { type Client as SSEClient } from "graphql-sse";
  *
  * @returns Nuxt plugin with SSE client provider.
  */
-declare const _default: any;
+declare const _default: import("#app").Plugin<{
+    getGraphQLSSEClient: () => SSEClient;
+}> & import("#app").ObjectPlugin<{
+    getGraphQLSSEClient: () => SSEClient;
+}>;
 export default _default;
 declare module "#app/nuxt" {
     interface NuxtApp {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lewebsimple/nuxt-graphql",
-  "version": "0.6.11",
+  "version": "0.6.12",
   "description": "Opinionated Nuxt module for using GraphQL",
   "repository": "lewebsimple/nuxt-graphql",
   "license": "AGPL-3.0-only",
@@ -33,7 +33,7 @@
     "@graphql-tools/graphql-file-loader": "^8.1.9",
     "@graphql-tools/load": "^8.1.8",
     "@graphql-tools/schema": "^10.0.31",
-    "@graphql-tools/stitch": "^10.1.10",
+    "@graphql-tools/stitch": "^10.1.11",
     "@nuxt/kit": "^4.3.1",
     "defu": "^6.1.4",
     "graphql": "^16.12.0",
@@ -44,7 +44,7 @@
     "unstorage": "^1.17.4"
   },
   "devDependencies": {
-    "@nuxt/devtools": "^3.1.1",
+    "@nuxt/devtools": "^3.2.1",
     "@nuxt/eslint-config": "^1.15.1",
     "@nuxt/module-builder": "^1.0.2",
     "@nuxt/schema": "^4.3.1",