feat(prefetch,query-keys): add prefetch helpers and normalize query params

Author: KaiUweCZE

libs/storefront-data/src/shared/cache-config.ts

@@ -6,6 +6,8 @@ export type CacheOptions = {
   refetchOnReconnect?: boolean
 }
 
+export type PrefetchCacheOptions = Pick<CacheOptions, "staleTime" | "gcTime">
+
 export type CacheConfig = {
   static: CacheOptions
   semiStatic: CacheOptions
@@ -56,3 +58,14 @@ export function createCacheConfig(
     userData: { ...defaultCacheConfig.userData, ...overrides.userData },
   }
 }
+
+export function getPrefetchCacheOptions(
+  cacheConfig: CacheConfig,
+  strategy: keyof CacheConfig
+): PrefetchCacheOptions {
+  const config = cacheConfig[strategy]
+  return {
+    staleTime: config.staleTime,
+    gcTime: config.gcTime,
+  }
+}

libs/storefront-data/src/shared/index.ts

@@ -1,8 +1,13 @@
-export { createCacheConfig, defaultCacheConfig } from "./cache-config"
+export {
+  createCacheConfig,
+  defaultCacheConfig,
+  getPrefetchCacheOptions,
+} from "./cache-config"
 export type {
   CacheConfig,
   CacheConfigOverrides,
   CacheOptions,
+  PrefetchCacheOptions,
 } from "./cache-config"
 export { createMedusaSdk } from "./medusa-client"
 export type {
@@ -12,8 +17,17 @@ export type {
 } from "./medusa-client"
 export { createQueryClientConfig, getQueryClient, makeQueryClient } from "./query-client"
 export type { QueryClientConfig } from "./query-client"
-export { createQueryKey, createQueryKeyFactory } from "./query-keys"
-export type { QueryKey, QueryNamespace } from "./query-keys"
+export {
+  createQueryKey,
+  createQueryKeyFactory,
+  normalizeQueryKeyPart,
+  normalizeQueryKeyParams,
+} from "./query-keys"
+export type {
+  NormalizeQueryKeyParamsOptions,
+  QueryKey,
+  QueryNamespace,
+} from "./query-keys"
 export type {
   InfiniteQueryOptions,
   InfiniteQueryResult,
@@ -27,3 +41,5 @@ export type {
 } from "./hook-types"
 export type { RegionInfo } from "./region"
 export { RegionProvider, useRegionContext } from "./region-context"
+export { isQueryFresh, shouldSkipPrefetch } from "./prefetch"
+export type { PrefetchSkipMode } from "./prefetch"

libs/storefront-data/src/shared/prefetch.ts

@@ -0,0 +1,39 @@
+import type { QueryClient } from "@tanstack/react-query"
+import type { CacheOptions } from "./cache-config"
+import type { QueryKey } from "./query-keys"
+
+export type PrefetchSkipMode = "fresh" | "any"
+
+export const isQueryFresh = (
+  queryClient: QueryClient,
+  queryKey: QueryKey,
+  staleTime: number
+) => {
+  const state = queryClient.getQueryState(queryKey)
+  if (!state || state.isInvalidated || state.data === undefined) {
+    return false
+  }
+  return Date.now() - state.dataUpdatedAt < staleTime
+}
+
+export const shouldSkipPrefetch = (params: {
+  queryClient: QueryClient
+  queryKey: QueryKey
+  cacheOptions: Pick<CacheOptions, "staleTime">
+  skipIfCached: boolean
+  skipMode: PrefetchSkipMode
+}) => {
+  if (!params.skipIfCached) {
+    return false
+  }
+
+  if (params.skipMode === "any") {
+    return params.queryClient.getQueryData(params.queryKey) !== undefined
+  }
+
+  return isQueryFresh(
+    params.queryClient,
+    params.queryKey,
+    params.cacheOptions.staleTime
+  )
+}

libs/storefront-data/src/shared/query-keys.ts

@@ -1,6 +1,9 @@
 export type QueryKey = readonly unknown[]
 
 export type QueryNamespace = string | readonly string[]
+export type NormalizeQueryKeyParamsOptions = {
+  omitKeys?: readonly string[]
+}
 
 const isPlainObject = (value: unknown): value is Record<string, unknown> => {
   if (!value || typeof value !== "object") {
@@ -45,6 +48,94 @@ const stableValue = (value: unknown, visited: WeakSet<object>): unknown => {
   return value
 }
 
+const normalizeValue = (
+  value: unknown,
+  visited: WeakSet<object>,
+  omitKeys: ReadonlySet<string>
+): unknown => {
+  if (Array.isArray(value)) {
+    if (visited.has(value)) {
+      throw new Error("QueryKey contains a circular reference")
+    }
+    visited.add(value)
+    const result = value
+      .map((entry) => normalizeValue(entry, visited, omitKeys))
+      .filter((entry) => entry !== undefined)
+    visited.delete(value)
+    return result
+  }
+
+  if (isPlainObject(value)) {
+    if (visited.has(value)) {
+      throw new Error("QueryKey contains a circular reference")
+    }
+    visited.add(value)
+    const entries = Object.entries(value).sort(([a], [b]) =>
+      a.localeCompare(b)
+    )
+    const result: Record<string, unknown> = {}
+    for (const [key, entryValue] of entries) {
+      if (omitKeys.has(key) || entryValue === undefined) {
+        continue
+      }
+      const normalizedValue = normalizeValue(entryValue, visited, omitKeys)
+      if (normalizedValue === undefined) {
+        continue
+      }
+      result[key] = normalizedValue
+    }
+    visited.delete(value)
+    return result
+  }
+
+  return value
+}
+
+/**
+ * Normalizes object-like query params before putting them into query keys.
+ *
+ * - Removes `undefined` values recursively
+ * - Removes keys listed in `omitKeys` (for non-cache-affecting flags like `enabled`)
+ * - Sorts object keys for stable hashing
+ */
+export function normalizeQueryKeyParams<TParams extends Record<string, unknown>>(
+  params: TParams,
+  options?: NormalizeQueryKeyParamsOptions
+): Record<string, unknown> {
+  if (!isPlainObject(params)) {
+    throw new Error(
+      "QueryKey params must be a plain object. Use a serializer before normalizeQueryKeyParams."
+    )
+  }
+  const visited = new WeakSet<object>()
+  const omitKeys = new Set(options?.omitKeys ?? [])
+  const normalized = normalizeValue(params, visited, omitKeys)
+  if (isPlainObject(normalized)) {
+    return normalized
+  }
+  return {}
+}
+
+/**
+ * Safe normalization for query-key parts used by hook factories.
+ *
+ * - Plain objects are normalized via `normalizeQueryKeyParams`
+ * - `undefined` maps to `{}` for stable optional key parts
+ * - Other values are passed through the stable serializer
+ */
+export function normalizeQueryKeyPart(
+  value: unknown,
+  options?: NormalizeQueryKeyParamsOptions
+): unknown {
+  if (value === undefined) {
+    return {}
+  }
+  if (isPlainObject(value)) {
+    return normalizeQueryKeyParams(value, options)
+  }
+  return stableValue(value, new WeakSet<object>())
+}
+
 export function createQueryKey(
   namespace: QueryNamespace,
   ...parts: readonly unknown[]