@jsenv/navi 0.30.10 → 0.30.12

package/dist/dev/jsenv_navi.js

@@ -3977,6 +3977,7 @@ const actionWeakMap = new WeakMap();
  *   long is this still true?" belongs to the question: a court list is good for
  *   the session, a count of people watching grows on its own and is worth a few
  *   minutes, a payment status is worth nothing at all.
+ *   A resource declares it for its reads: `resource()`'s `keep`.
  * @param {Array<Object | { resource: Object, on: string[] }> | (() => Array<Object | { resource: Object, on: string[] }>)} [rootOptions.dependencies] -
  *   the resources whose writes make the answer out of date — a count, a
  *   summary, anything read that is no row of a resource. After a listed write
@@ -4562,9 +4563,10 @@ const createAction = (callback, rootOptions = {}) => {
             }
           }
           runningStateSignal.value = RUNNING;
-          if (!isPrerun) {
-            isPrerunSignal.value = false;
-          }
+          // What fills the instance says what it holds: an answer only a
+          // prerun asked for is one nothing on screen has read yet, and the
+          // run that asks for it next is promoted onto it (see updateActions).
+          isPrerunSignal.value = isPrerun;
         });
 
         const args = [];
@@ -5375,10 +5377,16 @@ const actionRunEffect = (
           runUnwatched(() =>
             actionTarget.run({ reason: "params restored from falsy state" }),
           );
-        } else if (getActionPrivateProperties(actionTarget).keepsAnswers) {
+        } else if (
+          getActionPrivateProperties(actionTarget).keepsAnswers ||
+          actionTarget.isPrerunSignal.peek()
+        ) {
           // The lookup that moved the binding here already reset an answer
           // older than its `keep`: what the instance holds is still good, and
-          // a prerun still out is joined rather than asked again.
+          // a prerun still out is joined rather than asked again. So is an
+          // answer only a prerun asked for, kept or not: asked ahead for this
+          // very arrival (a <RouteTravel prefetch> neighbour), nothing has read
+          // it yet, and the run promotes it.
           runUnwatched(() => actionTarget.run({ reason: "params modified" }));
         } else {
           runUnwatched(() => actionTarget.rerun({ reason: "params modified" }));
@@ -29173,6 +29181,16 @@ const createResourceLifecycleManager = () => {
       }
     }
 
+    // A head start the write made stale is dropped, not asked again: nothing
+    // on screen reads it, and its owner, finding it idle, asks on arriving
+    // instead of promoting what left before the write.
+    for (const action of actionsToRerun) {
+      if (action.isPrerunSignal.peek()) {
+        actionsToRerun.delete(action);
+        actionsToReset.add(action);
+      }
+    }
+
     return {
       actionsToRerun,
       actionsToReset,
@@ -29260,9 +29278,8 @@ const createResourceLifecycleManager = () => {
 // A read to ask again after a write: answered before it landed, or still out —
 // an answer that left before the write is as stale as a completed one, and
 // would replace what the write put in the store (a rerun aborts it and asks
-// again). A head start is its owner's to ask.
+// again). A head start is its owner's to ask (findEffectOnActions resets it).
 const isAnsweredOrAsking = (action, triggeringAction) =>
-  !action.isPrerun &&
   (action.completed || action.runningState === RUNNING) &&
   action !== triggeringAction;
 // A write named in `writes` says for itself which reads of its own resource it
@@ -29994,6 +30011,7 @@ const RESOURCE_OPTIONS = new Set([
   "idKey",
   "uniqueKeys",
   "rerunOn",
+  "keep",
   "dependencies",
   "persist",
   "writes",
@@ -30067,7 +30085,7 @@ const SCOPED_MANY_OPTIONS = new Set([
  * "What a read shows while its params move").
  *
  * @param {string} name - resource name, used in action names and error messages
- * @param {Object} restCallbacks - `{ idKey, uniqueKeys, rerunOn, dependencies, persist, writes, GET, GET_MANY, GET_RANGE, POST, POST_MANY, PUT, PUT_MANY, PATCH, PATCH_MANY, DELETE, DELETE_MANY }`
+ * @param {Object} restCallbacks - `{ idKey, uniqueKeys, rerunOn, keep, dependencies, persist, writes, GET, GET_MANY, GET_RANGE, POST, POST_MANY, PUT, PUT_MANY, PATCH, PATCH_MANY, DELETE, DELETE_MANY }`
  * @param {string} [restCallbacks.idKey] - primary key property, defaults to `"id"`
  * @param {string[]} [restCallbacks.uniqueKeys] - alternate keys the store can find an item by (e.g. `"username"`)
  * @param {Array<Object | { resource: Object, on?: string[], reads?: Array<"GET" | "GET_MANY" | "GET_RANGE"> }> | (() => Array<Object | { resource: Object, on?: string[], reads?: Array<"GET" | "GET_MANY" | "GET_RANGE"> }>)} [restCallbacks.dependencies] -
@@ -30091,6 +30109,22 @@ const SCOPED_MANY_OPTIONS = new Set([
  *   follows `rerunOn` for its verb. A name a verb takes, or one the resource
  *   already exposes (`withParams`, `store`…), throws. A `.scopedOne()` or
  *   `.scopedMany()` takes `writes` too, `.scopedMany()` with the plural verbs.
+ * @param {{ GET?: { ms?: number, max?: number }, GET_MANY?: { ms?: number, max?: number } }} [restCallbacks.keep] -
+ *   how long an answer of a read is trusted, coming back to the same params
+ *   within `ms` asking nothing. Left out, coming back asks again: the right
+ *   default for anything that moves on its own (a count of registrations), and
+ *   worth declaring for what barely does (a description, a finished
+ *   tournament). The store keeps the rows either way, and a `GET` draws the row
+ *   it holds while its request is out, so a kept answer and a fresh one look
+ *   alike: what `keep` saves is the request. Keyed by read, so a list can be
+ *   trusted for less time than an item. The rules are createAction's `keep`:
+ *   `ms` counts from the moment the answer landed, `max` caps the answers held
+ *   at once (the least recently looked-at going first), and past either the
+ *   read is asked again. A write that reruns the read (`rerunOn`,
+ *   `dependencies`) reruns a kept answer too, and the new one counts its `ms`
+ *   again. A `withParams()` scope keeps as its resource does, `max` counted per
+ *   scope; the reads of a relation are questions of their own and keep
+ *   nothing. `GET_RANGE` throws: a range reader holds no answer to keep.
  * @param {{ signal: import("@preact/signals").Signal, when?: () => boolean }} [restCallbacks.persist] -
  *   mirrors the rows `GET` lands with into `signal` — a `stateSignal` with
  *   `persists: true` and `type: "object"` keeps them across a reload, whose
@@ -30131,6 +30165,7 @@ const resource = (name, restCallbacks = {}) => {
     idKey = "id",
     uniqueKeys = [],
     rerunOn,
+    keep,
     dependencies,
     persist,
     writes,
@@ -30150,6 +30185,9 @@ const resource = (name, restCallbacks = {}) => {
   {
     warnUnknownOptions(`resource(${name})`, restCallbacks, RESOURCE_OPTIONS);
   }
+  if (keep) {
+    assertKeepNamesReads(name, keep);
+  }
   const declarationSite = getDeclarationSite();
   const setupCallbackSet = new Set();
   const addItemSetup = (callback) => {
@@ -30274,6 +30312,7 @@ const resource = (name, restCallbacks = {}) => {
     findItemForGet,
     persistence,
     declarationSite,
+    keep,
   });
   return createResource(name, {
     idKey,
@@ -31607,6 +31646,7 @@ const createRestActionFactoryForRoot = (
     findItemForGet,
     persistence,
     declarationSite,
+    keep = {},
   },
 ) => {
   const createActionForRoot = (
@@ -31708,6 +31748,7 @@ const createRestActionFactoryForRoot = (
           : undefined,
       // Another params' answer is another row.
       inheritData: verb !== "GET",
+      keep: verb === "GET" ? keep.GET : undefined,
       completeSideEffect: onActionComplete,
     });
     if (verb === "GET") {
@@ -31739,6 +31780,7 @@ const createRestActionFactoryForRoot = (
       // A binding moving to new params hands over the previous answer: a list
       // standing in for the next one beats a skeleton.
       inheritData: true,
+      keep: verb === "GET" ? keep.GET_MANY : undefined,
       // The rows the page kept from the previous document (kept_reads.js),
       // drawn while the request is out when nothing was handed over.
       provisionalValue:
@@ -31821,6 +31863,24 @@ const applyNetworkPolicy = (
   };
 };
 
+// What can never be kept throws, as a rerunOn that never fires does: a range
+// reader holds no answer, its lists ask again for the window they draw.
+const KEEP_READS = ["GET", "GET_MANY"];
+const assertKeepNamesReads = (name, keep) => {
+  for (const read of Object.keys(keep)) {
+    if (read === "GET_RANGE") {
+      throw new Error(
+        `resource(${name}): keep.GET_RANGE keeps nothing — a range reader holds no answer, its lists ask again for the window they draw`,
+      );
+    }
+    if (!KEEP_READS.includes(read)) {
+      throw new Error(
+        `resource(${name}): keep.${read} is not a read that keeps an answer — keep takes GET and GET_MANY`,
+      );
+    }
+  }
+};
+
 // A `dependencies` given as a function is read before the first request
 // leaves (see item_lifecycle_manager.js).
 const readLazyDependenciesFirst = (restCallback) => {
@@ -85872,6 +85932,7 @@ const css$w = /* css */`@property --list-group-label-height {
 
   &[data-continued] {
     margin-top: calc(-1 * var(--x-list-gap, 0px));
+    grid-template-columns: minmax(0, 1fr);
     display: grid;
 
     & > .navi_list_item_group_label, & > .navi_list_item_group_list {