Function cleanupQueryIfIdle

packages/query-db-collection/src/query.ts:1556–1623

(hashedQueryKey: string)

     * Respects refcounts and invalidateQueries cycles via hasListeners().
     */
    const cleanupQueryIfIdle = (hashedQueryKey: string) => {
      const refcount = queryRefCounts.get(hashedQueryKey) || 0
      const observer = state.observers.get(hashedQueryKey)
      const effectivePersistedGcTime =
        effectivePersistedGcTimes.get(hashedQueryKey)

      if (refcount <= 0) {
        // Drop our subscription so hasListeners reflects only active consumers
        unsubscribes.get(hashedQueryKey)?.()
        unsubscribes.delete(hashedQueryKey)
      }

      const hasListeners = observer?.hasListeners() ?? false

      if (hasListeners) {
        // During invalidateQueries, TanStack Query keeps internal listeners alive.
        // Leave refcount at 0 but keep observer so it can resubscribe.
        queryRefCounts.set(hashedQueryKey, 0)
        return
      }

      // No listeners means the query is truly idle.
      // Even if refcount > 0, we treat hasListeners as authoritative to prevent leaks.
      // This can happen if subscriptions are GC'd without calling unloadSubset.
      if (refcount > 0) {
        console.warn(
          `[cleanupQueryIfIdle] Invariant violation: refcount=${refcount} but no listeners. Cleaning up to prevent leak.`,
          { hashedQueryKey },
        )
      }

      if (
        effectivePersistedGcTime !== undefined &&
        metadata &&
        persistedMetadata?.row.scanPersisted
      ) {
        begin()
        metadata.collection.set(
          `${QUERY_COLLECTION_GC_PREFIX}${hashedQueryKey}`,
          {
            queryHash: hashedQueryKey,
            mode:
              effectivePersistedGcTime === Number.POSITIVE_INFINITY
                ? `until-revalidated`
                : `ttl`,
            ...(effectivePersistedGcTime === Number.POSITIVE_INFINITY
              ? {}
              : { expiresAt: Date.now() + effectivePersistedGcTime }),
          },
        )
        commit()
        if (effectivePersistedGcTime !== Number.POSITIVE_INFINITY) {
          schedulePersistedRetentionExpiry({
            queryHash: hashedQueryKey,
            mode: `ttl`,
            expiresAt: Date.now() + effectivePersistedGcTime,
          })
        }