@nxgt/janus 0.18.0 → 0.19.0

package/docs/guide/users.md

@@ -180,6 +180,7 @@ In the one-type form these are on `auth` itself; with several types, on
 | --- | --- | --- |
 | `create(fields & { password?, active? })` | the user; no session | `USER_INVALID`, `PASSWORD_TOO_SHORT`, `LOGIN_TAKEN` |
 | `find(id)` | the user, or `null` — for a malformed id, an unknown one, or one of another type | |
+| `findMany(ids)` | the users, in the order of `ids`, each once; an id `find` answers `null` for is left out — see [below](#several-users-at-once--findmany) | |
 | `get(id)` | the user | `NOT_FOUND` |
 | `list({ after?, limit? })` | `CursorPage<User>`, in creation order | `INVALID_CURSOR` |
 | `update(user, patch, { ifVersion? })` | the user as written; sends `user.emailChanged` when the e-mail changed | `USER_INVALID`, `LOGIN_TAKEN`, `VERSION_CONFLICT`, `NOT_FOUND` |
@@ -249,6 +250,53 @@ idempotent: calling it again finishes the job. When it deleted the user, it
 sends a [`user.deleted` event](events.md) — once, after the sessions, tokens and relation tuples are gone, and even when an outage interrupts removing them;
 `create` and `signUp` send `user.created`.
 
+### Several users at once — `findMany`
+
+A list of rows that each name a user — a staff list showing every member's
+account state — reads them in one call, not one `find` per row:
+
+```ts
+const rows = await db.staffRows();                       // your own table, 100 rows
+const members = await clinic.staff.findMany(rows.map((row) => row.staffId));
+const byId = new Map(members.map((member) => [member.id, member]));
+
+const shown = rows.map((row) => {
+	const member = byId.get(row.staffId);                // undefined: nobody holds this id
+	return { ...row, active: member?.active ?? false, verified: member?.emailVerified ?? false };
+});
+```
+
+- **Order**: the order of `ids`. A repeated id is answered once, at its first
+  place.
+- **Absence**: an id `find` would answer `null` for — malformed, unknown, or
+  held by a user of another type — is **left out**, never an error. The answer
+  may be shorter than `ids`, so match by `user.id`, never by position.
+- **Empty**: `[]`, or a list with no well-formed id, answers `[]` without
+  reaching the store.
+- **Size**: any length. The store is asked 100 ids at a time, one batch after
+  another, so no query grows with your list.
+- **Failure**: `STORE_FAILED`, never a shorter list. Something other than an
+  array is a bare `TypeError`: only your code passes one.
+- **Cost**: one query per 100 ids when the users store implements the
+  optional `findUsers` — the reference store, `@nxgt/janus-drizzle` and
+  `@nxgt/janus-mongo` do. A store that does not is read with `findUser`,
+  **ten at a time**, so a third-party adapter keeps working and never opens
+  more than ten reads at once for one call; see
+  [writing an adapter](adapters.md#userstorefindusers-optional).
+
+**A GraphQL resolver per row** can batch through a DataLoader of your own —
+`@nxgt/janus-graphql` loads no users itself:
+
+```ts
+import DataLoader from 'dataloader';
+
+// One per request, so nothing is cached across users' requests.
+const staffById = new DataLoader(async (ids: readonly string[]) => {
+	const found = new Map((await clinic.staff.findMany(ids)).map((u) => [u.id, u]));
+	return ids.map((id) => found.get(id) ?? null);
+});
+```
+
 ### Paging every user
 
 ```ts

package/docs/roadmap.md

@@ -20,6 +20,11 @@ Nothing yet.
   window. A port method to collect them, as sessions are, would let the
   core do it.
 
+- **A batch read across types** — `findMany` reads one user type, as `find`
+  does. The shared `findUser(id)` has no batch counterpart yet; one on the
+  instance, answering a union narrowed by `user.type`, would serve a list that
+  mixes types.
+
 - **More official adapters** — the ports are cut where atomicity is not
   required, so users, sessions and permission tuples can each live in the
   database that suits them. MongoDB is the first adapter
@@ -71,6 +76,13 @@ Nothing yet.
 The last ten, newest first, each with the version it came in. Everything
 before is in the [CHANGELOG](../CHANGELOG.md).
 
+- **Several users by id in one query, v0.18.0** — `auth.<type>.findMany(ids)`
+  answers the type's users in the order of `ids`, each once, and leaves out an
+  id nobody of that type holds — for a list of rows that would otherwise make
+  one `find` per row and fill the connection pool. The users store gains an
+  optional `findUsers`, implemented by the reference store,
+  `@nxgt/janus-drizzle` 0.7.0 and `@nxgt/janus-mongo` 0.8.0; a store without it
+  is read with `findUser`, ten at a time, so third-party adapters keep working.
 - **Requests that send e-mail are throttled, v0.18.0** —
   `janus({ mail: { throttle: { attempts, window } } })`, five per ten
   minutes by default and `false` to turn it off. `magicLink.request`,
@@ -153,20 +165,6 @@ before is in the [CHANGELOG](../CHANGELOG.md).
   user only — or a security settings page; `null` for a user with no active
   factor. The listener can now tell the user how many codes remain, as
   `@nxgt/janus-mail`'s `recoveryCodeUsed` e-mail does.
-- **Recovery codes, v0.10.0** — a user who loses their authenticator app
-  still signs in, with no operator resetting the account.
-  `secondFactor.activate` answers `{ user, recoveryCodes }`: ten single-use
-  codes, shown once and stored only as keyed hashes (breaking: read `.user`).
-  `secondFactor.recover(challenge, code)` redeems a sign-in's challenge with
-  one and answers the session with `recoveryCodesLeft`;
-  `secondFactor.regenerateRecoveryCodes(user, code)` replaces them all on a
-  fresh code from the app, and counts its attempts itself — five per user
-  per 15-minute window, in the store — so a stolen session cannot guess the
-  code, and the route needs no limiter of its own. Two user events,
-  `user.recoveryCodesRegenerated` and `user.recoveryCodeUsed`. For adapters:
-  `SecondFactorRecord.recoveryCodes`,
-  stored by the users stores of `@nxgt/janus-drizzle` and
-  `@nxgt/janus-mongo`, with conformance cases.
 - **Sending the e-mails, `@nxgt/janus-mail` v0.1.0** — a package of its
   own, built on the `@nxgt/mail` toolkit: `janusMail({ mailer, from, brand,
   links })` takes what each flow answers —

package/docs/troubleshooting.md

@@ -49,6 +49,9 @@ How the messages are shaped:
 **Users, sessions and tokens**
 - [`STORE_FAILED` — `<slot>.<method>: the store could not answer`](#store_failed--slotmethod-the-store-could-not-answer)
 - [`STORE_FAILED` — `<slot>.<method> answered undefined …`](#store_failed--slotmethod-answered-undefined-an-absence-is-null-so-this-store-forgot-to-answer)
+- [`STORE_FAILED` — `users.findUsers answered no list …`](#store_failed--usersfindusers-answered-no-list-an-absence-is-a-shorter-list-so-this-store-forgot-to-answer)
+- [`<call>: ids must be an array of user ids`](#call-ids-must-be-an-array-of-user-ids)
+- [`findMany` answers fewer users than ids](#findmany-answers-fewer-users-than-ids)
 - [`NOT_FOUND` — `<call>: no <type> has this id`](#not_found--call-no-type-has-this-id)
 - [`LOGIN_TAKEN` — `<call>: the login is taken by another <type>`](#login_taken--call-the-login-is-taken-by-another-type)
 - [`VERSION_CONFLICT` — `<call>: expected version <n>, found <m>`](#version_conflict--call-expected-version-n-found-m)
@@ -283,10 +286,10 @@ janus({ ..., hasher: scryptHasher(), verifiers: [legacyBcrypt] }); // not [scryp
 
 ### `janus: store.<slot> has no method <method>, which the port requires`
 
-Also: `janus: store.<slot> is missing`, `janus: store must be an object with users, sessions and tokens`, `janus: store.sessions.deleteExpiredSessions must be a function or absent`.
+Also: `janus: store.<slot> is missing`, `janus: store must be an object with users, sessions and tokens`, `janus: store.sessions.deleteExpiredSessions must be a function or absent`, `janus: store.users.findUsers must be a function or absent`.
 
 **When:** `janus({...})`, from JavaScript or with a store typed loosely. TypeScript refuses a partial store at compile time and names the method.
-**Why:** `store` is `{ users, sessions, tokens }`, and each slot must answer every method of the port. `deleteExpiredSessions` is the one optional method: absent, or a function.
+**Why:** `store` is `{ users, sessions, tokens }`, and each slot must answer every method of the port. Two methods are optional — `sessions.deleteExpiredSessions` and `users.findUsers` — and each is absent, or a function: a value in its place (`findUsers: true`, a property copied from a config) is a wiring mistake, not an absent capability.
 An adapter written for an earlier `@nxgt/janus` reports the method a later
 release added to the port: `store.tokens has no method countAttempt` for one
 written against 0.3 (the method came in 0.4), and
@@ -543,6 +546,40 @@ try {
 **Why:** a method that can find nothing must answer `null`. `undefined` is also what a missing `return` produces, so it is treated as a bug in the store, not as "not found".
 **Fix:** `return doc ?? null;` — and run `@nxgt/janus/conformance` against the store.
 
+### `STORE_FAILED` — `users.findUsers answered no list: an absence is a shorter list, so this store forgot to answer`
+
+**When:** `findMany`, over a users store you wrote that implements the optional `findUsers`.
+**Why:** `findUsers` answered `null`, `undefined` or something else than an array. An id nobody holds is left out of the list, and nobody at all is `[]`; anything else is a store that forgot to answer, so it fails rather than read as "nobody".
+**Fix:** answer the rows you found, mapped to records — or leave `findUsers` out, and `findMany` reads with `findUser`:
+
+```ts
+findUsers: async (ids) => (await db.users.where('id', 'in', ids)).map(toUser), // [] when none
+```
+
+### `<call>: ids must be an array of user ids`
+
+A bare `TypeError` — `findMany: …`, or `staff.findMany: …` with several user types.
+
+**When:** `findMany` was given something other than an array: one id, a `Set`, a comma-separated string.
+**Why:** `findMany` takes a list; one id is `find`. Only your code passes the wrong shape, and TypeScript refuses it.
+**Fix:** pass an array, or use `find` for one id:
+
+```ts
+await auth.staff.findMany([...selectedIds]); // from a Set
+await auth.staff.find(id);                   // one id
+```
+
+### `findMany` answers fewer users than ids
+
+**When:** always, when an id is malformed, unknown, held by a user of another type, or repeated.
+**Why:** `findMany` leaves out what `find` answers `null` for, and answers a repeated id once — it never puts `null` in a place. Reading `users[i]` as the user of `ids[i]` then shows one row's account on another.
+**Fix:** match by id:
+
+```ts
+const byId = new Map((await auth.staff.findMany(ids)).map((user) => [user.id, user]));
+const member = byId.get(row.staffId); // undefined: nobody of this type holds it
+```
+
 ### `NOT_FOUND` — `<call>: no <type> has this id`
 
 `NotFoundError`, from `get`, `getUser`, `update`, `setActive`, `setPassword`, `verifyEmail.send`, `secondFactor.recoveryCodesLeft`. Also `<call>: the user has no e-mail`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/janus",
-	"version": "0.18.0",
+	"version": "0.19.0",
 	"description": "Embeddable, type-safe identities and permissions: bring your own database",
 	"license": "MIT",
 	"type": "module",