How to deal with contextual and non serizalizable query key ?

[stevebeauge]

I'm working on a project requiring some custom HTTP client to fetch API data. The project is actually a plugin of a 3rd party application that injects the plugin using a DOM node and a render method. The render method get a custom http client as parameter. There's no "global" object I can use to get such http client.
This works well, but it breaks react query dependency array check, because the class is not serializable (cyclic dependency).

I created a code sandbox repro to illustrate:

https://codesandbox.io/s/thirsty-shamir-p4y89x?file=/src/App.tsx

Both query client and custom Http client are provider to the react tree using context providers:

export default function App() {
  return (
    <CustHttpClientProvider value={customHttpClient}>
      <QueryClientProvider client={queryClient}>
          .....
      </QueryClientProvider>
    </CustHttpClientProvider>
  );
}

This allows me to write component that requires both context objects:

const UserInfoKO: React.FC<{ userId: number }> = ({ userId }) => {
  const httpClient = useCustHttpClient();
  const { data, status } = useQuery({
    queryKey: ["userInfo", userId, httpClient], // <=== My custom http client is a dependency
    queryFn: () => api(httpClient, userId)
  });

  return (
    <div>
      {status}: {data}
    </div>
  );
};

But this code fails because the httpClient variable cannot be serialized : TypeError: cyclic object value.

If I don't put this variable in the dependency array, the code runs but the eslint rule yell because of the missing dependency (this can be removed, but it may hide also other dependency miss.

I can trick react query using something like:

  const httpClient = useCustHttpClient();
  const apiWithClient = api.bind(null, httpClient); // <== the trick is there, 
  const { data, status } = useQuery({
    queryKey: ["userInfo", userId],
    queryFn: () => apiWithClient(userId)
  });

this works at runtime, eslint rule is doing its job because the argument is out of the query function. But this requires a lot more non obvious code to add everytime an API is required.

Is there any proper way to handle such situation ?

Is there any way to "extend" the query client with arbitrary data ? Something like a custom "context" that may be set to query client ?

thanks for advise!

[stevebeauge]

Some explorations later, I have found the "meta" option of the useQuery hook

const UserInfoOK3: React.FC<{ userId: number }> = ({ userId }) => {
  const httpClient = useCustHttpClient();
  const { data, status } = useQuery({
    queryKey: ["userInfo", userId],
    queryFn: ({ meta }: { meta: WithHttpClientMeta }) =>
      api(meta.httpClient, userId),
    meta: {
      httpClient
    }
  });

  return (
    <div>
      {status}: {data}
    </div>
  );
};

There's no, however, strong typing of the meta object, neither isolation.

[stevebeauge]

I confirm @TkDodo's answer. Since my initial post, I've succeed in building react query production apps that requires some weird 3rd party objects in my async code.

My global query client is built like this:

const customQueryClient = new QueryClient({
    defaultOptions: {
        queries: {
            refetchOnWindowFocus: false,
            retry: false,
            queryKeyHashFn: queryKeyHashFnCustom,
        },
    },
});

which defaults query key hash to a custom one. This function is similar to:

const queryKeyHashFnCustom: QueryKeyHashFunction<QueryKey> = (key) => {
    const fixKeys = key.map((k) => {
        if (k instanceof WeirdType1) {
            return getNonSerializableUID(k);
        }
        if (k instanceof WeirdType2) {
            return k.instanceId;
        }
        if (hasQueryQueryKeyHashFn(k)) {
            return k.getQueryKeyHash();
        }
        if (queryKeyShouldUseWeakMap(k)) {
            return getNonSerializableUID(k);
        }
        return k;
    });
    return hashQueryKey(fixKeys);
};

// Store every non serializable object in a WeakMap, associated with a unique id.
const instanceMap = new WeakMap<object, string>();
function getNonSerializableUID(k: object): string {
    if (!instanceMap.has(k)) {
        const id = crypto.randomUUID();
        instanceMap.set(k, id);
    }

    return notnull(instanceMap.get(k));
}

Basically, the code will test if key is of type of some specific and non serializable classes, generate a random ID and store it inside a weak map (to avoid memory leak). This is useful for 3rd party classes I cannot extends.

I also test for some other type, also from 3rd party lib I cannot change, and use one of its property to get a uniqueID, and use this id to serialize the key.

Finally, for my own types, where internal implementation make the object non serializable, I define some interface I can implement to provide a custom key for the object. Here's the implementation of the typescript type guards:

interface IHasQueryQueryKeyHashFn {
    getQueryKeyHash: () => string;
}

const hasQueryQueryKeyHashFn = (obj: unknown): obj is IHasQueryQueryKeyHashFn => {
    return (
        typeof obj === "object" &&
        obj !== null &&
        "getQueryKeyHash" in obj &&
        typeof (obj as IHasQueryQueryKeyHashFn).getQueryKeyHash === "function"
    );
};

// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
interface IQueryKeyShouldUseWeakMap {
    useWeakMap: boolean;
}

const queryKeyShouldUseWeakMap = (obj: unknown): obj is IQueryKeyShouldUseWeakMap => {
    return (
        typeof obj === "object" &&
        obj !== null &&
        "useWeakMap" in obj &&
        typeof (obj as IQueryKeyShouldUseWeakMap).useWeakMap === "boolean"
    );
};

If I know a type won't work in the OOB query fn, I can implement either of the two interfaces, wheter I have some unique value, or if I need a week map:

abstract class BaseService implements IQueryKeyShouldUseWeakMap {
    protected readonly context: WeirdType;
    protected readonly webUrl: string;

    constructor(context: WeirdType, webUrl = context.pageContext.web.absoluteUrl) {
        this.context = context;
        this.webUrl = webUrl;
    }
    public readonly useWeakMap = true;
}

Ultimately, if none of the tests is satisfied, I let the react query native hash function handle the serialization.

[UNLRN]

So I'm not really sure how something can be passed to the queryFn that is stable but still comes from a hook and also doesn't affect the underlying fetch call at all. What would that be?

There are utilities that are unrelated to fetching, like helpers that wrap libs/browser apis or just provide metadata of the current running env. But what goes on inside an API function that receives the utilities is sometimes more than just calling utilities.fetch so the whole utilities object gets passed instead of just utilities.fetch 😅

The ideal for me is to limit the surface area that would be impacted by migrating to react-query. Hiding some implementation details so that our developers can use react-query hooks as vanilla as possible without us adding our own abstractions over the hooks would be my preference, which is why I'm exploring options. If we can continue passing the whole utilities object and just serialize it properly, that's one option. But if we end up needing to pull items off utilities and pass them, there are some things that aren't relevant to the queryKey that we could just ignore.

Regardless, we still have to handle serialization, so at least having the queryKeyHashFn at the global level will be useful.

@stevebeauge thanks for the code samples. It will be helpful to use this as a reference when we implement something similar.

[stevebeauge]

Side note : my code is for v4 (can't use react 18)
Maybe v5 has some change or improvement that can help

[TkDodo]

There are utilities that are unrelated to fetching, like helpers that wrap libs/browser apis or just provide metadata of the current running env. But what goes on inside an API function that receives the utilities is sometimes more than just calling utilities.fetch so the whole utilities object gets passed instead of just utilities.fetch 😅

sure, but again, if they are stable, there is no need for them to be a hook that lives inside the react component tree. If it e.g. contains the BASE_URL env that is either localhost or your deployed url - why would that be a hook?

[jlowcs]

Adding some context over a year later:

Yes, utilities is stable, but across a render. For instance, client-side, it is created once at bootstrap and never modified, so it is stable, and could in theory be a global variable.

The issue is that we're using that utilities object on the server too (SSR). On the server, we can generate multiple pages in parallel for which utilities would not be the same. So, even though it is stable within a single render, it cannot be global, otherwise that would cause collisions. That is why it is retrieved through a hook even though it is considered stable client-side.

[stevebeauge]

Sorry for the long delay. To conclude, I followed your suggestion to implement queryKeyHashFn. I use this code:

import { hashQueryKey, useQuery } from "@tanstack/react-query";
...
...
    const { data } = useQuery({
        queryKey: ["data", serviceScope, config],
        queryKeyHashFn: (key) => {
            const fixKeys = key.map((k) => {
                if (k instanceof ServiceScope) {
                    return serviceScope.id.toString();
                } else {
                    return k;
                }
            });
            return hashQueryKey(fixKeys);
        },
        queryFn: () => {
            return getData({ serviceScope, config  });
        },
    });

This way, I keep the original hashQueryKey, but I hook the non serializable type to extract some internal ID.

Thanks for the suggestion !