setQueryDefaults/getQueryDefaults and query defaults registration order

[GLabat]

We use setQueryDefaults/getQueryDefaults in our app to factorise and centralize query behaviours while keeping usage simple.
Once defaults are registered, the only thing we use is a key factory like:

const someKey = keyFactory.detail(someId)
return useQuery(someKey)

When using useQuery(key), internally a call to queryClient.getQueryDefaults(key) is performed to retrieve the query defaults associated with the key.

To be able to do that, we register defaults for our queries.
On some of our entities, we have several defaults, associated to different keys.
While implementing all this, we identify a behaviour which could be considered as WAD, but which triggers the discussion here, since it may also be considered as a bug.

The following CodeSandbox tries to illustrate the issue: https://codesandbox.io/s/nifty-ride-q3ln3?file=/src/index.js.

Please check the CodeSandbox before reading below.

The "problem" is the order of registration of query defaults.

After some code reading sessions, the behaviour is WAD in the sense that queryDefaults of QueryClient is an Array.
When registering some defaults, RQ looks for existing default with strict key matching and either replaces existing defaults (no order change) or push into an array.

Code extracted and commented from: https://github.com/tannerlinsley/react-query/blob/e7a3207f74b27bc112d6ab583831cceac60f94c5/src/core/queryClient.ts#L540

setQueryDefaults(queryKey, options) {
  // Key matching is strict when registering/updating
  const result = this.queryDefaults.find(
    x => hashQueryKey(queryKey) === hashQueryKey(x.queryKey)
  )
  if (result) {
    result.defaultOptions = options
  } else {
    // "push" here means: "queryDefaults have an order"
    this.queryDefaults.push({ queryKey, defaultOptions: options })
  }
}

To get query defaults from a key, RQ checks for defaults using a loose key matching AND find Array method.

getQueryDefaults(queryKey) {
  return queryKey
    ? this.queryDefaults.find(x => partialMatchKey(queryKey, x.queryKey))
        ?.defaultOptions
    : undefined
}

==> Since find Array method is used, the first matching defaults are returned, which may not be the expected ones. <==

There seems to be no way to prevent from these default key collisions to happen, some actions could be taken:

• Either mention in the doc that similarly to "*" path in standard client-side router, the queryDefaults associated with the most generic key must be registered last.
• Be able to apply query filters (strict etc.) when getting query defaults
• Provide a way to identify collision

Note: partialMatchKey (used in getQueryDefaults) uses internally partialDeepEqual (code here).
We could narrow the behaviour above with the following code:

function partialDeepEqual(a, b) {
  if (a === b) {
    return true
  }

  if (typeof a !== typeof b) {
    return false
  }

  if (a && b && typeof a === "object" && typeof b === "object") {
    return !Object.keys(b).some((key) => !partialDeepEqual(a[key], b[key]))
  }

  return false
}

const keyABCD = [
  {
    a: "a",
    b: "b",
    c: "c",
    d: "d",
  },
]

const keyABC = [
  {
    a: "a",
    b: "b",
    c: "c",
  },
]

// True is the normal behaviour for `partialDeepEqual`
// But when used to retrieve defaults with `find`, it may not be the expected behaviour
console.log(`partialDeepEqual(keyABCD, keyABC):`, partialDeepEqual(keyABCD, keyABC)) //  => true

Feedbacks would be welcome.
And contributing to either the doc or the code is an option for us.

Thanks for reading!

[TkDodo]

Thank you for the question, that's an interesting problem for sure. It seems that exact matches should take precedence over loose ones. However, even if we do that, in case of multiple loose matches we would still have to depend on the order I think ...

[GLabat]

Exact match might not be the solution, at least for some use-cases.
The whole point of queryDefaults is to define defaults for a "class" of queries, which by definition is not an exact key.

As a temporary addition, could we imagine something like that? (Pure JS, I'm not TS-fluent yet 😅)

findQueryDefaults(queryKey) {
  // First retrieve all matching defaults for the given key
  const matchingDefaults = this.queryDefaults.filter((x) =>
    partialMatchKey(queryKey, x.queryKey)
  )
  // It is ok not having defaults, but it is error prone to have more than 1 default for a given key
  assert(
     matchingDefaults.length <= 1,
    `[QueryClient] Several defaults match with key '${JSON.stringify(
      queryKey
    )}'. Please check how query defaults are registered. Order does matter here. cf. http://react-query.com/some/link/to/document#queryDefaults`
  )
  // Explicitly returns the first one
  const firstMatchingDefaults = matchingDefaults?.[0]
  return firstMatchingDefaults?.defaultOptions || undefined
}

getQueryDefaults(queryKey) {
  const queryDefaults = this.findQueryDefaults(queryKey)
  return queryDefaults?.defaultOptions
}

A little bit of overhead since we browse the whole queryDefaults array to find all the matches but there should not be that many.