bank20baht-validator 0.5.0 → 0.5.1

package/README.md

@@ -69,6 +69,7 @@ step with the core version or the validator's `tsc` build resolves a stale copy
 
 `options` is `{ strict?: boolean }` (default `true`, see above).
 | `parseSchema(json)` | structural gate for storing builder output (throws on bad input) |
+| `verifyReferences(schema, data, registry?)` | async: resolves every `reference` field id through `registry.references[name].resolve` and returns issues for records that do not exist (call after `validateSubmission`) |
 | `isFormDefinition` / `isWorkflowDefinition` | schema kind guards |
 
 All results are `{ valid, issues, data }`; issues are `{ ref, message }` where `ref` is the field key (forms) or `form_name.key` (workflows).

package/dist/index.d.ts

@@ -52,6 +52,21 @@ export declare function validateWorkflowData(workflow: WorkflowDefinition, input
  *   const result = validateSubmission(schema, body.data);
  */
 export declare function validateSubmission(schema: SchemaDefinition, data: unknown, registry?: Registry, locale?: Locale, options?: ValidateOptions): ValidationResult;
+/**
+ * Do the records picked in `reference` fields exist? `validateSubmission` only checks that a
+ * reference value is an id string — existence needs the lookup, which is async. Call this
+ * after it, with the same registry the client uses:
+ *
+ *   const result = validateSubmission(schema, body.data, registry);
+ *   const missing = await verifyReferences(schema, result.data, registry);
+ *
+ * Each distinct `lookup + id` is resolved once (in parallel). An id `resolve` returns `null`
+ * for is an issue on that field ("Record not found"); a lookup the schema names but the
+ * registry lacks is an issue too; a lookup without `resolve` is trusted. Workflow refs are
+ * `form_name.key`. Top-level fields only (reference fields inside repeater rows are not
+ * resolved).
+ */
+export declare function verifyReferences(schema: SchemaDefinition, data: unknown, registry?: Registry): Promise<ValidationIssue[]>;
 /**
  * Structural gate for storing builder output — the same checks the builder's
  * Import applies, so the server only ever stores schemas the client could

package/dist/index.js

@@ -13,7 +13,7 @@
 // every value must have the shape the UI control could actually emit before
 // the authored validators run.
 // ---------------------------------------------------------------------------
-import { applyFlags, approvalFields, conditionRowRefs, createScriptContext, defaultValue, evaluate, hasScripts, runScripts, getCatalog, normalizeTagsValue, parseDisabledEntry, parseIsoDate, parseIsoDateTime, parseRowRef, resolveViewFields, setCatalog, setLocale, t, isBlank, isSafeUrl, isUnsafePattern, validateField, walkPath, normalizeLegacySchema, } from 'bank20baht-ui/engine';
+import { applyFlags, approvalFields, conditionRowRefs, createScriptContext, defaultValue, evaluate, hasScripts, runScripts, getCatalog, normalizeTagsValue, parseDisabledEntry, parseIsoDate, parseIsoDateTime, parseRowRef, rangeBounds, ratingMax, resolveViewFields, setCatalog, setLocale, t, isBlank, isSafeUrl, isUnsafePattern, validateField, walkPath, normalizeLegacySchema, } from 'bank20baht-ui/engine';
 /**
  * Run `fn` with the catalog switched to `locale`, restoring the previous
  * catalog after. The engine catalog is module-global; validation is fully
@@ -34,6 +34,10 @@ function withLocale(locale, fn) {
 }
 /** Keys that write through Object.prototype — never valid as field/form names. */
 const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+/** Static blocks (`label`, `section`): no value, never in the payload, never validated. */
+function isStatic(field) {
+    return field.type === 'label' || field.type === 'section';
+}
 const DATE_MODES = new Set(['single', 'range', 'multiple']);
 const FIELD_TYPES = new Set([
     'text',
@@ -50,8 +54,12 @@ const FIELD_TYPES = new Set([
     'date',
     'file',
     'label',
+    'section',
     'repeater',
     'tags',
+    'rating',
+    'range',
+    'reference',
 ]);
 export function isWorkflowDefinition(schema) {
     return (isRecord(schema) &&
@@ -156,11 +164,13 @@ function typeIssue(field, value) {
         case 'textarea':
         case 'email':
         case 'password':
+        case 'reference':
             return shapeMessage(typeof value === 'string');
         case 'date':
             return dateIssue(field, value);
         case 'number':
         case 'currency':
+        case 'range':
             return shapeMessage(typeof value === 'number' && Number.isFinite(value));
         case 'checkbox':
         case 'toggle':
@@ -172,6 +182,11 @@ function typeIssue(field, value) {
             return multiChoiceIssue(value, optionKeys);
         case 'tags':
             return tagsShapeIssue(field, value, optionKeys);
+        case 'rating':
+            return shapeMessage(typeof value === 'number' &&
+                Number.isInteger(value) &&
+                value >= 1 &&
+                value <= ratingMax(field));
         case 'file':
             return fileIssue(field, value);
         case 'repeater':
@@ -198,7 +213,7 @@ function shapeIssues(field, value, ref) {
                 return;
             }
             for (const sub of field.fields ?? []) {
-                if (sub.type === 'label' || UNSAFE_KEYS.has(sub.key))
+                if (isStatic(sub) || UNSAFE_KEYS.has(sub.key))
                     continue;
                 const v = Object.hasOwn(row, sub.key) ? row[sub.key] : undefined;
                 const m = typeIssue(sub, v);
@@ -323,7 +338,7 @@ function canonicalRow(field, row) {
         return row;
     const next = {};
     for (const sub of field.fields ?? []) {
-        if (sub.type === 'label' || UNSAFE_KEYS.has(sub.key) || !Object.hasOwn(row, sub.key))
+        if (isStatic(sub) || UNSAFE_KEYS.has(sub.key) || !Object.hasOwn(row, sub.key))
             continue;
         next[sub.key] = normalizeCanonicalValue(sub, row[sub.key]);
     }
@@ -373,7 +388,7 @@ function formDataResult(form, input, registry) {
     const issues = [];
     const fields = [];
     for (const f of sorted(form.fields)) {
-        if (f.type === 'label')
+        if (isStatic(f))
             continue;
         if (UNSAFE_KEYS.has(f.key)) {
             issues.push({ ref: f.key, message: 'unsafe field key' });
@@ -526,7 +541,7 @@ function rowStatesOf(form, field, derived) {
 function formFieldIssues(form, derived, registry) {
     const issues = [];
     for (const field of sorted([...form.fields, ...approvalFields(form)])) {
-        if (field.type === 'label')
+        if (isStatic(field))
             continue;
         issues.push(...workflowFieldIssues(form, field, derived, registry));
     }
@@ -613,6 +628,67 @@ export function validateSubmission(schema, data, registry, locale, options) {
         data: {},
     };
 }
+/**
+ * Do the records picked in `reference` fields exist? `validateSubmission` only checks that a
+ * reference value is an id string — existence needs the lookup, which is async. Call this
+ * after it, with the same registry the client uses:
+ *
+ *   const result = validateSubmission(schema, body.data, registry);
+ *   const missing = await verifyReferences(schema, result.data, registry);
+ *
+ * Each distinct `lookup + id` is resolved once (in parallel). An id `resolve` returns `null`
+ * for is an issue on that field ("Record not found"); a lookup the schema names but the
+ * registry lacks is an issue too; a lookup without `resolve` is trusted. Workflow refs are
+ * `form_name.key`. Top-level fields only (reference fields inside repeater rows are not
+ * resolved).
+ */
+export async function verifyReferences(schema, data, registry) {
+    const checks = [];
+    const collect = (fields, values, prefix) => {
+        if (!isRecord(values))
+            return;
+        for (const field of fields) {
+            if (field.type !== 'reference' || !Object.hasOwn(values, field.key))
+                continue;
+            const id = values[field.key];
+            if (typeof id === 'string' && id !== '') {
+                checks.push({ ref: `${prefix}${field.key}`, lookup: field.reference ?? '', id });
+            }
+        }
+    };
+    if (isWorkflowDefinition(schema)) {
+        for (const form of schema.forms) {
+            collect(form.fields, isRecord(data) ? data[form.form_name] : undefined, `${form.form_name}.`);
+        }
+    }
+    else if (isFormDefinition(schema)) {
+        collect(schema.fields, data, '');
+    }
+    const lookups = registry?.references ?? {};
+    const found = new Map();
+    const exists = (lookup, id) => {
+        const resolve = Object.hasOwn(lookups, lookup) ? lookups[lookup]?.resolve : undefined;
+        if (!resolve)
+            return null;
+        const key = `${lookup}\u0000${id}`;
+        let pending = found.get(key);
+        if (!pending) {
+            pending = Promise.resolve(resolve(id)).then((record) => record !== null, () => false);
+            found.set(key, pending);
+        }
+        return pending;
+    };
+    const issues = await Promise.all(checks.map(async ({ ref, lookup, id }) => {
+        if (!Object.hasOwn(lookups, lookup)) {
+            return { ref, message: `unknown reference lookup ${JSON.stringify(lookup)}` };
+        }
+        const pending = exists(lookup, id);
+        if (pending === null)
+            return null; // no resolver: trusted
+        return (await pending) ? null : { ref, message: t('referenceNotFound') };
+    }));
+    return issues.filter((issue) => issue !== null);
+}
 /**
  * Structural gate for storing builder output — the same checks the builder's
  * Import applies, so the server only ever stores schemas the client could
@@ -725,7 +801,7 @@ function fieldRefs(wf) {
     const refs = new Set();
     for (const form of wf.forms) {
         for (const field of [...form.fields, ...approvalFields(form)]) {
-            if (field.type === 'label')
+            if (isStatic(field))
                 continue;
             refs.add(`${form.form_name}.${field.key}`);
             for (const ref of rowRefsOf(form.form_name, field))
@@ -773,9 +849,9 @@ function assertValidFields(form) {
     }
 }
 function assertFieldKey(field, form_name) {
-    // labels are static blocks and may omit the key; everything else needs one
+    // labels/sections are static blocks and may omit the key; everything else needs one
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime guard: value is untrusted JSON
-    if (field.type === 'label' && field.key === undefined)
+    if (isStatic(field) && field.key === undefined)
         return;
     if (typeof field.key !== 'string' || field.key === '') {
         throw new Error(`field on ${form_name} needs a non-empty string key`);
@@ -822,6 +898,13 @@ function assertFieldShape(field, form_name) {
     assertFieldKey(field, form_name);
     if (field.type === 'date')
         assertDateProps(field, form_name);
+    if (field.type === 'rating')
+        assertRatingProps(field, form_name);
+    if (field.type === 'range')
+        assertRangeProps(field, form_name);
+    if (field.type === 'reference' && (typeof field.reference !== 'string' || !field.reference)) {
+        throw new Error(`reference on ${form_name}.${field.key} must name a registry lookup (registry.references)`);
+    }
     if (field.options !== undefined &&
         (!Array.isArray(field.options) ||
             field.options.some((o) => !isRecord(o) || typeof o.key !== 'string'))) {
@@ -830,6 +913,27 @@ function assertFieldShape(field, form_name) {
     assertFieldValidators(field, form_name);
 }
 /** Calendar constraints must be well-formed or the picker silently ignores them. */
+function assertRatingProps(field, form_name) {
+    const max = field.max;
+    if (max === undefined)
+        return;
+    if (typeof max !== 'number' || !Number.isInteger(max) || max < 1 || max > 10) {
+        throw new Error(`max on ${form_name}.${field.key} must be a whole number from 1 to 10 (star count)`);
+    }
+}
+function assertRangeProps(field, form_name) {
+    const where = `${form_name}.${field.key}`;
+    const { min, max, step } = field;
+    const notNumber = (v) => v !== undefined && (typeof v !== 'number' || !Number.isFinite(v));
+    if (notNumber(min) || notNumber(max))
+        throw new Error(`min and max on ${where} must be numbers`);
+    const bounds = rangeBounds(field);
+    if (bounds.min >= bounds.max)
+        throw new Error(`min on ${where} must be below max`);
+    if (step !== undefined && (typeof step !== 'number' || !(step > 0))) {
+        throw new Error(`step on ${where} must be a positive number`);
+    }
+}
 function assertDateProps(field, form_name) {
     const where = `${form_name}.${field.key}`;
     if (field.date_mode !== undefined && !DATE_MODES.has(field.date_mode)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bank20baht-validator",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "type": "module",
   "description": "Runtime validation for bahtui form/workflow JSON \u2014 the exact engine rules the client runs, on the server.",
   "license": "MIT",
@@ -41,12 +41,12 @@
     "test:coverage": "vitest run --coverage"
   },
   "devDependencies": {
-    "bank20baht-ui": "^0.13.0",
+    "bank20baht-ui": "^0.13.3",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4"
   },
   "peerDependencies": {
-    "bank20baht-ui": ">=0.13.0 <0.14.0"
+    "bank20baht-ui": ">=0.13.3 <0.14.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",