@loadbare/app 0.5.5 → 0.6.0

package/dist/tests/lb-server.test.js

@@ -7,8 +7,7 @@
  */
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
-import { createHub, patch, rows, } from "../server/lb-server";
-import { isProjection } from "../core/lb-types";
+import { createHub, list, patch, row, } from "../server/lb-server";
 import { captured } from "./helpers/console";
 /**
  * A context to compare by identity.
@@ -21,25 +20,25 @@ import { captured } from "./helpers/console";
 function context() {
     return {};
 }
-/** A query that answers a fixed tuple and records that it ran. */
+/** A query that answers a fixed row and records that it ran. */
 function stub(log, name, answer) {
-    return (ctx) => {
+    return row((ctx) => {
         log.push(name);
         seen.set(name, ctx);
         return answer;
-    };
+    });
 }
 const seen = new Map();
 function pages(entries) {
     const map = {};
     for (const [name, entry] of Object.entries(entries)) {
-        map[name] = { queries: entry.queries, hooks: entry.hooks ?? {} };
+        map[name] = { queries: entry.queries, requests: entry.requests ?? {} };
     }
     return map;
 }
-// --- The page GET --------------------------------------------------------
-describe("a page GET", () => {
-    it("runs beforeGet before any query, then the whole query set", async () => {
+// --- Entering a page ----------------------------------------------------
+describe("entering a page", () => {
+    it("runs onPageEnter before any query, then the whole query set", async () => {
         const log = [];
         const hub = createHub(pages({
             report: {
@@ -47,16 +46,16 @@ describe("a page GET", () => {
                     head: stub(log, "head", { title: "Q1" }),
                     body: stub(log, "body", { line: "one" }),
                 },
-                hooks: {
-                    beforeGet: () => void log.push("beforeGet"),
+                requests: {
+                    onPageEnter: () => void log.push("onPageEnter"),
                 },
             },
         }));
         const data = await hub.dataForPage("report", context());
-        assert.deepEqual(log, ["beforeGet", "head", "body"]);
+        assert.deepEqual(log, ["onPageEnter", "head", "body"]);
         assert.deepEqual(data, { head: { title: "Q1" }, body: { line: "one" } });
     });
-    it("runs the query set when the page declares no hooks", async () => {
+    it("runs the query set when the page declares no requests", async () => {
         const log = [];
         const hub = createHub(pages({ report: { queries: { head: stub(log, "head", { a: "1" }) } } }));
         assert.deepEqual(await hub.dataForPage("report", context()), {
@@ -89,7 +88,7 @@ describe("a page GET", () => {
     });
     it("awaits a query that returns a promise", async () => {
         const hub = createHub(pages({
-            report: { queries: { head: async () => ({ a: "1" }) } },
+            report: { queries: { head: row(async () => ({ a: "1" })) } },
         }));
         assert.deepEqual(await hub.dataForPage("report", context()), {
             head: { a: "1" },
@@ -97,6 +96,28 @@ describe("a page GET", () => {
     });
 });
 // --- Actions -------------------------------------------------------------
+describe("a reserved name", () => {
+    // Names beginning with lb- are Loadbare's: the hub's own query, the CRUD
+    // operations. See LB_RESERVED_PREFIX in core/lb-constants.ts.
+    it("is refused as a query, at startup", () => {
+        assert.throws(() => createHub({
+            home: {
+                queries: { "lb-navigation": row(async () => ({})) },
+                requests: {},
+            },
+        }), /page 'home' declares 'lb-navigation', but names beginning with 'lb-' are reserved/);
+    });
+    it("is refused as an action, at startup", () => {
+        assert.throws(() => createHub({
+            home: {
+                queries: {},
+                requests: {
+                    actions: { "lb-delete": { run: () => { }, refresh: [] } },
+                },
+            },
+        }), /declares 'lb-delete', but names beginning with 'lb-' are reserved/);
+    });
+});
 describe("an action", () => {
     it("is refused unless the page declared it", async () => {
         // The rule that keeps this from being an RPC endpoint: the wire cannot
@@ -105,7 +126,7 @@ describe("an action", () => {
         const hub = createHub(pages({
             counter: {
                 queries: { count: stub(log, "count", { n: "1" }) },
-                hooks: {
+                requests: {
                     actions: {
                         bump: { run: () => void log.push("bump"), refresh: ["count"] },
                     },
@@ -131,7 +152,7 @@ describe("an action", () => {
                     count: stub(log, "count", { n: "1" }),
                     unrelated: stub(log, "unrelated", { x: "9" }),
                 },
-                hooks: {
+                requests: {
                     actions: {
                         bump: { run: () => void log.push("bump"), refresh: ["count"] },
                     },
@@ -147,16 +168,16 @@ describe("an action", () => {
         const hub = createHub(pages({
             roster: {
                 queries: {},
-                hooks: {
+                requests: {
                     actions: {
                         pick: { run: (_ctx, w) => void (where = w), refresh: [] },
                     },
                 },
             },
         }));
-        await hub.runAction("roster", "pick", { query: "members", key: "7", cell: "role", value: "lead" }, context());
+        await hub.runAction("roster", "pick", { list: "members", key: "7", cell: "role", value: "lead" }, context());
         assert.deepEqual(where, {
-            query: "members",
+            list: "members",
             key: "7",
             cell: "role",
             value: "lead",
@@ -169,7 +190,7 @@ describe("an action", () => {
         const hub = createHub(pages({
             counter: {
                 queries: { count: stub(log, "count", {}) },
-                hooks: {
+                requests: {
                     actions: {
                         bump: {
                             run: (ctx) => void (actionCtx = ctx),
@@ -190,8 +211,8 @@ describe("an action", () => {
         const store = { n: 1 };
         const hub = createHub(pages({
             counter: {
-                queries: { count: () => ({ n: String(store.n) }) },
-                hooks: {
+                queries: { count: row(() => ({ n: String(store.n) })) },
+                requests: {
                     actions: {
                         bump: { run: () => void (store.n += 1), refresh: ["count"] },
                     },
@@ -208,8 +229,8 @@ describe("an action", () => {
         // what it changed and may say only that. The narrower answer wins.
         const hub = createHub(pages({
             roster: {
-                queries: { members: () => rows([{ id: "1" }, { id: "2" }]) },
-                hooks: {
+                queries: { members: list(() => [{ id: "1" }, { id: "2" }]) },
+                requests: {
                     actions: {
                         rename: {
                             run: () => ({ members: patch({ rows: [{ id: "2" }] }) }),
@@ -220,13 +241,15 @@ describe("an action", () => {
             },
         }));
         const data = await hub.runAction("roster", "rename", {}, context());
-        assert.deepEqual(data, { members: { op: "patch", rows: [{ id: "2" }] } });
+        assert.deepEqual(data, { members: { rows: [{ id: "2" }] } });
     });
     it("answers with the refresh set alone when it states nothing", async () => {
         const hub = createHub(pages({
             counter: {
-                queries: { count: () => ({ n: "1" }) },
-                hooks: { actions: { bump: { run: () => { }, refresh: ["count"] } } },
+                queries: { count: row(() => ({ n: "1" })) },
+                requests: {
+                    actions: { bump: { run: () => { }, refresh: ["count"] } },
+                },
             },
         }));
         assert.deepEqual(await hub.runAction("counter", "bump", {}, context()), {
@@ -236,8 +259,8 @@ describe("an action", () => {
     it("skips a refresh name the page does not declare, and runs its siblings", async () => {
         const hub = createHub(pages({
             counter: {
-                queries: { count: () => ({ n: "1" }) },
-                hooks: {
+                queries: { count: row(() => ({ n: "1" })) },
+                requests: {
                     actions: {
                         bump: { run: () => { }, refresh: ["ghost", "count"] },
                     },
@@ -253,7 +276,9 @@ describe("an action", () => {
             run: async () => ({ count: { n: "5" } }),
             refresh: [],
         };
-        const hub = createHub(pages({ counter: { queries: {}, hooks: { actions: { bump: action } } } }));
+        const hub = createHub(pages({
+            counter: { queries: {}, requests: { actions: { bump: action } } },
+        }));
         assert.deepEqual(await hub.runAction("counter", "bump", {}, context()), {
             count: { n: "5" },
         });
@@ -262,10 +287,10 @@ describe("an action", () => {
 // --- Cell change -----------------------------------------------------------
 describe("a cell-change", () => {
     it("is refused unless the query declared it", async () => {
-        const hub = createHub(pages({ roster: { queries: { members: () => rows([]) } } }));
-        const { result, warn } = await captured(() => hub.runCellChange("roster", { query: "members", key: "1", cell: "name", value: "Ada" }, context()));
+        const hub = createHub(pages({ roster: { queries: { members: list(() => []) } } }));
+        const { result, warn } = await captured(() => hub.runCellChange("roster", { list: "members", key: "1", cell: "name", value: "Ada" }, context()));
         assert.deepEqual(result, {});
-        assert.match(warn.join("\n"), /page 'roster' declares no cell-change for query 'members'/);
+        assert.match(warn.join("\n"), /page 'roster' declares no cellChange for 'members'/);
     });
     it("hands the operation its key, cell and value, then runs its refresh set", async () => {
         let where;
@@ -273,7 +298,7 @@ describe("a cell-change", () => {
         const hub = createHub(pages({
             roster: {
                 queries: { members: stub(log, "members", { n: "1" }) },
-                hooks: {
+                requests: {
                     crud: {
                         members: {
                             cellChange: {
@@ -285,7 +310,7 @@ describe("a cell-change", () => {
                 },
             },
         }));
-        const data = await hub.runCellChange("roster", { query: "members", key: "7", cell: "role", value: "lead" }, context());
+        const data = await hub.runCellChange("roster", { list: "members", key: "7", cell: "role", value: "lead" }, context());
         assert.deepEqual(where, { key: "7", cell: "role", value: "lead" });
         assert.deepEqual(log, ["members"]);
         assert.deepEqual(data, { members: { n: "1" } });
@@ -293,8 +318,8 @@ describe("a cell-change", () => {
     it("lays what it stated over what the refresh produced", async () => {
         const hub = createHub(pages({
             roster: {
-                queries: { members: () => rows([{ id: "1" }, { id: "2" }]) },
-                hooks: {
+                queries: { members: list(() => [{ id: "1" }, { id: "2" }]) },
+                requests: {
                     crud: {
                         members: {
                             cellChange: {
@@ -308,29 +333,29 @@ describe("a cell-change", () => {
                 },
             },
         }));
-        const data = await hub.runCellChange("roster", { query: "members", key: "2", cell: "name", value: "Grace" }, context());
+        const data = await hub.runCellChange("roster", { list: "members", key: "2", cell: "name", value: "Grace" }, context());
         assert.deepEqual(data, {
-            members: { op: "patch", rows: [{ id: "2", name: "Grace" }] },
+            members: { rows: [{ id: "2", name: "Grace" }] },
         });
     });
 });
-// --- Tuple delete ------------------------------------------------------
-describe("a tuple-delete", () => {
+// --- Row delete ------------------------------------------------------
+describe("a row-delete", () => {
     it("is refused unless the query declared it", async () => {
-        const hub = createHub(pages({ roster: { queries: { members: () => rows([]) } } }));
-        const { result, warn } = await captured(() => hub.runTupleDelete("roster", { query: "members", key: "1" }, context()));
+        const hub = createHub(pages({ roster: { queries: { members: list(() => []) } } }));
+        const { result, warn } = await captured(() => hub.runRowDelete("roster", { list: "members", key: "1" }, context()));
         assert.deepEqual(result, {});
-        assert.match(warn.join("\n"), /page 'roster' declares no tuple-delete for query 'members'/);
+        assert.match(warn.join("\n"), /page 'roster' declares no rowDelete for 'members'/);
     });
     it("hands the operation its key, then runs its refresh set", async () => {
         let where;
         const hub = createHub(pages({
             roster: {
-                queries: { members: () => rows([]) },
-                hooks: {
+                queries: { members: list(() => []) },
+                requests: {
                     crud: {
                         members: {
-                            tupleDelete: {
+                            rowDelete: {
                                 run: (_ctx, w) => void (where = w),
                                 refresh: [],
                             },
@@ -339,17 +364,17 @@ describe("a tuple-delete", () => {
                 },
             },
         }));
-        await hub.runTupleDelete("roster", { query: "members", key: "7" }, context());
+        await hub.runRowDelete("roster", { list: "members", key: "7" }, context());
         assert.deepEqual(where, { key: "7" });
     });
     it("answers with the drop it stated", async () => {
         const hub = createHub(pages({
             roster: {
-                queries: { members: () => rows([{ id: "1" }, { id: "2" }]) },
-                hooks: {
+                queries: { members: list(() => [{ id: "1" }, { id: "2" }]) },
+                requests: {
                     crud: {
                         members: {
-                            tupleDelete: {
+                            rowDelete: {
                                 run: (_ctx, w) => ({
                                     members: patch({ drop: [w.key] }),
                                 }),
@@ -360,27 +385,27 @@ describe("a tuple-delete", () => {
                 },
             },
         }));
-        const data = await hub.runTupleDelete("roster", { query: "members", key: "1" }, context());
-        assert.deepEqual(data, { members: { op: "patch", drop: ["1"] } });
+        const data = await hub.runRowDelete("roster", { list: "members", key: "1" }, context());
+        assert.deepEqual(data, { members: { drop: ["1"] } });
     });
 });
-// --- Tuple insert --------------------------------------------------------
-describe("a tuple-insert", () => {
+// --- Row insert --------------------------------------------------------
+describe("a row-insert", () => {
     it("is refused unless the query declared it", async () => {
-        const hub = createHub(pages({ roster: { queries: { members: () => rows([]) } } }));
-        const { result, warn } = await captured(() => hub.runTupleInsert("roster", { query: "members", values: { name: "Ada" } }, context()));
+        const hub = createHub(pages({ roster: { queries: { members: list(() => []) } } }));
+        const { result, warn } = await captured(() => hub.runRowInsert("roster", { list: "members", values: { name: "Ada" } }, context()));
         assert.deepEqual(result, {});
-        assert.match(warn.join("\n"), /page 'roster' declares no tuple-insert for query 'members'/);
+        assert.match(warn.join("\n"), /page 'roster' declares no rowInsert for 'members'/);
     });
     it("hands the operation the gathered values, then runs its refresh set", async () => {
         let where;
         const hub = createHub(pages({
             roster: {
-                queries: { members: () => rows([]) },
-                hooks: {
+                queries: { members: list(() => []) },
+                requests: {
                     crud: {
                         members: {
-                            tupleInsert: {
+                            rowInsert: {
                                 run: (_ctx, w) => void (where = w),
                                 refresh: [],
                             },
@@ -389,17 +414,17 @@ describe("a tuple-insert", () => {
                 },
             },
         }));
-        await hub.runTupleInsert("roster", { query: "members", values: { name: "Ada", role: "Analyst" } }, context());
+        await hub.runRowInsert("roster", { list: "members", values: { name: "Ada", role: "Analyst" } }, context());
         assert.deepEqual(where, { values: { name: "Ada", role: "Analyst" } });
     });
     it("answers with the row it stated", async () => {
         const hub = createHub(pages({
             roster: {
-                queries: { members: () => rows([{ id: "1" }]) },
-                hooks: {
+                queries: { members: list(() => [{ id: "1" }]) },
+                requests: {
                     crud: {
                         members: {
-                            tupleInsert: {
+                            rowInsert: {
                                 run: (_ctx, w) => ({
                                     members: patch({ rows: [{ id: "2", ...w.values }] }),
                                 }),
@@ -410,29 +435,29 @@ describe("a tuple-insert", () => {
                 },
             },
         }));
-        const data = await hub.runTupleInsert("roster", { query: "members", values: { name: "Ada" } }, context());
+        const data = await hub.runRowInsert("roster", { list: "members", values: { name: "Ada" } }, context());
         assert.deepEqual(data, {
-            members: { op: "patch", rows: [{ id: "2", name: "Ada" }] },
+            members: { rows: [{ id: "2", name: "Ada" }] },
         });
     });
 });
-// --- Tuple update ----------------------------------------------------------
-describe("a tuple-update", () => {
+// --- Row update ----------------------------------------------------------
+describe("a row-update", () => {
     it("is refused unless the query declared it", async () => {
-        const hub = createHub(pages({ roster: { queries: { members: () => rows([]) } } }));
-        const { result, warn } = await captured(() => hub.runTupleUpdate("roster", { query: "members", key: "1", values: { name: "Ada" } }, context()));
+        const hub = createHub(pages({ roster: { queries: { members: list(() => []) } } }));
+        const { result, warn } = await captured(() => hub.runRowUpdate("roster", { list: "members", key: "1", values: { name: "Ada" } }, context()));
         assert.deepEqual(result, {});
-        assert.match(warn.join("\n"), /page 'roster' declares no tuple-update for query 'members'/);
+        assert.match(warn.join("\n"), /page 'roster' declares no rowUpdate for 'members'/);
     });
     it("hands the operation the key and the gathered values, then runs its refresh set", async () => {
         let where;
         const hub = createHub(pages({
             roster: {
-                queries: { members: () => rows([]) },
-                hooks: {
+                queries: { members: list(() => []) },
+                requests: {
                     crud: {
                         members: {
-                            tupleUpdate: {
+                            rowUpdate: {
                                 run: (_ctx, w) => void (where = w),
                                 refresh: [],
                             },
@@ -441,7 +466,7 @@ describe("a tuple-update", () => {
                 },
             },
         }));
-        await hub.runTupleUpdate("roster", { query: "members", key: "7", values: { name: "Ada", role: "Analyst" } }, context());
+        await hub.runRowUpdate("roster", { list: "members", key: "7", values: { name: "Ada", role: "Analyst" } }, context());
         assert.deepEqual(where, {
             key: "7",
             values: { name: "Ada", role: "Analyst" },
@@ -450,11 +475,11 @@ describe("a tuple-update", () => {
     it("answers with the row it stated", async () => {
         const hub = createHub(pages({
             roster: {
-                queries: { members: () => rows([{ id: "1", name: "old" }]) },
-                hooks: {
+                queries: { members: list(() => [{ id: "1", name: "old" }]) },
+                requests: {
                     crud: {
                         members: {
-                            tupleUpdate: {
+                            rowUpdate: {
                                 run: (_ctx, w) => ({
                                     members: patch({ rows: [{ id: w.key, ...w.values }] }),
                                 }),
@@ -465,31 +490,57 @@ describe("a tuple-update", () => {
                 },
             },
         }));
-        const data = await hub.runTupleUpdate("roster", { query: "members", key: "1", values: { name: "Ada" } }, context());
+        const data = await hub.runRowUpdate("roster", { list: "members", key: "1", values: { name: "Ada" } }, context());
         assert.deepEqual(data, {
-            members: { op: "patch", rows: [{ id: "1", name: "Ada" }] },
+            members: { rows: [{ id: "1", name: "Ada" }] },
         });
     });
 });
 // --- The wire vocabulary -------------------------------------------------
-describe("the projection helpers", () => {
-    it("name the whole set", () => {
-        assert.deepEqual(rows([{ id: "1" }]), { op: "rows", rows: [{ id: "1" }] });
-    });
-    it("name only what changed, and carry nothing they were not given", () => {
-        assert.deepEqual(patch({ drop: ["1"] }), { op: "patch", drop: ["1"] });
-        assert.deepEqual(patch({}), { op: "patch" });
-    });
-    it("are what isProjection recognises", () => {
-        assert.equal(isProjection(rows([])), true);
-        assert.equal(isProjection(patch({})), true);
-        assert.equal(isProjection({ id: "1", name: "Ada" }), false);
-    });
-    it("share one word with a tuple's cells, which reserves it", () => {
-        // Stated in core/lb-types.ts: `op` is a reserved cell name, because a
-        // tuple carrying one whose value is 'rows' or 'patch' is read as a
-        // projection. The hazard is real and this is where it is written down.
-        assert.equal(isProjection({ op: "rows" }), true);
-        assert.equal(isProjection({ op: "deleted" }), false);
+describe("cardinality is declared, not inspected", () => {
+    it("marks a list query and a row query apart", () => {
+        assert.equal(list(() => []).kind, "list");
+        assert.equal(row(() => ({})).kind, "row");
+    });
+    it("carries a whole set as the array itself, with no wrapper", async () => {
+        const set = [{ id: "1" }, { id: "2" }];
+        const hub = createHub(pages({ roster: { queries: { members: list(() => set) } } }));
+        assert.deepEqual(await hub.dataForPage("roster", context()), {
+            members: set,
+        });
+    });
+    it("carries only what changed as an object, and adds nothing", () => {
+        assert.deepEqual(patch({ drop: ["1"] }), { drop: ["1"] });
+        assert.deepEqual(patch({}), {});
+    });
+    it("tells a whole set from a patch by Array.isArray, so no column is reserved", () => {
+        // `op` used to be a reserved column name, because the hub read it to
+        // decide which shape had arrived. Nothing inspects a value now.
+        assert.equal(Array.isArray(patch({ rows: [] })), false);
+        assert.equal(Array.isArray([{ op: "rows" }]), true);
+    });
+    it("refuses a list query that answers with one row", async () => {
+        const hub = createHub(pages({
+            roster: {
+                queries: {
+                    members: list(() => ({})),
+                },
+            },
+        }));
+        const { result, warn } = await captured(() => hub.dataForPage("roster", context()));
+        assert.deepEqual(result, {});
+        assert.match(warn.join("\n"), /query 'members' is declared list but answered with one row/);
+    });
+    it("refuses a row query that answers with rows", async () => {
+        const hub = createHub(pages({
+            roster: {
+                queries: {
+                    chosen: row(() => []),
+                },
+            },
+        }));
+        const { result, warn } = await captured(() => hub.dataForPage("roster", context()));
+        assert.deepEqual(result, {});
+        assert.match(warn.join("\n"), /query 'chosen' is declared row but answered with rows/);
     });
 });

package/dist/tests/origins.test.js

@@ -91,7 +91,7 @@ describe("scanOrigin", () => {
         const dir = await tree({
             "chrome.html": "<lb-hub><main></main></lb-hub>",
             "about.page.html": "<h1>About</h1>",
-            "about.hooks.ts": "export const hooks = {};",
+            "about.requests.ts": "export const requests = {};",
             "imports.ts": "export default {};",
         });
         try {
@@ -118,6 +118,24 @@ describe("scanOrigin", () => {
             await rm(dir, { recursive: true, force: true });
         }
     });
+    it("throws when a definition filename carries capitals", async () => {
+        const dir = await tree({ "App-Box.html": "<div></div>" });
+        try {
+            await assert.rejects(() => scanOrigin({ name: "src", dirs: [dir] }), /carries capitals.*must be named 'app-box\.html'/);
+        }
+        finally {
+            await rm(dir, { recursive: true, force: true });
+        }
+    });
+    it("throws when a widget script filename carries capitals", async () => {
+        const dir = await tree({ "App-Box.browser.ts": "export {};" });
+        try {
+            await assert.rejects(() => scanOrigin({ name: "src", dirs: [dir] }), /must be named 'app-box\.browser\.ts'/);
+        }
+        finally {
+            await rm(dir, { recursive: true, force: true });
+        }
+    });
     it("throws when one origin has two definitions for the same tag", async () => {
         const dir = await tree({
             "a/app-box.html": "<div></div>",

package/dist/tests/pages.test.d.ts

@@ -1,5 +1,5 @@
 /**
- * Discovering `*.hooks.ts`/`*.queries.ts` pairs (build/locations.ts) and
+ * Discovering `*.requests.ts`/`*.queries.ts` pairs (build/locations.ts) and
  * generating the hub registry from them (build/pages.ts).
  */
 export {};