Executing a mutation in offline mode with optimistic configuration enabled hangs the UI when I await the promise

[fuintis]

Hi everyone:

I tried many options to fix this issue. I asked many IAs for help to solve this issue, and none of the offered solutions solve the problem. The usecase is very simple:
I have a very simple vue2 prototype web app (i know, soon i will update to vue3, but not yet) to handle a very specific requirement: Get the immediate result of the mutation that inserts or updates an item inside a list. Because the package "@urql/vue" only supports vue3, with the help of IA i handcrafted two composables compatible with vue2. This functions uses the wonka's stream API for reactivity, This approach avoids that front hangs awaiting the promise to solve against backend. The useQuery one works like a charm: When i inserts a new document, the list is updated with the new data, but i need to await the mutation because the response is used to display the new data in a summary screen that i develop. all works fine, but when the app is in offline mode, the awaits of mutation hangs until the app is online again. Here the code of the composables, the client configuration and the vue2 component:

This is a temporary version of the composables "fixed" by the IA trying to solve the issue, but nothing happens

/**
 * @description Corrected composables for offline-first URQL usage in Vue 2.
 * The useMutation composable is updated to prevent hanging in offline mode and to properly unsubscribe.
 * The subscribe method is now compatible with @urql/core v5.2.
 */
import { TypedDocumentNode } from '@graphql-typed-document-node/core';
import { AnyVariables, OperationContext, OperationResult, CombinedError, Client } from '@urql/core';
import { inject, InjectionKey, Ref, isRef, ref, computed, watch, onUnmounted } from 'vue';
import { nopMap } from '@afz/base-library';

export const urqlClientKey: InjectionKey<Client> = Symbol('urqlClient');

const watchOptions = { deep: true, immediate: true } as const;

// No changes needed for useQuery, it is included for completeness.
export function useQuery<Data, Variables extends AnyVariables>(
  query: TypedDocumentNode<Data, Variables>,
  variables?: Ref<Variables> | Variables,
  pause?: Ref<boolean> | boolean,
  context?: Ref<Partial<OperationContext>> | Partial<OperationContext>,
) {
  const client = inject(urqlClientKey) as Client;
  if (!client) {
    throw new Error('UrqlClient no disponible');
  }

  const data = ref<Data>();
  const fetching = ref(false) as Ref<boolean>;
  const error = ref<CombinedError>();
  const isPaused = computed(() => (isRef(pause) ? pause.value : !!pause));

  let subscription: { unsubscribe: () => void } | undefined;

  function executeQuery(awaited?: false): void;
  function executeQuery(awaited: true, inVars?: Variables): Promise<OperationResult<Data, Variables>>;
  function executeQuery(awaited?: boolean, inVars?: Variables): Promise<OperationResult<Data, Variables>> | void {
    const vars = inVars ?? (isRef<Variables>(variables) ? variables.value : variables) ?? (nopMap as Variables);

    if (awaited) {
      fetching.value = true;
      return client
        .query<Data, Variables>(query, vars, isRef(context) ? context.value : context)
        .toPromise()
        .then(function (result) {
          data.value = result.data;
          error.value = result.error;
          fetching.value = false;
          return result;
        });
    }

    if (isPaused.value) {
      return;
    }

    if (subscription) {
      subscription.unsubscribe();
    }

    fetching.value = true;
    subscription = client
      .query<Data, Variables>(query, vars, isRef(context) ? context.value : context)
      .subscribe(function (result) {
        data.value = result.data;
        error.value = result.error;
        fetching.value = false;
      });
  }

  watch(
    [() => (isRef(variables) ? variables.value : variables), isPaused],
    function (): void {
      executeQuery();
    },
    watchOptions,
  );

  onUnmounted(function (): void {
    if (subscription) {
      subscription.unsubscribe();
    }
  });

  return { data, fetching, error, executeQuery };
}

/**
 * MODIFIED useMutation
 * This version uses .subscribe() instead of .toPromise() to handle offline mutations gracefully.
 * It returns a promise that resolves with the first result (e.g., an optimistic update),
 * preventing the app from hanging while offline.
 * It now also correctly unsubscribes after the first result is received to prevent memory leaks.
 * The subscribe method signature has been updated for compatibility with older urql versions.
 */
export function useMutation<Data, Variables extends AnyVariables>(mutation: TypedDocumentNode<Data, Variables>) {
  const client = inject(urqlClientKey) as Client;
  if (!client) {
    throw new Error('UrqlClient no disponible');
  }

  const data = ref<Data>();
  const fetching = ref(false) as Ref<boolean>;
  const error = ref<CombinedError>();

  function executeMutation(
    variables: Variables,
    isOnline: { value: boolean },
    context?: Ref<Partial<OperationContext>> | Partial<OperationContext>,
  ): Promise<OperationResult<Data, Variables>> {
    fetching.value = true;
    error.value = undefined;

    return new Promise<OperationResult<Data, Variables>>(function (resolve, reject) {
      let resolved = false;

      const sub = client
        .mutation<Data, Variables>(mutation, variables, isRef(context) ? context.value : context)
        .subscribe(function (result) {
          data.value = result.data;
          error.value = result.error;

          // Handle optimistic response (offline case)
          if (result.stale && !isOnline.value) {
            fetching.value = false;
            resolve(result); // Resolve immediately with optimistic data
            resolved = true;
          }

          // Handle final response
          if (!result.stale) {
            fetching.value = false;
            if (!resolved) {
              if (result.error) reject(result.error);
              else resolve(result);
            }
            sub?.unsubscribe();
          }
        });
    });
  }

  return { data, fetching, error, executeMutation };
}

This is the client configuration, also modified by the IA to track the posible errors in the updates an optimistic props:

/**
 * @description Debugging version of the urql cacheConfig. The multiSort call has been
 * commented out to isolate the cause of the hang.
 */
/* eslint-disable */
import { ClientOptions, fetchExchange, createClient } from '@urql/core';
import { offlineExchange } from '@urql/exchange-graphcache';
import { DefaultStorage, makeDefaultStorage } from '@urql/exchange-graphcache/default-storage';
import { Empty, AnyKey, nopList, createUuid } from '@afz/base-library';
import { SortBy } from '@afz/base-store';
import { EventEvent, GetEventEventsQueryVariables } from './gen/graphql.js';
import { GraphCacheConfig } from './gen/urql-graphcache.js';
import { default as schema } from './gen/schema.json';
import { getEventsQuery, findEventFragment } from './operations.js';

type TypeHint = 'date' | 'int' | true;

type FieldSpecs = {
  type: TypeHint;
  path: string;
};

type SortMap = Record<string, FieldSpecs | TypeHint>;

function getValue<Type, Return>(map: Type, path: AnyKey): Return {
  return path
    .toString()
    .split('.')
    .reduce((subMap, key) => subMap?.[key as keyof Type] as Type, map) as unknown as Return;
}

export function multiSort<Type, Map extends SortMap>(
  map: SortMap,
  items: Type[],
  sortBy: (SortBy<Exclude<keyof Map, number | symbol>> & string)[] | Empty,
): Type[] {
  // IMPORTANT: This uses .sort() which mutates the array. For immutable updates,
  // it should be changed to `[...items].sort(...)`
  return items.sort((a, b) => {
    for (const criterion of sortBy || nopList) {
      const key = criterion.endsWith('Desc')
        ? (criterion.slice(0, -4) as unknown as keyof Type)
        : (criterion as unknown as keyof Type);
      const direction = criterion.endsWith('Desc') ? -1 : 1;

      let aValue;
      let bValue;
      const fType = (map[key as keyof SortMap] as FieldSpecs)?.type || map[key as keyof SortMap];
      const fPath = (map[key as keyof SortMap] as FieldSpecs)?.path || key;
      const aRaw: string = getValue(a, fPath);
      const bRaw: string = getValue(b, fPath);

      if (fType === 'date') {
        aValue = aRaw ? new Date(aRaw).getTime() : aRaw;
        bValue = bRaw ? new Date(bRaw).getTime() : bRaw;
      } else if (fType === 'int') {
        aValue = aRaw ? parseInt(aRaw, 10) : aRaw;
      } else {
        aValue = aRaw;
        bValue = bRaw;
      }

      let comparison = 0;
      if (aValue === null || aValue === undefined) {
        comparison = -1;
      } else if (bValue === null || bValue === undefined) {
        comparison = 1;
      } else if (aValue < bValue) {
        comparison = -1;
      } else if (aValue > bValue) {
        comparison = 1;
      }

      if (comparison !== 0) {
        return comparison * direction;
      }
    }

    return 0;
  });
}

const sortMap = { createdAt: 'date' } as const;

const cacheConfig: GraphCacheConfig & { storage: DefaultStorage } = {
  storage: makeDefaultStorage({
    idbName: 'vue-offline-app-cache',
    maxAge: 7,
  }),
  schema,
  updates: {
    Mutation: {
      eventSaveEvent(result, _, cache) {
        try {
          const input = result.eventSaveEvent;
          if (!input?.id) {
            return;
          }

          const allQueries = cache.inspectFields('Query').filter((field) => field.fieldName === 'eventEvents');
          allQueries.forEach(function (field) {
            const variables = field.arguments as GetEventEventsQueryVariables;
            cache.updateQuery(
              {
                query: getEventsQuery,
                variables,
              },
              function (data) {
                if (!data?.eventEvents) {
                  return data;
                }

                const existingEvents = data.eventEvents;
                const eventExists = existingEvents.some((item) => item.id === input.id);

                let updatedEvents;
                if (eventExists) {
                  // Update existing item: create a new array using map
                  updatedEvents = existingEvents.map((event) =>
                    event.id === input.id ? (input as EventEvent) : event,
                  );
                } else {
                  // Add new item: create a new array by concatenating
                  updatedEvents = [...existingEvents, input as EventEvent];
                }

                // Return a new data object with the new events array
                return { ...data, eventEvents: updatedEvents };
              },
            );
          });
        } catch (e) {
          console.error('URQL Error in updates.eventSaveEvent:', e);
        }
      },
    },
  },
  optimistic: {
    eventSaveEvent({ input }, cache) {
      try {
        const cached = input.id
          ? cache.readFragment(findEventFragment, { id: input.id, __typename: 'EventEvent' })
          : null;

        const optimisticResponse = {
          __typename: 'EventEvent',
          id: input.id || createUuid(),
          type: {
            __typename: 'EventEventType',
            id: input.type?.id,
            code: '__PRUEBA__',
            createdAt: new Date().toISOString(),
            description: '__PRUEBA__',
            isDeleted: false,
            isDisabled: false,
            updatedAt: new Date().toISOString(),
          },
          data: input.data ?? {},
          parent: null,
          metadata: {},
          indexMap: {},
          isPersistent: input.isPersistent ?? true,
          createdAt: cached?.createdAt ?? new Date().toISOString(),
          createdBy: null,
          isDisabled: false,
        };

        return optimisticResponse;
      } catch (e) {
        console.error('URQL Error in optimistic.eventSaveEvent:', e);
        return {} as EventEvent;
      }
    },
  },
};

const clientOptions: ClientOptions = {
  url: 'https://dev.currant.cl/api/graphql',
  exchanges: [offlineExchange(cacheConfig), fetchExchange],
  requestPolicy: 'cache-and-network',
};

export const urqlClient = createClient(clientOptions);

Finally, the vue2 component:

<template>
  <div class="form-container">
    <form @submit.prevent="handleSubmit">
      <h2>{{ isEditing ? 'Edit Event' : 'Create New Event' }}</h2>
      <div class="form-group">
        <label for="event-details">Event Details:</label>
        <input
          id="event-details"
          v-model="formState.data.details"
          type="text"
          placeholder="e.g., Project kickoff meeting"
          required
        />
      </div>
      <div class="form-group">
        <label for="event-type">Event Type:</label>
        <select id="event-type" v-model="formState.type.id" required>
          <option disabled value="">Please select one</option>
          <option value="018eba81-1e95-7181-84dd-49afde897c91">InvItemBatchSynced</option>
          <option value="018d8676-6020-7dc5-bd66-ade83bd8d1b8">InvTransactionBatchSynced</option>
          <option value="018d861a-30d1-77dc-a843-47be011169ca">FarmWorkTeamFormBatchSynced</option>
        </select>
      </div>
      <div class="form-actions">
        <button type="submit" :disabled="isSaving">
          {{ isSaving ? 'Saving...' : 'Save Event' }}
        </button>
        <button type="button" class="cancel-button" @click="$emit('close')">Cancel</button>
      </div>
      <p v-if="mutationError" class="error-message">An error occurred: {{ mutationError.message }}</p>
    </form>
  </div>
</template>

<script setup lang="ts">
import { ref, watch, computed } from 'vue';
import { DeepPartial } from '@afz/base-library';
import { useMutation } from '@afz/app-clientgql';
import { connState } from './base.js';
import { saveEventMutation } from './gql/operations.js';
import { EventEvent, EventEventCarrier } from './gql/gen/graphql.js';

const props = defineProps<{ eventToEdit?: DeepPartial<EventEvent> | null }>();
const emit = defineEmits(['submitted', 'close']);

const saveMutation = useMutation(saveEventMutation);
const isSaving = computed(() => saveMutation.fetching.value);
const mutationError = computed(() => saveMutation.error.value);

const isEditing = computed(() => !!props.eventToEdit);

const createDefaultFormState = () => ({
  id: undefined as string | undefined,
  type: { id: '' },
  data: { details: '' },
});

const formState = ref(createDefaultFormState());

watch(
  () => props.eventToEdit,
  (newEvent) => {
    if (newEvent) {
      formState.value = {
        id: newEvent.id,
        type: { id: newEvent.type?.id || '' },
        data: { details: (newEvent.data?.details as string) || '' },
      };
    } else {
      formState.value = createDefaultFormState();
    }
  },
  { immediate: true },
);

const handleSubmit = async () => {
  const input: EventEventCarrier = {
    id: formState.value.id,
    type: { id: formState.value.type.id },
    data: formState.value.data,
  };

  await saveMutation.executeMutation({ input }, connState.isOnline); // this await hangs the app until is online again
  emit('submitted');
};
</script>

<style scoped>
.form-container {
  background-color: #f9f9f9;
  padding: 2rem;
  border-radius: 8px;
  box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1);
  max-width: 500px;
  margin: 2rem auto;
}

.form-group {
  margin-bottom: 1.5rem;
}

.form-group label {
  display: block;
  margin-bottom: 0.5rem;
  font-weight: bold;
  color: #333;
}

.form-group input,
.form-group select {
  width: 100%;
  padding: 0.75rem;
  border: 1px solid #ccc;
  border-radius: 4px;
  box-sizing: border-box;
}

.form-actions {
  display: flex;
  justify-content: flex-end;
  gap: 1rem;
}

button {
  padding: 0.75rem 1.5rem;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  font-weight: bold;
  transition: background-color 0.2s;
}

button[type='submit'] {
  background-color: #4a90e2;
  color: white;
}

button[type='submit']:disabled {
  background-color: #a0c8f0;
  cursor: not-allowed;
}

button[type='submit']:hover:not(:disabled) {
  background-color: #357abd;
}

.cancel-button {
  background-color: #e0e0e0;
  color: #333;
}

.cancel-button:hover {
  background-color: #c7c7c7;
}

.error-message {
  color: #d9534f;
  margin-top: 1rem;
}
</style>

Any help will be very appreciate it.
Many thanks in advance.

[fuintis]

this is the Gemini PRO diagnosis. It sounds ok, but it makes no sense to me the part of "... blocks the optimistic result from ever being emitted...". Here an extract of the full response:

The Hang: This is the critical failure. The urql client now has conflicting signals. It has a successful optimistic update ready to go (Path A), but it also has a definitive network failure for the same operation (Path B). In this specific edge case, the immediate network error seems to take precedence or create an internal state that blocks the optimistic result from ever being emitted to your subscribe callback. The operation gets stuck in limbo—it hasn't fully failed in a way that would reject your promise, but it also can't proceed to resolve it with the optimistic data. It just hangs.

Why the network error takes precedence over the optimistic result?

[kitten]

Side-note, I've spotted that you used cache-and-network here. That kind of defeats the point of a normalised cache pretty frequently, so be careful with that.

tl;dr: graphcache isn't a full sync'ing offline, so there's trade-offs. Optimistic implies fire-and-forget.

---

Regarding the optimistic mutation, when you define an optimistic mutation result, Graphcache goes into a different "mode" for it, which is more similar to a fire-and-forget. This means that it expects that the mutation can silently fail. Basically, when you're offline, the mutation will be attempted, but there might not be a response.

When it is able to do a mutation that can silently fail, that means that it may hold on to the optimistic change indefinitetly. This directly conflicts with what you're trying to do.

When you have a confirmation screen that uses the result of the optimistic mutation, you're basically setting two expectations:

• I'd like this result to not always work (when I'm offline, since it's optimistic, I'd like to just move on)
• I'd like this result to always work (always resolve to give me a result; which it won't)

That's what Gemini actually spots pretty nicely, despite it saying this in a weird way:

It has a successful optimistic update ready to go (Path A), but it also has a definitive network failure for the same operation (Path B).

Basically, these two conditions are mutually exclusive! That's because we had to make decisions of what's more important, in this case:

• is it more important that the optimistic mutation "fakes" to succeed?
• or; is it more important that the optimistic mutation manipulates other states and that you won't get "fake" results?

Basically, the latter here is true in our perspective: A mutation that delivers a result to you shouldn't lie about where it came from i.e. it shouldn't give you your optimistic result, because mutations inform you about an actual change (side-effect) that happened. In other words, we don't resolve/deliver the "optimistic/fake" mutation result instead of a real one.

This is because that would defeat the point of being optimistic here. You've define an optimistic entry, so you know that you can create a "fake" result immediately, and we're trying to encourage you not to tell the user that it's succeeded when it couldn't have.

This basically gives you two options:

• don't use optimistic mutations for mutations that are "important" enough for you to display them to the user
• use the optimistic mutation, but fake the confirmation modal as well (worst case, maybe by making an equivalent modal for the confirmation screen)

To put this in a real example, imagine a social network. Our offline capability isn't a full-sync one, so that's usually the best example:

• liking a post is low stakes. The UI changes a little in response (the query updates for a list screen), and whether this succeeds or fails later won't matter. We can immediately tell the user this happened, even if they're offline.
• creating a post/reply is high stakes. We can't fake this, as when the user is offline this doesn't actually happen. It's not a good fit for optimistic mutations as the user definitely has signalled intent for this to be sent to the API.

In your case it's similar: if you want this to definitely succeed, don't tell the user it did. However, it does say "save". What you could do is to make sure to save the post outside of Graphcache/Offline and then have outside logic that acts as a fallback (e.g. a "Mail" app may mark an email as sent optimistically but have an "Outbox" where it shows mails being sent, even if that failed)

[kitten]

Before I forget, let me also point out the direct conflict that Gemini was attempting to describe:

• you've defined an optimistic mutation
• the mutation is being executed
• Graphcache applies the optimistic change for the mutation (OPT)
• the real mutation request is sent
• the request fails because you're offline, which triggers a network error
• because you have an optimistic mutation on the offlineExchange version of Graphcache it knows that it must not "undo/destroy" the optimistic version of the mutation (Created in OPT)
• So it puts the mutation on a failure queue and then keeps the optimistic change around. Hence, the network error cannot be observable and the mutation hasn't resolved yet

[fuintis]

Ok, I understand your point, but I don't get why the list of items is visibly updated in real time when I create a new item. So, the data is in there; the UI shows it. Can I query the cache for the newly created item by his ID (the ID field is a UUIDv7 created always by the app)? Doing this, I can fake the response from the backend, because the item is already in the list. Yes, I know that I need to notify the user that the response is a "temporary" one, but the functionality of the app remains the same.

[kitten]

Yes, basically, queries can transparently access the optimistic data. Mutations can't

[fuintis]

I can't access the recently created data by executing a query that tries to fetch it by id. I'm really lost here because any solution that I tried didn't work. I change the requestPolicy to 'cache-first', and it didn't work either. How can I query the data created offline? I don't want to change to another library, but make URQL work in offline mode is near to impossible. Anyone have any successful cases here?

[fuintis]

I managed to solve the problem, but now I need to apply sorting and filtering to the eventEvents query after storing a new event. Can the resolver linked to the eventEvents query be executed to use the same variables that the app employs when executing the query?

This is my updated client code:

import { ClientOptions, createClient, fetchExchange } from '@urql/core';
import { offlineExchange } from '@urql/exchange-graphcache';
import { makeDefaultStorage } from '@urql/exchange-graphcache/default-storage';
import { isBoolean, isArray, nopMap, createUuid } from '@afz/base-library';
import { OfflineExchangeOpts, sortAndSlice } from '@afz/app-clientgqlvue2';
import { EventEventFieldsFragment, GraphCacheConfig } from './gen/graphql.js';
import { default as schema } from './gen/schema.json';
import { findEventFragment, eventFieldsFragment } from './operations.js';

const sortMap = { createdAt: 'date' } as const;

const cacheConfig: GraphCacheConfig & OfflineExchangeOpts = {
  storage: makeDefaultStorage({
    idbName: 'vue-offline-app-cache',
    maxAge: 7,
  }),
  isOfflineError(error) {
    return !!error?.networkError;
  },
  schema,
  resolvers: {
    Query: {
      eventEvent(_, args) {
        return {
          __typename: 'EventEvent',
          id: args.id,
        };
      },
      eventEvents(_, args, cache) {
        const specs = args.specs ?? (nopMap as NonNullable<typeof args.specs>);
        const list: EventEventFieldsFragment[] = [];
        const deduper = new Set<string>();

        const queries = cache.inspectFields('Query');
        for (const query of queries) {
          if (query.fieldName !== 'eventEvents' && query.fieldName !== 'eventEvent') {
            continue;
          }

          const keys = cache.resolve({ __typename: 'Query', id: 'QUERY' }, query.fieldKey) as string[] | string | null;
          for (const key of isArray(keys) ? keys : [keys]) {
            if (key && !deduper.has(key)) {
              deduper.add(key);
              const data = cache.readFragment(eventFieldsFragment, key);
              if (data) {
                list.push(data);
              }
            }
          }
        }

        function filter(item: EventEventFieldsFragment) {
          if (isBoolean(specs.isDisabled) && item.isDisabled !== specs.isDisabled) {
            return false;
          }

          if (specs.typeIds?.length && !specs.typeIds.includes(item.type.id)) {
            return false;
          }

          if (specs.ids?.length && !specs.ids.includes(item.id)) {
            return false;
          }

          return true;
        }

        return sortAndSlice(sortMap, list.filter(filter), specs);
      },
    },
  },
  updates: {
    Query: {
      eventEvents(result) {
        console.log('[Query Updater] Network data received:', result);
      },
    },
    Mutation: {
      eventSaveEvent(result, _, cache) {
        if (result.eventSaveEvent) {
          cache.writeFragment(eventFieldsFragment, result.eventSaveEvent as EventEventFieldsFragment);
        }

        cache.invalidate('Query', 'eventEvents'); // This line was added by the IA, but without effect
      },
    },
  },
  optimistic: {
    eventSaveEvent({ input }, cache) {
      const cached = input.id
        ? cache.readFragment(findEventFragment, { __typename: 'EventEvent', id: input.id })
        : null;

      return {
        __typename: 'EventEvent',
        id: input.id || createUuid(),
        type: {
          __typename: 'EventEventType',
          id: input.type?.id,
        },
        data: input.data ?? {},
        parent: null,
        metadata: {},
        indexMap: {},
        isPersistent: input.isPersistent ?? true,
        createdAt: cached?.createdAt ?? new Date().toISOString(),
        isDisabled: false,
      };
    },
  },
};

const clientOptions: ClientOptions = {
  url: 'https://dev.currant.cl/api/graphql',
  exchanges: [offlineExchange(cacheConfig), fetchExchange],
  requestPolicy: 'cache-and-network',
};

export const urqlClient = createClient(clientOptions);