@loadbare/app 0.8.2 → 0.9.0

package/skills/loadbare-app/SKILL.md

@@ -169,11 +169,22 @@ shows, a filter, a date range: each is a query parm,
 shows the same thing.  A control writes one with `lb-query-parm="acct"`, which
 replaces the history entry, reloads the page at the new URL, and sends no
 request.  A link writes several with an ordinary `lb-nav-link` href.  Queries
-still take no arguments: `contextFor` reads `req.query` onto `ctx`, and a
-query reads it there.  A parm is user input, so validate it where you read
-it.  Do not keep a selection in server state set by an action; that forces
-`refresh: []` and a hand-written re-answer of everything the selection
-touches.
+still take no arguments: `contextFor(req, parms)` puts parms onto `ctx`, and
+a query reads them there.  Read them from `parms`, never `req.query`, because
+`contextFor` may be called twice for one request.  A parm is user input, so
+validate it where you read it.  Do not keep a selection in server state set
+by an action; that forces `refresh: []` and a hand-written re-answer of
+everything the selection touches.
+
+**When a server response changes the query parms.**  After an insert, only
+the server knows the new key.  After a delete, only the server knows the parm
+should go.  Have `run` return `queryParms({ acct: String(id) })`, or
+`queryParms({ acct: "" })` to remove the parm.  The page loads at the new
+query string in the same round trip, and the history entry is replaced to
+match.  This is Post/Redirect/Get without the redirect: the path never
+changes, and there is no second request.  Do not reach for a redirect, a
+hand-written refresh of every query, or server state holding the selection.
+See [refresh and patch](references/page-files.md#refresh-and-patch).
 
 **Loadbare is for applications, not sites.**  Every route is answered with
 `app.html`, and a path that names no page is found in the browser, not

package/skills/loadbare-app/references/TECHREF-1.0.md

@@ -501,6 +501,9 @@ not a way to show a different detail per row.
 
 Which master a page shows is a query parm, which a query reads off `ctx`
 since it takes no argument from the browser — see [Query parms](#query-parms).
+When a write creates or removes the master, the server response changes that
+parm — see
+[When a server response changes the query parms](#when-a-server-response-changes-the-query-parms).
 
 ### Requests
 
@@ -746,9 +749,54 @@ A control that writes a query parm sends no request.  One that also carries
 sent twice.
 
 Every round trip carries the query string the browser is showing, a page
-load and an action alike.  The server reads the parms off `req.query` in
-`contextFor` — see [The Express server](#the-express-server).  Nothing in
-Loadbare assigns a parm a meaning.
+load and an action alike.  The server hands its parms to `contextFor` — see
+[The Express server](#the-express-server).  Nothing in Loadbare assigns a
+parm a meaning.
+
+#### When a server response changes the query parms
+
+Some query parms can only be known once a write has run.  After an insert,
+the key of the new row exists only on the server.  After a delete, only the
+server knows that the row the page was showing is gone.
+
+The usual web answer is Post/Redirect/Get: the server answers the write with
+a redirect to a URL naming the result, and the browser makes a second request
+to load it.  Loadbare/app does the same work in one round trip, and never
+changes the path.
+
+A request's `run` returns `queryParms()`, naming the parms the write decided.
+The server loads the page with those parms set, as a cold load of the
+resulting URL would: `onPageEnter`, then every query.  The server response
+carries the parms and that load together.  The hub sets the parms in the URL,
+replacing the history entry, and then lands the load.
+
+```ts
+rowInsert: {
+  run: async (ctx, { values }) => {
+    const id = await ctx.db.addAccount(values);
+    return queryParms({ acct: String(id) });
+  },
+  refresh: [],
+},
+```
+
+- Only query parms change.  A server response cannot send the browser to
+  another page.
+- Parms the response does not name are left as they are.  An empty value
+  removes its parm.
+- At least one parm is named, and every value is a string.  Otherwise the
+  server warns, ignores the parms, and runs the refresh set as usual.
+- The refresh set does not run, and anything else `run` returned is dropped.
+  Both were answers for the query string the page is leaving.
+- If loading the page fails, the write has still happened.  The response
+  carries the parms alone, and the hub loads the page itself.  A failure
+  there is a page load's, and is not stamped on the element that sent the
+  request.
+- A user who has left the page by the time the response arrives keeps the
+  URL they are on.
+
+The page is loaded with a second context, built by `contextFor` from the new
+parms — see [The Express server](#the-express-server).
 
 ### lb-navigation
 
@@ -929,17 +977,23 @@ only real requirement is that the catch-all for app.html is at the end,
 so it does not catch any other files.
 
 `hubRoutes` answers `POST /lb/<page>`, with the query string the browser is
-showing after it, verbatim.  So `req.query` holds the page's query parms, and
-`contextFor` puts on the context whatever a query reads from them.  They are
-user input:
+showing after it, verbatim.  It hands `contextFor` that query string's parms
+as a second argument, and `contextFor` puts on the context whatever a query
+reads from them.  They are user input:
 
 ```ts
-function contextFor(req: Request): HubContext {
-  const { acct } = req.query;
-  return { db: openDb(), acct: typeof acct === "string" ? acct : "" };
+function contextFor(req: Request, parms: URLSearchParams): HubContext {
+  return { db: openDb(), acct: parms.get("acct") ?? "" };
 }
 ```
 
+Read the parms from that argument, not from `req.query`.  After a request
+whose `run` returned `queryParms()`, `contextFor` is called a second time for
+the same request, with the new parms, to load the page at them.  So it must
+be safe to call twice, and a write must be visible to the second context by
+the time its `run` returns.  A handle opened per request without a
+transaction around it is both.
+
 Give the server the origin root.  The hub reaches its own endpoints by
 absolute path, so an application cannot be hosted under a subpath such as
 `example.com/myapp/`, and anything proxying in front of the server passes
@@ -1010,6 +1064,13 @@ interaction happened, as `list`, `row`, `key`, `cell` and `value`.  Under
 ones.  That is how a delta reaches the browser: wrap it in `patch()`, naming
 the rows that arrived or changed and the keys that went.
 
+`run` may instead return `queryParms()`, naming query parms only the write
+can know, such as the key of a row it inserted.  The page then loads at them
+in the same round trip, in place of the refresh set — see
+[When a server response changes the query parms](#when-a-server-response-changes-the-query-parms).
+A `rowDelete` that removes the row on screen returns `queryParms({ acct: "" })`
+and leaves any other delete to its refresh set.
+
 ```ts
 // members.requests.ts
 import { patch, type Requests } from "@loadbare/app/server";

package/skills/loadbare-app/references/data-binding.md

@@ -328,7 +328,12 @@ an absent parm lands empty, so the control shows what the address bar says.
 A control that writes a query parm sends no request, and one that also
 carries `lb-action` has that request refused.
 
-The server reads the parms off `req.query` in `contextFor`; see
+A request can write parms too, when only the write knows their value, such as
+the key of a row it inserted; see
+[refresh and patch](./page-files.md#refresh-and-patch). The page loads at
+them in the same round trip, and they land on their controls as above.
+
+The server hands the parms to `contextFor`; see
 [the Express server](./server.md#database-layer). See
 [Query parms](./TECHREF-1.0.md#query-parms) for the whole rule.
 

package/skills/loadbare-app/references/page-files.md

@@ -192,3 +192,42 @@ resetRoster: {
   refresh: ["roster"],
 },
 ```
+
+Return `queryParms()` instead when the server response changes the query
+parms: after an insert, only the server knows the new key, and after a delete,
+only the server knows the parm should go. The page loads at the query string
+with those parms set, in the same round trip, and the hub writes them into the
+URL, replacing the history entry. This is Post/Redirect/Get without the
+redirect. The refresh set does not run, and nothing else `run` returned is
+sent, since both answered for the query string the page left. Name at least
+one parm, give each a string, and use an empty string to take one out:
+
+```ts
+// src/pages/accounts.requests.ts
+import { queryParms, type Requests } from "@loadbare/app/server";
+
+export const requests: Requests = {
+  crud: {
+    accounts: {
+      rowInsert: {
+        run: async (ctx, { values }) => {
+          const id = await ctx.db.addAccount(values);
+          return queryParms({ acct: String(id) });
+        },
+        refresh: [],
+      },
+      rowDelete: {
+        run: async (ctx, { key }) => {
+          await ctx.db.deleteAccount(key);
+          if (key === ctx.acct) return queryParms({ acct: "" });
+        },
+        refresh: ["accounts"],
+      },
+    },
+  },
+};
+```
+
+Only parms: `run` cannot send the browser to another page. The loaded page
+reads the new parms through `contextFor` like any others; see
+[the Express server](./server.md#database-layer).

package/skills/loadbare-app/references/server.md

@@ -137,17 +137,23 @@ declare module "@loadbare/app/server" {
 }
 ```
 
-The query string the browser is showing arrives on every data request, so
-`req.query` holds the page's query parms. Put on the context whatever a query
-reads from them, and treat them as user input:
+The query string the browser is showing arrives on every data request, and
+`contextFor` gets its parms as a second argument. Put on the context whatever
+a query reads from them, and treat them as user input:
 
 ```ts
-function contextFor(req: Request): HubContext {
-  const { team } = req.query;
-  return { db: openDb(), team: typeof team === "string" ? team : "" };
+function contextFor(req: Request, parms: URLSearchParams): HubContext {
+  return { db: openDb(), team: parms.get("team") ?? "" };
 }
 ```
 
+Read the parms from that argument, not from `req.query`. When a server
+response changes the query parms, `contextFor` is called a second time for
+that request, with the new parms, to load the page at them; see [refresh and patch](./page-files.md#refresh-and-patch). Write it to
+be safe to call twice, and make a write visible to the second context by the
+time `run` returns: a handle opened per request, with no transaction held
+open across the two, is both.
+
 Add a field for anything else a request needs — the authenticated user, a
 request id, a feature flag set. Queries and requests read them from `ctx`; see
 [page files](./page-files.md).