bank20baht-validator 0.0.1

package/README.md

@@ -0,0 +1,63 @@
+# bank20baht-validator
+
+Server-side validation for [`bank20baht-ui`](https://www.npmjs.com/package/bank20baht-ui) form/workflow JSON — by re-running **the exact engine code the client runs**, at request time.
+
+No JSON-Schema translation, no codegen, no drift: the schema your builder exported is the validator. Store new JSON, validation follows immediately — no recompile, no redeploy.
+
+```bash
+bun add bank20baht-validator   # or npm i bank20baht-validator
+```
+
+## Quick start (Elysia)
+
+```ts
+import { Elysia, t } from 'elysia';
+import { parseSchema, validateSubmission } from 'bank20baht-validator';
+
+// any storage works — this is just JSON at rest
+const schemas = new Map([['todo-form', parseSchema(todoFormJson)]]);
+
+new Elysia()
+  .post(
+    '/api/submissions',
+    ({ body, status }) => {
+      const schema = schemas.get(body.id);
+      if (!schema) return status(404, { error: `unknown schema "${body.id}"` });
+
+      const result = validateSubmission(schema, body.data);
+      if (!result.valid) return status(422, { valid: false, errors: result.issues });
+
+      // result.data is canonical: defaults filled, hidden fields cleared —
+      // identical to what the client emits on baht-submit. Persist THIS.
+      return status(201, { valid: true, data: result.data });
+    },
+    // one endpoint serves every schema — data stays open on purpose
+    { body: t.Object({ id: t.String(), data: t.Any() }) },
+  )
+  .listen(3001);
+```
+
+A request that bypasses your frontend gets the same verdict the frontend would have shown, message for message:
+
+```
+POST /api/submissions {"id":"todo-form","data":{"title":"ab"}}
+→ 422 {"errors":[{"ref":"title","message":"Must be at least 3 characters"}]}
+```
+
+## What it enforces
+
+- Every declarative validator of the field descriptors: `required`, `minLength`, `maxLength`, `min`, `max`, `pattern`, `email`, and `custom` (via a `Registry`).
+- **Workflow rules first** (`evaluate` from `bank20baht-ui/engine`): fields hidden by rules are excluded and smuggled values are cleared; `required` derived from rules is enforced; `setValue` results are computed.
+- Approval steps: a `decision` must be present, and the comment policy (`required` / `requireOnReject`) is honored.
+
+## API
+
+| export | what it does |
+| --- | --- |
+| `validateSubmission(schema, data, registry?)` | dispatches on schema kind — the single server entry point |
+| `validateFormData(form, data, registry?)` | mirrors `<baht-form>.validate()` for a standalone form |
+| `validateWorkflowData(workflow, data, registry?)` | evaluates rules, then validates every visible form |
+| `parseSchema(json)` | structural gate for storing builder output (throws on bad input) |
+| `isFormDefinition` / `isWorkflowDefinition` | schema kind guards |
+
+All results are `{ valid, issues, data }`; issues are `{ ref, message }` where `ref` is the field key (forms) or `formName.key` (workflows).

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import { approvalFields, defaultValue, evaluate, validateField, type FormDefinition, type NestedData, type Registry, type WorkflowDefinition, type WorkflowForm } from 'bank20baht-ui/engine';
+export type SchemaDefinition = FormDefinition | WorkflowDefinition;
+/** One violation. `ref` is the field key for forms, `formName.key` for workflows. */
+export interface ValidationIssue {
+    ref: string;
+    message: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    issues: ValidationIssue[];
+    /**
+     * Canonical data the server should persist: input overlaid on field
+     * defaults; for workflows also with hidden fields cleared and setValue
+     * rules applied — identical to what the client emits on `baht-submit`.
+     */
+    data: Record<string, unknown> | NestedData;
+}
+export declare function isWorkflowDefinition(schema: unknown): schema is WorkflowDefinition;
+export declare function isFormDefinition(schema: unknown): schema is FormDefinition;
+/**
+ * Validate a standalone form submission — mirrors `<baht-form>.validate()`
+ * with no derived field states: every non-label field, missing values fall
+ * back to the field default before checking.
+ */
+export declare function validateFormData(form: FormDefinition, input: unknown, registry?: Registry): ValidationResult;
+/**
+ * Validate a whole workflow submission — mirrors what `<baht-workflow>`
+ * enforces across its steps: rules are evaluated first (`evaluate`), invisible
+ * forms/fields are excluded, rule-derived `required` overrides the descriptor,
+ * and approval steps demand a decision plus their comment policy.
+ */
+export declare function validateWorkflowData(workflow: WorkflowDefinition, input: unknown, registry?: Registry): ValidationResult;
+/**
+ * Validate a submission body's `data` against whichever schema kind `id`
+ * resolved to. This is the single server entry point:
+ *
+ *   const schema = store.get(body.id);
+ *   const result = validateSubmission(schema, body.data);
+ */
+export declare function validateSubmission(schema: SchemaDefinition, data: unknown, registry?: Registry): ValidationResult;
+/**
+ * Structural gate for storing builder output — the same checks the builder's
+ * Import applies, so the server only ever stores schemas the client could
+ * render. Throws with a human-readable message on bad input.
+ */
+export declare function parseSchema(json: unknown): SchemaDefinition;
+export { approvalFields, defaultValue, evaluate, validateField };
+export type { FormDefinition, NestedData, Registry, WorkflowDefinition, WorkflowForm };

package/dist/index.js

@@ -0,0 +1,161 @@
+// ---------------------------------------------------------------------------
+// bank20baht-validator — run the client's validation on the server, at runtime.
+//
+// The builder exports plain JSON (FormDefinition / WorkflowDefinition). The
+// client validates it with bank20baht-ui/engine (`evaluate` + `validateField`).
+// This package feeds the same JSON through the same engine functions, so a
+// request that bypasses the frontend hits the exact same rules — no codegen,
+// no recompile: swap the stored JSON and validation follows.
+// ---------------------------------------------------------------------------
+import { approvalFields, defaultValue, evaluate, validateField, } from 'bank20baht-ui/engine';
+export function isWorkflowDefinition(schema) {
+    return (isRecord(schema) &&
+        typeof schema['workflowId'] === 'string' &&
+        Array.isArray(schema['forms']) &&
+        Array.isArray(schema['rules']));
+}
+export function isFormDefinition(schema) {
+    return (isRecord(schema) &&
+        !isWorkflowDefinition(schema) &&
+        typeof schema['formId'] === 'string' &&
+        typeof schema['formName'] === 'string' &&
+        Array.isArray(schema['field_data']));
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function sorted(fields) {
+    return [...fields].sort((a, b) => a.order - b.order);
+}
+/**
+ * Validate a standalone form submission — mirrors `<baht-form>.validate()`
+ * with no derived field states: every non-label field, missing values fall
+ * back to the field default before checking.
+ */
+export function validateFormData(form, input, registry) {
+    if (!isRecord(input)) {
+        return { valid: false, issues: [{ ref: '$', message: 'data must be an object' }], data: {} };
+    }
+    const issues = [];
+    const data = {};
+    for (const field of sorted(form.field_data)) {
+        if (field.type === 'label')
+            continue;
+        const value = field.key in input ? input[field.key] : defaultValue(field);
+        data[field.key] = value;
+        for (const err of validateField(field, value, registry)) {
+            issues.push({ ref: err.key, message: err.message });
+        }
+    }
+    return { valid: issues.length === 0, issues, data };
+}
+/**
+ * Validate a whole workflow submission — mirrors what `<baht-workflow>`
+ * enforces across its steps: rules are evaluated first (`evaluate`), invisible
+ * forms/fields are excluded, rule-derived `required` overrides the descriptor,
+ * and approval steps demand a decision plus their comment policy.
+ */
+export function validateWorkflowData(workflow, input, registry) {
+    if (!isRecord(input)) {
+        return { valid: false, issues: [{ ref: '$', message: 'data must be an object' }], data: {} };
+    }
+    for (const [name, values] of Object.entries(input)) {
+        if (values !== undefined && !isRecord(values)) {
+            return {
+                valid: false,
+                issues: [{ ref: name, message: 'form data must be an object' }],
+                data: {},
+            };
+        }
+    }
+    const derived = evaluate(workflow, input);
+    const issues = [...derived.errors];
+    const forms = [...workflow.forms].sort((a, b) => a.order - b.order);
+    for (const form of forms) {
+        if (derived.forms[form.formName]?.visible === false)
+            continue;
+        if (form.kind === 'approval') {
+            issues.push(...approvalIssues(form, derived.data));
+            continue;
+        }
+        for (const field of sorted(form.field_data)) {
+            if (field.type === 'label')
+                continue;
+            const ref = `${form.formName}.${field.key}`;
+            const state = derived.fields[ref];
+            if (state && !state.visible)
+                continue; // hidden fields excluded (spec 02 §5)
+            const required = state ? state.required : !!field.required;
+            const descriptor = required === !!field.required ? field : { ...field, required };
+            const value = derived.data[form.formName]?.[field.key];
+            for (const err of validateField(descriptor, value, registry)) {
+                issues.push({ ref, message: err.message });
+            }
+        }
+    }
+    return { valid: issues.length === 0, issues, data: derived.data };
+}
+/** Approval step checks — same gate `<baht-workflow>.decide()` applies. */
+function approvalIssues(form, data) {
+    const issues = [];
+    const values = data[form.formName] ?? {};
+    const decision = values['decision'];
+    if (decision !== 'approved' && decision !== 'rejected') {
+        issues.push({ ref: `${form.formName}.decision`, message: 'A decision is required.' });
+    }
+    const mode = form.approval?.comment ?? 'optional';
+    const commentRequired = mode === 'required' || (mode === 'requireOnReject' && decision === 'rejected');
+    if (commentRequired && String(values['comment'] ?? '').trim() === '') {
+        issues.push({ ref: `${form.formName}.comment`, message: 'A comment is required.' });
+    }
+    return issues;
+}
+/**
+ * Validate a submission body's `data` against whichever schema kind `id`
+ * resolved to. This is the single server entry point:
+ *
+ *   const schema = store.get(body.id);
+ *   const result = validateSubmission(schema, body.data);
+ */
+export function validateSubmission(schema, data, registry) {
+    if (isWorkflowDefinition(schema))
+        return validateWorkflowData(schema, data, registry);
+    if (isFormDefinition(schema))
+        return validateFormData(schema, data, registry);
+    return {
+        valid: false,
+        issues: [{ ref: '$', message: 'unrecognized schema: neither a form nor a workflow' }],
+        data: {},
+    };
+}
+/**
+ * Structural gate for storing builder output — the same checks the builder's
+ * Import applies, so the server only ever stores schemas the client could
+ * render. Throws with a human-readable message on bad input.
+ */
+export function parseSchema(json) {
+    const parsed = typeof json === 'string' ? JSON.parse(json) : json;
+    if (!isRecord(parsed))
+        throw new Error('not an object');
+    if (isWorkflowDefinition(parsed)) {
+        for (const f of parsed.forms) {
+            if (typeof f.formName !== 'string' || !Array.isArray(f.field_data)) {
+                throw new Error(`invalid form ${JSON.stringify(f.formId)}`);
+            }
+            if (f.kind !== undefined && f.kind !== 'form' && f.kind !== 'approval') {
+                throw new Error(`invalid form kind ${JSON.stringify(f.kind)} on ${f.formName}`);
+            }
+        }
+        const names = parsed.forms.map((f) => f.formName);
+        if (new Set(names).size !== names.length) {
+            throw new Error('formName must be unique in a workflow');
+        }
+        return parsed;
+    }
+    if (isFormDefinition(parsed))
+        return parsed;
+    throw new Error('missing workflowId/forms/rules (workflow) or formId/formName/field_data (form)');
+}
+// Re-exported so servers can type stores and registries without a direct
+// dependency on bank20baht-ui.
+export { approvalFields, defaultValue, evaluate, validateField };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "bank20baht-validator",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Runtime validation for bahtui form/workflow JSON — the exact engine rules the client runs, on the server.",
+  "license": "MIT",
+  "author": "Nattapong Promthong",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bank20baht/bahtui.git",
+    "directory": "packages/validator"
+  },
+  "homepage": "https://github.com/bank20baht/bahtui#readme",
+  "bugs": {
+    "url": "https://github.com/bank20baht/bahtui/issues"
+  },
+  "keywords": [
+    "forms",
+    "workflow",
+    "validation",
+    "server",
+    "json-schema"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "bank20baht-ui": "^0.0.6"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  }
+}