@symbo.ls/fetch 3.14.661 → 3.14.662

package/index.js

@@ -1,6 +1,8 @@
 'use strict'
 
 import { isArray, isFunction, isObject, isString, exec } from '@symbo.ls/utils'
+import { createEffect } from '@symbo.ls/signal'
+import { dropEarly } from './early.js'
 
 // --- Adapter resolution ---
 
@@ -122,6 +124,16 @@ export const registerAdapter = (name, loader) => {
   }
 }
 
+// Whether `name` resolves without waiting: a built-in, or a custom adapter
+// that has already been registered (in any module copy — CUSTOM_ADAPTERS is
+// the shared globalThis slot). resolveDb() waits up to
+// _ADAPTER_REGISTRATION_TIMEOUT for an unknown name, which is right for a
+// browser boot race and wrong for a server render, where no page runtime will
+// ever register the platform's 'sdk' adapter — @symbo.ls/brender asks first
+// and skips server prefetch instead of stalling every route for 5 s.
+export const hasAdapter = (name) =>
+  typeof name === 'string' && !!(CUSTOM_ADAPTERS[name] || BUILTIN_ADAPTERS[name])
+
 export const createAdapter = (config) => {
   const adapter = {}
   for (const method of ADAPTER_METHODS) {
@@ -189,31 +201,58 @@ const cacheStore = new Map()
 const querySubscribers = new Map() // key -> Set of elements
 const activeQueries = new Map() // key -> Promise (deduplication)
 
+// Request order. Every request a query sends, every cache write and every
+// invalidation takes the next number. A reply then knows whether it is older
+// than its key's last invalidation (its rows may predate the write: kept, but
+// never served as fresh) and whether a request that started after it has
+// already written its answer (that newer answer wins — a slow reply never
+// puts old rows back over it).
+let fetchSeq = 0
+const invalidatedAt = new Map() // key -> seq of the key's last invalidation or removal
+const requestSeqs = new WeakMap() // in-flight promise -> seq of its request
+
+// The cache (and dedup) key of a query. runFetch writes its entry under it and
+// the window-focus check reads it back, so both build it here, from the params
+// RESOLVED with the element (resolveParams: params written as a function, or
+// with function values) — a check that read them unresolved (a function
+// serialises to nothing) never found a fresh entry and ran the query again on
+// every focus, writing the cached rows back into state each time.
 // Cache key includes lang when provided so different-locale responses don't
 // collide. The fetch plugin injects Accept-Language on requests, so the same
 // (from, method, params) tuple yields different bodies per lang. queryClient.
 // dropNonLang(keepLang) leans on this suffix to evict stale-language entries
 // on a setLang() event without touching the kept lang's cache.
-const buildCacheKey = (config, lang, scope) => {
+//
+// The page a request asks for is part of its answer, so `page` (offset pages)
+// and `cursor` (an infinite query's next / previous page) are in the key too,
+// RESOLVED like params (`page: (el, s) => s.page`). The cursor was missing:
+// fetchNextPage asked under page 1's key, so with a cache the next page came
+// back as page 1, and page 2's rows were written over page 1's entry.
+const queryCacheKey = (config, params, scope, lang, page = config.page, cursor = config.cursor) => {
   if (config.cache?.key) return config.cache.key
-  const params = resolveParamsSync(config.params)
+  const { from, method, infinite } = config
   // Scope segment sits AFTER `${from}:${method}:` so `from`/`from:method`
   // prefix matching (mutation `invalidates`, queryClient string patterns)
   // and the trailing lang suffix (dropNonLang) are both preserved.
   const scopeSeg = scope ? `${scope}:` : ''
-  const base = `${config.from}:${config.method}:${scopeSeg}${JSON.stringify(params || '')}`
-  return lang ? `${base}:${lang}` : base
+  const langSuffix = lang ? `:${lang}` : ''
+  const pageSeg = page ? ':p' + JSON.stringify(page) : ''
+  const cursorSeg = cursor !== undefined && cursor !== null ? ':c' + JSON.stringify(cursor) : ''
+  return `${from}:${method}:${scopeSeg}${JSON.stringify(params || '')}${infinite ? ':infinite' : ''}${pageSeg}${cursorSeg}${langSuffix}`
 }
 
 const getCacheEntry = (key) => cacheStore.get(key) || null
 
-const setCacheEntry = (key, data, error) => {
-  const existing = cacheStore.get(key)
+// `seq` is the request the rows came from (a direct write — setQueryData,
+// initialData, a prefetch — is its own, current one); `stale` is set for rows
+// whose request started before the key's last invalidation.
+const setCacheEntry = (key, data, error, seq = ++fetchSeq, stale = false) => {
   const entry = {
     data,
     error,
     time: Date.now(),
-    stale: false
+    stale,
+    seq
   }
   cacheStore.set(key, entry)
 
@@ -228,23 +267,26 @@ const setCacheEntry = (key, data, error) => {
   return entry
 }
 
-const invalidateCache = (key) => {
-  if (key) {
-    const entry = cacheStore.get(key)
-    if (entry) entry.stale = true
-    return
-  }
-  // Invalidate all
-  for (const [, entry] of cacheStore) {
-    entry.stale = true
-  }
+// The entry a request that started after `seq` wrote (an error aside): the
+// newer answer, which an older reply must not replace.
+const newerEntry = (key, seq) => {
+  const entry = key ? cacheStore.get(key) : null
+  return entry && !entry.error && entry.seq > seq ? entry : null
 }
 
+// A request that started before its key's last invalidation (or removal).
+const isOutdated = (key, seq) => (invalidatedAt.get(key) || 0) > seq
+
+// Removing an entry also marks its key, so a reply still in flight writes
+// its rows back as stale, never as fresh.
 const removeCache = (key) => {
   if (key) {
     cacheStore.delete(key)
+    invalidatedAt.set(key, ++fetchSeq)
     return
   }
+  for (const [cacheKey] of cacheStore) invalidatedAt.set(cacheKey, ++fetchSeq)
+  for (const [inFlightKey] of activeQueries) invalidatedAt.set(inFlightKey, ++fetchSeq)
   cacheStore.clear()
 }
 
@@ -275,6 +317,28 @@ const parseCacheConfig = (cache) => {
   }
 }
 
+// --- Mounted queries ---
+//
+// The queries on screen: one record per element and `on: 'create'` query
+// config, registered by executeFetch. An invalidation refetches the ones whose
+// CURRENT key it selects (TanStack's "active" queries) instead of leaving them
+// on the old rows until their next mount or a window focus. The key is
+// computed when needed — the same resolution as the focus check — because
+// params, language and tenant scope can move after mount. A record whose
+// element was removed (`__ref` gone or replaced) is dropped whenever the
+// registry is walked: an invalidation, or the GC sweep.
+const mountedQueries = new Set()
+
+const isMounted = (record) => !!record.ref && record.element.__ref === record.ref
+
+const mountedKey = ({ config, element, context }) => {
+  try {
+    return elementQueryKey(config, element, context)
+  } catch (e) {
+    return null // a params function that throws names no key
+  }
+}
+
 // --- GC ---
 
 let gcTimer = null
@@ -290,6 +354,14 @@ const startGC = () => {
         cacheStore.delete(key)
       }
     }
+    // What nothing can need any more: an invalidation mark matters while its
+    // key has rows or a request out, and a removed element is not mounted.
+    for (const [key] of invalidatedAt) {
+      if (!cacheStore.has(key) && !activeQueries.has(key)) invalidatedAt.delete(key)
+    }
+    for (const record of mountedQueries) {
+      if (!isMounted(record)) mountedQueries.delete(record)
+    }
   }, 30000)
   if (gcTimer.unref) gcTimer.unref()
 }
@@ -301,8 +373,13 @@ startGC()
 const DEFAULT_RETRY = 3
 const DEFAULT_RETRY_DELAY = (attempt) => Math.min(1000 * 2 ** attempt, 30000)
 
-const resolveRetryConfig = (config) => {
+// `write`: the config changes data (insert / update / upsert / delete, an rpc
+// action). A write is not sent again unless `retry` asks for it: one that
+// failed by timing out may have been applied, and a retry applies it twice.
+// Reads keep the default retries.
+const resolveRetryConfig = (config, write) => {
   const retry = config.retry
+  if (retry === undefined && write) return { count: 0 }
   if (retry === false) return { count: 0 }
   if (retry === true || retry === undefined) return { count: DEFAULT_RETRY, delay: DEFAULT_RETRY_DELAY }
   if (typeof retry === 'number') return { count: retry, delay: DEFAULT_RETRY_DELAY }
@@ -389,9 +466,23 @@ const resolveFetchConfig = (fetchProp, element) => {
   return null
 }
 
-const resolveParamsSync = (params) => {
-  if (!params || isFunction(params)) return params
-  return params
+// --- Writes and actions ---
+//
+// insert / update / upsert / delete are writes (runMutation). An `rpc` is a
+// call that may write, so it is an ACTION — sent on every trigger, never
+// answered from or written to the query cache, never re-sent by a refetch or
+// an invalidation, its `invalidates` run on success — when a user event fires
+// it (`on: 'submit'`, `on: 'click'`), when it declares `invalidates`, or with
+// `mutation: true` (which makes any method an action). `mutation: false`
+// keeps an rpc a cached query. An rpc read on create stays what it was: a
+// cached, deduplicated view of data.
+const MUTATION_METHODS = ['insert', 'update', 'upsert', 'delete']
+const isMutationMethod = (method) => MUTATION_METHODS.includes(method)
+
+const isAction = (config) => {
+  if (config.mutation === true) return true
+  if (config.mutation === false || config.method !== 'rpc') return false
+  return config.on === 'submit' || config.on === 'click' || config.invalidates != null
 }
 
 const resolveLanguage = (element, context) => {
@@ -431,6 +522,22 @@ const resolveParams = (params, element, context) => {
   return resolved
 }
 
+// A paging value (`page`, `cursor`) written as a function resolves with the
+// element, as params do. The README's `page: (el, s) => s.page` was never
+// called: it sent no offset, and its key carried no page.
+const resolveValue = (value, element) => (isFunction(value) ? value(element, element.state) : value)
+
+// The key a query of `config` has for `element` right now: the one runFetch
+// writes, the focus check reads, an invalidation matches and keyFor returns.
+const elementQueryKey = (config, element, context) => queryCacheKey(
+  config,
+  resolveParams(config.params, element, context),
+  resolveScope(element, context),
+  resolveLanguage(element, context),
+  resolveValue(config.page, element),
+  resolveValue(config.cursor, element)
+)
+
 export const initAdapterAuth = async (adapter, context) => {
   if (!adapter || adapter.__authInitialized) return
   adapter.__authInitialized = true
@@ -572,11 +679,31 @@ const setFetchStatus = (element, status) => {
   // `TypeError: Cannot set properties of null` from every status write.
   const ref = element?.__ref
   if (!ref) return
-  ref.__fetchStatus = status
+  // `isError` is part of the documented status shape; no call site set it.
+  ref.__fetchStatus = { ...status, isError: !!status.error }
   ref.__fetching = status.isFetching
   ref.__fetchError = status.error
 }
 
+// --- Infinite queries ---
+
+// The next / previous cursor of an infinite query, as documented:
+// getNextPageParam(lastPage, allPages), getPreviousPageParam(firstPage,
+// allPages). Both used to receive the page just fetched, so a previous page
+// moved the next cursor. Called on every reply and when the first page is
+// served from the cache.
+const setPageCursors = (ref, config, fetched) => {
+  const pages = ref.__pages && ref.__pages.length ? ref.__pages : [fetched]
+  if (isFunction(config.getNextPageParam)) {
+    ref.__nextPageParam = config.getNextPageParam(pages[pages.length - 1], pages)
+    ref.__hasNextPage = ref.__nextPageParam != null
+  }
+  if (isFunction(config.getPreviousPageParam)) {
+    ref.__prevPageParam = config.getPreviousPageParam(pages[0], pages)
+    ref.__hasPreviousPage = ref.__prevPageParam != null
+  }
+}
+
 // --- Core fetch runner ---
 
 const runFetch = async (config, element, context, opts = {}) => {
@@ -621,7 +748,7 @@ const runFetch = async (config, element, context, opts = {}) => {
     single, auth, fields, as: stateKey, limit, offset, order,
     headers, baseUrl, responseType,
     // Pagination
-    page, cursor, getNextPageParam, getPreviousPageParam, infinite,
+    page, cursor, infinite,
     // TanStack-style options
     placeholderData, initialData, select: selectTransform,
     keepPreviousData
@@ -634,9 +761,15 @@ const runFetch = async (config, element, context, opts = {}) => {
   }
 
   const params = resolveParams(rawParams, element, context)
-  // No cache key for a single-use body: no cache entry, no dedup sharing.
-  const cacheConfig = isSingleUse(config) ? null : parseCacheConfig(cacheRaw)
-  const retryConfig = resolveRetryConfig(config)
+  const pageValue = resolveValue(page, element)
+  const cursorValue = resolveValue(cursor, element)
+  // An action (isAction) is a call, not a view of data: each trigger sends
+  // exactly one request — a second submit inside the stale time used to be
+  // answered from the cache, unsent.
+  const action = isAction(config)
+  // No cache key for a single-use body or an action: no cache entry, no dedup sharing.
+  const cacheConfig = isSingleUse(config) || action ? null : parseCacheConfig(cacheRaw)
+  const retryConfig = resolveRetryConfig(config, action || isMutationMethod(method))
   const lang = resolveLanguage(element, context)
 
   // Build cache key — lang suffix lets queryClient.dropNonLang(keepLang)
@@ -644,11 +777,7 @@ const runFetch = async (config, element, context, opts = {}) => {
   // scopeSeg (after `${from}:${method}:`) isolates the cache + dedup keys per
   // tenant so an org/workspace switch never serves — or dedup-collapses into —
   // the previous tenant's entry, while keeping `from:method` as the key prefix.
-  const langSuffix = lang ? `:${lang}` : ''
-  const scopeSeg = scope ? `${scope}:` : ''
-  const cacheKey = cacheConfig
-    ? (cacheRaw?.key || `${from}:${method}:${scopeSeg}${JSON.stringify(params || '')}${infinite ? ':infinite' : ''}${page ? ':p' + JSON.stringify(page) : ''}${langSuffix}`)
-    : null
+  const cacheKey = cacheConfig ? queryCacheKey(config, params, scope, lang, pageValue, cursorValue) : null
 
   // Apply initial/placeholder data on first mount
   if (!ref.__fetchInitialized && cacheKey) {
@@ -659,21 +788,35 @@ const runFetch = async (config, element, context, opts = {}) => {
     }
   }
 
-  // Check cache (stale-while-revalidate)
-  if ((method === 'select' || method === 'rpc') && cacheKey && cacheConfig) {
+  // Check cache (stale-while-revalidate). A run that must reach the network
+  // skips it: a refresh (an invalidation refetching a mounted query — the
+  // element shows these rows already) and a forced run (`el.__ref.refetch()`,
+  // refetchInterval, reconnect, fetchNextPage). `force` used to skip only the
+  // dedup, so while the entry was fresh every one of those answered from the
+  // cache and sent nothing — a poll shorter than the stale time never polled.
+  if ((method === 'select' || method === 'rpc') && cacheKey && cacheConfig && !opts.refresh && !opts.force) {
     const cached = getCacheEntry(cacheKey)
     if (cached && !cached.error) {
       const age = Date.now() - cached.time
       const isStale = cached.stale || age > (cacheConfig.staleTime || 0)
+      // An infinite query served from the cache starts its page list there,
+      // with its next / previous cursor, so fetchNextPage can go on from it.
+      if (infinite && isArray(cached.data) && !ref.__pages) {
+        ref.__pages = [cached.data]
+        setPageCursors(ref, config, cached.data)
+      }
       let data = cached.data
       if (isFunction(selectTransform)) data = selectTransform(data, element, element.state)
       if (transform) data = transform(data, element, element.state)
       if (!isCurrent()) return
-      updateElementState(element, data, stateKey)
+      // The status first: the state update re-renders, and a render that
+      // reads `__fetchStatus` must see the answer it renders (report #25).
       if (!isStale) {
         setFetchStatus(element, { isFetching: false, isLoading: false, isStale: false, isSuccess: true, error: null, status: 'success', fetchStatus: 'idle' })
+        updateElementState(element, data, stateKey)
         return
       }
+      updateElementState(element, data, stateKey)
       // Stale — continue to background refetch
     } else if (placeholderData !== undefined) {
       const phData = isFunction(placeholderData) ? placeholderData(element, element.state) : placeholderData
@@ -683,14 +826,29 @@ const runFetch = async (config, element, context, opts = {}) => {
     }
   }
 
-  // Deduplication — if same query is already in-flight, share the promise (with timeout)
-  if (cacheKey && activeQueries.has(cacheKey) && !opts.force) {
-    const existing = activeQueries.get(cacheKey)
+  // Deduplication — if same query is already in-flight, share the promise (with
+  // timeout). Never one that started before the key's last invalidation: its
+  // reply may predate the write.
+  const existing = cacheKey && !opts.force ? activeQueries.get(cacheKey) : null
+  if (existing && !isOutdated(cacheKey, requestSeqs.get(existing) || 0)) {
+    // The shared request failed: so did this query, with the same error. It
+    // used to read an error answer as null rows (onFetchComplete(null)) and a
+    // thrown one as nothing at all.
+    const fail = (error) => {
+      setFetchStatus(element, { isFetching: false, isLoading: false, isStale: false, isSuccess: false, error, status: 'error', fetchStatus: 'idle' })
+      triggerCallback(element, 'onFetchError', error)
+      triggerConfigCallback(config, element, 'onFetchError', error)
+    }
     try {
       const result = await Promise.race([existing, new Promise((_, r) => setTimeout(() => r('DEDUP_TIMEOUT'), 15000))])
       if (!isCurrent()) return
-      if (result?.data !== undefined) {
-        let finalData = result.data
+      if (result?.error) {
+        fail(result.error)
+      } else if (result?.data !== undefined) {
+        // A request that started later (an invalidation's refetch) may have
+        // landed first: its rows are the newer answer.
+        const newer = !infinite && newerEntry(cacheKey, requestSeqs.get(existing) || 0)
+        let finalData = newer ? newer.data : result.data
         if (isFunction(selectTransform)) finalData = selectTransform(finalData, element, element.state)
         if (transform) finalData = transform(finalData, element, element.state)
         if (!isCurrent()) return
@@ -700,7 +858,9 @@ const runFetch = async (config, element, context, opts = {}) => {
       }
     } catch (e) {
       if (!isCurrent()) return
-      // Error handled by the original caller
+      // A dedup timeout is no error of the request: this query only stopped
+      // waiting for it.
+      if (e !== 'DEDUP_TIMEOUT') fail(e)
     }
     return
   }
@@ -750,21 +910,21 @@ const runFetch = async (config, element, context, opts = {}) => {
       request.headers = { ...request.headers, 'Accept-Language': lang }
     }
 
-    // Pagination support
-    if (page !== undefined) {
-      if (isObject(page)) {
-        if (page.offset !== undefined) request.offset = page.offset
-        if (page.limit !== undefined) request.limit = page.limit
-        if (page.cursor !== undefined) request.params = { ...request.params, cursor: page.cursor }
-      } else if (typeof page === 'number') {
+    // Pagination support (the values resolved with the element, as the key is)
+    if (pageValue !== undefined) {
+      if (isObject(pageValue)) {
+        if (pageValue.offset !== undefined) request.offset = pageValue.offset
+        if (pageValue.limit !== undefined) request.limit = pageValue.limit
+        if (pageValue.cursor !== undefined) request.params = { ...request.params, cursor: pageValue.cursor }
+      } else if (typeof pageValue === 'number') {
         const pageSize = config.pageSize || limit || 20
-        request.offset = (page - 1) * pageSize
+        request.offset = (pageValue - 1) * pageSize
         request.limit = pageSize
       }
     }
 
-    if (cursor !== undefined) {
-      request.params = { ...request.params, cursor }
+    if (cursorValue !== undefined) {
+      request.params = { ...request.params, cursor: cursorValue }
     }
 
     if (method === 'insert' || method === 'update' || method === 'upsert') {
@@ -794,9 +954,20 @@ const runFetch = async (config, element, context, opts = {}) => {
           : formData
       }
       request.params = rpcParams
+      // A cached rpc query is a read; an action may write. The REST adapter
+      // sends a `read` rpc as a GET when its `reads.rpc` says the backend
+      // serves those (no CORS preflight); `read: false` keeps one a POST.
+      request.read = !action && config.read !== false
     }
 
     if (method === 'subscribe') {
+      // One subscription per element: a re-run (`el.__ref.refetch()`) closes
+      // the one it replaces instead of opening a second beside it.
+      if (isFunction(ref.__unsubscribe)) {
+        const close = ref.__unsubscribe
+        ref.__unsubscribe = null
+        try { close() } catch (e) { /* the old stream is gone either way */ }
+      }
       const unsubscribe = adapter.subscribe(
         { from, params, on: config.subscribeOn },
         (newData, oldData, payload) => {
@@ -818,20 +989,28 @@ const runFetch = async (config, element, context, opts = {}) => {
   }
 
   // Execute with retry
+  const requestSeq = ++fetchSeq
   const fetchPromise = withRetry(doFetch, retryConfig)
+  requestSeqs.set(fetchPromise, requestSeq)
 
   // Store for deduplication
   if (cacheKey) activeQueries.set(cacheKey, fetchPromise)
 
   try {
     const result = await fetchPromise
+    // An action's write happened whatever became of the element that fired
+    // it (a dialog that closed on submit): its `invalidates` runs on success.
+    if (action && config.invalidates && result && !result.error && !result.subscribed) {
+      runInvalidates(config.invalidates, from)
+    }
     if (!isCurrent()) return
     if (result?.subscribed) return
 
     const { data, error } = result || {}
 
     if (error) {
-      if (cacheKey) setCacheEntry(cacheKey, null, error)
+      // An older request's failure never replaces a newer answer.
+      if (cacheKey && !newerEntry(cacheKey, requestSeq)) setCacheEntry(cacheKey, null, error, requestSeq)
       setFetchStatus(element, { isFetching: false, isLoading: false, isStale: false, isSuccess: false, error, status: 'error', fetchStatus: 'idle' })
       triggerCallback(element, 'onFetchError', error)
       triggerConfigCallback(config, element, 'onFetchError', error)
@@ -844,45 +1023,54 @@ const runFetch = async (config, element, context, opts = {}) => {
     }
 
     if (data !== undefined) {
+      let rows = data
       // Update cache
       if ((method === 'select' || method === 'rpc') && cacheKey) {
-        const entry = setCacheEntry(cacheKey, data, null)
-        entry.gcTime = cacheConfig?.gcTime || 300000
+        // A request that started later has written its newer rows already:
+        // show those, leave the cache alone. (Not for an infinite query —
+        // each of its replies is one page, not the whole answer.)
+        const newer = !infinite && newerEntry(cacheKey, requestSeq)
+        if (newer) {
+          rows = newer.data
+        } else {
+          // Invalidated while this request was out: kept, never served as fresh.
+          const entry = setCacheEntry(cacheKey, data, null, requestSeq, isOutdated(cacheKey, requestSeq))
+          entry.gcTime = cacheConfig?.gcTime || 300000
+        }
       }
 
-      let finalData = data
+      let finalData = rows
 
       // Infinite query — append pages
       if (infinite && isArray(data)) {
-        if (!ref.__pages) ref.__pages = []
+        // Any run that is not a next / previous step — a refetch, an
+        // invalidation's refresh, a stale cache's revalidation — asks for the
+        // first page and starts the list again. Appending it to the loaded
+        // pages listed it twice.
+        if (!ref.__pages || !opts.direction) ref.__pages = []
         if (opts.direction === 'previous') {
           ref.__pages.unshift(data)
         } else {
           ref.__pages.push(data)
         }
         finalData = ref.__pages.flat()
-
-        // Resolve pagination cursors
-        if (getNextPageParam) {
-          ref.__nextPageParam = getNextPageParam(data, ref.__pages)
-          ref.__hasNextPage = ref.__nextPageParam != null
-        }
-        if (getPreviousPageParam) {
-          ref.__prevPageParam = getPreviousPageParam(data, ref.__pages)
-          ref.__hasPreviousPage = ref.__prevPageParam != null
-        }
+        setPageCursors(ref, config, data)
       }
 
       if (isFunction(selectTransform)) finalData = selectTransform(finalData, element, element.state)
       if (transform) finalData = transform(finalData, element, element.state)
       if (!isCurrent()) return
 
+      // The status first: the state update re-renders, and a render that
+      // reads `__fetchStatus` saw the request still pending beside its own
+      // rows (report #25).
+      setFetchStatus(element, { isFetching: false, isLoading: false, isStale: false, isSuccess: true, error: null, status: 'success', fetchStatus: 'idle' })
+
       // keepPreviousData — don't clear state while fetching new page
       if (!keepPreviousData || finalData !== undefined) {
         updateElementState(element, finalData, stateKey)
       }
 
-      setFetchStatus(element, { isFetching: false, isLoading: false, isStale: false, isSuccess: true, error: null, status: 'success', fetchStatus: 'idle' })
       triggerCallback(element, 'onFetchComplete', finalData)
       triggerConfigCallback(config, element, 'onFetchComplete', finalData)
       if (_emitNet) _emitNet({
@@ -911,6 +1099,8 @@ const runFetch = async (config, element, context, opts = {}) => {
 const bindEvent = (config, element, context) => {
   const on = config.on
   const ref = element.__ref
+  // Bound a microtask after create: the element may have been removed since.
+  if (!ref) return
   if (!ref.__fetchListeners) ref.__fetchListeners = []
   const runner = config.__runner || runFetch
 
@@ -932,10 +1122,49 @@ const bindEvent = (config, element, context) => {
       ref.__fetchListeners.push(() => node.removeEventListener('click', handler))
     }
   } else if (on === 'stateChange') {
-    ref.__fetchOnStateChange = () => runner(config, element, context)
+    bindStateChange(config, element, context, runner)
   }
 }
 
+// `on: 'stateChange'` — the query runs when the state it reads changes
+// (search as you type). It never fired: the pre-v4 runtime called
+// `ref.__fetchOnStateChange()` from the element's update(), the signal rewrite
+// dropped that call, and a signal-only state change fires no update hook.
+// Its inputs — params, `enabled`, `skip`, `page`, resolved as a request would
+// — are read inside a signal effect, which subscribes to exactly the state
+// they read (helmet's metadata effect works the same way); a change of their
+// values runs the query. Never on create (that is `on: 'create'`) and never
+// for its own rows: they land in state while its inputs stay as they were.
+// The effect is one of the element's `__ref.__effects`, so dispose() stops it.
+const bindStateChange = (config, element, context, runner) => {
+  const ref = element.__ref
+  let last
+  const effect = createEffect(() => {
+    let inputs
+    try {
+      inputs = JSON.stringify([
+        resolveParams(config.params, element, context) ?? null,
+        isFunction(config.enabled) ? !!config.enabled(element, element.state) : config.enabled !== false,
+        isFunction(config.skip) ? !!config.skip(element, element.state) : config.skip === true,
+        resolveValue(config.page, element) ?? null
+      ])
+    } catch (e) {
+      return // an input that throws names no request
+    }
+    if (last === undefined) {
+      last = inputs
+      return
+    }
+    if (inputs === last) return
+    last = inputs
+    // Outside the effect: the run reads state as well, and none of that may
+    // become the effect's dependency.
+    Promise.resolve().then(() => runner(config, element, context))
+  })
+  if (Array.isArray(ref.__effects)) ref.__effects.push(effect)
+  else ref.__fetchListeners.push(() => effect.dispose())
+}
+
 // --- Refetch interval / focus / reconnect binding ---
 
 const bindAutoRefetch = (config, element, context) => {
@@ -969,9 +1198,7 @@ const bindAutoRefetch = (config, element, context) => {
   // refetchOnWindowFocus
   if (onFocusEnabled) {
     const onFocus = () => {
-      const lang = resolveLanguage(element, context)
-      const scope = resolveScope(element, context)
-      const cacheKey = buildCacheKey(config, lang, scope)
+      const cacheKey = elementQueryKey(config, element, context)
       const entry = getCacheEntry(cacheKey)
       const cacheConfig = parseCacheConfig(config.cache)
       if (!entry || entry.stale || (Date.now() - entry.time) > (cacheConfig?.staleTime || 0)) {
@@ -1012,8 +1239,13 @@ const applyOptimisticUpdate = (element, config, mutationData) => {
   return snapshot
 }
 
+// Rolls back only what `optimistic` applied, and never on a removed element
+// (a dialog that closed while its write was out): the write failing used to
+// call this for every mutation, and read `__ref` of a removed one — a
+// TypeError in the failure path.
 const rollbackOptimistic = (element, config) => {
   const ref = element.__ref
+  if (!ref || !config.optimistic) return
   const snapshot = ref.__optimisticSnapshot
   if (snapshot !== undefined) {
     updateElementState(element, snapshot, config.as)
@@ -1021,6 +1253,91 @@ const rollbackOptimistic = (element, config) => {
   }
 }
 
+// --- Invalidation ---
+
+// Which keys a match selects — one rule for queryClient, the project
+// functions and a write's `invalidates`: nothing (every key), a key prefix or
+// substring, a list of key parts (joined with ':'), a RegExp, or a predicate
+// `(key) => boolean`.
+const keyMatcher = (match) => {
+  if (!match) return () => true
+  if (isString(match)) return (key) => key.includes(match)
+  if (isArray(match)) {
+    const parts = match.join(':')
+    return (key) => key.includes(parts)
+  }
+  if (match instanceof RegExp) {
+    return (key) => {
+      match.lastIndex = 0 // a /g pattern keeps its position between tests
+      return match.test(key)
+    }
+  }
+  if (isFunction(match)) {
+    // A predicate that throws selects nothing: it must not turn the write
+    // whose `invalidates` it is into a failed one.
+    return (key) => {
+      try { return !!match(key) } catch (e) { return false }
+    }
+  }
+  return () => false
+}
+
+// Refetch the mounted queries whose current key `matches` selects. The first
+// on a key sends the request; the others on that key share it through the
+// dedup, which never shares a request that started before the key's
+// invalidation — so no one is handed the pre-write rows.
+const refreshMounted = (matches) => {
+  const runs = []
+  for (const record of mountedQueries) {
+    if (!isMounted(record)) {
+      mountedQueries.delete(record)
+      continue
+    }
+    const key = mountedKey(record)
+    if (key && matches(key)) runs.push(runFetch(record.config, record.element, record.context, { refresh: true }))
+  }
+  return Promise.allSettled(runs).then(() => {})
+}
+
+// Mark every key `matches` selects as invalidated — its cache entry stale, and
+// a first load still in flight outdated — then refetch the mounted queries on
+// those keys; resolves once those refetches settle. The answers the pre-boot
+// script asked for (early.js) are dropped as well: an invalidation means a
+// write happened, and they may predate it.
+const invalidateMatching = (matches) => {
+  dropEarly()
+  for (const [key, entry] of cacheStore) {
+    if (!matches(key)) continue
+    entry.stale = true
+    invalidatedAt.set(key, ++fetchSeq)
+  }
+  for (const [key] of activeQueries) {
+    if (!cacheStore.has(key) && matches(key)) invalidatedAt.set(key, ++fetchSeq)
+  }
+  return refreshMounted(matches)
+}
+
+// A write's `invalidates`: `true` or '*' selects every query of the write's
+// own `from`; anything else — or each item of a list — is a match as
+// invalidateQueries takes it. (Whole keys only, before: the documented
+// `invalidates: ['posts']` matched no real key.)
+const runInvalidates = (invalidates, from) => {
+  const matchers = (isArray(invalidates) ? invalidates : [invalidates]).map((match) => {
+    if (match === true || match === '*') return (key) => key.startsWith(from + ':')
+    return match ? keyMatcher(match) : () => false
+  })
+  return invalidateMatching((key) => matchers.some((matches) => matches(key)))
+}
+
+const removeMatching = (matches) => {
+  for (const [key] of cacheStore) {
+    if (matches(key)) removeCache(key)
+  }
+  for (const [key] of activeQueries) {
+    if (matches(key)) invalidatedAt.set(key, ++fetchSeq)
+  }
+}
+
 // --- Mutation runner (insert/update/delete with optimistic + invalidation) ---
 
 const runMutation = async (config, element, context) => {
@@ -1089,7 +1406,7 @@ const runMutation = async (config, element, context) => {
       request.headers = { ...request.headers, 'Accept-Language': lang }
     }
 
-    const retryConfig = resolveRetryConfig(config)
+    const retryConfig = resolveRetryConfig(config, true)
     const result = await withRetry(() => fn(request), retryConfig)
     const { data, error } = result || {}
 
@@ -1109,13 +1426,15 @@ const runMutation = async (config, element, context) => {
 
     delete ref.__optimisticSnapshot
 
+    // The status first, as for a query: the state update re-renders.
+    setFetchStatus(element, { isFetching: false, isLoading: false, isStale: false, isSuccess: true, error: null, status: 'success', fetchStatus: 'idle' })
+
     // A body value (Blob, stream, …) lands in state only under `as`.
     if (data !== undefined && (stateKey || !isBodyValue(data))) {
       const finalData = stateKey ? { [stateKey]: data } : data
       if (element.state?.update) element.state.update(finalData, { preventFetch: true })
     }
 
-    setFetchStatus(element, { isFetching: false, isLoading: false, isStale: false, isSuccess: true, error: null, status: 'success', fetchStatus: 'idle' })
     triggerCallback(element, 'onFetchComplete', data)
     triggerConfigCallback(config, element, 'onFetchComplete', data)
     if (isFunction(onSuccess)) onSuccess(data, mutationData, element)
@@ -1125,20 +1444,8 @@ const runMutation = async (config, element, context) => {
       durationMs: (typeof performance !== 'undefined' ? performance.now() : Date.now()) - __analyzeStart
     })
 
-    // Invalidate related queries
-    if (invalidates) {
-      const keys = isArray(invalidates) ? invalidates : [invalidates]
-      for (const k of keys) {
-        if (k === true || k === '*') {
-          // Invalidate all queries matching this `from`
-          for (const [ck] of cacheStore) {
-            if (ck.startsWith(from + ':')) invalidateCache(ck)
-          }
-        } else {
-          invalidateCache(k)
-        }
-      }
-    }
+    // Invalidate related queries — the mounted ones refetch now
+    if (invalidates) runInvalidates(invalidates, from)
   } catch (e) {
     if (snapshot !== undefined) rollbackOptimistic(element, config)
     setFetchStatus(element, { isFetching: false, isLoading: false, isStale: false, isSuccess: false, error: e, status: 'error', fetchStatus: 'idle' })
@@ -1158,6 +1465,24 @@ const runMutation = async (config, element, context) => {
 
 // --- Public API ---
 
+// What the plugin bound for an element: the auto-refetch interval and the
+// window focus / online listeners (bindAutoRefetch), the submit / click
+// listeners (bindEvent), the realtime subscription and the mounted-query
+// records. dispose() calls this unguarded, so nothing here may throw.
+const releaseFetch = (ref) => {
+  const release = (cleanup) => {
+    try { cleanup() } catch (e) { /* one cleanup never stops the rest */ }
+  }
+  for (const cleanup of ref.__fetchCleanups || []) release(cleanup)
+  for (const cleanup of ref.__fetchListeners || []) release(cleanup)
+  if (isFunction(ref.__unsubscribe)) release(ref.__unsubscribe)
+  for (const record of ref.__fetchMounted || []) mountedQueries.delete(record)
+  ref.__fetchCleanups = []
+  ref.__fetchListeners = []
+  ref.__unsubscribe = null
+  ref.__fetchMounted = []
+}
+
 export const executeFetch = (param, element, state, context) => {
   if (!param) return
   const db = context?.fetch
@@ -1170,9 +1495,32 @@ export const executeFetch = (param, element, state, context) => {
     ? fetchProp.map(c => resolveFetchConfig(exec(c, element), element)).filter(Boolean)
     : [resolveFetchConfig(fetchProp, element)].filter(Boolean)
 
+  // This element's mounted queries (refetched by an invalidation). A re-run
+  // replaces its configs, so it replaces their records too.
+  const ref = element.__ref
+  if (ref.__fetchMounted) {
+    for (const record of ref.__fetchMounted) mountedQueries.delete(record)
+  }
+  ref.__fetchMounted = []
+
+  // Released with the element. dispose() — the one way an element leaves —
+  // calls every `__ref.__effects` entry (helmet's head layers use the same
+  // path; the element package sends plugins no remove hook). The interval,
+  // the window focus / online listeners and a realtime subscription used to
+  // outlive their element. An entry without `_execute` is skipped by the
+  // update levers that re-run effects.
+  if (!ref.__fetchDisposer && isArray(ref.__effects)) {
+    ref.__fetchDisposer = { dispose: () => releaseFetch(ref) }
+    ref.__effects.push(ref.__fetchDisposer)
+  }
+
   for (const config of configs) {
-    const isMutation = config.method === 'insert' || config.method === 'update' || config.method === 'upsert' || config.method === 'delete'
+    const isMutation = isMutationMethod(config.method)
     const runner = isMutation ? runMutation : runFetch
+    // An action never re-sends itself: no refetch on focus, reconnect or an
+    // interval, and an invalidation does not fire it again. Nor does a live
+    // subscription — each re-run opened a second one beside the first.
+    const isQuery = !isMutation && !isAction(config) && config.method !== 'subscribe'
 
     if (config.on === 'create') {
       runner(config, element, context)
@@ -1183,15 +1531,20 @@ export const executeFetch = (param, element, state, context) => {
     }
 
     // Bind auto-refetch for queries
-    if (!isMutation && config.on === 'create') {
+    if (isQuery && config.on === 'create') {
       if (config.refetchInterval || config.refetchOnWindowFocus !== false || config.refetchOnReconnect !== false) {
         bindAutoRefetch(config, element, context)
       }
+      // A single-use body has no cache key to invalidate.
+      if (!isSingleUse(config)) {
+        const record = { element, ref, config, context }
+        mountedQueries.add(record)
+        ref.__fetchMounted.push(record)
+      }
     }
   }
 
   // Expose imperative methods on element
-  const ref = element.__ref
   ref.refetch = (opts) => {
     for (const config of configs) {
       runFetch(config, element, context, { force: true, ...opts })
@@ -1220,37 +1573,20 @@ export const executeFetch = (param, element, state, context) => {
 // --- Query client (global cache management) ---
 
 export const queryClient = {
-  invalidateQueries: (keyOrPattern) => {
-    if (!keyOrPattern) {
-      invalidateCache()
-      return
-    }
-    if (isString(keyOrPattern)) {
-      for (const [key] of cacheStore) {
-        if (key.startsWith(keyOrPattern) || key.includes(keyOrPattern)) {
-          invalidateCache(key)
-        }
-      }
-    } else if (isArray(keyOrPattern)) {
-      const pattern = keyOrPattern.join(':')
-      for (const [key] of cacheStore) {
-        if (key.includes(pattern)) invalidateCache(key)
-      }
-    }
-  },
-
+  // Marks every matching entry stale and refetches the mounted queries on
+  // those keys; resolves once those refetches settle. `keyOrPattern`: nothing
+  // (every key), a key prefix or substring, a list of key parts (joined with
+  // ':'), a RegExp, or a predicate `(key) => boolean`.
+  invalidateQueries: (keyOrPattern) => invalidateMatching(keyMatcher(keyOrPattern)),
+
+  // Drops every matching entry (same matches). A mounted query keeps the rows
+  // it shows; the next mount loads them afresh.
   removeQueries: (keyOrPattern) => {
     if (!keyOrPattern) {
       removeCache()
       return
     }
-    if (isString(keyOrPattern)) {
-      for (const [key] of cacheStore) {
-        if (key.startsWith(keyOrPattern) || key.includes(keyOrPattern)) {
-          removeCache(key)
-        }
-      }
-    }
+    removeMatching(keyMatcher(keyOrPattern))
   },
 
   getQueryData: (key) => {
@@ -1271,8 +1607,15 @@ export const queryClient = {
     const adapter = await resolveAdapter(db, context)
     if (!adapter) return
 
-    const cacheKey = config.cache?.key || `${config.from}:${config.method || 'select'}:${JSON.stringify(config.params || '')}`
-    const fn = adapter[config.method || 'select']
+    // The key — and the request — a declarative query of this config builds
+    // in this context: its tenant scope and language (queryCacheKey, as
+    // runFetch does). The key used to carry neither, so an element with a
+    // language never read what was prefetched for it.
+    const method = config.method || 'select'
+    const scope = resolveScope(null, context)
+    const lang = resolveLanguage(null, context)
+    const cacheKey = queryCacheKey({ ...config, method }, config.params, scope, lang)
+    const fn = adapter[method]
     if (!isFunction(fn)) return
 
     const request = {
@@ -1285,11 +1628,17 @@ export const queryClient = {
       headers: config.headers,
       baseUrl: config.baseUrl
     }
+    if (lang) request.headers = { ...request.headers, 'Accept-Language': lang }
     if (config.responseType !== undefined) request.responseType = config.responseType
+    // A prefetched rpc is the query a mount reads: a read, as in runFetch.
+    if (method === 'rpc') request.read = !isAction(config) && config.read !== false
+    const requestSeq = ++fetchSeq
     const result = await fn(request)
 
-    if (result?.data !== undefined && !result?.error && !isSingleUse(config)) {
-      const entry = setCacheEntry(cacheKey, result.data, null)
+    // Ordered like a query's reply: never over newer rows, stale when the key
+    // was invalidated while the prefetch was out.
+    if (result?.data !== undefined && !result?.error && !isSingleUse(config) && !newerEntry(cacheKey, requestSeq)) {
+      const entry = setCacheEntry(cacheKey, result.data, null, requestSeq, isOutdated(cacheKey, requestSeq))
       entry.gcTime = parseCacheConfig(config.cache)?.gcTime || 300000
     }
 
@@ -1324,6 +1673,28 @@ export const queryClient = {
   }
 }
 
+// --- Project functions ---
+//
+// The query cache's controls for project code. smbls registers these into
+// `context.functions` whenever `context.fetch` is set (createDomql), so a
+// component reaches them as `el.call('invalidateQueries', 'articles')`:
+// project code cannot import `queryClient` — frank serializes an import of
+// @symbo.ls/fetch to a stub. Same names and matches as queryClient. `this` is
+// the calling element: given a fetch config instead of a key, getQueryData /
+// setQueryData use the key that element would build for it (its params
+// resolved, its language, its tenant scope).
+const keyFor = (keyOrConfig, element) => {
+  if (!isObject(keyOrConfig)) return keyOrConfig
+  return elementQueryKey({ method: 'select', ...keyOrConfig }, element, element?.context)
+}
+
+export const fetchFunctions = {
+  invalidateQueries (keyOrPattern) { return queryClient.invalidateQueries(keyOrPattern) },
+  removeQueries (keyOrPattern) { return queryClient.removeQueries(keyOrPattern) },
+  getQueryData (keyOrConfig) { return queryClient.getQueryData(keyFor(keyOrConfig, this)) },
+  setQueryData (keyOrConfig, updater) { return queryClient.setQueryData(keyFor(keyOrConfig, this), updater) }
+}
+
 // --- Plugin interface ---
 
 /**