@teleporthq/teleport-plugin-next-data-source 0.43.66 → 0.43.68

package/src/fetchers/utils/rest-api-response-cache.ts

@@ -0,0 +1,188 @@
+import { DataCache } from '@teleporthq/teleport-shared'
+
+/**
+ * The REST API data source's response cache: `config.cache` as the editor
+ * stores it on the data source.
+ */
+export interface RESTAPICacheConfig {
+  enabled?: boolean
+  ttlSeconds?: number
+}
+
+/** A year: past that, the window only ever ends with the next deployment. */
+const MAX_TTL_SECONDS = 31_536_000
+
+/**
+ * Bounds for the one store every REST API data source in a server process
+ * shares. Entries are raw JSON text, so the character budget is close to the
+ * memory the cache holds.
+ */
+const MAX_ENTRIES = 100
+const MAX_CHARS = 33_554_432
+
+/**
+ * How long a request may wait on an upstream call another request started.
+ * An older call is treated as stuck and a new one is made, so one hung socket
+ * cannot hold every later visitor.
+ */
+const IN_FLIGHT_JOIN_MS = 10_000
+
+/**
+ * The window, in whole seconds, a REST API data source caches its upstream
+ * response for — or `undefined` when caching is off, which keeps the emitted
+ * fetcher exactly what it was before this option existed.
+ */
+export const resolveRESTAPICacheTTLSeconds = (
+  cache: RESTAPICacheConfig | undefined
+): number | undefined => {
+  if (!cache || typeof cache !== 'object' || cache.enabled !== true) {
+    return undefined
+  }
+
+  const { ttlSeconds } = cache
+  const seconds =
+    typeof ttlSeconds === 'number' && Number.isFinite(ttlSeconds) && ttlSeconds > 0
+      ? Math.max(1, Math.floor(ttlSeconds))
+      : DataCache.DEFAULT_CACHE_TTL_SECONDS
+
+  return Math.min(seconds, MAX_TTL_SECONDS)
+}
+
+/**
+ * Runtime helpers of a cached REST API fetcher.
+ *
+ * The cache sits under the handler, around the upstream `fetch` only: every
+ * caller — the API route, `getStaticProps` through `fetchData`, the count
+ * route, the global-state route — asks the same URL, and search, filters, sort
+ * and paging are applied to the cached payload afterwards. One upstream call
+ * per window therefore serves every page, filter and visitor.
+ *
+ * - The store lives on `globalThis`, so every data-source module in the
+ *   process (each API route is its own bundle) shares it. On a serverless host
+ *   that is one store per warm instance; the `s-maxage` header below is what
+ *   carries the window to the CDN in front of all of them.
+ * - Entries are keyed by the whole upstream request (method, URL, headers,
+ *   body) and hold the response TEXT: every reader parses its own copy, so a
+ *   handler that sorts in place can never reorder another request's rows.
+ * - Freshness is judged by the READER's window, so two data sources calling
+ *   the same URL with different windows each get what they asked for.
+ * - Only a 2xx JSON response is kept. Errors, non-JSON bodies and network
+ *   failures reach the caller as before and are retried by the next request.
+ *
+ * Emitted inside a template literal: no backticks or template placeholders in
+ * here, not even in comments.
+ */
+export const generateRESTAPIResponseCacheCode = (ttlSeconds: number): string => {
+  return `const REST_API_CACHE_TTL_MS = ${ttlSeconds * 1000}
+const REST_API_CACHE_MAX_ENTRIES = ${MAX_ENTRIES}
+const REST_API_CACHE_MAX_CHARS = ${MAX_CHARS}
+const REST_API_IN_FLIGHT_JOIN_MS = ${IN_FLIGHT_JOIN_MS}
+
+// One store per server process, shared by every REST API data source module.
+if (!globalThis.__tqRestApiCache) {
+  globalThis.__tqRestApiCache = { entries: new Map(), inFlight: new Map(), chars: 0 }
+}
+const restApiCache = globalThis.__tqRestApiCache
+
+function restApiCacheKey(url, options) {
+  return JSON.stringify([options.method, url, options.headers, options.body === undefined ? null : options.body])
+}
+
+function forgetRestApiResponse(key) {
+  const entry = restApiCache.entries.get(key)
+  if (entry) {
+    restApiCache.entries.delete(key)
+    restApiCache.chars -= entry.bodyText.length
+  }
+}
+
+function rememberRestApiResponse(key, entry) {
+  forgetRestApiResponse(key)
+  if (entry.bodyText.length > REST_API_CACHE_MAX_CHARS) {
+    return
+  }
+  restApiCache.entries.set(key, entry)
+  restApiCache.chars += entry.bodyText.length
+  // A Map iterates in insertion order and every hit re-inserts its entry, so
+  // the first key is always the least recently used one.
+  while (
+    restApiCache.entries.size > REST_API_CACHE_MAX_ENTRIES ||
+    restApiCache.chars > REST_API_CACHE_MAX_CHARS
+  ) {
+    forgetRestApiResponse(restApiCache.entries.keys().next().value)
+  }
+}
+
+async function requestRestApi(url, options) {
+  const response = await fetch(url, options)
+  if (!response.ok) {
+    return { ok: false, status: response.status, statusText: response.statusText }
+  }
+  const bodyText = await response.text()
+  // Parsed once here so a body that is not JSON fails this request, as
+  // response.json() would, instead of being cached and failing every request
+  // until the window ends.
+  JSON.parse(bodyText)
+  return {
+    ok: true,
+    status: response.status,
+    statusText: response.statusText,
+    bodyText,
+    fetchedAt: Date.now(),
+  }
+}
+
+function fetchRestApiWithCache(url, options) {
+  const key = restApiCacheKey(url, options)
+  const now = Date.now()
+
+  const cached = restApiCache.entries.get(key)
+  if (cached && now >= cached.fetchedAt && now - cached.fetchedAt < REST_API_CACHE_TTL_MS) {
+    restApiCache.entries.delete(key)
+    restApiCache.entries.set(key, cached)
+    return Promise.resolve(cached)
+  }
+
+  // Concurrent misses share one upstream call instead of each making their own.
+  const pending = restApiCache.inFlight.get(key)
+  if (pending && now - pending.startedAt < REST_API_IN_FLIGHT_JOIN_MS) {
+    return pending.promise
+  }
+
+  const flight = { startedAt: now, promise: null }
+  const release = () => {
+    if (restApiCache.inFlight.get(key) === flight) {
+      restApiCache.inFlight.delete(key)
+    }
+  }
+  flight.promise = requestRestApi(url, options).then(
+    (result) => {
+      release()
+      if (result.ok) {
+        rememberRestApiResponse(key, result)
+      }
+      return result
+    },
+    (error) => {
+      release()
+      throw error
+    }
+  )
+  restApiCache.inFlight.set(key, flight)
+  return flight.promise
+}
+
+// Lets the CDN answer this exact URL until the upstream response it was built
+// from expires, so neither layer serves it longer than the window. Only a real
+// GET response gets the header: fetchData, fetchCount and tqWithCache call the
+// handler with a bare { status, json } object.
+function applyRestApiCacheHeaders(req, res, fetchedAt) {
+  if (!req || req.method !== 'GET' || !res || typeof res.setHeader !== 'function') {
+    return
+  }
+  const remainingSeconds = Math.floor((fetchedAt + REST_API_CACHE_TTL_MS - Date.now()) / 1000)
+  if (remainingSeconds > 0) {
+    res.setHeader('Cache-Control', 'public, max-age=0, s-maxage=' + remainingSeconds)
+  }
+}`
+}

package/src/fetchers/utils/table-access-guard.ts

@@ -0,0 +1,39 @@
+import { SessionCookieResolver, TableAccess } from '@teleporthq/teleport-shared'
+import { generateBrowserRowAccessCall, generateBrowserRowPolicyCode } from './browser-row-policy'
+
+/**
+ * The money-table guard for a generated per-table read route
+ * (`/api/teleport-<table>-<source>` and its `-count` twin).
+ *
+ * Every table a page binds gets such a route, and the route serves the whole
+ * table — plus any single SELECT through `?rawQuery=` — to whoever asks. For a
+ * catalogue that is the product; for gift cards and voucher codes it is theft.
+ * The guard refuses a protected table (see `TableAccess.PROTECTED_TABLES`)
+ * unless the caller is a server segment presenting the app secret or a
+ * signed-in member of a trusted role — the generated admin, whose list pages
+ * are the one browser reader these tables have. It is followed by the
+ * browser row policy (see `browser-row-policy.ts`): unpublished rows and
+ * private columns of the public tables, and the admin-only tables.
+ */
+
+/** Declares the session resolver and the `__ta*` guard once per module. */
+export const generateTableAccessPreamble = (trustedReaderRoles: ReadonlyArray<string>): string => {
+  return `${SessionCookieResolver.generateCommonJsSessionTokenResolverCode()}
+${TableAccess.generateTableAccessHelperCode({ trustedReaderRoles })}
+${generateBrowserRowPolicyCode()}`
+}
+
+/**
+ * The early return at the top of a handler, before the client connects:
+ * `tableName` is the module's table, `rawQueryExpr` the request's raw statement
+ * (or `null` where the handler accepts none).
+ */
+export const generateReadGuardCall = (tableName: string, rawQueryExpr: string | null): string => {
+  return `  const __access = await __taGuardRead(req, ${JSON.stringify(tableName)}, ${
+    rawQueryExpr || 'null'
+  })
+  if (__access) {
+    return res.status(__access.status).json({ success: false, error: __access.message, timestamp: Date.now() })
+  }
+${generateBrowserRowAccessCall(tableName, rawQueryExpr)}`
+}

package/src/index.ts

@@ -4,6 +4,7 @@ import {
   FileType,
   ChunkType,
   UIDLComponentSEO,
+  UIDLDependency,
   UIDLDynamicReference,
 } from '@teleporthq/teleport-types'
 import { UIDLUtils, StringUtils } from '@teleporthq/teleport-shared'
@@ -16,6 +17,7 @@ import {
 import { createNextArrayMapperPaginationPlugin } from './pagination-plugin'
 import { buildProductTransformOptions } from './transformations'
 import { DATA_SOURCE_ISR_REVALIDATE_SECONDS } from './isr'
+import { ensureRouterDeclaration } from './request-locale'
 import * as types from '@babel/types'
 
 interface SearchConfig {
@@ -55,6 +57,41 @@ interface WrapContext {
 // from user-defined or standard renderPropIdentifier values
 const WRAPPED_DS_EXPR_PREFIX = '__dsExpr_'
 
+/**
+ * The statements of the component function the `jsx-component` chunk declares
+ * (`const Page = (props) => { … }`), or `null` when the chunk holds another
+ * shape — a test may hand the plugin a bare element.
+ */
+const findComponentBody = (componentChunk: { content: unknown }): types.Statement[] | null => {
+  const content = componentChunk.content as types.Node | undefined
+  if (content?.type !== 'VariableDeclaration') {
+    return null
+  }
+  const init = content.declarations[0]?.init
+  if (
+    (init?.type !== 'ArrowFunctionExpression' && init?.type !== 'FunctionExpression') ||
+    init.body.type !== 'BlockStatement'
+  ) {
+    return null
+  }
+  return init.body.body
+}
+
+/**
+ * A client-side fetch in a localized project reads `router.locale` (see
+ * `extractDataSourceIntoNextAPIFolder`), so the router has to be declared in
+ * the component that fetches.
+ */
+const ensureRouterForClientFetches = (
+  componentChunk: { content: unknown },
+  dependencies: Record<string, UIDLDependency>
+): void => {
+  const body = findComponentBody(componentChunk)
+  if (body) {
+    ensureRouterDeclaration(body, dependencies)
+  }
+}
+
 function containsDataSourceDataReference(astNode: any): boolean {
   if (!astNode || typeof astNode !== 'object') {
     return false
@@ -490,6 +527,11 @@ export const createNextPagesDataSourcePlugin: ComponentPluginFactory<{}> = () =>
 
     let getStaticPropsChunk = chunks.find((chunk) => chunk.name === 'getStaticProps')
 
+    const transformOptions = buildProductTransformOptions(options)
+    // Whether a provider on this page fetches client-side — in a localized
+    // project that fetch reads `router.locale`.
+    let wiredClientFetch = false
+
     // Track the first data source info for wrapping dataSourceData expressions
     let firstDataSourceInfo: DataSourceInfo | null = null
     // Track fetcher import name for wrapped providers
@@ -609,7 +651,7 @@ export const createNextPagesDataSourcePlugin: ComponentPluginFactory<{}> = () =>
           dependencies,
           dynamicRouteAttr,
           uidl.outputOptions?.folderPath,
-          buildProductTransformOptions(options)
+          transformOptions
         )
 
         if (result.success && result.chunk) {
@@ -641,17 +683,23 @@ export const createNextPagesDataSourcePlugin: ComponentPluginFactory<{}> = () =>
             }
           }
         }
-      } else {
+      } else if (
         extractDataSourceIntoNextAPIFolder(
           dataSourceNode,
           dataSources,
           componentChunk,
           options.extractedResources,
-          buildProductTransformOptions(options)
+          transformOptions
         )
+      ) {
+        wiredClientFetch = true
       }
     })
 
+    if (wiredClientFetch && transformOptions.localization) {
+      ensureRouterForClientFetches(componentChunk, dependencies)
+    }
+
     // After processing all data source nodes, wrap any element props containing dataSourceData
     // expressions in a DataProvider
     if (firstDataSourceInfo && componentChunk.content) {
@@ -1207,6 +1255,11 @@ export const createNextComponentDataSourcePlugin: ComponentPluginFactory<{}> = (
       return structure
     }
 
+    const transformOptions = buildProductTransformOptions(options)
+    // Whether a provider in this component fetches client-side — in a
+    // localized project that fetch reads `router.locale`.
+    let wiredClientFetch = false
+
     // Track the first data source info for wrapping dataSourceData expressions
     let firstDataSourceInfo: DataSourceInfo | null = null
 
@@ -1264,15 +1317,23 @@ export const createNextComponentDataSourcePlugin: ComponentPluginFactory<{}> = (
         }
       }
 
-      extractDataSourceIntoNextAPIFolder(
-        dataSourceNode,
-        dataSources,
-        componentChunk,
-        options.extractedResources,
-        buildProductTransformOptions(options)
-      )
+      if (
+        extractDataSourceIntoNextAPIFolder(
+          dataSourceNode,
+          dataSources,
+          componentChunk,
+          options.extractedResources,
+          transformOptions
+        )
+      ) {
+        wiredClientFetch = true
+      }
     })
 
+    if (wiredClientFetch && transformOptions.localization) {
+      ensureRouterForClientFetches(componentChunk, dependencies)
+    }
+
     // If no data source nodes were found but there are dataSources available,
     // use the first available dataSource to create firstDataSourceInfo
     // This handles the case where a component has element props with dataSourceData expressions
@@ -1355,7 +1416,7 @@ export const createNextComponentDataSourcePlugin: ComponentPluginFactory<{}> = (
               dataSource,
               firstDataSourceInfo.tableName,
               false,
-              buildProductTransformOptions(options)
+              transformOptions
             )
             options.extractedResources[`utils/${fileName}`] = {
               fileName,
@@ -1399,8 +1460,15 @@ export * from './utils'
 export * from './array-mapper-pagination'
 export * from './pagination-plugin'
 export * from './count-fetchers'
+export * from './product-price-sort'
+export * from './product-filter-fields'
 // The product transform's build-time options (category taxonomy + storefront
 // tax rate) — every package that emits a data-source fetcher has to derive
 // them the same way.
 export { buildProductTransformOptions } from './transformations'
 export type { EcommerceProductTransformOptions, EntityTransformOptions } from './transformations'
+// How a fetch says which language it is for, and when a project needs it to —
+// shared with every other package that emits a data-source fetch.
+export { isLocalizedProject, resolveContentLocalization } from './content-localization'
+export type { ContentLocalization } from './content-localization'
+export { REQUEST_LOCALE_PARAM, buildServerLocaleParam } from './request-locale'

package/src/items-path.ts

@@ -0,0 +1,74 @@
+import * as types from '@babel/types'
+
+/**
+ * Where a paginated/searchable list's rows sit inside the payload its data
+ * source returns, read off the repeater's `source` expression.
+ *
+ * A REST API or JavaScript source may answer `{ templates: [...], total }`, and
+ * the editor binds the list to `All_Templates_data_data?.templates || []`. The
+ * generated fetcher only searches, filters, sorts and slices a payload that IS
+ * an array, so without this every row came back on every page (the canvas
+ * slices on the client and looked right) and the count measured the wrapper as
+ * 0 rows, disabling "Next".
+ *
+ * Returns undefined when the list is bound to the payload itself, or when the
+ * source is anything other than a plain property chain off the data source's
+ * render prop — an expression this cannot read is left exactly as before.
+ */
+const SEGMENT_RE =
+  /^(?:\?\.([A-Za-z_$][\w$]*)|\.([A-Za-z_$][\w$]*)|(?:\?\.)?\[\s*(?:"([^"]*)"|'([^']*)')\s*\])/
+
+const PATH_AWARE_SOURCE_TYPES = new Set(['rest-api', 'javascript'])
+
+export const extractItemsPath = (
+  source: unknown,
+  dataSourceIdentifier: string,
+  dataSourceType: string
+): string[] | undefined => {
+  if (typeof source !== 'string' || !dataSourceIdentifier) {
+    return undefined
+  }
+  if (!PATH_AWARE_SOURCE_TYPES.has(dataSourceType)) {
+    return undefined
+  }
+
+  let rest = source
+    .trim()
+    .replace(/\s*\|\|\s*\[\s*\]$/, '')
+    .trim()
+  if (!rest.startsWith(dataSourceIdentifier)) {
+    return undefined
+  }
+  rest = rest.slice(dataSourceIdentifier.length)
+
+  const path: string[] = []
+  while (rest.length > 0) {
+    const match = rest.match(SEGMENT_RE)
+    if (!match) {
+      return undefined
+    }
+    path.push(match[1] ?? match[2] ?? match[3] ?? match[4])
+    rest = rest.slice(match[0].length)
+  }
+
+  return path.length > 0 ? path : undefined
+}
+
+/**
+ * Push `<key>: '["templates"]'` onto a params object. Fetch calls send it as
+ * `itemsPath` (process the inner array, keep the wrapper the page reads back
+ * through); count calls send it as `collectionPath`, so the count handler
+ * measures the inner array instead of the wrapper.
+ */
+export const appendItemsPathParam = (
+  paramsProps: types.ObjectProperty[],
+  itemsPath: string[] | undefined,
+  key: 'itemsPath' | 'collectionPath'
+): void => {
+  if (!itemsPath || itemsPath.length === 0) {
+    return
+  }
+  paramsProps.push(
+    types.objectProperty(types.identifier(key), types.stringLiteral(JSON.stringify(itemsPath)))
+  )
+}

package/src/loading-state.ts

@@ -67,6 +67,19 @@ export interface LoadingStateVars {
    * stale rows back for the rest of the second request.
    */
   inFlightRefVar: string
+  /**
+   * Ref counting the requests STARTED, so a response can tell whether a newer
+   * request has overtaken it. `DataProvider` keeps whatever resolves last:
+   * two controls changed in quick succession (a "Clear all" emptying several
+   * filter states, one state write after another) start two requests, and
+   * when the older, slower one settles after the newer it painted the OLDER
+   * rows over the newer — a list showing two products for a URL that filters
+   * nothing. Each request notes its sequence number and, if overtaken, hands
+   * over the newest settled rows instead of its own.
+   */
+  fetchSeqRefVar: string
+  /** Ref holding the rows of the newest request that settled — what an overtaken one resolves with. */
+  latestDataRefVar: string
 }
 
 export function getLoadingStateVars(index: number): LoadingStateVars {
@@ -74,14 +87,18 @@ export function getLoadingStateVars(index: number): LoadingStateVars {
     isFetchingVar: `ds_${index}_isFetching`,
     setIsFetchingVar: `setDs_${index}_isFetching`,
     inFlightRefVar: `ds_${index}_fetchesInFlight`,
+    fetchSeqRefVar: `ds_${index}_fetchSeq`,
+    latestDataRefVar: `ds_${index}_latestData`,
   }
 }
 
 /**
  * `const ds_N_fetchesInFlight = useRef(0)`
+ * `const ds_N_fetchSeq = useRef(0)`
+ * `const ds_N_latestData = useRef(undefined)`
  * `const [ds_N_isFetching, setDs_N_isFetching] = useState(false)`
  *
- * Both are stable across renders (a ref object and a `useState` setter), which
+ * All are stable across renders (ref objects and a `useState` setter), which
  * is what lets the wrapped `fetchData` keep its empty `useCallback` dependency
  * array — a changing `fetchData` identity would retrigger the provider's fetch
  * effect on every render.
@@ -94,6 +111,18 @@ export function buildLoadingStateDeclarations(vars: LoadingStateVars): types.Sta
         types.callExpression(types.identifier('useRef'), [types.numericLiteral(0)])
       ),
     ]),
+    types.variableDeclaration('const', [
+      types.variableDeclarator(
+        types.identifier(vars.fetchSeqRefVar),
+        types.callExpression(types.identifier('useRef'), [types.numericLiteral(0)])
+      ),
+    ]),
+    types.variableDeclaration('const', [
+      types.variableDeclarator(
+        types.identifier(vars.latestDataRefVar),
+        types.callExpression(types.identifier('useRef'), [types.identifier('undefined')])
+      ),
+    ]),
     types.variableDeclaration('const', [
       types.variableDeclarator(
         types.arrayPattern([
@@ -183,10 +212,54 @@ function injectTrackingIntoCachedBody(body: types.BlockStatement, vars: LoadingS
 
   const tracked = buildTrackedFetchBody(networkChain.statement.argument as types.Expression, vars)
   body.body.splice(networkChain.index, 1, ...tracked.body)
+  markCacheHitAsNewest(body, vars)
 
   return true
 }
 
+/**
+ * A cache hit answers synchronously with the rows of THIS request, so it is
+ * the newest settled result too: it advances the sequence and records its rows,
+ * or an older network request still in flight would resolve after it and paint
+ * over it. Adds the two statements at the head of the hit branch — before its
+ * `return Promise.resolve(__tqHit)` — and nothing else, so the flag the branch
+ * deliberately never raises stays untouched.
+ */
+function markCacheHitAsNewest(body: types.BlockStatement, vars: LoadingStateVars): void {
+  const hit = body.body.find(
+    (statement): statement is types.IfStatement =>
+      statement.type === 'IfStatement' &&
+      statement.test.type === 'BinaryExpression' &&
+      statement.test.left.type === 'Identifier' &&
+      statement.test.left.name === CACHE_HIT_IDENTIFIER &&
+      statement.consequent.type === 'BlockStatement'
+  )
+  if (!hit || hit.consequent.type !== 'BlockStatement') {
+    return
+  }
+  hit.consequent.body.unshift(
+    types.expressionStatement(types.updateExpression('++', refCurrent(vars.fetchSeqRefVar), true)),
+    types.expressionStatement(
+      types.assignmentExpression(
+        '=',
+        refCurrent(vars.latestDataRefVar),
+        types.identifier(CACHE_HIT_IDENTIFIER)
+      )
+    )
+  )
+}
+
+/** The identifier the cache wiring binds a hit to — see `cache/ast.ts`. */
+const CACHE_HIT_IDENTIFIER = '__tqHit'
+/** The rows a tracked request resolved with, inside its own `then`. */
+const TRACKED_ROWS_IDENTIFIER = '__tqRows'
+/** This request's sequence number. */
+const TRACKED_SEQ_IDENTIFIER = '__tqSeq'
+
+function refCurrent(refVar: string): types.MemberExpression {
+  return types.memberExpression(types.identifier(refVar), types.identifier('current'))
+}
+
 // tslint:disable-next-line:no-any
 function containsIdentifier(node: any, name: string): boolean {
   if (!node || typeof node !== 'object') {
@@ -257,9 +330,16 @@ function findMemoizedFetchDataArrow(
  * Turns `(params) => fetch(...).then(...)` into
  *
  *   (params) => {
+ *     const __tqSeq = ++ds_N_fetchSeq.current
  *     ds_N_fetchesInFlight.current += 1
  *     setDs_N_isFetching(true)
- *     return fetch(...).then(...).finally(() => {
+ *     return fetch(...).then(...).then((__tqRows) => {
+ *       if (__tqSeq !== ds_N_fetchSeq.current) {
+ *         return ds_N_latestData.current !== undefined ? ds_N_latestData.current : __tqRows
+ *       }
+ *       ds_N_latestData.current = __tqRows
+ *       return __tqRows
+ *     }).finally(() => {
  *       ds_N_fetchesInFlight.current -= 1
  *       if (ds_N_fetchesInFlight.current <= 0) {
  *         ds_N_fetchesInFlight.current = 0
@@ -268,6 +348,12 @@ function findMemoizedFetchDataArrow(
  *     })
  *   }
  *
+ * The `then` is the stale guard (see `fetchSeqRefVar`): a request overtaken by
+ * a newer one resolves with the newest settled rows rather than its own, so
+ * the provider — which keeps whatever resolves LAST — never paints older rows
+ * over newer ones. An overtaken request whose successor has not settled yet
+ * resolves with its own rows; the successor then replaces them.
+ *
  * `finally` (rather than a `then` pair) keeps the flag honest when the request
  * rejects: the provider switches to its error status and the loading state must
  * not stay on screen. The counter is clamped at 0 so a late settle from a
@@ -317,7 +403,52 @@ function buildTrackedFetchBody(
     ])
   )
 
+  const latestData = refCurrent(vars.latestDataRefVar)
+  const staleGuard = types.arrowFunctionExpression(
+    [types.identifier(TRACKED_ROWS_IDENTIFIER)],
+    types.blockStatement([
+      types.ifStatement(
+        types.binaryExpression(
+          '!==',
+          types.identifier(TRACKED_SEQ_IDENTIFIER),
+          refCurrent(vars.fetchSeqRefVar)
+        ),
+        types.blockStatement([
+          types.returnStatement(
+            types.conditionalExpression(
+              types.binaryExpression(
+                '!==',
+                types.cloneNode(latestData, true),
+                types.identifier('undefined')
+              ),
+              types.cloneNode(latestData, true),
+              types.identifier(TRACKED_ROWS_IDENTIFIER)
+            )
+          ),
+        ])
+      ),
+      types.expressionStatement(
+        types.assignmentExpression(
+          '=',
+          types.cloneNode(latestData, true),
+          types.identifier(TRACKED_ROWS_IDENTIFIER)
+        )
+      ),
+      types.returnStatement(types.identifier(TRACKED_ROWS_IDENTIFIER)),
+    ])
+  )
+  const guardedFetch = types.callExpression(
+    types.memberExpression(fetchExpression, types.identifier('then')),
+    [staleGuard]
+  )
+
   return types.blockStatement([
+    types.variableDeclaration('const', [
+      types.variableDeclarator(
+        types.identifier(TRACKED_SEQ_IDENTIFIER),
+        types.updateExpression('++', refCurrent(vars.fetchSeqRefVar), true)
+      ),
+    ]),
     types.expressionStatement(
       types.assignmentExpression(
         '+=',
@@ -329,7 +460,7 @@ function buildTrackedFetchBody(
       types.callExpression(types.identifier(vars.setIsFetchingVar), [types.booleanLiteral(true)])
     ),
     types.returnStatement(
-      types.callExpression(types.memberExpression(fetchExpression, types.identifier('finally')), [
+      types.callExpression(types.memberExpression(guardedFetch, types.identifier('finally')), [
         settleHandler,
       ])
     ),