@farm.js/core 0.1.0-beta.95 → 0.1.0-beta.97

package/dist/api.cjs

@@ -75,7 +75,13 @@ function recordFarmEventTrace(event) {
       activeSpan.addEvent(event.type, toEventAttributes(event), event.timestamp);
     }
     const error = event.type === "request.error" ? void 0 : getEventError(event);
-    if (error !== void 0) recordSpanError(activeSpan, error);
+    if (error !== void 0) {
+      if (event.type === "render.error") {
+        recordSpanException(activeSpan, error);
+      } else {
+        recordSpanError(activeSpan, error);
+      }
+    }
   }
   const completedTraceContext = recordCompletedEventSpan(event, activeContext);
   return traceContext ?? completedTraceContext;
@@ -169,12 +175,25 @@ function getCompletedSpanDescriptor(event) {
       return void 0;
   }
 }
+function hashFarmCacheKey(value) {
+  let hash = 2166136261;
+  for (let index = 0; index < value.length; index++) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
 function toEventAttributes(event) {
   const attributes = {};
+  const redactKey = typeof event.type === "string" && event.type.startsWith("cache.");
   for (const [key, value] of Object.entries(event)) {
     if (key === "timestamp" || key === "level" || key === "error" || key === "traceId" || key === "spanId" || key === "traceSampled" || value === void 0) {
       continue;
     }
+    if (redactKey && key === "key" && typeof value === "string") {
+      attributes["farm.key_hash"] = hashFarmCacheKey(value);
+      continue;
+    }
     if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
       attributes[`farm.${key}`] = value;
     } else if (Array.isArray(value)) {
@@ -192,9 +211,13 @@ function toEventAttributes(event) {
 function getEventError(event) {
   return "error" in event ? event.error : void 0;
 }
-function recordSpanError(span, error) {
+function recordSpanException(span, error) {
   const normalized = error instanceof Error ? error : new Error(String(error));
   span.recordException(normalized);
+  return normalized;
+}
+function recordSpanError(span, error) {
+  const normalized = recordSpanException(span, error);
   span.setStatus({ code: import_api.SpanStatusCode.ERROR, message: normalized.message });
 }
 function setResponseStatus(span, status) {
@@ -245,8 +268,10 @@ var init_tracing = __esm({
     __name(recordFarmEventTrace, "recordFarmEventTrace");
     __name(recordCompletedEventSpan, "recordCompletedEventSpan");
     __name(getCompletedSpanDescriptor, "getCompletedSpanDescriptor");
+    __name(hashFarmCacheKey, "hashFarmCacheKey");
     __name(toEventAttributes, "toEventAttributes");
     __name(getEventError, "getEventError");
+    __name(recordSpanException, "recordSpanException");
     __name(recordSpanError, "recordSpanError");
     __name(setResponseStatus, "setResponseStatus");
     __name(getSpanTraceContext, "getSpanTraceContext");
@@ -393,15 +418,27 @@ function getFarmCacheInvalidationState() {
     taskListeners: /* @__PURE__ */ new Set()
   });
 }
+function warnFarmCacheListenerError(scope, error) {
+  const detail = error instanceof Error ? error.stack ?? error.message : String(error);
+  console.warn(`[farm:cache] ${scope} listener failed: ${detail}`);
+}
 function notifyFarmCacheInvalidation(key) {
   if (typeof key !== "string" || key.length === 0) return;
   for (const listener of getFarmCacheInvalidationState().listeners) {
-    listener(key);
+    try {
+      listener(key);
+    } catch (error) {
+      warnFarmCacheListenerError("invalidation", error);
+    }
   }
 }
 function notifyFarmCacheTask(task) {
   for (const listener of getFarmCacheInvalidationState().taskListeners) {
-    listener(task);
+    try {
+      listener(task);
+    } catch (error) {
+      warnFarmCacheListenerError("task", error);
+    }
   }
 }
 function applyFarmCacheInvalidations(keys) {
@@ -443,6 +480,7 @@ var init_cache_invalidation = __esm({
     FARM_CACHE_INVALIDATION_STATE = /* @__PURE__ */ Symbol.for("farm.cacheInvalidationState");
     globalState = globalThis;
     __name(getFarmCacheInvalidationState, "getFarmCacheInvalidationState");
+    __name(warnFarmCacheListenerError, "warnFarmCacheListenerError");
     __name(notifyFarmCacheInvalidation, "notifyFarmCacheInvalidation");
     __name(notifyFarmCacheTask, "notifyFarmCacheTask");
     __name(applyFarmCacheInvalidations, "applyFarmCacheInvalidations");
@@ -2250,6 +2288,7 @@ __export(api_exports, {
   POST: () => POST,
   PUT: () => PUT,
   QUERY: () => QUERY,
+  applyServerFnOptimisticUpdates: () => applyServerFnOptimisticUpdates,
   createAPIClient: () => createAPIClient,
   createApiClients: () => createApiClients,
   createEndpoint: () => createEndpoint,
@@ -2278,6 +2317,8 @@ __export(api_exports, {
   resolveFarmAPIRequestURL: () => resolveFarmAPIRequestURL,
   resolveFarmAPIServerBasePath: () => resolveFarmAPIServerBasePath,
   resolvePluginRoutes: () => resolvePluginRoutes,
+  resolveServerFnInvalidateTargets: () => resolveServerFnInvalidateTargets,
+  settleServerFnOptimisticUpdates: () => settleServerFnOptimisticUpdates,
   toFormData: () => toFormData
 });
 module.exports = __toCommonJS(api_exports);
@@ -2323,12 +2364,15 @@ function jsonStream(source, init = {}) {
   const iterator = toAsyncIterator(source);
   const encoder = new TextEncoder();
   let finished = false;
+  let cleanup;
+  const closeSource = /* @__PURE__ */ __name((reason) => cleanup ?? (cleanup = Promise.resolve().then(() => iterator.return?.(reason))), "closeSource");
   const body = new ReadableStream(
     {
       async pull(controller) {
         if (finished) return;
         try {
           const next = await iterator.next();
+          if (finished) return;
           if (next.done) {
             finished = true;
             controller.close();
@@ -2337,9 +2381,10 @@ function jsonStream(source, init = {}) {
           controller.enqueue(encoder.encode(`${JSON.stringify(next.value)}
 `));
         } catch (error) {
+          if (finished) return;
           finished = true;
           try {
-            await iterator.return?.(error);
+            await closeSource(error);
           } catch {
           }
           controller.error(error);
@@ -2347,7 +2392,7 @@ function jsonStream(source, init = {}) {
       },
       async cancel(reason) {
         finished = true;
-        await iterator.return?.(reason);
+        await closeSource(reason);
       }
     },
     {
@@ -2380,6 +2425,7 @@ function readJSONStream(response) {
   const decoder = new TextDecoder();
   let buffer = "";
   let completed = false;
+  let cancelled = false;
   let claimed = false;
   let released = false;
   const releaseReader = /* @__PURE__ */ __name(() => {
@@ -2399,39 +2445,54 @@ function readJSONStream(response) {
       throw error;
     }
   }, "parseLine");
-  const iterator = {
-    async next() {
-      while (true) {
-        const lineEnd = buffer.indexOf("\n");
-        if (lineEnd >= 0) {
-          const line = buffer.slice(0, lineEnd).trim();
-          buffer = buffer.slice(lineEnd + 1);
-          if (!line) continue;
-          return { done: false, value: await parseLine(line) };
-        }
-        if (completed) {
-          const line = buffer.trim();
-          buffer = "";
-          if (!line) {
-            releaseReader();
-            return { done: true, value: void 0 };
-          }
-          return { done: false, value: await parseLine(line) };
-        }
-        let chunk;
-        try {
-          chunk = await reader.read();
-        } catch (error) {
-          completed = true;
-          buffer = "";
+  const readNext = /* @__PURE__ */ __name(async () => {
+    while (true) {
+      if (cancelled) return { done: true, value: void 0 };
+      const lineEnd = buffer.indexOf("\n");
+      if (lineEnd >= 0) {
+        const line = buffer.slice(0, lineEnd).trim();
+        buffer = buffer.slice(lineEnd + 1);
+        if (!line) continue;
+        return { done: false, value: await parseLine(line) };
+      }
+      if (completed) {
+        const line = buffer.trim();
+        buffer = "";
+        if (!line) {
           releaseReader();
-          throw error;
+          return { done: true, value: void 0 };
         }
-        completed = chunk.done;
-        buffer += decoder.decode(chunk.value, { stream: !chunk.done });
+        return { done: false, value: await parseLine(line) };
+      }
+      let chunk;
+      try {
+        chunk = await reader.read();
+      } catch (error) {
+        if (cancelled) return { done: true, value: void 0 };
+        completed = true;
+        buffer = "";
+        releaseReader();
+        throw error;
       }
+      if (cancelled) return { done: true, value: void 0 };
+      completed = chunk.done;
+      buffer += decoder.decode(chunk.value, { stream: !chunk.done });
+    }
+  }, "readNext");
+  let readQueue = Promise.resolve();
+  const iterator = {
+    next() {
+      const result = readQueue.then(readNext);
+      readQueue = result.then(
+        () => {
+        },
+        () => {
+        }
+      );
+      return result;
     },
     async return() {
+      cancelled = true;
       completed = true;
       buffer = "";
       if (!released) {
@@ -2447,6 +2508,7 @@ function readJSONStream(response) {
   return {
     response,
     async cancel(reason) {
+      cancelled = true;
       completed = true;
       buffer = "";
       if (!released) {
@@ -2573,6 +2635,7 @@ function createEndpoint(pathOrOptions, optionsOrHandler, maybeHandler) {
     body: options.body,
     inputBody: isMultipartSchema(options.body) ? "form-data" : options.body,
     query: options.query,
+    inputQuery: options.query,
     headers: options.headers,
     response: null,
     errors
@@ -4904,7 +4967,8 @@ async function executeServerOperation(operation, input, options, requestOptions,
         serverRequestOptions?.baseURL ?? options.baseURL,
         request
       );
-      const url = new URL(operation.path, baseURL);
+      const origin = resolveServerBaseURL(void 0, request);
+      const url = new URL(operation.path, new URL(baseURL, origin));
       appendQuery(url, input.query);
       const headers = new Headers();
       appendHeaders(
@@ -4957,7 +5021,9 @@ async function executeServerOperation(operation, input, options, requestOptions,
       }
       appendIntegrationClientDataHeader(headers, data);
       const body = createOperationBody(operation, input.body, headers);
-      const response = await (options.fetch ?? fetch)(url.toString(), {
+      const httpURL = resolveFarmAPIRequestURL(operation.path, baseURL, origin);
+      appendQuery(httpURL, input.query);
+      const response = await (options.fetch ?? fetch)(httpURL.toString(), {
         method: operation.method,
         headers,
         body,
@@ -5143,6 +5209,7 @@ __name(createServerNamespaceProxy, "createServerNamespaceProxy");
 // src/client-cache.ts
 init_cache();
 init_cache_invalidation();
+var invalidationTrackers = /* @__PURE__ */ new WeakMap();
 var cacheFinalizer = typeof FinalizationRegistry === "function" ? new FinalizationRegistry((unsubscribe) => unsubscribe()) : void 0;
 function subscribeWeakCache(reference) {
   const unsubscribe = subscribeFarmCacheInvalidation((key) => {
@@ -5158,6 +5225,7 @@ function subscribeWeakCache(reference) {
   return dispose;
 }
 __name(subscribeWeakCache, "subscribeWeakCache");
+var DEFAULT_GC_SWEEP_INTERVAL_MS = 3e4;
 var _FarmClientDataCache = class _FarmClientDataCache {
   constructor(options = {}) {
     this.entries = /* @__PURE__ */ new Map();
@@ -5165,6 +5233,7 @@ var _FarmClientDataCache = class _FarmClientDataCache {
     this.invalidatedAt = /* @__PURE__ */ new Map();
     this.listeners = /* @__PURE__ */ new Map();
     this.inflight = /* @__PURE__ */ new Map();
+    this.gcSweepIntervalMs = options.gcSweepIntervalMs ?? DEFAULT_GC_SWEEP_INTERVAL_MS;
     if (options.subscribeToInvalidation !== false) {
       if (typeof WeakRef === "function") {
         const reference = new WeakRef(this);
@@ -5181,6 +5250,10 @@ var _FarmClientDataCache = class _FarmClientDataCache {
   get size() {
     return this.entries.size;
   }
+  /** @internal Attach or detach the persistence engine's observation sink. */
+  attachPersistence(sink) {
+    this.persistence = sink;
+  }
   resolveKey(key) {
     let resolved = key;
     const seen = /* @__PURE__ */ new Set();
@@ -5196,6 +5269,7 @@ var _FarmClientDataCache = class _FarmClientDataCache {
     if (!entry) return void 0;
     if (entry.gcAt !== void 0 && now >= entry.gcAt) {
       this.entries.delete(resolved);
+      this.persistence?.onDelete(resolved);
       this.emit(resolved);
       return void 0;
     }
@@ -5209,6 +5283,8 @@ var _FarmClientDataCache = class _FarmClientDataCache {
       this.invalidatedAt.delete(resolved);
     }
     this.entries.set(resolved, nextEntry);
+    if (nextEntry.gcAt !== void 0) this.scheduleGcSweep();
+    this.persistence?.onSet(resolved, nextEntry);
     this.emit(resolved);
     return this;
   }
@@ -5216,6 +5292,7 @@ var _FarmClientDataCache = class _FarmClientDataCache {
     const resolved = this.resolveKey(key);
     const deleted = this.entries.delete(resolved);
     this.inflight.delete(resolved);
+    if (deleted) this.persistence?.onDelete(resolved);
     this.emit(resolved);
     return deleted;
   }
@@ -5225,11 +5302,16 @@ var _FarmClientDataCache = class _FarmClientDataCache {
     this.aliases.clear();
     this.invalidatedAt.clear();
     this.inflight.clear();
+    this.persistence?.onClear();
     for (const key of keys) this.emit(key);
   }
   dispose() {
     this.unsubscribeInvalidation?.();
     this.unsubscribeInvalidation = void 0;
+    if (this.gcTimer !== void 0) {
+      clearTimeout(this.gcTimer);
+      this.gcTimer = void 0;
+    }
     this.clear();
   }
   isStale(key, now = Date.now()) {
@@ -5238,6 +5320,7 @@ var _FarmClientDataCache = class _FarmClientDataCache {
   }
   invalidate(key, now = Date.now()) {
     const resolved = this.resolveKey(key);
+    for (const keys of invalidationTrackers.get(this) ?? []) keys.add(resolved);
     this.invalidatedAt.set(resolved, now);
     const entry = this.entries.get(resolved);
     if (entry) {
@@ -5257,8 +5340,9 @@ var _FarmClientDataCache = class _FarmClientDataCache {
     const resolvedInvalidatedAt = this.invalidatedAt.get(resolved);
     if (aliasEntry && !this.entries.has(resolved)) {
       this.entries.set(resolved, aliasEntry);
+      this.persistence?.onSet(resolved, aliasEntry);
     }
-    this.entries.delete(alias);
+    if (this.entries.delete(alias)) this.persistence?.onDelete(alias);
     this.invalidatedAt.delete(alias);
     const invalidatedAt = [aliasInvalidatedAt, resolvedInvalidatedAt].reduce(
       (latest, value) => value === void 0 ? latest : latest === void 0 ? value : Math.max(latest, value),
@@ -5298,7 +5382,9 @@ var _FarmClientDataCache = class _FarmClientDataCache {
     listeners.add(listener);
     return () => {
       listeners.delete(listener);
-      if (listeners.size === 0) this.listeners.delete(key);
+      if (listeners.size === 0 && this.listeners.get(key) === listeners) {
+        this.listeners.delete(key);
+      }
     };
   }
   getInflight(key) {
@@ -5310,6 +5396,30 @@ var _FarmClientDataCache = class _FarmClientDataCache {
   deleteInflight(key) {
     this.inflight.delete(this.resolveKey(key));
   }
+  scheduleGcSweep() {
+    if (this.gcSweepIntervalMs === false || this.gcTimer !== void 0) return;
+    const timer = setTimeout(() => {
+      this.gcTimer = void 0;
+      this.sweepExpiredEntries();
+    }, this.gcSweepIntervalMs);
+    timer.unref?.();
+    this.gcTimer = timer;
+  }
+  sweepExpiredEntries(now = Date.now()) {
+    const watched = /* @__PURE__ */ new Set();
+    for (const key of this.listeners.keys()) watched.add(this.resolveKey(key));
+    let remaining = false;
+    for (const [key, entry] of this.entries) {
+      if (entry.gcAt === void 0) continue;
+      if (now < entry.gcAt || entry.fetching || this.inflight.has(key) || watched.has(key)) {
+        remaining = true;
+        continue;
+      }
+      this.entries.delete(key);
+      this.persistence?.onDelete(key);
+    }
+    if (remaining) this.scheduleGcSweep();
+  }
   emit(key, event) {
     this.notifyListeners(key, event);
     for (const [alias, target] of this.aliases) {
@@ -5588,69 +5698,6 @@ function createAPIClientRuntime(options = {}, transport) {
   let scopedRequestState;
   const routeMeta = transport?.routeMeta ?? /* @__PURE__ */ new WeakMap();
   let requestCounter = 0;
-  const applyOptimisticLayer = /* @__PURE__ */ __name((entry, layer) => {
-    let data = entry?.data;
-    for (const updater of layer.updaters) data = updater(data);
-    return {
-      data,
-      updatedAt: layer.updatedAt,
-      staleAt: entry?.staleAt ?? layer.staleAt,
-      gcAt: entry?.gcAt ?? layer.gcAt,
-      invalidatedAt: entry?.invalidatedAt
-    };
-  }, "applyOptimisticLayer");
-  const storeOptimisticEntry = /* @__PURE__ */ __name((cacheState, key, stack, entry) => {
-    if (!entry) {
-      cacheState.delete(key);
-      stack.renderedEntry = void 0;
-      return;
-    }
-    cacheState.set(key, entry);
-    if (stack.invalidatedAt !== void 0) {
-      cacheState.invalidate(key, stack.invalidatedAt);
-    }
-    stack.renderedEntry = cacheState.get(key);
-  }, "storeOptimisticEntry");
-  const reconcileOptimisticInvalidation = /* @__PURE__ */ __name((cacheState, key, stack) => {
-    const current = cacheState.get(key);
-    const rendered = stack.renderedEntry;
-    if (current === rendered) return true;
-    if (!current || !rendered || current.data !== rendered.data || current.updatedAt !== rendered.updatedAt || current.gcAt !== rendered.gcAt || current.status !== rendered.status || current.error !== rendered.error || current.fetching !== rendered.fetching || current.staleAt !== 0 || current.invalidatedAt === void 0) {
-      return false;
-    }
-    stack.invalidatedAt = current.invalidatedAt;
-    stack.renderedEntry = current;
-    return true;
-  }, "reconcileOptimisticInvalidation");
-  const renderOptimisticStack = /* @__PURE__ */ __name((cacheState, key, stack) => {
-    let entry = stack.entry ? { ...stack.entry } : void 0;
-    for (const layer of stack.layers) entry = applyOptimisticLayer(entry, layer);
-    storeOptimisticEntry(cacheState, key, stack, entry);
-  }, "renderOptimisticStack");
-  const settleOptimisticUpdates = /* @__PURE__ */ __name((cacheState, optimisticState, snapshots, outcome) => {
-    const settledKeys = [];
-    for (const snapshot of snapshots) {
-      const stack = optimisticState.get(snapshot.key);
-      if (stack !== snapshot.stack) continue;
-      if (!reconcileOptimisticInvalidation(cacheState, snapshot.key, stack)) {
-        optimisticState.delete(snapshot.key);
-        continue;
-      }
-      if (outcome === "rollback") {
-        stack.layers = stack.layers.filter((layer) => layer !== snapshot.layer);
-      } else {
-        snapshot.layer.committed = true;
-        if (outcome === "invalidate") stack.invalidatedAt = Date.now();
-      }
-      while (stack.layers[0]?.committed) {
-        stack.entry = applyOptimisticLayer(stack.entry, stack.layers.shift());
-      }
-      renderOptimisticStack(cacheState, snapshot.key, stack);
-      if (stack.layers.length === 0) optimisticState.delete(snapshot.key);
-      settledKeys.push(snapshot.key);
-    }
-    return settledKeys;
-  }, "settleOptimisticUpdates");
   const fetchClient = /* @__PURE__ */ __name(async (path4, requestOptions, defaultHeaders, cancellation) => {
     const url = resolveFarmAPIRequestURL(path4, baseURL);
     const method = String(requestOptions.method || "GET").toUpperCase();
@@ -5883,6 +5930,9 @@ function createAPIClientRuntime(options = {}, transport) {
       const executeNetwork = /* @__PURE__ */ __name(async (opts) => {
         const release = cancellation.hold();
         let unsubscribeInvalidation;
+        let readOwners;
+        let readOwner;
+        const resolvedCacheKey = cacheState.resolveKey(cacheKey);
         try {
           const dedupeMs = cacheOptions?.dedupeMs ?? 0;
           const inflight = inflightState.get(cacheKey);
@@ -5906,6 +5956,9 @@ function createAPIClientRuntime(options = {}, transport) {
           }
           let invalidatedDuringRequest = false;
           if (isCacheEnabled) {
+            readOwners = getCacheReadOwners(cacheState);
+            readOwner = {};
+            readOwners.set(resolvedCacheKey, readOwner);
             unsubscribeInvalidation = cacheState.subscribe(cacheKey, (event) => {
               if (event === "invalidate") invalidatedDuringRequest = true;
             });
@@ -6013,15 +6066,27 @@ function createAPIClientRuntime(options = {}, transport) {
           inflightState.set(cacheKey, inflightEntry);
           try {
             const result2 = await promise;
-            if (inflightState.get(cacheKey) === inflightEntry && !invalidatedDuringRequest && !result2.error && isCacheEnabled && !isFarmAPIStream(result2.data)) {
+            if (inflightState.get(cacheKey) === inflightEntry && readOwners?.get(resolvedCacheKey) === readOwner && !invalidatedDuringRequest && !result2.error && isCacheEnabled && !isFarmAPIStream(result2.data)) {
               const updatedAt = Date.now();
-              cacheState.set(cacheKey, {
+              const cached = {
                 data: result2.data,
                 updatedAt,
                 staleAt: updatedAt + staleTime,
                 gcAt: getGcAt(updatedAt, cacheOptions?.gcTime),
-                invalidatedAt: void 0
-              });
+                invalidatedAt: void 0,
+                persist: cacheOptions?.persist === true ? true : void 0,
+                [API_CACHE_REFETCH]: createCacheRefetch(
+                  request,
+                  path4,
+                  method,
+                  input,
+                  cacheKey,
+                  cacheOptions,
+                  clientOptions,
+                  options.onError
+                )
+              };
+              cacheState.set(cacheKey, cached);
             }
             if (result2.error) {
               emitStatus("error", { error: result2.error, isBackground: opts?.isBackground });
@@ -6049,6 +6114,9 @@ function createAPIClientRuntime(options = {}, transport) {
             }
           }
         } finally {
+          if (readOwner && readOwners?.get(resolvedCacheKey) === readOwner) {
+            readOwners.delete(resolvedCacheKey);
+          }
           unsubscribeInvalidation?.();
           release();
         }
@@ -6059,6 +6127,7 @@ function createAPIClientRuntime(options = {}, transport) {
           targets: clientOptions.invalidate.targets,
           refetch: clientOptions.invalidate.refetch ?? false
         };
+        const refetches = /* @__PURE__ */ new Set();
         for (const target of invalidateOptions.targets) {
           const targetKey = resolveTargetKey(
             routeMeta,
@@ -6070,20 +6139,22 @@ function createAPIClientRuntime(options = {}, transport) {
           );
           if (!targetKey) continue;
           const existing = cacheState.get(targetKey);
+          const invalidatedAt = Date.now();
+          cacheState.invalidate(targetKey, invalidatedAt);
           if (existing) {
-            const invalidatedAt = Date.now();
             const stack = optimisticState.get(targetKey);
-            cacheState.invalidate(targetKey, invalidatedAt);
             if (stack?.renderedEntry === existing) {
               stack.invalidatedAt = invalidatedAt;
               stack.renderedEntry = cacheState.get(targetKey);
             }
           }
           emitStatus("invalidated", { key: targetKey });
-          if (invalidateOptions.refetch && existing && targetKey === cacheKey) {
-            void executeNetwork({ isBackground: true, callCallbacks: false });
+          const refetch = existing?.[API_CACHE_REFETCH];
+          if (invalidateOptions.refetch && refetch) {
+            refetches.add(refetch);
           }
         }
+        for (const refetch of refetches) refetch();
       }, "invalidateTargets");
       const optimisticSnapshots = requestContextError ? [] : applyOptimisticUpdates();
       if (isCacheEnabled && !requestContextError && !cancellation.signal?.aborted) {
@@ -6317,7 +6388,31 @@ function createServerAPIClient(endpoints, options = {}) {
   return endpoints;
 }
 __name(createServerAPIClient, "createServerAPIClient");
+var API_CACHE_REFETCH = /* @__PURE__ */ Symbol.for("farm.api.cache-refetch");
+function createCacheRefetch(request, path4, method, input, key, cache, options, onError) {
+  const readOptions = {
+    cache: { ...cache, key, policy: "network-only", dedupeMs: 0 },
+    retry: options?.retry,
+    timeoutMs: options?.timeoutMs
+  };
+  return () => {
+    void request(path4, method, input, readOptions).catch((error) => {
+      notifyClientObserver(onError, [normalizeError(error)]);
+    });
+  };
+}
+__name(createCacheRefetch, "createCacheRefetch");
 var optimisticStates = /* @__PURE__ */ new WeakMap();
+var cacheReadOwners = /* @__PURE__ */ new WeakMap();
+function getCacheReadOwners(cache) {
+  let owners = cacheReadOwners.get(cache);
+  if (!owners) {
+    owners = /* @__PURE__ */ new Map();
+    cacheReadOwners.set(cache, owners);
+  }
+  return owners;
+}
+__name(getCacheReadOwners, "getCacheReadOwners");
 function getOptimisticState(cache) {
   let state = optimisticStates.get(cache);
   if (!state) {
@@ -6327,6 +6422,151 @@ function getOptimisticState(cache) {
   return state;
 }
 __name(getOptimisticState, "getOptimisticState");
+function applyOptimisticLayer(entry, layer) {
+  let data = entry?.data;
+  for (const updater of layer.updaters) data = updater(data);
+  return {
+    data,
+    updatedAt: layer.updatedAt,
+    staleAt: entry?.staleAt ?? layer.staleAt,
+    gcAt: entry?.gcAt ?? layer.gcAt,
+    invalidatedAt: entry?.invalidatedAt,
+    [API_CACHE_REFETCH]: entry?.[API_CACHE_REFETCH]
+  };
+}
+__name(applyOptimisticLayer, "applyOptimisticLayer");
+function storeOptimisticEntry(cacheState, key, stack, entry) {
+  if (!entry) {
+    cacheState.delete(key);
+    stack.renderedEntry = void 0;
+    return;
+  }
+  cacheState.set(key, entry);
+  if (stack.invalidatedAt !== void 0) {
+    cacheState.invalidate(key, stack.invalidatedAt);
+  }
+  stack.renderedEntry = cacheState.get(key);
+}
+__name(storeOptimisticEntry, "storeOptimisticEntry");
+function reconcileOptimisticInvalidation(cacheState, key, stack) {
+  const current = cacheState.get(key);
+  const rendered = stack.renderedEntry;
+  if (current === rendered) return true;
+  if (!current || !rendered || current.data !== rendered.data || current.updatedAt !== rendered.updatedAt || current.gcAt !== rendered.gcAt || current.status !== rendered.status || current.error !== rendered.error || current.fetching !== rendered.fetching || current.staleAt !== 0 || current.invalidatedAt === void 0) {
+    return false;
+  }
+  stack.invalidatedAt = current.invalidatedAt;
+  stack.renderedEntry = current;
+  return true;
+}
+__name(reconcileOptimisticInvalidation, "reconcileOptimisticInvalidation");
+function renderOptimisticStack(cacheState, key, stack) {
+  let entry = stack.entry ? { ...stack.entry } : void 0;
+  for (const layer of stack.layers) entry = applyOptimisticLayer(entry, layer);
+  storeOptimisticEntry(cacheState, key, stack, entry);
+}
+__name(renderOptimisticStack, "renderOptimisticStack");
+function settleOptimisticUpdates(cacheState, optimisticState, snapshots, outcome) {
+  const settledKeys = [];
+  for (const snapshot of snapshots) {
+    const stack = optimisticState.get(snapshot.key);
+    if (stack !== snapshot.stack) continue;
+    if (!reconcileOptimisticInvalidation(cacheState, snapshot.key, stack)) {
+      optimisticState.delete(snapshot.key);
+      continue;
+    }
+    if (outcome === "rollback") {
+      stack.layers = stack.layers.filter((layer) => layer !== snapshot.layer);
+    } else {
+      snapshot.layer.committed = true;
+      if (outcome === "invalidate") stack.invalidatedAt = Date.now();
+    }
+    while (stack.layers[0]?.committed) {
+      stack.entry = applyOptimisticLayer(stack.entry, stack.layers.shift());
+    }
+    renderOptimisticStack(cacheState, snapshot.key, stack);
+    if (stack.layers.length === 0) optimisticState.delete(snapshot.key);
+    settledKeys.push(snapshot.key);
+  }
+  return settledKeys;
+}
+__name(settleOptimisticUpdates, "settleOptimisticUpdates");
+function applyServerFnOptimisticUpdates(updates, now = Date.now()) {
+  const cacheState = getFarmClientDataCache();
+  const optimisticState = getOptimisticState(cacheState);
+  const snapshots = /* @__PURE__ */ new Map();
+  for (const update of updates) {
+    if (update.length !== 2) continue;
+    const [target, updater] = update;
+    if (typeof updater !== "function") continue;
+    const targetKey = typeof target === "string" || Array.isArray(target) ? normalizeFarmClientCacheKey(target) : null;
+    if (!targetKey) continue;
+    const targetEntry = getValidCacheEntry(cacheState, targetKey, now);
+    const currentEntry = cacheState.get(targetKey);
+    let stack = optimisticState.get(targetKey);
+    if (stack && !reconcileOptimisticInvalidation(cacheState, targetKey, stack)) {
+      stack = void 0;
+    }
+    if (!stack) {
+      stack = {
+        entry: targetEntry ? { ...targetEntry } : void 0,
+        layers: [],
+        renderedEntry: currentEntry
+      };
+      optimisticState.set(targetKey, stack);
+    }
+    let snapshot = snapshots.get(targetKey);
+    if (!snapshot) {
+      const previousEntry = stack.layers.length === 0 ? stack.entry : stack.renderedEntry;
+      const layer = {
+        updaters: [],
+        updatedAt: now,
+        // A server function has no cache policy of its own; preserve the
+        // target read's freshness metadata when it exists.
+        staleAt: targetEntry?.staleAt ?? now,
+        gcAt: targetEntry?.gcAt
+      };
+      stack.layers.push(layer);
+      snapshot = { key: targetKey, stack, layer };
+      snapshots.set(targetKey, snapshot);
+      snapshot.layer.updaters.push(updater);
+      const nextEntry2 = applyOptimisticLayer(previousEntry, {
+        ...snapshot.layer,
+        updaters: [updater]
+      });
+      storeOptimisticEntry(cacheState, targetKey, stack, nextEntry2);
+      continue;
+    }
+    snapshot.layer.updaters.push(updater);
+    const nextEntry = applyOptimisticLayer(stack.renderedEntry, {
+      ...snapshot.layer,
+      updaters: [updater]
+    });
+    storeOptimisticEntry(cacheState, targetKey, stack, nextEntry);
+  }
+  return Array.from(snapshots.values());
+}
+__name(applyServerFnOptimisticUpdates, "applyServerFnOptimisticUpdates");
+function settleServerFnOptimisticUpdates(snapshots, outcome) {
+  if (snapshots.length === 0) return;
+  const cacheState = getFarmClientDataCache();
+  settleOptimisticUpdates(cacheState, getOptimisticState(cacheState), snapshots, outcome);
+}
+__name(settleServerFnOptimisticUpdates, "settleServerFnOptimisticUpdates");
+function resolveServerFnInvalidateTargets(invalidate2) {
+  const targets = Array.isArray(invalidate2) ? invalidate2 : invalidate2.targets;
+  const keys = [];
+  for (const target of targets) {
+    if (typeof target === "string" || Array.isArray(target)) {
+      if (Array.isArray(target) && typeof target[0] === "function") continue;
+      keys.push(normalizeFarmClientCacheKey(target));
+    } else if (target && typeof target === "object" && "key" in target) {
+      keys.push(normalizeFarmClientCacheKey(target.key));
+    }
+  }
+  return keys;
+}
+__name(resolveServerFnInvalidateTargets, "resolveServerFnInvalidateTargets");
 function buildCacheKey(method, path4, input, baseURL, defaultHeaders) {
   const keyInput = input && typeof input === "object" ? {
     query: input.query,
@@ -7286,6 +7526,7 @@ __name(farmApiPlugin, "farmApiPlugin");
   POST,
   PUT,
   QUERY,
+  applyServerFnOptimisticUpdates,
   createAPIClient,
   createApiClients,
   createEndpoint,
@@ -7314,6 +7555,8 @@ __name(farmApiPlugin, "farmApiPlugin");
   resolveFarmAPIRequestURL,
   resolveFarmAPIServerBasePath,
   resolvePluginRoutes,
+  resolveServerFnInvalidateTargets,
+  settleServerFnOptimisticUpdates,
   toFormData
 });
 //# sourceMappingURL=api.cjs.map