@jsenv/navi 0.30.11 → 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
@@ -30010,6 +30011,7 @@ const RESOURCE_OPTIONS = new Set([
   "idKey",
   "uniqueKeys",
   "rerunOn",
+  "keep",
   "dependencies",
   "persist",
   "writes",
@@ -30083,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] -
@@ -30107,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
@@ -30147,6 +30165,7 @@ const resource = (name, restCallbacks = {}) => {
     idKey = "id",
     uniqueKeys = [],
     rerunOn,
+    keep,
     dependencies,
     persist,
     writes,
@@ -30166,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) => {
@@ -30290,6 +30312,7 @@ const resource = (name, restCallbacks = {}) => {
     findItemForGet,
     persistence,
     declarationSite,
+    keep,
   });
   return createResource(name, {
     idKey,
@@ -31623,6 +31646,7 @@ const createRestActionFactoryForRoot = (
     findItemForGet,
     persistence,
     declarationSite,
+    keep = {},
   },
 ) => {
   const createActionForRoot = (
@@ -31724,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") {
@@ -31755,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:
@@ -31837,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) => {
@@ -85888,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 {