@opentf/afw 0.39.0 → 0.40.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/core/fn-codec.js CHANGED
@@ -10,6 +10,15 @@ export { SerializeError };
10
10
 
11
11
  export const CONTENT_TYPE = "application/json";
12
12
 
13
+ /** The most query calls one action refreshes in its response; the rest go back stale. */
14
+ export const MAX_REFRESH = 20;
15
+
16
+ /** Action request header: the body is `{ input, live }`, `live` the calls the page shows. */
17
+ export const LIVE_HEADER = "x-afw-live";
18
+
19
+ /** Action response header: the body is `{ result, refresh }` (single-flight updates). */
20
+ export const REFRESH_HEADER = "x-afw-refresh";
21
+
13
22
  /** Deepest nesting accepted from a request (`[[1]]` is depth 2). */
14
23
  export const MAX_DEPTH = 64;
15
24
 
package/jsx-runtime.d.ts CHANGED
@@ -15,15 +15,35 @@ export namespace JSX {
15
15
  type ElementType = string | ((props: any, ...rest: any[]) => unknown) | (new (props: any, ...rest: any[]) => unknown) | LazyLoader;
16
16
  /** A lazy loader's props are the props of the component it loads. */
17
17
  type LibraryManagedAttributes<C, P> = C extends LazyLoader ? PropsOf<LazyTarget<C>> : P;
18
- interface IntrinsicAttributes { key?: string | number }
18
+ /**
19
+ * Props every component accepts: `key` for keyed lists, and `ref` for a `$ref()`
20
+ * variable or a signal that receives the component's element (with anything it
21
+ * publishes through `$expose`).
22
+ */
23
+ interface IntrinsicAttributes {
24
+ key?: string | number;
25
+ ref?: unknown;
26
+ }
19
27
 
20
28
  type Handler<E, T extends Event> = (event: T & { currentTarget: E }) => void;
21
29
  type Events<E> = {
22
30
  [K in keyof GlobalEventHandlersEventMap as `on${K}`]?: Handler<E, GlobalEventHandlersEventMap[K]>;
23
31
  } & {
24
32
  [K in keyof GlobalEventHandlersEventMap as `on${Capitalize<K>}`]?: Handler<E, GlobalEventHandlersEventMap[K]>;
33
+ } & {
34
+ [K in keyof GlobalEventHandlersEventMap as `on${K}:${ListenerModifiers}`]?: Handler<E, GlobalEventHandlersEventMap[K]>;
35
+ } & {
36
+ [K in keyof GlobalEventHandlersEventMap as `on${Capitalize<K>}:${ListenerModifiers}`]?: Handler<E, GlobalEventHandlersEventMap[K]>;
25
37
  };
38
+ /**
39
+ * Listener modifiers after a `:`: `capture`, `passive`, `once` or `listen`, combined
40
+ * with `-` (`onclick:once`, `onscroll:once-passive`). Kept as a pattern rather than
41
+ * every combination so each element's props stay small.
42
+ */
43
+ type ListenerModifiers = `${"capture" | "passive" | "once" | "listen"}${string}`;
26
44
  type Common<E> = Events<E> & {
45
+ /** Identifies a row in a keyed list, so an update moves it instead of rebuilding it. */
46
+ key?: string | number;
27
47
  children?: unknown;
28
48
  class?: string | Record<string, unknown> | unknown[];
29
49
  className?: string;
@@ -52,7 +72,31 @@ export namespace JSX {
52
72
  in?: Transition | null | false;
53
73
  out?: Transition | null | false;
54
74
  };
55
- type HTML = { [K in keyof HTMLElementTagNameMap]: Properties<HTMLElementTagNameMap[K]> & Common<HTMLElementTagNameMap[K]> & Transitions };
75
+ /** Invoker commands (`<button commandfor="dialog" command="show-modal">`). */
76
+ type Command = "show-modal" | "close" | "request-close" | "show-popover" | "hide-popover" | "toggle-popover" | `--${string}`;
77
+ /** Controls another element: a popover, a dialog, or an interest target. */
78
+ type Invoker = {
79
+ commandfor?: string;
80
+ command?: Command;
81
+ popovertarget?: string;
82
+ popovertargetaction?: "toggle" | "show" | "hide";
83
+ interestfor?: string;
84
+ };
85
+ /**
86
+ * HTML attributes that have no matching DOM property in TypeScript's DOM types yet
87
+ * (they are written as attributes, as the compiler does for any non-property name).
88
+ */
89
+ type Attributes = {
90
+ button: Invoker;
91
+ input: Invoker & { switch?: boolean };
92
+ dialog: { closedby?: "any" | "closerequest" | "none" };
93
+ };
94
+ /** `popover` on any element: `auto` (light dismiss), `manual`, or `hint`. */
95
+ type Popover = { popover?: "auto" | "manual" | "hint" | "" | boolean | null };
96
+ type HTML = {
97
+ [K in keyof HTMLElementTagNameMap]: Omit<Properties<HTMLElementTagNameMap[K]>, "popover"> & Common<HTMLElementTagNameMap[K]> & Transitions & Popover
98
+ & (K extends keyof Attributes ? Attributes[K] : {});
99
+ };
56
100
  type SVG = { [K in Exclude<keyof SVGElementTagNameMap, keyof HTML>]: Common<SVGElementTagNameMap[K]> & { [attribute: string]: unknown } };
57
101
  type IntrinsicElements = HTML & SVG & {
58
102
  [tag: `${string}-${string}`]: Common<HTMLElement> & { [attribute: string]: unknown };
package/macros.d.ts CHANGED
@@ -19,6 +19,19 @@ declare global {
19
19
  function $context<T>(context: Context<T>): T;
20
20
  /** Publish methods on this component's element for a parent holding its `$ref`. */
21
21
  function $expose(api: Record<string, unknown>): void;
22
+
23
+ // Lifecycle hooks: globals too, wired to the component host by the compiler.
24
+ // The same functions are exported from `@opentf/afw` for code that prefers an import.
25
+ /** Run once the component is connected; a returned function runs on removal. */
26
+ function onMount(callback: () => void | (() => void)): void;
27
+ /** Run when the component is removed from the DOM. */
28
+ function onCleanup(callback: () => void): void;
29
+ /** Run when the component's host element changes size. */
30
+ function onResize(callback: (entry: ResizeObserverEntry) => void): void;
31
+ /** Run with the query's match state on mount and whenever it changes. */
32
+ function onMediaQuery(query: string, callback: (matches: boolean, event: MediaQueryListEvent | undefined) => void): void;
33
+ /** Run when the component's host element enters or leaves the viewport. */
34
+ function onVisibilityChange(callback: (visible: boolean, entry: IntersectionObserverEntry) => void): void;
22
35
  }
23
36
 
24
37
  export {};
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@opentf/afw",
3
- "version": "0.39.0",
3
+ "version": "0.40.0",
4
4
  "description": "The AFW runtime: signals and zero-VDOM DOM bindings, with routing and server rendering.",
5
5
  "type": "module",
6
6
  "scripts": {
package/runtime/dom.d.ts CHANGED
@@ -37,6 +37,8 @@ export function clsx(value: any): any;
37
37
  * else falls back to `setAttribute`.
38
38
  */
39
39
  export function setAttr(el: any, name: any, value: any): void;
40
+ /** Put `node` before `ref` in `parent`, moving it with `moveBefore()` (keeping its state) where supported. */
41
+ export function moveNode(parent: Node, node: Node, ref?: Node | null): void;
40
42
  /**
41
43
  * Apply a named prop to a *child component* element. Set it as a property when the
42
44
  * element exposes one (custom-element prop setters, `value`, `checked`, …) so rich
package/runtime/dom.js CHANGED
@@ -418,6 +418,24 @@ function htmlToNodes(html) {
418
418
  return [...tpl.content.childNodes];
419
419
  }
420
420
 
421
+ /**
422
+ * Put `node` before `ref` in `parent` (at the end when `ref` is null). A node that is
423
+ * already in the document moves with `moveBefore()` where the browser has it, so it keeps
424
+ * its state: focus, a playing video, an iframe's page, running animations. Anything else
425
+ * (a new node, a detached parent, an older browser) is inserted as before.
426
+ */
427
+ export function moveNode(parent, node, ref = null) {
428
+ if (typeof parent.moveBefore === "function" && node.isConnected && parent.isConnected) {
429
+ try {
430
+ parent.moveBefore(node, ref);
431
+ return;
432
+ } catch {
433
+ // A move the browser refuses (across documents, an ancestor into itself): insert.
434
+ }
435
+ }
436
+ parent.insertBefore(node, ref);
437
+ }
438
+
421
439
  /** Flatten a reactive child value into DOM nodes: nodes pass through, arrays
422
440
  * recurse, nullish/booleans render nothing, `{__html}` markers are parsed back into
423
441
  * the nodes the server rendered, and primitives become text nodes. */
@@ -469,7 +487,19 @@ export function hydrateChild(cur, adoptFn, buildFn, depsFn) {
469
487
  claimRegionStart(cur);
470
488
  // Adopt inside a scope so the adopted branch owns its bindings' effects; the
471
489
  // region disposes it when a reactive change swaps the branch out.
472
- const adoptedScope = scope(() => toNodes(adoptFn(cur)));
490
+ const adoptedScope = scope(() => {
491
+ const value = adoptFn(cur);
492
+ // A branch that evaluates to text — `{count && <b/>}` with `count` 0, or
493
+ // `{ok ? <b/> : "none"}` — was written by the server as a text node in the region:
494
+ // claim it rather than build a second one beside it.
495
+ const primitive = typeof value === "string" || typeof value === "number" || typeof value === "bigint";
496
+ if (primitive && cur.node?.nodeType === 3) {
497
+ const text = cur.node;
498
+ cur.node = text.nextSibling;
499
+ return [text];
500
+ }
501
+ return toNodes(value);
502
+ });
473
503
  const anchor = claimRegionEnd(cur);
474
504
  // Seed with the adopted nodes and skip the first effect run's DOM write: the branch is
475
505
  // already in place; from the second run on it swaps normally.
@@ -612,19 +642,20 @@ function reconcileList(anchor, sourceFn, renderItem, keyFn, cache, prevKeys) {
612
642
  // signal every row's class reads). Without this every discarded row
613
643
  // leaves a zombie effect that all later writes keep re-running.
614
644
  const s = scope(() => renderItem(sig, index));
615
- entry = { sig, node: s.result, dispose: s.dispose };
645
+ entry = { sig, node: s.result, nodes: itemNodes(s.result), dispose: s.dispose };
616
646
  prevIndex[index] = -1;
617
647
  }
618
648
  next.set(key, entry);
619
649
  newKeys[index] = key;
620
- nodes[index] = entry.node;
650
+ nodes[index] = entry.nodes ??= itemNodes(entry.node);
621
651
  }
622
652
 
623
653
  // Remove nodes whose keys disappeared, and dispose their bindings.
624
654
  for (const entry of cache.values()) {
625
655
  if (entry.dispose) entry.dispose();
626
- const node = entry.node;
627
- if (node.parentNode && !(tx.leave && tx.leave(node))) node.parentNode.removeChild(node);
656
+ for (const node of entry.nodes ?? itemNodes(entry.node)) {
657
+ if (node.parentNode && !(tx.leave && tx.leave(node))) node.parentNode.removeChild(node);
658
+ }
628
659
  }
629
660
  cache = next;
630
661
  prevKeys = newKeys;
@@ -638,13 +669,16 @@ function reconcileList(anchor, sourceFn, renderItem, keyFn, cache, prevKeys) {
638
669
  const keep = longestIncreasingRun(prevIndex);
639
670
  const host = anchor.parentNode;
640
671
  if (!host) return; // anchor detached (list torn down) — nothing to place
672
+ // Each item is the nodes it rendered: one element, or a fragment's children.
641
673
  for (let i = nodes.length - 1; i >= 0; i--) {
642
674
  if (keep.has(i)) continue;
643
- const ref = i + 1 < nodes.length ? nodes[i + 1] : anchor;
644
- if (nodes[i].nextSibling !== ref) host.insertBefore(nodes[i], ref);
675
+ const ref = i + 1 < nodes.length ? nodes[i + 1][0] : anchor;
676
+ const item = nodes[i];
677
+ if (item[item.length - 1].nextSibling === ref && item.every((n, j) => j === 0 || n.previousSibling === item[j - 1])) continue;
678
+ for (const n of item) moveNode(host, n, ref);
645
679
  }
646
680
  if (tx.enter) {
647
- for (let i = 0; i < nodes.length; i++) if (prevIndex[i] === -1) tx.enter(nodes[i], initial);
681
+ for (let i = 0; i < nodes.length; i++) if (prevIndex[i] === -1) for (const n of nodes[i]) tx.enter(n, initial);
648
682
  }
649
683
  initial = false;
650
684
  });
@@ -657,6 +691,21 @@ function reconcileList(anchor, sourceFn, renderItem, keyFn, cache, prevKeys) {
657
691
  };
658
692
  }
659
693
 
694
+ /**
695
+ * The nodes a list item occupies, taken when it is built (a fragment empties itself into
696
+ * the DOM on insertion, so its children are recorded first). An item that renders nothing
697
+ * holds an empty comment, so it still has a place for its neighbours to be ordered against.
698
+ */
699
+ function itemNodes(result) {
700
+ if (result != null && result.nodeType === 11) {
701
+ const children = [...result.childNodes];
702
+ return children.length ? children : [document.createComment("")];
703
+ }
704
+ if (result instanceof Node) return [result];
705
+ const built = toNodes(result);
706
+ return built.length ? built : [document.createComment("")];
707
+ }
708
+
660
709
  /**
661
710
  * Indices `i` of `seq` whose values form a longest strictly-increasing
662
711
  * subsequence (patience sorting, O(n log n)). Entries equal to -1 (new nodes)
@@ -16,6 +16,7 @@
16
16
 
17
17
  import { reportError } from "../core/errors.js";
18
18
  import { routeErrorHandler } from "./route-errors.js";
19
+ import { toNodes } from "./dom.js";
19
20
 
20
21
  /**
21
22
  * Report a caught render/mount error and route it to the nearest enclosing
@@ -100,8 +101,17 @@ export class ErrorBoundaryElement extends HTMLElement {
100
101
  } catch (e) {
101
102
  reportError(e, { phase: "fallback" });
102
103
  }
104
+ // A string reads as the message inside the built-in fallback. Anything else renders
105
+ // the way a JSX hole would: a node, an array or fragment, or a compiled JSX value
106
+ // (`hydratableNode`, what a server-rendered page's build emits for
107
+ // `fallback={(error, reset) => <div>…</div>}`).
108
+ const nodes = typeof view === "string" ? [] : toNodes(view);
109
+ if (nodes.length) {
110
+ this.append(...nodes);
111
+ return;
112
+ }
103
113
  const message = typeof view === "string" ? view : (error && error.message) || "Something went wrong";
104
- this.appendChild(view instanceof Node ? view : defaultFallback(message, reset));
114
+ this.appendChild(defaultFallback(message, reset));
105
115
  }
106
116
 
107
117
  reset() {
package/runtime/hmr.js CHANGED
@@ -5,8 +5,35 @@
5
5
  // current implementation rather than redefining an existing tag.
6
6
  import { scope } from "../core/signals.js";
7
7
  import { collectHotState, takeHotState, withHotCarry } from "./hot-carry.js";
8
+ import { invalidate } from "./invalidate.js";
8
9
  import { refreshHotRoute } from "./router.js";
9
10
 
11
+ // A server-only edit (a server function, loader, middleware or API route) restarts or
12
+ // reloads the server but leaves the page alone: esdev sends `esdev:server-update` once
13
+ // the new server listens, and vite-plugin-afw sends `afw:server-update`. The page then
14
+ // refetches its data in place (`invalidate()`), keeping component state and scroll.
15
+ const SERVER_EVENTS = ["esdev:server-update", "afw:server-update"];
16
+ let refetchQueued = false;
17
+
18
+ function serverUpdated() {
19
+ // Every route module listens; one refetch covers them all.
20
+ if (refetchQueued) return;
21
+ refetchQueued = true;
22
+ queueMicrotask(() => {
23
+ refetchQueued = false;
24
+ void invalidate();
25
+ });
26
+ }
27
+
28
+ /**
29
+ * Refetch the page's data when the dev server's code changes. Listeners belong to the
30
+ * module that added them and are dropped when it is replaced, so each version adds its own.
31
+ */
32
+ export function watchServerUpdates(hot) {
33
+ if (typeof hot?.on !== "function") return;
34
+ for (const event of SERVER_EVENTS) hot.on(event, serverUpdated);
35
+ }
36
+
10
37
  const components = new Map();
11
38
 
12
39
  // The `$state` slots of the page/layout view currently being built.
@@ -41,6 +68,7 @@ function keep(hot, key, make) {
41
68
  */
42
69
  export function registerHotRoute(hot, factory, shape = "", exports = "", data = {}) {
43
70
  if (!hot) return factory;
71
+ watchServerUpdates(hot);
44
72
  if (hot.data.afwRouteBoundary && hot.data.afwExports !== exports) {
45
73
  hot.data.afwExports = exports;
46
74
  hot.invalidate();
@@ -197,7 +225,22 @@ export function registerHotModule(hot, entries, accept = true, exports = "") {
197
225
  const signature = entries.map(([component, shape]) => [component.tag, shape]);
198
226
  const previous = hot?.data.afwSignature;
199
227
  if (previous && (JSON.stringify(previous) !== JSON.stringify(signature) || hot.data.afwExports !== exports)) {
228
+ // A defined element keeps its class, so a component whose shape changed (a prop
229
+ // added, a state declaration renamed) cannot take the new version in place: the
230
+ // page's elements would keep running the old code. Reload instead.
231
+ const before = new Map(previous);
232
+ const reshaped = entries.some(([component, shape]) =>
233
+ before.has(component.tag) && before.get(component.tag) !== shape && customElements.get(component.tag));
234
+ if (reshaped) {
235
+ hotReload();
236
+ return;
237
+ }
238
+ // The importers re-run against *this* module instance, so install its components
239
+ // first: a renamed or added component's tag must be defined before they render it.
240
+ hot.data.afwSignature = signature;
241
+ hot.data.afwExports = exports;
200
242
  hot.data.afwInvalidated = true;
243
+ install(entries);
201
244
  hot.invalidate();
202
245
  return;
203
246
  }
@@ -206,6 +249,32 @@ export function registerHotModule(hot, entries, accept = true, exports = "") {
206
249
  hot.data.afwExports = exports;
207
250
  hot.data.afwInvalidated = false;
208
251
  }
252
+ const changed = install(entries, hot);
253
+ // Install all implementations first. Refresh existing ancestors before their
254
+ // descendants, so children recreated by a parent don't mount twice per update.
255
+ const jobs = changed.flatMap(record => [...record.instances].map(host => {
256
+ let depth = 0;
257
+ for (let parent = host.parentElement; parent; parent = parent.parentElement) depth++;
258
+ return { record, host, depth };
259
+ }));
260
+ jobs.sort((a, b) => a.depth - b.depth);
261
+ for (const { record, host } of jobs) refresh(record, [host]);
262
+ if (accept) hot?.accept();
263
+ }
264
+
265
+ /** A full page load, for an edit a refresh cannot apply. Replaceable in tests. */
266
+ let hotReload = () => globalThis.location?.reload();
267
+ /** Tests only: observe reloads instead of performing them. */
268
+ export function __setHotReload(fn) {
269
+ hotReload = fn;
270
+ }
271
+
272
+ /**
273
+ * Point each component's tag at its latest implementation: an already registered tag
274
+ * gets the new callbacks (returned, for the caller to refresh its instances), a new tag
275
+ * is defined. `hot`, when given, is invalidated for a tag defined outside this runtime.
276
+ */
277
+ function install(entries, hot = null) {
209
278
  const changed = [];
210
279
  for (const [component] of entries) {
211
280
  const tag = component.tag;
@@ -240,14 +309,5 @@ export function registerHotModule(hot, entries, accept = true, exports = "") {
240
309
  };
241
310
  customElements.define(tag, component);
242
311
  }
243
- // Install all implementations first. Refresh existing ancestors before their
244
- // descendants, so children recreated by a parent don't mount twice per update.
245
- const jobs = changed.flatMap(record => [...record.instances].map(host => {
246
- let depth = 0;
247
- for (let parent = host.parentElement; parent; parent = parent.parentElement) depth++;
248
- return { record, host, depth };
249
- }));
250
- jobs.sort((a, b) => a.depth - b.depth);
251
- for (const { record, host } of jobs) refresh(record, [host]);
252
- if (accept) hot?.accept();
312
+ return changed;
253
313
  }
@@ -39,6 +39,10 @@ export function afterHydration(fn: any): void;
39
39
  * its prop signals, falling back to attributes/defaults when it returns `null`.
40
40
  */
41
41
  export function hydrationProps(el: any): any;
42
+ /** Defer a hydrating component's adoption until its parent sets the function props the payload names. */
43
+ export function awaitHydrationProps(host: HTMLElement): boolean;
44
+ /** Resume a deferred adoption once the parent has set every awaited prop. */
45
+ export function hydrationPropSet(host: HTMLElement, name: string): void;
42
46
  /** Reset the cached payload (tests only — a fresh document between cases). */
43
47
  export function __resetHydrationPayload(): void;
44
48
  /** A walker over `parent`'s children, positioned at the next node to claim. */
@@ -15,6 +15,8 @@
15
15
  // to static text (which the HTML parser would otherwise merge into one text node).
16
16
  // Static structure carries no markers and is claimed by position.
17
17
 
18
+ import { untracked } from "../core/signals.js";
19
+
18
20
  /** Comment markers bounding a dynamic text hole in server HTML. */
19
21
  export const HOLE_START = "$";
20
22
  export const HOLE_END = "/";
@@ -247,6 +249,48 @@ export function hydrationProps(el) {
247
249
  }
248
250
  }
249
251
 
252
+ /**
253
+ * The function props a parent passes to a server-rendered component (`onSave={…}`,
254
+ * `render={(x) => …}`) cannot travel in the payload, which names them instead
255
+ * (`__afwFn`). The component upgrades and would adopt as soon as its module loads, before
256
+ * the parent's hydrate pass sets them, so its adopt walk would bind `undefined` handlers
257
+ * and call missing functions. When any is still unset, this defers the adoption: the
258
+ * parent's assignment of the last one resumes it, still inside the pass. Returns whether
259
+ * the caller (the component's `connectedCallback`) must stop for now. The component's
260
+ * property setters report each assignment through {@link hydrationPropSet}.
261
+ */
262
+ export function awaitHydrationProps(host) {
263
+ if (!_hydrating || host.__afwAwait) return !!host.__afwAwait;
264
+ const names = hydrationProps(host)?.__afwFn;
265
+ if (!Array.isArray(names)) return false;
266
+ // Only declared props: their setters report the assignment (an undeclared one never would).
267
+ const declared = host._props ?? {};
268
+ const missing = names.filter((name) => name in declared && host[name] == null);
269
+ if (missing.length === 0) return false;
270
+ host.__afwAwait = new Set(missing);
271
+ // A parent that never sets one: build from scratch once the pass is over.
272
+ afterHydration(() => {
273
+ if (!host.__afwAwait) return;
274
+ host.__afwAwait = null;
275
+ if (!host.isConnected) return;
276
+ host.replaceChildren();
277
+ untracked(() => host.connectedCallback());
278
+ });
279
+ return true;
280
+ }
281
+
282
+ /** A parent set `name` on `host` (its property setter): resume a deferred adoption once all are in. */
283
+ export function hydrationPropSet(host, name) {
284
+ const waiting = host.__afwAwait;
285
+ if (!waiting) return;
286
+ waiting.delete(name);
287
+ if (waiting.size) return;
288
+ host.__afwAwait = null;
289
+ // Untracked: the parent calls this from its prop effect, which must not subscribe to
290
+ // what the child's adopt walk reads.
291
+ if (host.isConnected) untracked(() => host.connectedCallback());
292
+ }
293
+
250
294
  /** Reset the cached payload (tests only — a fresh document between cases). */
251
295
  export function __resetHydrationPayload() {
252
296
  _payload = undefined;
@@ -7,6 +7,7 @@ export * from "./router.js";
7
7
  export * from "./route-data.js";
8
8
  export * from "./resource.js";
9
9
  export { invalidate } from "./invalidate.js";
10
+ export { optimistic, setQueryData } from "./mutate.js";
10
11
  export { ServerFunctionError, serverFunction } from "./server-function.js";
11
12
  export * from "./context.js";
12
13
  export * from "./error-boundary.js";
package/runtime/index.js CHANGED
@@ -18,6 +18,7 @@ export * from "./router.js";
18
18
  export * from "./route-data.js";
19
19
  export * from "./resource.js";
20
20
  export { invalidate } from "./invalidate.js";
21
+ export { optimistic, setQueryData } from "./mutate.js";
21
22
  export { ServerFunctionError, serverFunction } from "./server-function.js";
22
23
  export * from "./context.js";
23
24
  export * from "./error-boundary.js";
@@ -1,6 +1,9 @@
1
1
  /**
2
- * Refetch the live resources that called any of `fns` (server functions imported from a
3
- * `.server` module). With no arguments: every live resource, and the current page's
4
- * loader data. Browser only; resolves at once on the server.
2
+ * Refetch the live resources that called the given server functions (imported from a
3
+ * `.server` module). A value right after a function narrows it to the call with that
4
+ * input: `invalidate(getTodo, { id: 1 }, listTodos)`. With no arguments: every live
5
+ * resource, and the current page's loader data. Cached entries that are not on screen
6
+ * are marked stale. Browser only; resolves at once on the server. A failed refetch shows
7
+ * on its resource and does not reject.
5
8
  */
6
- export function invalidate(...fns: Array<(...args: any[]) => unknown>): Promise<void>;
9
+ export function invalidate(...targets: unknown[]): Promise<void>;