@loadbare/app 0.25.0 → 0.26.0

package/dist/server/lb-express.js.map

@@ -1 +1 @@
-{"version":3,"file":"lb-express.js","sourceRoot":"","sources":["../../server/lb-express.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The Express adapter — the standard hand-off from an Express router to a\n * Hub built by createHub(). Every Hub application wires this same router,\n * which is why it ships from here rather than being copied into each one.\n *\n * Express itself is a peer dependency: nothing outside this file imports it,\n * so an application that hosts Hub some other way never pays for it.\n *\n * One endpoint, and no second:\n *\n *   POST /lb/<stub>?<query string>\n *                          an empty body asks for the page's queries, or for\n *                          the page loaded at the new URL its onPageEnter\n *                          returned; a body carrying a request runs its\n *                          handler and answers with the refresh set, or with\n *                          the page loaded at the new URL the handler\n *                          returned\n *\n * The page rides on the path rather than in the body, which is what lets the\n * operation set stay closed. The query string is the one the browser is\n * showing, verbatim, and `contextFor` is handed its parms. What a parm means\n * is the application's: nothing here reads one. Every hub call is a POST, so\n * an application's own GET routes never collide with this one and no page\n * name is reserved.\n */\n\nimport express, {\n  type NextFunction,\n  type Request,\n  type Response,\n  type Router,\n} from \"express\";\nimport {\n  LB_ENDPOINT,\n  LB_REFUSAL_STATUS,\n  URL_QUERY,\n} from \"../core/lb-constants.js\";\nimport {\n  nextLocation,\n  type HubRequest,\n  type HubResponse,\n} from \"../core/lb-types.js\";\nimport { Refusal, type Hub, type HubContext } from \"./lb-server.js\";\n\n/**\n * Building the context is the application's job — it is where an\n * authenticated database handle comes from — so it is injected rather than\n * assumed. Whatever established identity has already run by the time this\n * router is reached; where that happens is the application's ordering\n * decision, not Hub's.\n *\n * The query parms arrive as `parms`, and are read there rather than off\n * `req.query`. The two agree except after a request that wrote parms: the\n * page is then loaded at the new query string in the same round trip, and\n * this is called a second time for that load, with the same `req` and the\n * new `parms`. So it must be safe to call twice for one request, and a\n * write must be visible to the second context by the time its `run`\n * returns.\n *\n * Parms are user input like any other, typed into an address bar or mailed\n * in a link, and are validated where they are read.\n */\nexport type ContextFor = (req: Request, parms: URLSearchParams) => HubContext;\n\n/**\n * The router's options, one key per concern.\n *\n * `json` is handed to `express.json()` untouched, so it takes whatever that\n * takes. The one an application is likely to want is `limit`: the default\n * of 100kb refuses a page that sends a file's text as a value.\n */\nexport interface HubRoutesOptions {\n  json?: Parameters<typeof express.json>[0];\n}\n\nexport function hubRoutes(\n  hub: Hub,\n  contextFor: ContextFor,\n  options: HubRoutesOptions = {},\n): Router {\n  const router = express.Router();\n\n  // Mounted here rather than on the app so that Hub's need for a parsed\n  // body is stated where the routes that need it are.\n  router.use(express.json(options.json));\n\n  router.post(`${LB_ENDPOINT}/*page`, async (req, res) => {\n    // A page name may hold a slash, so the path below the endpoint is\n    // gathered whole.\n    const page = (req.params.page as string[]).join(\"/\");\n    const request = req.body as HubRequest | undefined;\n    // Parsed here rather than taken from req.query, so that the parms a\n    // context is built from are the same kind of thing on both calls.\n    const parms = new URL(req.originalUrl, \"http://localhost\").searchParams;\n    const ctx = contextFor(req, parms);\n\n    // No body at all is the page load: the browser is asking for this\n    // page's queries. A body that carries something but no name is\n    // malformed.\n    if (request === undefined || Object.keys(request).length === 0) {\n      const items = await hub.dataForPage(page, ctx, { parms });\n      const moved = items.find((item) => item.query === URL_QUERY);\n      if (moved === undefined) {\n        res.json(items);\n        return;\n      }\n      // onPageEnter moved the URL, so the page loads there, and that load\n      // does not follow onPageEnter again: no page can move the URL forever.\n      res.json(\n        await loadAt(\n          moved,\n          nextLocation(page, parms, moved.row ?? {}),\n          `entering '${page}'`,\n        ),\n      );\n      return;\n    }\n\n    if (!request.name) {\n      console.warn(`loadbare: request without a name`);\n      res.status(400).json([]);\n      return;\n    }\n\n    // A thrown error is how application code (a query, a handler) says\n    // \"this request is invalid\" or hits an unexpected failure — it resolves\n    // to a real response rather than an unhandled rejection, so the browser\n    // side has something to catch.\n    // A refusal carries words the handler wrote for the user, and goes to\n    // the browser with them. Anything else thrown is a failure, and goes\n    // with nothing, so a stack or a database message never reaches a page.\n    let items: HubResponse;\n    try {\n      items = await hub.runRequest(page, request, ctx);\n    } catch (err) {\n      if (err instanceof Refusal) {\n        res.status(LB_REFUSAL_STATUS).json({ refusal: err.refusal });\n        return;\n      }\n      console.error(`loadbare: '${request.name}' threw`, err);\n      res.status(500).json([]);\n      return;\n    }\n\n    const moved = items.find((item) => item.query === URL_QUERY);\n    if (moved === undefined) {\n      res.json(items);\n      return;\n    }\n    // The handler returned a new row for lb-url, so the page loads there, as\n    // a cold load of the new URL would. The handler has already run: from\n    // here a failure must not read as the request failing, or the user would\n    // send it again. The item goes back alone instead, and the hub, writing\n    // the URL with nothing to land, loads the page itself.\n    res.json(\n      await loadAt(\n        moved,\n        nextLocation(page, parms, moved.row ?? {}),\n        `'${request.name}'`,\n      ),\n    );\n\n    /**\n     * The `lb-url` item and the page loaded where it leads. A load that\n     * throws is not the failure of what moved the URL: the item goes back\n     * alone, and the hub, writing the URL with nothing to land, loads the\n     * page itself.\n     */\n    async function loadAt(\n      moved: HubResponse[number],\n      next: { page: string; parms: URLSearchParams },\n      what: string,\n    ): Promise<HubResponse> {\n      try {\n        const load = await hub.dataForPage(\n          next.page,\n          contextFor(req, next.parms),\n          { follow: false },\n        );\n        return [moved, ...load];\n      } catch (err) {\n        console.error(\n          `loadbare: ${what} moved the URL, and loading '${next.page}' ` +\n            `there threw`,\n          err,\n        );\n        return [moved];\n      }\n    }\n  });\n\n  // A body that never parsed, or was too large to read, is refused like any\n  // other malformed request, rather than falling through to the\n  // application's error handler, which would print a stack and call it a\n  // server failure. Only for the hub's own path: express.json() above sees\n  // every request, and a bad body sent to one of the application's routes is\n  // the application's to answer.\n  router.use(\n    `${LB_ENDPOINT}/*page`,\n    (err: unknown, _req: Request, res: Response, next: NextFunction) => {\n      const { type, limit } = err as { type?: string; limit?: number };\n      if (type === \"entity.parse.failed\") {\n        console.warn(`loadbare: request body is not JSON`);\n        res.status(400).json([]);\n        return;\n      }\n      if (type === \"entity.too.large\") {\n        // Named in the log, since nothing in the browser says which limit\n        // was hit or where to raise it.\n        console.warn(\n          `loadbare: request body is over the limit of ${limit} bytes; ` +\n            `raise it with hubRoutes' json.limit option`,\n        );\n        res.status(413).json([]);\n        return;\n      }\n      next(err);\n    },\n  );\n\n  return router;\n}\n"]}
+{"version":3,"file":"lb-express.js","sourceRoot":"","sources":["../../server/lb-express.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The Express adapter — the standard hand-off from an Express router to a\n * Hub built by createHub(). Every Hub application wires this same router,\n * which is why it ships from here rather than being copied into each one.\n *\n * Express itself is a peer dependency: nothing outside this file imports it,\n * so an application that hosts Hub some other way never pays for it.\n *\n * One endpoint, and no second:\n *\n *   POST /lb/<stub>?<query string>\n *                          an empty body asks for the page's queries, or for\n *                          the page loaded at the new URL its onPageEnter\n *                          returned; a body carrying a request runs its\n *                          handler and answers with the refresh set, or with\n *                          the page loaded at the new URL the handler\n *                          returned\n *\n * The page rides on the path rather than in the body, which is what lets the\n * operation set stay closed. The query string is the one the browser is\n * showing, verbatim, and `contextFor` is handed its parms. What a parm means\n * is the application's: nothing here reads one. Every hub call is a POST, so\n * an application's own GET routes never collide with this one and no page\n * name is reserved.\n */\n\nimport express, {\n  type NextFunction,\n  type Request,\n  type Response,\n  type Router,\n} from \"express\";\nimport {\n  LB_ENDPOINT,\n  LB_REFUSAL_STATUS,\n  URL_QUERY,\n} from \"../core/lb-constants.js\";\nimport {\n  nextLocation,\n  oneRow,\n  type HubRequest,\n  type HubResponse,\n} from \"../core/lb-types.js\";\nimport { Refusal, type Hub, type HubContext } from \"./lb-server.js\";\n\n/**\n * Building the context is the application's job — it is where an\n * authenticated database handle comes from — so it is injected rather than\n * assumed. Whatever established identity has already run by the time this\n * router is reached; where that happens is the application's ordering\n * decision, not Hub's.\n *\n * The query parms arrive as `parms`, and are read there rather than off\n * `req.query`. The two agree except after a request that wrote parms: the\n * page is then loaded at the new query string in the same round trip, and\n * this is called a second time for that load, with the same `req` and the\n * new `parms`. So it must be safe to call twice for one request, and a\n * write must be visible to the second context by the time its `run`\n * returns.\n *\n * Parms are user input like any other, typed into an address bar or mailed\n * in a link, and are validated where they are read.\n */\nexport type ContextFor = (req: Request, parms: URLSearchParams) => HubContext;\n\n/**\n * The router's options, one key per concern.\n *\n * `json` is handed to `express.json()` untouched, so it takes whatever that\n * takes. The one an application is likely to want is `limit`: the default\n * of 100kb refuses a page that sends a file's text as a value.\n */\nexport interface HubRoutesOptions {\n  json?: Parameters<typeof express.json>[0];\n}\n\nexport function hubRoutes(\n  hub: Hub,\n  contextFor: ContextFor,\n  options: HubRoutesOptions = {},\n): Router {\n  const router = express.Router();\n\n  // Mounted here rather than on the app so that Hub's need for a parsed\n  // body is stated where the routes that need it are.\n  router.use(express.json(options.json));\n\n  router.post(`${LB_ENDPOINT}/*page`, async (req, res) => {\n    // A page name may hold a slash, so the path below the endpoint is\n    // gathered whole.\n    const page = (req.params.page as string[]).join(\"/\");\n    const request = req.body as HubRequest | undefined;\n    // Parsed here rather than taken from req.query, so that the parms a\n    // context is built from are the same kind of thing on both calls.\n    const parms = new URL(req.originalUrl, \"http://localhost\").searchParams;\n    const ctx = contextFor(req, parms);\n\n    // No body at all is the page load: the browser is asking for this\n    // page's queries. A body that carries something but no name is\n    // malformed.\n    if (request === undefined || Object.keys(request).length === 0) {\n      const items = await hub.dataForPage(page, ctx, { parms });\n      const moved = items.find((item) => item.query === URL_QUERY);\n      if (moved === undefined) {\n        res.json(items);\n        return;\n      }\n      // onPageEnter moved the URL, so the page loads there, and that load\n      // does not follow onPageEnter again: no page can move the URL forever.\n      res.json(\n        await loadAt(\n          moved,\n          nextLocation(page, parms, oneRow(moved) ?? {}),\n          `entering '${page}'`,\n        ),\n      );\n      return;\n    }\n\n    if (!request.name) {\n      console.warn(`loadbare: request without a name`);\n      res.status(400).json([]);\n      return;\n    }\n\n    // A thrown error is how application code (a query, a handler) says\n    // \"this request is invalid\" or hits an unexpected failure — it resolves\n    // to a real response rather than an unhandled rejection, so the browser\n    // side has something to catch.\n    // A refusal carries words the handler wrote for the user, and goes to\n    // the browser with them. Anything else thrown is a failure, and goes\n    // with nothing, so a stack or a database message never reaches a page.\n    let items: HubResponse;\n    try {\n      items = await hub.runRequest(page, request, ctx);\n    } catch (err) {\n      if (err instanceof Refusal) {\n        res.status(LB_REFUSAL_STATUS).json({ refusal: err.refusal });\n        return;\n      }\n      console.error(`loadbare: '${request.name}' threw`, err);\n      res.status(500).json([]);\n      return;\n    }\n\n    const moved = items.find((item) => item.query === URL_QUERY);\n    if (moved === undefined) {\n      res.json(items);\n      return;\n    }\n    // The handler returned a new row for lb-url, so the page loads there, as\n    // a cold load of the new URL would. The handler has already run: from\n    // here a failure must not read as the request failing, or the user would\n    // send it again. The item goes back alone instead, and the hub, writing\n    // the URL with nothing to land, loads the page itself.\n    res.json(\n      await loadAt(\n        moved,\n        nextLocation(page, parms, oneRow(moved) ?? {}),\n        `'${request.name}'`,\n      ),\n    );\n\n    /**\n     * The `lb-url` item and the page loaded where it leads. A load that\n     * throws is not the failure of what moved the URL: the item goes back\n     * alone, and the hub, writing the URL with nothing to land, loads the\n     * page itself.\n     */\n    async function loadAt(\n      moved: HubResponse[number],\n      next: { page: string; parms: URLSearchParams },\n      what: string,\n    ): Promise<HubResponse> {\n      try {\n        const load = await hub.dataForPage(\n          next.page,\n          contextFor(req, next.parms),\n          { follow: false },\n        );\n        return [moved, ...load];\n      } catch (err) {\n        console.error(\n          `loadbare: ${what} moved the URL, and loading '${next.page}' ` +\n            `there threw`,\n          err,\n        );\n        return [moved];\n      }\n    }\n  });\n\n  // A body that never parsed, or was too large to read, is refused like any\n  // other malformed request, rather than falling through to the\n  // application's error handler, which would print a stack and call it a\n  // server failure. Only for the hub's own path: express.json() above sees\n  // every request, and a bad body sent to one of the application's routes is\n  // the application's to answer.\n  router.use(\n    `${LB_ENDPOINT}/*page`,\n    (err: unknown, _req: Request, res: Response, next: NextFunction) => {\n      const { type, limit } = err as { type?: string; limit?: number };\n      if (type === \"entity.parse.failed\") {\n        console.warn(`loadbare: request body is not JSON`);\n        res.status(400).json([]);\n        return;\n      }\n      if (type === \"entity.too.large\") {\n        // Named in the log, since nothing in the browser says which limit\n        // was hit or where to raise it.\n        console.warn(\n          `loadbare: request body is over the limit of ${limit} bytes; ` +\n            `raise it with hubRoutes' json.limit option`,\n        );\n        res.status(413).json([]);\n        return;\n      }\n      next(err);\n    },\n  );\n\n  return router;\n}\n"]}

package/dist/server/lb-server.d.ts

@@ -20,6 +20,10 @@ import type { ColumnTypes, HubData, HubRequest, HubResponse, HubResult, Kind, Ga
  */
 export interface HubContext {
 }
+/** What answers a `row` query. */
+type RowRun = (ctx: HubContext) => HubResult | Promise<HubResult>;
+/** What answers a `rows` query, given its resolved order. */
+type RowsRun = (ctx: HubContext, order: string) => HubResult | Promise<HubResult>;
 /**
  * A declared query: its kind, its key, and the run that answers it.
  *
@@ -33,7 +37,7 @@ export interface HubContext {
 export interface Query {
     readonly kind: Kind;
     readonly key: string;
-    readonly run: (ctx: HubContext) => HubResult | Promise<HubResult>;
+    readonly run: RowRun | RowsRun;
     /** A `rows` query's order, as `rows()` declared it. */
     readonly order?: string;
     /** A `rows` query's column types, as `rows()` declared them. */
@@ -44,12 +48,12 @@ export interface Query {
  *
  * `order` is the order the hub places its rows by: columns separated by
  * commas, each descending when it begins with `-`, as in
- * `category_order,-opened`. An order the user chose, held in `lb-choices`,
+ * `category_order,-opened`. An order the user chose, held in `lb-sort`,
  * replaces it. With neither, rows show in the order the query answered them
  * in.
  *
- * `types` names a type for any of its columns, and the hub sorts, filters
- * and takes `lb-min` and `lb-max` of that column read as its type rather
+ * `types` names a type for any of its columns, and the hub sorts and
+ * filters that column read as its type rather
  * than by the JSON type its values arrive as: `{ amount: "number" }` for a
  * Postgres `numeric` that arrives as a string. A column it does not name
  * compares by its JSON type. The order and the types go to the browser
@@ -68,8 +72,12 @@ export declare function row(key: string, run: (ctx: HubContext) => Row | null |
  * A query that answers with all its rows. Rows land by their `key` column: a
  * row whose key is not in the answer is gone. The hub places them by the
  * order in `options`, or in the order they arrived when there is none.
+ *
+ * `run` receives the resolved order — the user's, from `lb-sort`, or the
+ * one `options` declares — and orders its SQL by it, so the rows it answers
+ * arrive in the order the page shows them in.
  */
-export declare function rows(key: string, run: (ctx: HubContext) => Row[] | Promise<Row[]>, options?: RowsOptions): Query;
+export declare function rows(key: string, run: (ctx: HubContext, order: string) => Row[] | Promise<Row[]>, options?: RowsOptions): Query;
 /**
  * Only what changed, returned from a handler for a `rows` query. Rows named
  * here are added or updated, keys in `drop` are removed, and everything
@@ -99,14 +107,17 @@ export declare function patch(change: {
  */
 export declare function url(columns: Record<string, string | string[]>): HubData;
 /**
- * The user's choices for the page, returned from `onPageEnter` to restore
- * what the user last chose: an order, a filter. Each column is a column of
- * `lb-choices`, and the hub places the page's rows by them as they land.
- * Return it beside `url()` with the spread both are written for:
- *
- *     return { ...url({ acct: "23" }), ...choices({ sort: "-amount" }) };
+ * The resolved order for each `rows` query, returned from `onPageEnter` to
+ * restore what the user last chose. Each key is a query name and its value
+ * the order the query runs its rows in, as `rows()` declares one.
+ */
+export declare function sort(orders: Record<string, string>): HubData;
+/**
+ * The user's filters for the page, returned from `onPageEnter` to restore
+ * them. Each key is a query name and its value the filter values for that
+ * query's rows, by column.
  */
-export declare function choices(columns: Record<string, string>): HubData;
+export declare function filters(rows: Record<string, Record<string, string>>): HubData;
 /**
  * A handler's refusal: thrown, and answered to the browser with the words
  * it carries. Every other error a handler throws reaches the browser as a
@@ -185,12 +196,12 @@ export interface Crud {
  * page to other query parms or another page before anything shows, as an
  * application restoring what the user last had on screen does. The page
  * then loads there in the same round trip, and `onPageEnter` running for
- * that load is not followed again. It may return `choices()`, with `url()`
- * or alone, to restore the user's choices for the page.
+ * that load is not followed again. It may return `sort()`, `filters()`,
+ * with `url()` or alone, to restore the user's choices for the page.
  *
- * `onChoices` runs each time the user makes a choice, with every choice
- * made on the page, so an application can keep them for `onPageEnter` to
- * restore. It answers with nothing, by convention.
+ * `onChoices` runs each time the user changes the sort or a filter, with
+ * the query and its new sort or filters, so an application can keep them
+ * for `onPageEnter` to restore. It answers with nothing, by convention.
  *
  * `handlers` holds the page's declared requests, by name. A name the page
  * did not declare is refused, so the wire cannot reach anything the page has
@@ -200,7 +211,11 @@ export interface Crud {
  */
 export interface Requests {
     onPageEnter?: (ctx: HubContext) => void | HubData | Promise<void | HubData>;
-    onChoices?: (ctx: HubContext, choices: Record<string, string>) => void | HubData | Promise<void | HubData>;
+    onChoices?: (ctx: HubContext, change: {
+        query: string;
+        sort?: string;
+        filters?: Record<string, string>;
+    }) => void | HubData | Promise<void | HubData>;
     handlers?: Record<string, Handler>;
     crud?: Record<string, Crud>;
 }
@@ -211,7 +226,7 @@ export interface Page {
 }
 /**
  * The page registry. The builder writes it from every `.requests.ts` and
- * `.queries.ts` it discovers — see docs/reference/builder.md.
+ * `.queries.ts` it discovers.
  */
 export type Pages = Record<string, Page>;
 /**
@@ -244,4 +259,5 @@ export interface Hub {
  * context is not, and arrives with each call.
  */
 export declare function createHub(pages: Pages): Hub;
+export {};
 //# sourceMappingURL=lb-server.d.ts.map

package/dist/server/lb-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lb-server.d.ts","sourceRoot":"","sources":["../../server/lb-server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"lb-server.d.ts","sourceRoot":"","sources":["../../server/lb-server.ts"],"names":[],"mappings":"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"}

package/dist/server/lb-server.js

@@ -4,8 +4,8 @@
 // vocabulary the browser writes, this one is the vocabulary the application
 // writes. The engine below is the whole of Loadbare on the server. It ships
 // no HTTP server, no router, and no data layer.
-import { isRowRequest, nextLocation, parseOrder } from "../core/lb-types.js";
-import { CHOICES_QUERY, COLUMN_TYPES, KIND_ROW, KIND_ROWS, LB_RESERVED_PREFIX, REQUEST_ROW_DELETE, REQUEST_ROW_INSERT, REQUEST_ROW_UPDATE, URL_COLUMN_PATH, URL_QUERY, } from "../core/lb-constants.js";
+import { isRowRequest, nextLocation, oneRow, parseOrder } from "../core/lb-types.js";
+import { COLUMN_TYPES, FILTERS_COLUMN_QUERY, FILTERS_QUERY, KIND_ROW, KIND_ROWS, LB_RESERVED_PREFIX, REQUEST_READ, REQUEST_ROW_DELETE, REQUEST_ROW_INSERT, REQUEST_ROW_UPDATE, SORT_COLUMN_ORDER, SORT_COLUMN_QUERY, SORT_QUERY, URL_COLUMN_PATH, URL_QUERY, } from "../core/lb-constants.js";
 /**
  * A query that answers with one row, identified by its `key` column, or with
  * `null` when there is none.
@@ -17,6 +17,10 @@ export function row(key, run) {
  * A query that answers with all its rows. Rows land by their `key` column: a
  * row whose key is not in the answer is gone. The hub places them by the
  * order in `options`, or in the order they arrived when there is none.
+ *
+ * `run` receives the resolved order — the user's, from `lb-sort`, or the
+ * one `options` declares — and orders its SQL by it, so the rows it answers
+ * arrive in the order the page shows them in.
  */
 export function rows(key, run, options = {}) {
     return {
@@ -64,15 +68,30 @@ export function url(columns) {
     return { [URL_QUERY]: { ...columns } };
 }
 /**
- * The user's choices for the page, returned from `onPageEnter` to restore
- * what the user last chose: an order, a filter. Each column is a column of
- * `lb-choices`, and the hub places the page's rows by them as they land.
- * Return it beside `url()` with the spread both are written for:
- *
- *     return { ...url({ acct: "23" }), ...choices({ sort: "-amount" }) };
+ * The resolved order for each `rows` query, returned from `onPageEnter` to
+ * restore what the user last chose. Each key is a query name and its value
+ * the order the query runs its rows in, as `rows()` declares one.
  */
-export function choices(columns) {
-    return { [CHOICES_QUERY]: { ...columns } };
+export function sort(orders) {
+    return {
+        [SORT_QUERY]: Object.entries(orders).map(([query, order]) => ({
+            [SORT_COLUMN_QUERY]: query,
+            [SORT_COLUMN_ORDER]: order,
+        })),
+    };
+}
+/**
+ * The user's filters for the page, returned from `onPageEnter` to restore
+ * them. Each key is a query name and its value the filter values for that
+ * query's rows, by column.
+ */
+export function filters(rows) {
+    return {
+        [FILTERS_QUERY]: Object.entries(rows).map(([query, values]) => ({
+            [FILTERS_COLUMN_QUERY]: query,
+            ...values,
+        })),
+    };
 }
 /**
  * A handler's refusal: thrown, and answered to the browser with the words
@@ -197,9 +216,8 @@ export function createHub(pages) {
                         `${Array.isArray(result) ? "rows" : "a patch"}`);
                     continue;
                 }
-                // No row reaches the browser as null, which JSON keeps and
-                // undefined it would drop.
-                item.row = (result ?? null);
+                // Every answer is rows: a `row` query's is its row, or none.
+                item.rows = result == null ? [] : [result];
             }
             else {
                 if (result === null || result === undefined) {
@@ -210,8 +228,6 @@ export function createHub(pages) {
                     item.rows = result;
                 else
                     item.patch = result;
-                if (load && query.order !== undefined)
-                    item.order = query.order;
                 if (load && query.types !== undefined)
                     item.types = query.types;
             }
@@ -219,24 +235,35 @@ export function createHub(pages) {
         }
         return out;
     }
-    /** Run queries by name, each answering with all its rows or its row. */
-    async function run(page, names, ctx) {
+    /**
+     * Run queries by name, each answering with all its rows or its row. A
+     * `rows` query receives the resolved order for its name from `sorts`, or
+     * its declared default, and the order each ran with is returned beside the
+     * data for the caller to write to `lb-sort`.
+     */
+    async function run(page, names, ctx, sorts) {
         const data = {};
+        const orders = new Map();
         for (const name of names) {
             const query = pages[page]?.queries[name];
             if (!query) {
                 console.warn(`loadbare: page '${page}' declares no query '${name}'`);
                 continue;
             }
-            const result = await query.run(ctx);
+            const order = sorts?.get(name) ?? query.order ?? "";
+            const result = query.kind === KIND_ROWS
+                ? await query.run(ctx, order)
+                : await query.run(ctx);
             if (Array.isArray(result) !== (query.kind === KIND_ROWS)) {
                 console.warn(`loadbare: query '${name}' is declared ${query.kind} but answered ` +
                     `with ${Array.isArray(result) ? "rows" : result == null ? "nothing" : "one row"}`);
                 continue;
             }
             data[name] = result;
+            if (query.kind === KIND_ROWS && order !== "")
+                orders.set(name, order);
         }
-        return data;
+        return { data, orders };
     }
     /**
      * Run a handler, then its refresh set against the same context, laying
@@ -257,42 +284,7 @@ export function createHub(pages) {
         if (item)
             return [item];
         return items(page, {
-            ...(await run(page, handler.refresh, ctx)),
-            ...stated,
-        });
-    }
-    /**
-     * An update or a delete for several rows: the page's `crud` entry runs once
-     * per key, as it would for each row alone, so an application writes
-     * nothing more to allow it. What each run returns is laid together, a
-     * patch onto a patch, and the refresh set runs once.
-     *
-     * A run that returns `url()` is reported and its row ignored: a URL names
-     * one view, and several rows cannot each choose it.
-     */
-    async function eachKey(page, name, fields, ctx) {
-        const { keys, ...one } = fields;
-        const query = fields.query ?? "";
-        const handler = pages[page]?.requests.crud?.[query]?.[CRUD_KEYS[name]];
-        if (!handler) {
-            console.warn(`loadbare: page '${page}' declares no ${CRUD_KEYS[name]} for '${query}'`);
-            return [];
-        }
-        if (!Array.isArray(keys) || keys.some((key) => typeof key !== "string")) {
-            console.warn(`loadbare: '${name}' carries keys that are not strings`);
-            return [];
-        }
-        let stated = {};
-        for (const key of keys) {
-            const { [URL_QUERY]: moved, ...answer } = (await handler.run(ctx, { ...one, key })) ?? {};
-            if (moved !== undefined) {
-                console.warn(`loadbare: ${CRUD_KEYS[name]} for '${query}' returned url() for ` +
-                    `one of several rows, ignoring it`);
-            }
-            stated = layered(stated, answer);
-        }
-        return items(page, {
-            ...(await run(page, handler.refresh, ctx)),
+            ...(await run(page, handler.refresh, ctx)).data,
             ...stated,
         });
     }
@@ -303,22 +295,32 @@ export function createHub(pages) {
                 console.warn(`loadbare: no page '${page}'`);
                 return [];
             }
-            const { [URL_QUERY]: moved, [CHOICES_QUERY]: chose, ...stated } = (await entry.requests.onPageEnter?.(ctx)) ?? {};
+            const { [URL_QUERY]: moved, [SORT_QUERY]: sorts, [FILTERS_QUERY]: filters, ...stated } = (await entry.requests.onPageEnter?.(ctx)) ?? {};
             if (Object.keys(stated).length > 0) {
                 console.warn(`loadbare: page '${page}' onPageEnter returned answers; it returns ` +
-                    `url(), choices() or nothing, ignoring them`);
+                    `url(), sort(), filters() or nothing, ignoring them`);
             }
             const item = follow ? urlItem(page, moved) : undefined;
-            if (item && !(parms && leadsHere(page, parms, item.row)))
+            if (item && !(parms && leadsHere(page, parms, oneRow(item))))
                 return [item];
-            // The choices go first, so the rows that read them land by them.
+            const { data, orders } = await run(page, Object.keys(entry.queries), ctx, sortsToMap(sorts));
+            // The sort and filters go first, so the rows that read them land by
+            // them.
             return [
-                ...choicesItem(page, chose),
-                ...items(page, await run(page, Object.keys(entry.queries), ctx), true),
+                ...sortItem(orders),
+                ...filtersItem(page, filters),
+                ...items(page, data, true),
             ];
         },
-        runRequest(page, request, ctx) {
+        async runRequest(page, request, ctx) {
             const { name, ...sent } = request;
+            // The hub's read: the queries named, at the parms the request was sent
+            // at, answered as any query is.
+            if (name === REQUEST_READ) {
+                const declared = pages[page]?.queries ?? {};
+                const names = (Array.isArray(sent.queries) ? sent.queries : []).filter((q) => typeof q === "string" && q in declared);
+                return run(page, names, ctx).then(({ data }) => items(page, data));
+            }
             // Only a column of lb-url holds several values, and the hub answers
             // those itself: a column the server receives holds one.
             if (sent.values !== undefined && !stringValues(sent.values)) {
@@ -332,21 +334,26 @@ export function createHub(pages) {
                     `values by query, ignoring it`);
                 return Promise.resolve([]);
             }
-            // The user's choices, told to the page. One with no `onChoices` is
-            // not keeping them, and is not told.
-            if (fields.query === CHOICES_QUERY) {
+            // A sort or filter the user changed, told to the page. One with no
+            // `onChoices` is not keeping them, and is not told.
+            if (fields.query === SORT_QUERY || fields.query === FILTERS_QUERY) {
                 const onChoices = pages[page]?.requests.onChoices;
                 if (name !== REQUEST_ROW_UPDATE || !onChoices) {
                     return Promise.resolve([]);
                 }
-                return settle(page, {
-                    run: (c, r) => onChoices(c, r.values ?? {}),
-                    refresh: [],
-                }, fields, ctx, "");
-            }
-            if (fields.keys !== undefined &&
-                (name === REQUEST_ROW_UPDATE || name === REQUEST_ROW_DELETE)) {
-                return eachKey(page, name, fields, ctx);
+                const query = fields.key ?? "";
+                const sort = fields.query === SORT_QUERY
+                    ? fields.values?.[SORT_COLUMN_ORDER]
+                    : undefined;
+                const filters = fields.query === FILTERS_QUERY ? fields.values : undefined;
+                await onChoices(ctx, {
+                    query,
+                    ...(sort !== undefined && { sort }),
+                    ...(filters !== undefined && { filters }),
+                });
+                // The browser re-sorts or re-filters the rows it holds; the server
+                // only persists the change for the next page.
+                return [];
             }
             if (isRowRequest(name)) {
                 const query = fields.query ?? "";
@@ -413,31 +420,78 @@ function urlItem(page, moved) {
             query: URL_QUERY,
             kind: KIND_ROW,
             key: URL_COLUMN_PATH,
-            row: moved,
+            rows: [moved],
         };
     }
     console.warn(`loadbare: page '${page}' returned ${URL_QUERY} ${refused}, ignoring it`);
     return undefined;
 }
+/** The sorts `onPageEnter` returned, as a map of query name to order. */
+function sortsToMap(sorts) {
+    const map = new Map();
+    if (!Array.isArray(sorts))
+        return map;
+    for (const row of sorts) {
+        if (typeof row !== "object" || row === null)
+            continue;
+        const r = row;
+        if (typeof r[SORT_COLUMN_QUERY] === "string" &&
+            typeof r[SORT_COLUMN_ORDER] === "string") {
+            map.set(r[SORT_COLUMN_QUERY], r[SORT_COLUMN_ORDER]);
+        }
+    }
+    return map;
+}
 /**
- * The `lb-choices` item for the choices `onPageEnter` returned, or nothing
- * when it returned none or ones that cannot be used, which are reported.
+ * The `lb-sort` item for the orders each `rows` query ran with, or nothing
+ * when none ran with an order.
  */
-function choicesItem(page, chose) {
-    if (chose === undefined)
+function sortItem(orders) {
+    if (orders.size === 0)
         return [];
-    const refused = unusableUrl(chose, false);
-    if (refused !== undefined) {
-        console.warn(`loadbare: page '${page}' returned ${CHOICES_QUERY} ${refused}, ` +
-            `ignoring it`);
+    return [
+        {
+            query: SORT_QUERY,
+            kind: KIND_ROWS,
+            key: SORT_COLUMN_QUERY,
+            rows: [...orders.entries()].map(([query, order]) => ({
+                [SORT_COLUMN_QUERY]: query,
+                [SORT_COLUMN_ORDER]: order,
+            })),
+        },
+    ];
+}
+/**
+ * The `lb-filters` item for the filters `onPageEnter` returned, or nothing
+ * when it returned none. Each row names its query and its filter values, by
+ * column.
+ */
+function filtersItem(page, filters) {
+    if (filters === undefined)
         return [];
+    if (!Array.isArray(filters)) {
+        console.warn(`loadbare: page '${page}' returned ${FILTERS_QUERY} that is not a ` +
+            `list, ignoring it`);
+        return [];
+    }
+    const rows = [];
+    for (const row of filters) {
+        if (typeof row !== "object" || row === null)
+            continue;
+        const r = row;
+        if (typeof r[FILTERS_COLUMN_QUERY] !== "string")
+            continue;
+        const values = Object.fromEntries(Object.entries(r).filter(([key, value]) => key !== FILTERS_COLUMN_QUERY && typeof value === "string"));
+        rows.push({ [FILTERS_COLUMN_QUERY]: r[FILTERS_COLUMN_QUERY], ...values });
     }
+    if (rows.length === 0)
+        return [];
     return [
         {
-            query: CHOICES_QUERY,
-            kind: KIND_ROW,
-            key: URL_COLUMN_PATH,
-            row: chose,
+            query: FILTERS_QUERY,
+            kind: KIND_ROWS,
+            key: FILTERS_COLUMN_QUERY,
+            rows,
         },
     ];
 }
@@ -447,8 +501,7 @@ function leadsHere(page, parms, row) {
     return next.page === page && next.parms.toString() === parms.toString();
 }
 /**
- * Why a returned row for `lb-url` or `lb-choices` cannot be used, or nothing
- * when it can.
+ * Why a returned row for `lb-url` cannot be used, or nothing when it can.
  *
  * A value is a string, as a control's is and a URL's is, or for `lb-url`,
  * whose parms a URL may repeat, an array of strings. At least one column is