@jini-ai/admin 0.4.12 → 0.6.10

package/dist/core/entities/rules.js

@@ -42,40 +42,59 @@ const MAX_JSON_NODES = 10_000;
  *   {@link MAX_JSON_DEPTH}.
  * @overallScore 100
  */
-function describeNonJsonValue(value, depth = 0, budget = { nodes: 0 }) {
+function describeNonJsonValue({ value, depth, budget }, _optional = {}) {
     if (depth > MAX_JSON_DEPTH)
         return `nests deeper than ${MAX_JSON_DEPTH} levels`;
     if (++budget.nodes > MAX_JSON_NODES)
         return `holds more than ${MAX_JSON_NODES} values`;
-    if (value === null)
-        return null;
-    const type = typeof value;
-    if (type === 'string' || type === 'boolean')
-        return null;
-    if (type === 'number')
-        return Number.isFinite(value) ? null : 'is a non-finite number';
-    if (type !== 'object')
-        return `is a ${type}`;
-    if (Array.isArray(value)) {
-        for (const item of value) {
-            const reason = describeNonJsonValue(item, depth + 1, budget);
-            if (reason !== null)
-                return reason;
-        }
-        return null;
-    }
+    if (value === null || typeof value !== 'object')
+        return describeNonJsonScalar(value);
     // Rejects class instances, `Map`, `Date`, and anything else that survives `typeof === 'object'`
     // but does not round-trip through JSON as itself.
-    const proto = Object.getPrototypeOf(value);
-    if (proto !== Object.prototype && proto !== null)
+    if (!Array.isArray(value) && !isPlainObject(value))
         return 'is a non-plain object';
     for (const item of Object.values(value)) {
-        const reason = describeNonJsonValue(item, depth + 1, budget);
+        const reason = describeNonJsonValue({ value: item, depth: depth + 1, budget });
         if (reason !== null)
             return reason;
     }
     return null;
 }
+/** The leaf half of {@link describeNonJsonValue}: `null` or a non-object `value`. */
+function describeNonJsonScalar(value) {
+    if (value === null)
+        return null;
+    const type = typeof value;
+    if (type === 'string' || type === 'boolean')
+        return null;
+    if (type === 'number')
+        return Number.isFinite(value) ? null : 'is a non-finite number';
+    return `is a ${type}`;
+}
+function isPlainObject(value) {
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/** `null` when `typeof value` is `type`, otherwise "expected <label>, got <typeof value>". */
+function describeWrongType({ value, type, label }, _optional = {}) {
+    return typeof value === type ? null : `expected ${label}, got ${typeof value}`;
+}
+function describeNonDatetime(value) {
+    if (typeof value !== 'string')
+        return `expected an ISO-8601 string, got ${typeof value}`;
+    // A `datetime` that is not parseable renders fine and orders wrongly — the exact class of
+    // fault this whole check exists for, so it is a mismatch rather than a pass.
+    return Number.isNaN(Date.parse(value)) ? 'is not a parseable ISO-8601 timestamp' : null;
+}
+function describeNonNumber({ value, accepts, reason }, _optional = {}) {
+    if (typeof value !== 'number')
+        return `expected a number, got ${typeof value}`;
+    return accepts(value) ? null : reason;
+}
+function describeNonJson(value) {
+    const reason = describeNonJsonValue({ value, depth: 0, budget: { nodes: 0 } });
+    return reason === null ? null : `is not a JSON value: it ${reason}`;
+}
 /**
  * Whether `value` is a legal runtime value for `field`.
  *
@@ -98,27 +117,21 @@ export function describeAdminEntityFieldMismatch(field, value) {
     switch (field.kind) {
         case 'text':
         case 'relation':
-            return typeof value === 'string' ? null : `expected a string, got ${typeof value}`;
+            return describeWrongType({ value, type: 'string', label: 'a string' });
         case 'datetime':
-            if (typeof value !== 'string')
-                return `expected an ISO-8601 string, got ${typeof value}`;
-            // A `datetime` that is not parseable renders fine and orders wrongly — the exact class of
-            // fault this whole check exists for, so it is a mismatch rather than a pass.
-            return Number.isNaN(Date.parse(value)) ? 'is not a parseable ISO-8601 timestamp' : null;
+            return describeNonDatetime(value);
         case 'integer':
-            if (typeof value !== 'number')
-                return `expected a number, got ${typeof value}`;
-            return Number.isInteger(value) ? null : 'is not an integer';
+            return describeNonNumber({ value, accepts: Number.isInteger, reason: 'is not an integer' });
         case 'real':
-            if (typeof value !== 'number')
-                return `expected a number, got ${typeof value}`;
-            return Number.isFinite(value) ? null : 'is not a finite number';
+            return describeNonNumber({
+                value,
+                accepts: Number.isFinite,
+                reason: 'is not a finite number',
+            });
         case 'boolean':
-            return typeof value === 'boolean' ? null : `expected a boolean, got ${typeof value}`;
-        case 'json': {
-            const reason = describeNonJsonValue(value);
-            return reason === null ? null : `is not a JSON value: it ${reason}`;
-        }
+            return describeWrongType({ value, type: 'boolean', label: 'a boolean' });
+        case 'json':
+            return describeNonJson(value);
     }
 }
 /**
@@ -132,49 +145,63 @@ export function describeAdminEntityFieldMismatch(field, value) {
  * @complexity Time O(fields + row keys) plus the `json` walk; space O(violations).
  * @overallScore 100
  */
-function findRowViolations(descriptor, operation, row) {
+function findRowViolations({ descriptor, operation, row, }, _optional = {}) {
+    const hasId = typeof row.id === 'string' && row.id !== '';
+    const rowId = hasId ? row.id : '<no id>';
+    const at = { entity: descriptor.name, operation, rowId };
     const found = [];
-    const rowId = typeof row.id === 'string' && row.id !== '' ? row.id : '<no id>';
-    const push = (field, problem, detail) => {
-        found.push({ entity: descriptor.name, operation, rowId, field, problem, detail });
-    };
-    if (typeof row.id !== 'string' || row.id === '') {
-        push(IMPLICIT_ROW_KEY, 'wrong-type', 'every row must carry a non-empty string `id`');
+    if (!hasId) {
+        found.push({
+            ...at,
+            field: IMPLICIT_ROW_KEY,
+            problem: 'wrong-type',
+            detail: 'every row must carry a non-empty string `id`',
+        });
     }
-    const declared = new Set([IMPLICIT_ROW_KEY]);
     for (const field of descriptor.fields) {
-        declared.add(field.name);
-        const value = row[field.name];
-        if (value === undefined) {
-            if (field.required === true) {
-                push(field.name, 'missing-required', 'declared `required: true` but absent from the row');
-            }
-            continue;
-        }
-        const mismatch = describeAdminEntityFieldMismatch(field, value);
-        if (mismatch !== null)
-            push(field.name, 'wrong-type', `declared \`${field.kind}\`; ${mismatch}`);
+        const problem = describeFieldProblem({ field, value: row[field.name] });
+        if (problem !== null)
+            found.push({ ...at, field: field.name, ...problem });
     }
+    const declared = new Set([IMPLICIT_ROW_KEY, ...descriptor.fields.map((field) => field.name)]);
     for (const key of Object.keys(row)) {
         if (declared.has(key))
             continue;
-        push(key, 'undeclared-field', 'present on the row but not declared on the descriptor');
+        found.push({
+            ...at,
+            field: key,
+            problem: 'undeclared-field',
+            detail: 'present on the row but not declared on the descriptor',
+        });
     }
     return found;
 }
+/** What is wrong with one declared field's cell, or `null` when it conforms or is legally absent. */
+function describeFieldProblem({ field, value }, _optional = {}) {
+    if (value === undefined) {
+        return field.required === true
+            ? { problem: 'missing-required', detail: 'declared `required: true` but absent from the row' }
+            : null;
+    }
+    const mismatch = describeAdminEntityFieldMismatch(field, value);
+    return mismatch === null
+        ? null
+        : { problem: 'wrong-type', detail: `declared \`${field.kind}\`; ${mismatch}` };
+}
 /**
  * Runs `row` past its descriptor and reports anything wrong, then returns it unchanged.
  *
  * Deliberately identity-returning: this is an observation point, never a repair point. Coercing a
  * bad value here would hide the adapter bug it exists to expose.
  *
- * @complexity Time O(rows × fields); no-op and O(1) when `onViolation` is absent.
+ * Only {@link eraseEntityPort}'s checking wrapper calls this, and that wrapper exists only when
+ * `onViolation` is set — so the sink is required here rather than re-checked.
+ *
+ * @complexity Time O(rows × fields).
  * @overallScore 100
  */
-function checkRow(descriptor, operation, row, onViolation) {
-    if (onViolation === undefined)
-        return row;
-    for (const violation of findRowViolations(descriptor, operation, row))
+function checkRow({ descriptor, operation, row, onViolation, }, _optional = {}) {
+    for (const violation of findRowViolations({ descriptor, operation, row }))
         onViolation(violation);
     return row;
 }
@@ -208,18 +235,20 @@ export function eraseEntityPort(port, options = {}) {
         async list(query) {
             const page = await erased.list(query);
             for (const row of page.items)
-                checkRow(descriptor, 'list', row, onViolation);
+                checkRow({ descriptor, operation: 'list', row, onViolation });
             return page;
         },
         async get(id) {
             const row = await erased.get(id);
-            return row === null ? null : checkRow(descriptor, 'get', row, onViolation);
+            return row === null ? null : checkRow({ descriptor, operation: 'get', row, onViolation });
         },
         async create(input) {
-            return checkRow(descriptor, 'create', await erased.create(input), onViolation);
+            const row = await erased.create(input);
+            return checkRow({ descriptor, operation: 'create', row, onViolation });
         },
         async update(id, patch) {
-            return checkRow(descriptor, 'update', await erased.update(id, patch), onViolation);
+            const row = await erased.update(id, patch);
+            return checkRow({ descriptor, operation: 'update', row, onViolation });
         },
     };
     // Preserved by presence, not by a forwarding stub: a screen decides whether to render a delete
@@ -241,44 +270,60 @@ export function eraseEntityPort(port, options = {}) {
  * @complexity Time O(fields); space O(problems).
  * @overallScore 100
  */
-function findDescriptorProblems(descriptor, registryKey, registeredNames) {
-    const problems = [];
+function findDescriptorProblems({ descriptor, registryKey, registeredNames, }, _optional = {}) {
     const at = `'${registryKey}'`;
+    return [
+        ...findHeaderProblems({ descriptor, registryKey }),
+        ...findFieldProblems({ descriptor, registeredNames }),
+        ...findTitleFieldProblems({ descriptor }),
+    ].map((problem) => `${at}: ${problem}`);
+}
+function findHeaderProblems({ descriptor, registryKey }, _optional = {}) {
+    const problems = [];
     if (descriptor.name !== registryKey) {
         // One entity, one name. Allowing these to differ would leave the URL segment, the relation
         // target, and the registry key as three identifiers with no stated relationship between them.
-        problems.push(`${at}: registered under '${registryKey}' but its descriptor is named '${descriptor.name}'`);
+        problems.push(`registered under '${registryKey}' but its descriptor is named '${descriptor.name}'`);
     }
     if (descriptor.labelSingular === '' || descriptor.labelPlural === '') {
-        problems.push(`${at}: labelSingular and labelPlural must both be non-empty`);
+        problems.push('labelSingular and labelPlural must both be non-empty');
     }
     if (descriptor.fields.length === 0) {
-        problems.push(`${at}: declares no fields, so nothing but its id could ever be shown or edited`);
+        problems.push('declares no fields, so nothing but its id could ever be shown or edited');
     }
+    return problems;
+}
+function findFieldProblems({ descriptor, registeredNames, }, _optional = {}) {
+    const problems = [];
     const seen = new Set();
     for (const field of descriptor.fields) {
         if (field.name === '') {
-            problems.push(`${at}: a field has an empty name`);
+            problems.push('a field has an empty name');
             continue;
         }
         if (field.name === IMPLICIT_ROW_KEY) {
-            problems.push(`${at}: '${IMPLICIT_ROW_KEY}' is implicit on every row and must not be declared as a field`);
+            problems.push(`'${IMPLICIT_ROW_KEY}' is implicit on every row and must not be declared as a field`);
         }
         if (seen.has(field.name))
-            problems.push(`${at}: field '${field.name}' is declared more than once`);
+            problems.push(`field '${field.name}' is declared more than once`);
         seen.add(field.name);
         if (field.kind === 'relation' && !registeredNames.has(field.target)) {
-            problems.push(`${at}: field '${field.name}' targets '${field.target}', which is not a registered entity`);
+            problems.push(`field '${field.name}' targets '${field.target}', which is not a registered entity`);
         }
     }
+    return problems;
+}
+function findTitleFieldProblems({ descriptor }, _optional = {}) {
     const titleField = descriptor.fields.find((field) => field.name === descriptor.titleField);
     if (titleField === undefined) {
-        problems.push(`${at}: titleField '${descriptor.titleField}' does not name a declared field`);
+        return [`titleField '${descriptor.titleField}' does not name a declared field`];
     }
-    else if (titleField.kind !== 'text') {
-        problems.push(`${at}: titleField '${descriptor.titleField}' is kind '${titleField.kind}'; a title must be 'text'`);
+    if (titleField.kind !== 'text') {
+        return [
+            `titleField '${descriptor.titleField}' is kind '${titleField.kind}'; a title must be 'text'`,
+        ];
     }
-    return problems;
+    return [];
 }
 /**
  * Assembles entity ports into a registry, validating every descriptor first.
@@ -306,7 +351,7 @@ function findDescriptorProblems(descriptor, registryKey, registeredNames) {
 export function createAdminEntityRegistry(ports) {
     const entries = Object.entries(ports);
     const registeredNames = new Set(entries.map(([, port]) => port.descriptor.name));
-    const problems = entries.flatMap(([key, port]) => findDescriptorProblems(port.descriptor, key, registeredNames));
+    const problems = entries.flatMap(([key, port]) => findDescriptorProblems({ descriptor: port.descriptor, registryKey: key, registeredNames }));
     if (problems.length > 0) {
         throw new Error(`createAdminEntityRegistry: invalid descriptors\n- ${problems.join('\n- ')}`);
     }

package/dist/core/manifest/rules.js

@@ -35,8 +35,9 @@ export function resolvePanels({ panels }, context = {}) {
  * @complexity O(n log n) on the items within each group; O(n) otherwise.
  */
 export function buildNav({ panels }, options = {}) {
+    // A `Map` iterates in first-insertion order, so it alone records the order each group's first
+    // member was registered — no separate order list (and no lookup that could miss) is needed.
     const groups = new Map();
-    const groupOrder = [];
     // Sentinel for "no group". A panel cannot collide with it: `group` is `string | undefined`, and
     // an explicit empty-string group would be a labelless heading, which is the same thing.
     const UNGROUPED = '';
@@ -44,20 +45,19 @@ export function buildNav({ panels }, options = {}) {
         if (!panel.nav)
             return;
         const key = panel.nav.group ?? UNGROUPED;
-        if (!groups.has(key)) {
-            groups.set(key, []);
-            groupOrder.push(key);
-        }
-        groups.get(key)?.push({ ...panel.nav, id: panel.id, href: panelHref({ panelId: panel.id }, options) });
+        const group = groups.get(key) ?? [];
+        groups.set(key, group);
+        group.push({ ...panel.nav, id: panel.id, href: panelHref({ panelId: panel.id }, options) });
     });
     // Ungrouped first regardless of when it was registered — it is the top row, not a peer group.
+    const entries = [...groups.entries()];
     const ordered = [
-        ...groupOrder.filter((k) => k === UNGROUPED),
-        ...groupOrder.filter((k) => k !== UNGROUPED),
+        ...entries.filter(([k]) => k === UNGROUPED),
+        ...entries.filter(([k]) => k !== UNGROUPED),
     ];
-    return ordered.map((key) => ({
+    return ordered.map(([key, items]) => ({
         ...(key === UNGROUPED ? {} : { label: key }),
-        items: stableSortByOrder(groups.get(key) ?? []),
+        items: stableSortByOrder(items),
     }));
 }
 /** `Array.prototype.sort` is specified as stable, so equal `order` values keep registration