@jskit-ai/agent-docs 0.1.293 → 0.1.294

package/guide/agent/app-extras/realtime.md

@@ -103,10 +103,13 @@ audience contributor is registered and a target room is a user or workspace
 room, when its actor's contributed rooms include a target room or it has not
 signed in yet. A socket joins only its own actor's contributed rooms, so a
 publish to `workspace:7` checks that workspace's members' sockets, not every
-connected one. To decide, the publish resolves the contributed rooms of every
-signed-in socket's actor in one call to each contributor, whatever the number
-of sockets. Other sockets are not checked for that publish; the 30-second check
-reaches them. Sockets whose authentication requests are identical, such as tabs of
+connected one. To decide, the publish asks each contributor once about the
+actors of every signed-in socket outside the target rooms, whatever their
+number, naming only the target rooms' scopes, so a contributor reads only
+those (a publish to `workspace:7` reads workspace 7's memberships among them,
+and a publish to user rooms reads no memberships); meanwhile it looks up the
+contributed rooms of the actors already inside, for their checks. Other
+sockets are not checked for that publish; the 30-second check reaches them. Sockets whose authentication requests are identical, such as tabs of
 one browser, share one `authenticateRequest()` call within a publish or a
 30-second pass, and the sockets a publish or pass checks reuse that one lookup
 of their contributed rooms; nothing is reused from one publish or pass to the
@@ -140,12 +143,19 @@ them in one query rather than one per actor: it returns, or resolves to, a `Map`
 from actor id to that actor's event scopes (`{ kind: "user", id }`,
 `{ kind: "workspace", id }` or `{ kind: "workspace_user", workspaceId, userId }`);
 an actor it leaves out has none. A single actor is asked as a list of one.
+A publish asking whether actors outside its rooms belong to them calls
+`resolveActorsScopes(actorIds, { scopes })` with those rooms' scopes: the
+contributor may read only those scopes, and realtime keeps only them of its
+answer, so a contributor that ignores `scopes` still answers correctly.
 Realtime turns each scope into the same room an `event_scope` audience targets. Sockets
 join those rooms on connection and, on every revalidation, leave the contributed
 rooms the actor no longer belongs to; rooms joined by anything else are left
 alone. `@jskit-ai/workspaces-core` contributes the actors' active workspace
 memberships this way when realtime is installed, with
 `listActiveWorkspaceIdsByUserIds()`: one memberships query per 1,000 actors.
+Asked about some scopes, it reads only the memberships of the workspaces they
+name, with `listActiveWorkspaceIdsByUserIdsAmong()`, and none when they name
+no workspace.
 
 The authentication request includes parsed cookies, the `Host`, `Origin` and
 `X-Forwarded-Proto` headers when present, and the socket address and TLS state.

package/guide/agent/app-setup/multi-homing.md

@@ -196,12 +196,21 @@ method takes the call's `options` last and joins the transaction of the
 | Capability | Methods |
 | --- | --- |
 | `workspaces` | `findById(id, options)`, `findBySlug(slug, options)` (a deleted workspace is not found, though its slug stays taken), `listSlugsIn`, `findPersonalByOwnerUserId`, `listForUserId(userId, options)`, `insert`, `updateById`, `lock(workspaceId, options)` |
-| `workspaces.memberships` | `findByWorkspaceIdAndUserId`, `ensureOwnerMembership`, `upsertMembership(workspaceId, userId, patch, options)`, `addMember({ workspaceId, userId, roleSid }, options)`, `activeMemberIds(workspaceId, options)`, `listActiveByWorkspaceId`, `findActiveByWorkspaceIdAndUserId`, `listActiveWorkspaceIdsByUserId`, `listActiveWorkspaceIdsByUserIds` |
+| `workspaces.memberships` | `findByWorkspaceIdAndUserId`, `ensureOwnerMembership`, `upsertMembership(workspaceId, userId, patch, options)`, `addMember({ workspaceId, userId, roleSid }, options)`, `activeMemberIds(workspaceId, options)`, `listActiveByWorkspaceId`, `findActiveByWorkspaceIdAndUserId`, `listActiveWorkspaceIdsByUserId`, `listActiveWorkspaceIdsByUserIds`, `listActiveWorkspaceIdsByUserIdsAmong(userIds, workspaceIds, options)`, `joinSource({ alias, filters }, options)` |
 
 `addMember` makes the user an active member with the role (`member` when none
 is given), adding the membership or reactivating it. `activeMemberIds` answers
-the active members' user ids at the same cost however many members there
-are, without including their profiles. `lock` takes
+every active member's user id, without their profiles: it reads all of the
+workspace's active memberships, so its cost grows with the workspace, and so
+do `listActiveByWorkspaceId`'s and
+`workspaces.services.members.listMembers(workspace, options)`'s. Use them where
+the work needs every member, such as a job, a delivery's recipients or a
+realtime audience. A screen or list reads a page instead:
+`workspaces.services.members.listMembersPage(workspace, { cursor, limit }, options)`
+answers one page of active members by display name (`limit`, 20 when none)
+with the `nextCursor` that asks for the next, null on the last, and an app's
+own list of members pages them in SQL with one report over the memberships'
+`joinSource`. `lock` takes
 the workspace's row lock until the caller's transaction ends, so work that must
 not interleave for one workspace takes turns; it runs only inside a
 transaction, given its `txOptions`, and answers `{ id }`, or `null` when there

package/guide/agent/framework/client-features.md

@@ -519,6 +519,33 @@ let attachmentClientSequence = 0;
 let pendingDraft = "";
 ```
 
+### Search on the server
+
+**A search over a list's records runs on the server: the list's search
+(`useList({ search: { enabled: true } })`) sends what the person types as `q`,
+and the table resource defines `searchSchema.q`. An autocomplete over a list's
+items or a lookup's options takes `no-filter` and sends the typed text with
+`@update:search` (a lookup's `setLookupSearch`).**
+
+Why: a list holds the page it loaded, so a search over its items misses every
+row past that page.
+
+```vue
+<!-- good: the server searches every record -->
+<SelectField v-model="formState.serviceId" searchable no-filter
+  :search="resolveLookupSearch('serviceId')"
+  @update:search="setLookupSearch('serviceId', $event)"
+  :items="resolveLookupItems('serviceId', { selectedValue: formState.serviceId })" />
+
+<!-- bad: Vuetify searches only the options already loaded -->
+<v-autocomplete v-model="serviceId" :items="services.items" />
+```
+
+```js
+// bad: a search over the page the list loaded
+const visible = computed(() => list.items.filter((service) => service.name.includes(search.value)));
+```
+
 ## Helpers and sizes
 
 ### One helper per package
@@ -587,6 +614,7 @@ client-only rules below. The server's action and error rules do not apply.
 | `jskit/released-listeners` | a listener, interval, observer or subscription the file starts and never releases | [Released listeners](#released-listeners) |
 | `jskit/no-module-state` | a module-level `let`, `ref()` or `reactive()` | [Module state](#module-state) |
 | `jskit/selection-field` | a `v-select`, `v-autocomplete` or `v-combobox` whose items are not fixed, and a `SelectField` whose items are not fixed that binds no `loading` | [Selection fields](#selection-fields) |
+| `jskit/search-on-server` | a `computed()` that filters a list composable's items by a search ref; an autocomplete over a list's items or a lookup's options without `no-filter` or an `update:search` handler | [Search on the server](#search-on-the-server) |
 | `vue/require-prop-types`, `vue/require-default-prop`, `vue/require-valid-default-prop`, `vue/no-required-prop-with-default` | a prop without a type, optional without a default, or both | [Collaborator props](#collaborator-props) |
 | `vue/require-explicit-emits` | an emitted event the component does not declare | [Declared emits](#declared-emits) |
 

package/guide/agent/framework/crud-operations.md

@@ -256,6 +256,13 @@ mapping in the resource; do not add page-local filtering or duplicate request
 code. The full Books source example maps `q` to title, author and notes; narrow
 it when adapting the example to fewer fields.
 
+Every CRUD list also takes `id`, one record id or a list of them
+(`filter[id]` on the JSON:API transport), and answers only those of its rows,
+in the caller's scope. A picker whose selected values are not on the page it
+loaded reads them this way, all in one request, instead of showing their raw
+ids or reading pages until it finds them; `useCrudListFilterLookups()` does it
+for a lookup filter's chips and options.
+
 The browser page's route query and internal CRUD query use plain `q`. The
 JSON:API HTTP transport uses `filter[q]`. Shared CRUD clients encode and decode
 this automatically. Raw HTTP/API tests must send the transport key themselves:

package/guide/agent/framework/data-access.md

@@ -65,7 +65,9 @@ A grouped `aggregate` answers its groups from one statement, at most
 `pageLimits().request` of them (the resource's `queryMaxLimit`). When there
 are more it throws a 400 coded `RESOURCE_GROUP_LIMIT` instead of answering
 part of them. Narrow the filters, or read the groups in pages, `page: { size,
-number }` with `number` from 1, until a page answers fewer than `size` rows.
+number }` with `number` from 1. A page answers as a `query` page does, `{ rows,
+page: { size, number, hasMore, next } }`, never a bare array that could pass
+for every group: read the next while `page.hasMore`.
 Page numbers are offsets, so read every page before work that changes what
 the filters match.
 
@@ -715,12 +717,12 @@ takes first.
 // good: the lock is the transaction's first read, so the bookings read after it are current
 const reserve = (seatId, options) => seats.withTransaction(options, async (txOptions) => {
   await seats.lock(seatId, { ...txOptions, fields: ["status"] });
-  const taken = await bookings.queryAll({ filters: { seatIds: [seatId] } }, txOptions);
-  return taken.length > 0 ? null : bookings.create({ seatId }, { ...txOptions, returning: "id" });
+  const [taken] = await bookings.queryAll({ filters: { seatIds: [seatId] }, take: 1 }, txOptions);
+  return taken ? null : bookings.create({ seatId }, { ...txOptions, returning: "id" });
 });
 
 // bad: the read before the lock fixed the snapshot, so a booking committed while the lock waited is missed
-const free = await bookings.queryAll({ filters: { seatIds: [seatId] } }, txOptions);
+const [booked] = await bookings.queryAll({ filters: { seatIds: [seatId] }, take: 1 }, txOptions);
 await seats.lock(seatId, txOptions);
 ```
 
@@ -931,7 +933,11 @@ async function activeDays(memberIds, options) {
   `page.number` reads with OFFSET, which slows as the rows grow, so anything
   that grows pages with `page.after`. Each page is one statement, with no
   count: never walk pages to reach one.
-- A screen list never uses `queryAll`.
+- A screen list never uses `queryAll`, and neither does a picker: it reads
+  one page searched on the server as the person types (`q`), narrowed in the
+  query by what it depends on (the parent record, `active`), and reads its
+  selected values past that page by id. Reading every row for a dropdown, or
+  narrowing a page in code, either grows with the table or misses rows.
 - Related rows come by id list (`filters: { id: ids }`, or an `in` filter on
   another field) or `include`, grouped in memory. Never a query per row, however
   the loop is spelled (`for`, `map` with `Promise.all`, a helper called per
@@ -987,6 +993,66 @@ const { records: firstPage } = await subscriptions.query({ filters: { newsletter
 
 Bad: a list read 100-row pages in a loop for each of 40 related sets.
 
+## Narrow in the query
+
+A read asks the store for exactly the rows the code uses. The filter, sort,
+limit, existence check and count go in the read, never in code over the rows
+it answered: a read of every row then narrowed is slow, and a page or a `take`
+then narrowed is also wrong, since the row wanted can sit past it.
+
+- Filter with the resource's searchSchema: a field
+  (`filters: { status: "open" }`), an id list (`filters: { id: ids }`, or an
+  `in` filter on another field), or `q` for typed text, whose `oneOf` names the
+  fields it searches.
+- One row: a unique filter with `take: 1` or `page: { size: 1 }`, which also
+  answers whether one exists. A count: `aggregate()`.
+- Never filter, find, slice or count the rows a read answered, nor skip some
+  in a loop. Mapping them and grouping them by a key (`Map.groupBy`) narrow
+  nothing, and neither does code that needs every row it read: rows handed on
+  whole (returned, passed, stored, mapped or walked in full) with a subset
+  derived beside them, and rows matched against other items in a loop or a
+  callback (an in-memory join, one read instead of one per item).
+- A lookup field's picker and a list's Search box send what the person types
+  as `q` to the server, which searches every row; `useList` does with
+  `search: { enabled: true }`. The table resource defines `searchSchema.q`.
+  Never search the page a list loaded in the browser: it misses every row past
+  it.
+- A CRUD list refuses a query key it does not take with a 400
+  (`crud.query.undeclaredKeys`). A list filter is declared in the feature's
+  `listFilterQueryValidator` and the resource's searchSchema.
+- Prove a capped read with a test that seeds past the cap and makes the row
+  the cap leaves out (the oldest, for a newest-first read) the one that
+  matches: the read that asks for it finds it; a read narrowed in code does
+  not.
+
+```js
+// good: the store answers one module's sections
+const { records } = await sections.query({ filters: { moduleId }, sort: ["-createdAt"], page: { size: 50 } }, options);
+
+// bad: the newest 200 sections of every module, then one module's kept in code
+const { records: recent } = await sections.query({ sort: ["-createdAt"], page: { size: 200 } }, options);
+const moduleSections = recent.filter((section) => section.moduleId === moduleId);
+
+// good: one row says who holds a unique username
+const [holder] = await profiles.queryAll({ filters: { usernames: [username] }, take: 1 }, options);
+```
+
+`jskit/narrow-in-query` reports `.filter()`, `.find()`, `.some()`,
+`.every()`, `.slice()`, a lone `.length` and a loop that skips rows with
+`continue` over the rows a read answered in the same function, unless the
+code also uses those rows whole, runs the narrowing once per item of
+something else, read at most one row, or slices a read that asked for one row
+more than it keeps (`limit(size + 1)`) to learn whether more follow.
+`jskit/search-on-server` reports a client search over a list's loaded items.
+`jskit check` fails a lookup field or a CRUD list screen whose app table
+resource has no `searchSchema.q`, on the resource or its owns entry
+(`data/search-q`). Other code that needs every row a read answers says why on
+the line above the read or the narrowing:
+
+```js
+// readable-check: allow narrow-in-query - every row: a conversation holds at most keep + 1 summaries, since each save deletes the older ones
+```
+
 ## What changed since
 
 A page that catches up on a chat, a watch that acts on changes and a sync to
@@ -1082,10 +1148,10 @@ const SettlementFeature = defineFeature({
   async function settleDue(options) {
     const size = cohorts.pageLimits().request;
     const due = [];
-    for (let number = 1; ; number += 1) {
-      const page = await cohorts.aggregate({ measures: { cohorts: { count: "id" } }, groupBy: ["workspaceId"], filters: { status: "finished" }, page: { size, number } }, options);
-      due.push(...page);
-      if (page.length < size) break;
+    for (let number = 1; number; ) {
+      const { rows, page } = await cohorts.aggregate({ measures: { cohorts: { count: "id" } }, groupBy: ["workspaceId"], filters: { status: "finished" }, page: { size, number } }, options);
+      due.push(...rows);
+      number = page.next;
     }
     for (const { workspaceId } of due) {
       await settleWorkspace({ context: systemContext("settle finished weekly leagues for every user").forWorkspace(workspaceId) });

package/guide/agent/framework/sanity-checks.md

@@ -67,13 +67,13 @@ expects the relationship id or an unselected field never gets it.
 ### Every row
 
 - A handle's `query()` answers one page and refuses a missing or oversized
-  `page.size`, where json-rest-api would cut the list silently. A read its
-  callers treat as complete uses `queryAll()`, or the missing rows vanish from
-  every picker and delivery built on it
+  `page.size`, where json-rest-api would cut the list silently. A delivery
+  reaching every row uses `queryAll()`; a picker reads a page searched with
+  `q` and its selected values by `id`
   ([Reads](/guide/framework/data-access#reads-shaped-for-the-screen)).
 - A grouped `aggregate()` answers every group or throws
   `RESOURCE_GROUP_LIMIT`; past `pageLimits().request` groups, page it with
-  `page: { size, number }`
+  `page: { size, number }` (answers `{ rows, page }`)
   ([The handle's calls](/guide/framework/data-access#the-handle-s-calls)).
 - A lookup by a unique key matches at most one row: `get(id)`, or a `query()`
   of page size 1.

package/guide/agent/framework/typed-features.md

@@ -652,9 +652,9 @@ Why: a value with two defaults has two meanings, and a mode flag hides a
 second method inside the first.
 
 ```js
-// good
-async function list(filters, options = {}) {
-  return invoices.queryAll({ filters }, options);
+// good: one page, as a list shows it
+async function list(filters, page, options = {}) {
+  return invoices.query({ filters, page }, options);
 }
 
 // bad
@@ -776,6 +776,13 @@ handle's `queryAll(params, options)`. A `query()` names its page size, and
 answers one page.** [Reads shaped for the screen](/guide/framework/data-access#reads-shaped-for-the-screen)
 gives the rules and examples.
 
+### Narrow in the query
+
+**A read asks for exactly the rows the code uses: its filter, sort, limit,
+existence check and count go in the read, never in code over the rows it
+answered.** [Narrow in the query](/guide/framework/data-access#narrow-in-the-query)
+gives the rules and examples.
+
 ### Lists read related rows in batches
 
 **A read that builds a list fetches its related rows in batches, an id-list
@@ -1277,6 +1284,7 @@ Every finding ends with a link to the section of this page that explains it.
 | `jskit/app-error-code` | an `AppError`, `DomainError`, `ConflictError` or `NotFoundError` (or a subclass the module declares) without its own code, and one code naming two sentences in a module | [Refusals carry their own code](#refusals-carry-their-own-code) |
 | `jskit/no-patched-error` | `Object.assign(new Error(…), { statusCode })`, or an error builder's result given its status afterwards | [One construction per error](#one-construction-per-error) |
 | `jskit/no-test-only-export` | an export whose name says only tests use it (`…ForTests`, `__reset…`; `__testables` aside) | [No test-only exports](#no-test-only-exports) |
+| `jskit/narrow-in-query` | `.filter()`, `.find()`, `.some()`, `.every()`, `.slice()`, a lone `.length` or a loop that skips with `continue`, over the rows a read in the same function answered and uses no other way | [Narrow in the query](#narrow-in-the-query) |
 | `jskit/one-property-per-line` | two properties on one line in a returned `Object.freeze({ … })` or a `requires` / `optional` / `provides` map (`eslint --fix` splits them) | [Formatter](#formatter) |
 | `jskit/jsdoc-description-inside` | a `//` description directly above a `/** */` block | [Comments](#comments) |
 | `jskit/allow-comment-form` | a `readable-check: allow` reason without a prefix from the table below, or one that cites tests or the state of a project | [Exceptions](#exceptions) |
@@ -1328,6 +1336,7 @@ if (typeof buildSerializer !== "function") {
 | `filled by <repository>; convert with its supplier` | keeps a setter that another repository's code calls |
 | `cross-repository slot <token>` | keeps a probe for a token another repository supplies |
 | `shared resource:` | keeps client module state that every instance on the page shares on purpose ([client features](/guide/framework/client-features#module-state)) |
+| `every row: <why>` | code needs every row a read answers and narrows them for its own use, such as a read the data itself keeps small (a conversation's few summaries) whose oldest ones it deletes (`jskit/narrow-in-query`) |
 | `infrastructure: <what the module is>` | excuses a whole file whose job is data access itself from `jskit/no-direct-knex` or `jskit/no-transaction-reader`, one line per rule before its first line of code ([data access](/guide/framework/data-access#exceptions)) |
 
 One kind of probe gets one prefix and one wording everywhere, and a bare

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.293",
+  "version": "0.1.294",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/patterns/minimal-foundation/example/package.json

@@ -49,8 +49,8 @@
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.249",
-    "@jskit-ai/jskit-catalog": "0.2.45",
+    "@jskit-ai/config-eslint": "0.1.250",
+    "@jskit-ai/jskit-catalog": "0.2.46",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",

package/patterns/shell-foundation/example/package.json

@@ -45,13 +45,13 @@
     "vue-router": "^5.3.1",
     "vuetify": "^4.3.0",
     "@jskit-ai/http-runtime": "0.2.18",
-    "@jskit-ai/shell-web": "0.2.22",
+    "@jskit-ai/shell-web": "0.2.23",
     "@fastify/fast-json-stringify-compiler": "^5.1.0",
     "@vue/devtools-api": "^8.2.1"
   },
   "devDependencies": {
-    "@jskit-ai/config-eslint": "0.1.249",
-    "@jskit-ai/jskit-catalog": "0.2.45",
+    "@jskit-ai/config-eslint": "0.1.250",
+    "@jskit-ai/jskit-catalog": "0.2.46",
     "@playwright/test": "1.61.1",
     "@vitejs/plugin-vue": "^6.0.7",
     "eslint": "^10.8.0",