@ultimat3/admin 23.0.0 → 24.0.0

package/src/repo-entity.ts

@@ -5,6 +5,7 @@
 import { isUltimateError } from '@ultimat3/core';
 import { getEntity, invariantViolated } from '@ultimat3/entity';
 import { adminColumnsOf } from './entity-columns';
+import { seekPage } from './keyset-seek';
 import type {
   AdminDb,
   AdminEntity,
@@ -41,18 +42,21 @@ const literal = (text: string): string => text.replace(/[\\%_]/g, (wild) => `\\$
  * A comparison value, in the shape the column holds. An instant travels as ISO text — in a URL, in
  * a cursor — and the handle is given the `Date`: Postgres would cast the text, the memory driver
  * compares a `Date` to a string by its characters, and a keyset over `createdAt` (the admin's
- * default sort) then answers page one for every page.
+ * default sort) then answers page one for every page. An `integer` travels as text in a cursor
+ * too, and the memory driver's `eq` holds `'7'` and `7` to be two values where Postgres binds one.
  */
 type Typed = (field: string, value: unknown) => unknown;
 
 const typedBy = (entity: AdminEntity): Typed => {
-  const instants = new Set(
-    adminColumnsOf(entity)
-      .filter((column) => column.kind === 'timestamptz')
-      .map((column) => column.name),
-  );
+  const kinds = new Map(adminColumnsOf(entity).map((column) => [column.name, column.kind]));
   return (field, value) => {
-    if (typeof value !== 'string' || !instants.has(field)) return value;
+    if (typeof value !== 'string') return value;
+    const kind = kinds.get(field);
+    if (kind === 'integer') {
+      const count = Number(value);
+      return value.trim() !== '' && Number.isSafeInteger(count) ? count : value;
+    }
+    if (kind !== 'timestamptz') return value;
     const at = new Date(value);
     return Number.isNaN(at.getTime()) ? value : at;
   };
@@ -81,37 +85,6 @@ const filtered = (
   typed: Typed,
 ): AdminTableRead => where.reduce(predicate(typed), read);
 
-/**
- * `after`+asc and `before`+desc walk forward; the other two walk back. Written as one XOR rather
- * than a four-branch table, because the four branches are the same fact said twice.
- *
- * `gte`/`lte`, not `gt`/`lt`: rows sharing the boundary's sort value are still on the far side of
- * it, and `dropThroughTie` below is what removes the ones already served.
- */
-const sought = (read: AdminTableRead, query: AdminListQuery, typed: Typed): AdminTableRead => {
-  const bound = query.after ?? query.before;
-  if (bound === undefined) return read;
-  const forward = (query.after !== undefined) !== (query.sort.direction === 'desc');
-  // The bound is the STRING the cursor carried (`pagination.ts` writes a Date as ISO).
-  return read.andWhere(bound.field, forward ? 'gte' : 'lte', typed(bound.field, bound.value));
-};
-
-/**
- * Drop everything up to and including the cursor row. A typed chain cannot express the row-value
- * comparison `(sort, id) > (value, id)` a keyset needs, and the alternative — a strict `gt` on the
- * sort column alone — silently skips every row that ties with the boundary.
- */
-const dropThroughTie = (
-  rows: readonly AdminRow[],
-  query: AdminListQuery,
-  idField: string,
-): readonly AdminRow[] => {
-  const bound = query.after ?? query.before;
-  if (bound === undefined) return rows;
-  const at = rows.findIndex((row) => String(row[idField]) === bound.id);
-  return at === -1 ? rows : rows.slice(at + 1);
-};
-
 /**
  * One entity + its table → one `AdminRepo`.
  *
@@ -124,6 +97,7 @@ export function adminRepoFor(entity: AdminEntity, table: AdminTable): AdminRepo<
   const idField = entity.$primaryKey[0] ?? 'id';
   const idColumn = Object.hasOwn(entity.$columns, idField) ? entity.$columns[idField] : undefined;
   const typed = typedBy(entity);
+  const columns = adminColumnsOf(entity);
   /**
    * `AdminRepo` carries `id: string` — a URL param, untyped by nature. The primary key column's
    * OWN `$parse` is what earns the crossing: `/posts/nope` is judged here, at the door, instead
@@ -152,14 +126,31 @@ export function adminRepoFor(entity: AdminEntity, table: AdminTable): AdminRepo<
 
   return {
     async list(query: AdminListQuery): Promise<readonly AdminRow[]> {
-      const rows = await sought(filtered(table, query.where ?? [], typed), query, typed)
-        .orderBy(query.sort.field, query.sort.direction)
-        // The tie-break, always: a page boundary on a partial order repeats or drops a row.
-        .orderBy(idField, query.sort.direction)
-        // One over the requested page so the tie-drop cannot hand back a short page.
-        .limit(query.limit + 1)
-        .all();
-      return dropThroughTie(rows, query, idField).slice(0, query.limit);
+      const base = filtered(table, query.where ?? [], typed);
+      const sortField = query.sort.field;
+      const facts = columns.find((column) => column.name === sortField);
+      return seekPage(
+        query,
+        {
+          field: sortField,
+          idField,
+          nullable: facts?.nullable ?? true,
+          instant: facts?.kind === 'timestamptz',
+          typed: (value) => typed(sortField, value),
+        },
+        async (where, order, limit) => {
+          const read = where.reduce(
+            (chain, term) =>
+              term.value === undefined
+                ? chain.andWhere(term.field, term.op)
+                : chain.andWhere(term.field, term.op, term.value),
+            base,
+          );
+          // The tie-break, always: a page boundary on a partial order repeats or drops a row.
+          const sorted = order.by === 'pair' ? read.orderBy(sortField, order.direction) : read;
+          return [...(await sorted.orderBy(idField, order.direction).limit(limit).all())];
+        },
+      );
     },
     // `async`, so a refused id arrives as a rejection: these return promises, and a caller that
     // chains `.catch()` instead of `await`ing would never see a synchronous throw.

package/src/resource-list.ts

@@ -94,6 +94,12 @@ interface Declared {
   readonly entity: AdminEntity;
 }
 
+/**
+ * The list URL's spelling of "no scope, not even the default" — `?scope=*`, what a related card's
+ * "all" link opens. Reserved: a scope declared under it is refused, so the word means one thing.
+ */
+export const NO_SCOPE = '*';
+
 /** The declared scopes, in declaration order — which is the order the tabs are drawn in. */
 export function scopesOf(
   resource: Declared,
@@ -105,6 +111,9 @@ export function scopesOf(
   const refuse = (asked: string, cause: string): never => {
     throw new AdminFilterInvalidError({ entity: resource.name, asked, cause, known: names });
   };
+  if (Object.hasOwn(scopes ?? {}, NO_SCOPE)) {
+    refuse(`scopes.${NO_SCOPE}`, `is the list URL's word for "no scope" and cannot name one`);
+  }
   const defaults = entries.filter(([, scope]) => scope.default === true).map(([name]) => name);
   if (defaults.length > 1) {
     refuse(

package/src/row-version.ts

@@ -0,0 +1,20 @@
+// The version an edit form is rendered against: a keyed fingerprint of the row as it was READ,
+// posted back in a hidden field, so `adminUpdate` can tell "the row I was shown" from "the row as
+// it is now" and refuse a write that would silently overwrite a concurrent edit.
+
+import { keyedFingerprint } from '@ultimat3/core';
+import type { AdminRow } from './registry';
+
+/** The posted name of the version, beside `_operation`: never a column, never an input field. */
+export const VERSION_FIELD = '_version';
+
+/** The key a write against a stale version is refused and audited with. */
+export const ROW_CHANGED_REASON = 'admin.error.row-changed';
+
+/**
+ * Every value the row enumerates — a sealed one is non-enumerable and is not in it, so a password
+ * change is not a "concurrent edit" and no sealed value is ever folded into page text. Keyed: the
+ * page carries it, and an unkeyed hash of a row is an offline oracle for a short value in a column
+ * the form does not draw.
+ */
+export const rowVersion = (row: AdminRow): string => keyedFingerprint(row, 'admin.row-version');

package/src/screen-resource.tsx

@@ -36,6 +36,7 @@ import type { AdminRow } from './registry';
 import { relatedLists, relatedOf } from './related';
 import { type RelationNeed, relationNeeds, relationsFor } from './relations';
 import type { AdminResource } from './resource';
+import { ROW_CHANGED_REASON, rowVersion, VERSION_FIELD } from './row-version';
 import { batchWrite, rowActionFormScreen, rowActionWrite } from './screen-action';
 import {
   type AdminRouteRequest,
@@ -250,6 +251,9 @@ export function detailScreen(app: AdminApp, resource: AdminResource): AdminScree
         entityId: id,
         changes: true,
         limit: HISTORY_PAGE,
+        // The actor's tenant's entries only, as on the audit screen — a row two orgs may open
+        // does not show one org who in the other changed it.
+        ...(request.ctx.actor.orgId === undefined ? {} : { orgId: request.ctx.actor.orgId }),
         ...(before === undefined ? {} : { before }),
       }),
     ]);
@@ -310,6 +314,7 @@ async function form(
   mode: 'create' | 'edit',
   values: Readonly<Record<string, unknown>>,
   issues: readonly ValidationIssue[],
+  version: string | null,
 ): Promise<JSX.Element> {
   const list = listHref(app.basePath, resource);
   return (
@@ -323,10 +328,18 @@ async function form(
       ctx={await relationsOf(app, resource, request, values, true)}
       action={new URL(request.url).pathname}
       cancelHref={mode === 'create' ? list : rowHref(app, resource, idOf(request))}
+      version={version}
     />
   );
 }
 
+/** The form-level issue a write against a stale version is re-rendered with. */
+const ROW_CHANGED_ISSUE: ValidationIssue = {
+  path: VERSION_FIELD,
+  message: 'the row was changed after this form was opened',
+  messageKey: ROW_CHANGED_REASON,
+};
+
 export function createScreen(
   app: AdminApp,
   route: AdminRoute,
@@ -340,7 +353,7 @@ export function createScreen(
         app,
         request,
         resource.titleKey,
-        await form(app, resource, request, 'create', {}, []),
+        await form(app, resource, request, 'create', {}, [], null),
       );
     }
     const input = decodeForm(resource, request.form ?? {});
@@ -350,13 +363,14 @@ export function createScreen(
       return { kind: 'redirect', location: rowHref(app, resource, id) };
     }
     if (result.kind === 'denied') return refused(app, request, resource.titleKey, result.decision);
-    if (result.kind === 'missing') return notFound(app, resource, request);
+    // A create has no row to have gone missing or stale: neither is an answer it can give.
+    if (result.kind !== 'invalid') return notFound(app, resource, request);
     // 422, with what was typed: a refused form that came back empty is a form filled in twice.
     return framed(
       app,
       request,
       resource.titleKey,
-      await form(app, resource, request, 'create', input, result.issues),
+      await form(app, resource, request, 'create', input, result.issues, null),
       422,
     );
   };
@@ -365,8 +379,8 @@ export function createScreen(
 export function editScreen(app: AdminApp, route: AdminRoute, resource: AdminResource): AdminScreen {
   return async (request) => {
     const id = idOf(request);
+    const row = await findRow(resource, request.ctx.actor, id);
     if (request.method === 'GET') {
-      const row = await findRow(resource, request.ctx.actor, id);
       const decision = decideOperation(resource, 'update', request.ctx, id, row);
       if (!decision.allowed) return refusedPage(app, request, route, decision);
       if (row === null) return notFound(app, resource, request);
@@ -374,19 +388,53 @@ export function editScreen(app: AdminApp, route: AdminRoute, resource: AdminReso
         app,
         request,
         resource.titleKey,
-        await form(app, resource, request, 'edit', row, []),
+        await form(app, resource, request, 'edit', row, [], rowVersion(row)),
       );
     }
-    const input = decodeForm(resource, request.form ?? {});
-    const result = await adminUpdate<AdminRow>(resource, request.ctx, id, input);
+    const submitted = request.form ?? {};
+    // Decoded against the row as it is: an instant posted back as the minute it was drawn at is
+    // left out, not rewritten to that minute. A row that moved on since the form was rendered is
+    // refused below on its version, so "as it is" and "as it was drawn" are the same row here.
+    const input = decodeForm(resource, submitted, row ?? undefined);
+    // A post with no version is not a form this admin rendered: it is refused as stale, never run
+    // as an unversioned write — the version is how the form says which row it was looking at.
+    const version = posted(submitted, VERSION_FIELD) ?? '';
+    const result = await adminUpdate<AdminRow>(resource, request.ctx, id, input, { version });
     if (result.ok) return { kind: 'redirect', location: rowHref(app, resource, id) };
     if (result.kind === 'denied') return refused(app, request, resource.titleKey, result.decision);
     if (result.kind === 'missing') return notFound(app, resource, request);
+    if (result.kind === 'stale') {
+      // What they typed, over the row as it is NOW, under its current version: saving again is a
+      // decision taken with the other edit on screen, not an accident.
+      return framed(
+        app,
+        request,
+        resource.titleKey,
+        await form(
+          app,
+          resource,
+          request,
+          'edit',
+          { ...result.row, ...input },
+          [ROW_CHANGED_ISSUE],
+          result.version,
+        ),
+        409,
+      );
+    }
     return framed(
       app,
       request,
       resource.titleKey,
-      await form(app, resource, request, 'edit', input, result.issues),
+      await form(
+        app,
+        resource,
+        request,
+        'edit',
+        { ...(row ?? {}), ...input },
+        result.issues,
+        version,
+      ),
       422,
     );
   };

package/src/screen-system.tsx

@@ -14,8 +14,14 @@ import { adminSearch } from './search';
 const AUDIT_PAGE = 100;
 
 export function auditScreen(app: AdminApp, route: AdminRoute): AdminScreen {
-  return guardedScreen(app, route, async () => {
-    const entries = await app.audit.entries({ limit: AUDIT_PAGE });
+  return guardedScreen(app, route, async (request) => {
+    // The actor's tenant's trail: `audit:read` held in org A is not a read of org B's operators,
+    // their ids or what they touched. An actor with no org — the platform — reads every tenant's.
+    const orgId = request.ctx.actor.orgId;
+    const entries = await app.audit.entries({
+      limit: AUDIT_PAGE,
+      ...(orgId === undefined ? {} : { orgId }),
+    });
     return (
       <Card>
         {entries.length === 0 ? (

package/src/search.ts

@@ -105,6 +105,7 @@ async function searchResource(
 }
 
 const SKIPPED_FORBIDDEN = 'admin.search.skipped.forbidden';
+const SKIPPED_FAILED = 'admin.search.skipped.failed';
 
 export async function adminSearch(input: AdminSearchInput): Promise<AdminSearchResult> {
   const { ctx } = input;
@@ -160,7 +161,6 @@ export async function adminSearch(input: AdminSearchInput): Promise<AdminSearchR
       skipped.push({ entity: resource.name, reason: 'admin.search.skipped.no-repo' });
       continue;
     }
-    searched.push(resource.name);
     // Appended BEFORE the read, so a repo that throws still leaves the record that the rows were
     // asked for — `audit.ts`: if it isn't logged, it didn't happen.
     audit.push(
@@ -176,7 +176,15 @@ export async function adminSearch(input: AdminSearchInput): Promise<AdminSearchR
         reason: decision.reason,
       }),
     );
-    hits.push(...(await searchResource(resource, ctx.actor, term, limit)));
+    try {
+      hits.push(...(await searchResource(resource, ctx.actor, term, limit)));
+      searched.push(resource.name);
+    } catch {
+      // One resource whose repo fails is a resource this search could not read — listed, so the
+      // operator is never silently shown a subset — never a 500 for every other one. Nothing is
+      // read off the thrown value: a reason is a key.
+      skipped.push({ entity: resource.name, reason: SKIPPED_FAILED });
+    }
   }
 
   return { term, hits, searched, skipped, audit };

package/src/widgets.tsx

@@ -17,7 +17,7 @@ import {
 } from '@ultimat3/ui';
 import type { JSX } from 'solid-js';
 import type { AdminField } from './fields';
-import { currencyFieldOf } from './form-decode';
+import { currencyFieldOf, datetimeInputValue } from './form-decode';
 import { type WidgetContext, type WidgetProps, widgetProps } from './widget-value';
 
 export interface WidgetInput {
@@ -70,10 +70,6 @@ export const formatCalendarDate: DateTimeFormatter = (at, options) =>
     dateStyle: 'medium',
   }).format(at);
 
-/** `<input type="date">` wants `YYYY-MM-DD`; `datetime-local` wants `YYYY-MM-DDTHH:mm`. */
-const inputValueFor = (iso: string, precision: 'date' | 'instant'): string =>
-  iso.slice(0, precision === 'date' ? 10 : 16);
-
 /**
  * An enum value's label: its translation when the catalog has one, the value itself when it does
  * not. The value is an identifier the ENTITY declares (`public`, `draft`), so showing it is true;
@@ -238,7 +234,7 @@ function editView(props: WidgetProps, input: WidgetInput): JSX.Element {
           {...shared}
           name={props.field}
           type={props.precision === 'date' ? 'date' : 'datetime-local'}
-          value={props.value === null ? '' : inputValueFor(props.value, props.precision)}
+          value={props.value === null ? '' : datetimeInputValue(props.value, props.precision)}
           suffix={props.precision === 'date' ? undefined : 'UTC'}
           disabled={disabled}
           onInput={(event) => emit(input, event.currentTarget.value)}