rastack 0.0.46 → 0.0.48

package/dist/validate/machine.js

@@ -0,0 +1,347 @@
+"use strict";
+/**
+ * The constraint state machine — the validation core of the database generator.
+ *
+ * A field's constraints are not a bag of ad-hoc checks: they are compiled into
+ * a **deterministic finite state machine** whose intermediate states are the
+ * constraint gates a value must pass through, in a fixed order, to reach the
+ * accepting `valid` state:
+ *
+ * ```
+ * pristine → present → typed → bounded → member → unique → resolved → valid
+ *                └────────┴───── any gate fails ─────┴────────┘
+ *                                    ↓
+ *                                 invalid
+ * ```
+ *
+ * Compiling (`compileFieldMachine`) *builds the constraints*: each constraint
+ * on the field spec becomes exactly one gate (a guarded transition), and gates
+ * whose constraint is absent are simply not emitted — an unconstrained string
+ * field's machine is just `pristine → present → typed → valid`. Running
+ * (`runFieldMachine`) walks the gates with a raw value, coercing it along the
+ * way (`typed` parses `"12"` into `12`), and halts at the first failing gate,
+ * reporting the state reached and the constraint that rejected the value.
+ *
+ * Because the machine is pure data + pure functions (no filesystem, no DOM),
+ * the *same* machine drives every surface: the form hooks derive per-field
+ * machines from the write JSON Schema (`specFromSchemaProperty`), and the data
+ * import pipeline derives them from `schema.rastack.json`
+ * (`specFromManifestField`) — one validation brain, two adapters, mirroring
+ * how `rastack-api-core` is one request brain behind two transports.
+ *
+ * The `unique` and `resolved` (foreign-key) gates are dataset-level: they only
+ * engage when the {@link ValidationContext} provides the capability (a seen-set
+ * or a relation resolver). A context-free run — a form field validating a
+ * single keystroke — passes through them untouched, exactly like the server,
+ * where uniqueness and FK existence are checked against the table, not the
+ * payload.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GATE_ORDER = void 0;
+exports.compileFieldMachine = compileFieldMachine;
+exports.describeMachine = describeMachine;
+exports.runFieldMachine = runFieldMachine;
+exports.compileRecordMachine = compileRecordMachine;
+exports.runRecordMachine = runRecordMachine;
+exports.createDatasetContext = createDatasetContext;
+/** The intermediate (gate) states, in canonical machine order. */
+exports.GATE_ORDER = [
+    "present",
+    "typed",
+    "bounded",
+    "member",
+    "unique",
+    "resolved",
+];
+const EMPTY_CTX = {};
+// ---------------------------------------------------------------------------
+// Value predicates (shared by gates)
+// ---------------------------------------------------------------------------
+function isEmpty(value) {
+    return (value === undefined ||
+        value === null ||
+        (typeof value === "string" && value.trim() === ""));
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const URL_RE = /^https?:\/\/[^\s]+$/i;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const DATETIME_RE = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/;
+/** Coerce a raw value to the spec's scalar type, or explain why it can't be. */
+function coerce(spec, value) {
+    switch (spec.type) {
+        case "int": {
+            if (typeof value === "number" && Number.isInteger(value))
+                return { ok: true, value };
+            if (typeof value === "string" && /^-?\d+$/.test(value.trim()))
+                return { ok: true, value: parseInt(value.trim(), 10) };
+            return { ok: false, message: `"${String(value)}" is not an integer` };
+        }
+        case "float": {
+            if (typeof value === "number" && Number.isFinite(value))
+                return { ok: true, value };
+            if (typeof value === "string" &&
+                /^-?\d+(\.\d+)?$/.test(value.trim()))
+                return { ok: true, value: parseFloat(value.trim()) };
+            return { ok: false, message: `"${String(value)}" is not a number` };
+        }
+        case "bool": {
+            if (typeof value === "boolean")
+                return { ok: true, value };
+            if (typeof value === "string") {
+                const v = value.trim().toLowerCase();
+                if (["true", "yes", "1"].includes(v))
+                    return { ok: true, value: true };
+                if (["false", "no", "0"].includes(v))
+                    return { ok: true, value: false };
+            }
+            if (value === 1)
+                return { ok: true, value: true };
+            if (value === 0)
+                return { ok: true, value: false };
+            return { ok: false, message: `"${String(value)}" is not a boolean` };
+        }
+        case "datetime": {
+            if (value instanceof Date && !isNaN(value.getTime()))
+                return { ok: true, value: value.toISOString() };
+            if (typeof value === "string" &&
+                (DATETIME_RE.test(value.trim()) || DATE_RE.test(value.trim())) &&
+                !isNaN(Date.parse(value.trim())))
+                return { ok: true, value: value.trim() };
+            return { ok: false, message: `"${String(value)}" is not a datetime` };
+        }
+        case "uuid": {
+            if (typeof value === "string" && UUID_RE.test(value.trim()))
+                return { ok: true, value: value.trim() };
+            return { ok: false, message: `"${String(value)}" is not a uuid` };
+        }
+        case "fk": {
+            // FK values are opaque ids — integer or string, but never structured.
+            if (typeof value === "number" && Number.isInteger(value))
+                return { ok: true, value };
+            if (typeof value === "string" && value.trim() !== "") {
+                const v = value.trim();
+                return { ok: true, value: /^\d+$/.test(v) ? parseInt(v, 10) : v };
+            }
+            return { ok: false, message: `"${String(value)}" is not a valid id` };
+        }
+        default: {
+            // string (+ format refinement)
+            if (typeof value !== "string" &&
+                typeof value !== "number" &&
+                typeof value !== "boolean")
+                return { ok: false, message: "value is not a string" };
+            const str = String(value);
+            switch (spec.format) {
+                case "email":
+                    if (!EMAIL_RE.test(str))
+                        return { ok: false, message: `"${str}" is not an email address` };
+                    break;
+                case "uri":
+                case "url":
+                    if (!URL_RE.test(str))
+                        return { ok: false, message: `"${str}" is not a URL` };
+                    break;
+                case "date":
+                    if (!DATE_RE.test(str) || isNaN(Date.parse(str)))
+                        return { ok: false, message: `"${str}" is not a date` };
+                    break;
+                case "date-time":
+                    if (!DATETIME_RE.test(str) || isNaN(Date.parse(str)))
+                        return { ok: false, message: `"${str}" is not a datetime` };
+                    break;
+                case "uuid":
+                    if (!UUID_RE.test(str))
+                        return { ok: false, message: `"${str}" is not a uuid` };
+                    break;
+            }
+            return { ok: true, value: str };
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Compilation — the machine *is* the constraints
+// ---------------------------------------------------------------------------
+function typeConstraint(spec) {
+    if (spec.type === "fk")
+        return `references ${spec.relation ? `${spec.relation.app}.${spec.relation.model}` : "a related record"}`;
+    return spec.format ? `${spec.type} (${spec.format})` : spec.type;
+}
+/**
+ * Compile a field spec into its constraint state machine. Every present
+ * constraint becomes one gate; absent constraints emit no gate, so the state
+ * chain is exactly the field's constraint set.
+ */
+function compileFieldMachine(spec) {
+    const gates = [];
+    gates.push({
+        to: "present",
+        constraint: spec.required ? "required" : "optional",
+        check: (value) => spec.required && isEmpty(value)
+            ? { ok: false, message: `${spec.name} is required` }
+            : { ok: true, value },
+    });
+    gates.push({
+        to: "typed",
+        constraint: typeConstraint(spec),
+        check: (value) => coerce(spec, value),
+    });
+    if (spec.maxLength !== undefined) {
+        const max = spec.maxLength;
+        gates.push({
+            to: "bounded",
+            constraint: `maxLength ≤ ${max}`,
+            check: (value) => typeof value === "string" && value.length > max
+                ? {
+                    ok: false,
+                    message: `"${value}" is longer than ${max} characters`,
+                }
+                : { ok: true, value },
+        });
+    }
+    if (spec.options && spec.options.length > 0) {
+        const options = spec.options;
+        gates.push({
+            to: "member",
+            constraint: `one of ${options.map(String).join(", ")}`,
+            check: (value) => options.some((o) => o === value || String(o) === String(value))
+                ? { ok: true, value }
+                : {
+                    ok: false,
+                    message: `"${String(value)}" is not one of the allowed values`,
+                },
+        });
+    }
+    if (spec.unique) {
+        gates.push({
+            to: "unique",
+            constraint: "unique",
+            check: (value, ctx) => {
+                const seen = ctx.seen?.get(spec.name);
+                if (!seen)
+                    return { ok: true, value }; // no dataset context — gate is inert
+                const key = String(value);
+                if (seen.has(key))
+                    return { ok: false, message: `duplicate value "${key}"` };
+                seen.add(key);
+                return { ok: true, value };
+            },
+        });
+    }
+    if (spec.type === "fk" && spec.relation) {
+        const relation = spec.relation;
+        gates.push({
+            to: "resolved",
+            constraint: `exists on ${relation.app}.${relation.model}`,
+            check: (value, ctx) => {
+                if (!ctx.resolveRelation)
+                    return { ok: true, value }; // inert without a resolver
+                return ctx.resolveRelation(relation, value)
+                    ? { ok: true, value }
+                    : {
+                        ok: false,
+                        message: `no ${relation.app}.${relation.model} with id "${String(value)}"`,
+                    };
+            },
+        });
+    }
+    return {
+        spec,
+        gates,
+        states: ["pristine", ...gates.map((g) => g.to), "valid"],
+    };
+}
+/** The human-readable constraint chain — what the machine enforces, in order. */
+function describeMachine(machine) {
+    return machine.gates.map((g) => g.constraint);
+}
+// ---------------------------------------------------------------------------
+// Execution
+// ---------------------------------------------------------------------------
+/**
+ * Run a raw value through a field machine. Walks the gates in order, coercing
+ * the value as it goes; the first failing guard sends the machine to
+ * `invalid` with the offending constraint attached.
+ *
+ * An empty value on an optional field short-circuits from `present` straight
+ * to `valid` (yielding the default, else `null`) — there is nothing further
+ * to constrain, exactly like a nullable column.
+ */
+function runFieldMachine(machine, rawValue, ctx = EMPTY_CTX) {
+    const path = ["pristine"];
+    let value = rawValue;
+    for (const gate of machine.gates) {
+        const result = gate.check(value, ctx);
+        if (!result.ok) {
+            path.push("invalid");
+            return {
+                state: "invalid",
+                path,
+                value,
+                failed: {
+                    gate: gate.to,
+                    constraint: gate.constraint,
+                    message: result.message,
+                },
+            };
+        }
+        value = result.value;
+        path.push(gate.to);
+        // Optional + empty: nothing left to constrain — accept with the default.
+        if (gate.to === "present" && isEmpty(value)) {
+            path.push("valid");
+            return {
+                state: "valid",
+                path,
+                value: machine.spec.default !== undefined ? machine.spec.default : null,
+            };
+        }
+    }
+    path.push("valid");
+    return { state: "valid", path, value };
+}
+function compileRecordMachine(specs) {
+    return { fields: specs.map(compileFieldMachine) };
+}
+function runRecordMachine(machine, record, ctx = EMPTY_CTX) {
+    const fields = {};
+    const values = {};
+    const errors = [];
+    for (const fieldMachine of machine.fields) {
+        const name = fieldMachine.spec.name;
+        const run = runFieldMachine(fieldMachine, record[name], ctx);
+        fields[name] = run;
+        values[name] = run.value;
+        if (run.failed) {
+            errors.push({ field: name, ...run.failed });
+        }
+    }
+    return {
+        state: errors.length === 0 ? "valid" : "invalid",
+        values,
+        fields,
+        errors,
+    };
+}
+/**
+ * Build the dataset-level context for a record machine: a seen-set per
+ * `unique` field (so the `unique` gate engages), and — when related ids are
+ * supplied — a resolver for the `resolved` gate. `relatedIds` is keyed by
+ * `"app.model"`.
+ */
+function createDatasetContext(machine, opts = {}) {
+    const seen = new Map();
+    for (const field of machine.fields) {
+        if (field.spec.unique)
+            seen.set(field.spec.name, new Set());
+    }
+    const resolveRelation = opts.resolveRelation ??
+        (opts.relatedIds
+            ? (relation, value) => {
+                const ids = opts.relatedIds[`${relation.app}.${relation.model}`];
+                // Unknown target tables are out of scope for the check — stay inert.
+                return ids ? ids.has(String(value)) : true;
+            }
+            : undefined);
+    return { seen, resolveRelation };
+}

package/hooks/form/form.ts

@@ -8,7 +8,8 @@ import {
 } from "./interfaces";
 import { FlattenedRecord } from "../../types";
 import { formikJSONSchemaValidation } from "./validate-schema";
-import { getFieldStructure } from "./structure";
+import { getFieldMachine, getFieldStructure } from "./structure";
+import { describeMachine, runFieldMachine } from "../../src/validate";
 
 export function useForm<
   TFormValues extends object,
@@ -160,11 +161,18 @@ export function useForm<
     const { setValue: setFormValue, setTouched } =
       formik.getFieldHelpers(fieldName);
 
+    const validationSchema = mutations
+      ? mutations[updateMethod]?.validation
+      : undefined;
     const { type, isRequired, maxLength, options, relation, nullable, format } =
-      getFieldStructure(
-        mutations ? mutations[updateMethod]?.validation : undefined,
-        fieldName,
-      );
+      getFieldStructure(validationSchema, fieldName);
+
+    // The constraint state machine for this field — the same gate chain the
+    // import pipeline and the server run, so the form can show exactly which
+    // constraint the current value stops at.
+    const machine = getFieldMachine(validationSchema, fieldName);
+    const validation = machine ? runFieldMachine(machine, value) : undefined;
+    const constraints = machine ? describeMachine(machine) : undefined;
 
     const error = errorMessage ?? "";
     const isError = errorMessage !== undefined;
@@ -195,6 +203,9 @@ export function useForm<
       relation,
       nullable,
       format,
+      machine,
+      validation,
+      constraints,
     };
   };
 

package/hooks/form/interfaces.ts

@@ -2,6 +2,7 @@ import { FlattenedRecord } from "../../types";
 import { SchemaObject } from "ajv";
 import { IUpdateQueryResult } from "../../hooks";
 import { FormikValues } from "formik";
+import type { FieldMachine, FieldRun } from "../../src/validate";
 
 /** A choice for an `enum`-backed (`select`) field. */
 export interface FieldOption {
@@ -35,6 +36,20 @@ export interface FormFieldStructure<TValue> {
   nullable?: boolean;
   /** The schema `format` (`date-time`, `email`, `uuid`, …), for finer control choices. */
   format?: string;
+  /**
+   * The field's compiled constraint state machine (built from the write JSON
+   * Schema). Its gate chain *is* the field's constraint set, in the order the
+   * import pipeline and the server enforce it.
+   */
+  machine?: FieldMachine;
+  /**
+   * The machine's run against the current value: terminal state
+   * (`valid`/`invalid`), the states traversed, and — on failure — the exact
+   * gate/constraint that rejected the value.
+   */
+  validation?: FieldRun;
+  /** Human-readable constraint chain (one entry per gate), for UI hints. */
+  constraints?: string[];
 }
 
 interface FormMutation<

package/hooks/form/structure.ts

@@ -1,5 +1,10 @@
 import type { SchemaObject } from "ajv";
 import type { FieldOption, FormType, RelationTarget } from "./interfaces";
+import {
+  compileFieldMachine,
+  specFromSchemaProperty,
+  type FieldMachine,
+} from "../../src/validate";
 
 export interface GetFieldStructureResponse {
   isRequired: boolean;
@@ -23,6 +28,29 @@ export interface GetFieldStructureResponse {
  * `getFormField`) can render the correct input per datatype instead of a text
  * box for everything.
  */
+/**
+ * Compile the constraint state machine for one field of a write JSON Schema.
+ *
+ * The database generator's constraints *are* a state machine — `pristine →
+ * present → typed → bounded → member → unique → resolved → valid` — and this
+ * builds the form-side instance of it from the same schema
+ * {@link getFieldStructure} reads, so a form field steps through exactly the
+ * gates the import pipeline and the server enforce. Returns `undefined` when
+ * the schema doesn't describe the field.
+ */
+export function getFieldMachine<TFieldName>(
+  validationSchema: SchemaObject | undefined,
+  fieldName: TFieldName,
+): FieldMachine | undefined {
+  const spec = specFromSchemaProperty(
+    validationSchema as
+      | { properties?: Record<string, any>; required?: unknown }
+      | undefined,
+    fieldName as string,
+  );
+  return spec ? compileFieldMachine(spec) : undefined;
+}
+
 export function getFieldStructure<TFieldName>(
   validationSchema: SchemaObject | undefined,
   fieldName: TFieldName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rastack",
-  "version": "0.0.46",
+  "version": "0.0.48",
   "description": "",
   "main": "runtime.ts",
   "types": "runtime.ts",