rastack 0.0.49 → 0.0.50

package/src/import/tabular.ts

@@ -18,6 +18,7 @@ import {
   type FieldState,
   type RecordRun,
   type SpecRelation,
+  type TransitionsModel,
 } from "../validate";
 
 /** A parsed tabular source: one header row + string cell rows. */
@@ -36,7 +37,7 @@ export interface ColumnMapping {
 export interface ImportIssue {
   row: number;
   field: string;
-  gate: FieldState;
+  gate: FieldState | "transition";
   constraint: string;
   message: string;
 }
@@ -94,6 +95,12 @@ export interface ValidateDatasetOptions {
   relatedIds?: Record<string, Set<string>>;
   /** Custom FK resolver (wins over `relatedIds`). */
   resolveRelation?: (relation: SpecRelation, value: unknown) => boolean;
+  /**
+   * The resource's state machine (`schema.rastack.json` `transitions`).
+   * Imported rows are creates, so the record-level `transition` gate rejects
+   * rows born mid-machine (a state other than the initial one).
+   */
+  transitions?: TransitionsModel;
 }
 
 /**
@@ -108,7 +115,7 @@ export function validateDataset(
   options: ValidateDatasetOptions = {},
 ): ImportReport {
   const { columns, missingFields } = mapHeaders(data.headers, specs);
-  const machine = compileRecordMachine(specs);
+  const machine = compileRecordMachine(specs, options.transitions);
   const ctx = createDatasetContext(machine, options);
 
   const rows: RecordRun[] = [];

package/src/rastack-import.ts

@@ -148,7 +148,10 @@ function main(): void {
       `[${data.headers.length} column(s), ${data.rows.length} row(s)]\n`,
   );
 
-  const report = validateDataset(specs, data, { relatedIds });
+  const report = validateDataset(specs, data, {
+    relatedIds,
+    transitions: resource.transitions,
+  });
   printReport(report);
 
   const outPath = getArg("--out");

package/src/validate/adapters.ts

@@ -33,6 +33,7 @@ export function specFromManifestField(field: FieldModel): FieldSpec {
   };
   if (field.maxLength !== undefined) spec.maxLength = field.maxLength;
   if (field.unique) spec.unique = true;
+  if (field.options && field.options.length > 0) spec.options = field.options;
   if (field.default !== undefined) spec.default = field.default;
   if (field.type === "fk" && field.relation) spec.relation = field.relation;
   return spec;

package/src/validate/index.ts

@@ -1,2 +1,3 @@
 export * from "./machine";
 export * from "./adapters";
+export * from "./transitions";

package/src/validate/machine.ts

@@ -34,8 +34,18 @@
  * single keystroke — passes through them untouched, exactly like the server,
  * where uniqueness and FK existence are checked against the table, not the
  * payload.
+ *
+ * Record machines add one **record-level** gate on top of the per-field
+ * chains: `transition`. A resource that declares a `transitions` block gets
+ * its state-field writes guarded against the declared edges (with the
+ * persisted row supplied via `ctx.previous`), so an illegal state jump fails
+ * a form, an import row, and a server write with the same message — see
+ * `./transitions.ts`.
  */
 
+import type { TransitionsModel } from "../compile/model";
+import { describeTransitions, transitionGuard } from "./transitions";
+
 // ---------------------------------------------------------------------------
 // The field spec — the normalised constraint set a machine is compiled from
 // ---------------------------------------------------------------------------
@@ -143,6 +153,12 @@ export interface ValidationContext {
   seen?: Map<string, Set<string>>;
   /** Resolve whether a FK value exists on the target resource (the `resolved` gate). */
   resolveRelation?: (relation: SpecRelation, value: unknown) => boolean;
+  /**
+   * The persisted row this record updates (the record-level `transition`
+   * guard). Absent = create semantics: the state field must hold the initial
+   * state. Only consulted by record machines compiled with a transitions block.
+   */
+  previous?: Record<string, unknown>;
 }
 
 /** The result of running a value through a field machine. */
@@ -442,12 +458,19 @@ export function runFieldMachine(
 /** A record machine is the composition of its fields' machines. */
 export interface RecordMachine {
   fields: FieldMachine[];
+  /**
+   * The resource's declarative state machine, when it declares one. Runs as a
+   * record-level gate after the per-field gates: a write that moves the state
+   * field without a declared edge fails at the `transition` gate.
+   */
+  transitions?: TransitionsModel;
 }
 
 /** One field's failure inside a record run. */
 export interface RecordError {
   field: string;
-  gate: FieldState;
+  /** The gate that rejected the value — a field gate, or the record-level `transition` gate. */
+  gate: FieldState | "transition";
   constraint: string;
   message: string;
 }
@@ -462,8 +485,13 @@ export interface RecordRun {
   errors: RecordError[];
 }
 
-export function compileRecordMachine(specs: FieldSpec[]): RecordMachine {
-  return { fields: specs.map(compileFieldMachine) };
+export function compileRecordMachine(
+  specs: FieldSpec[],
+  transitions?: TransitionsModel,
+): RecordMachine {
+  const machine: RecordMachine = { fields: specs.map(compileFieldMachine) };
+  if (transitions) machine.transitions = transitions;
+  return machine;
 }
 
 export function runRecordMachine(
@@ -485,6 +513,30 @@ export function runRecordMachine(
     }
   }
 
+  // The record-level `transition` gate: with the per-field gates passed, a
+  // state-field change must follow a declared edge (against `ctx.previous`;
+  // no previous row = create semantics). A field-level failure on the state
+  // field already explains itself, so the gate only runs when that field is
+  // clean — one error per cause, like every other gate.
+  const transitions = machine.transitions;
+  if (transitions && !fields[transitions.field]?.failed) {
+    // Guard against what was actually submitted: an absent state field is not
+    // a transition, but the field machine defaults it in `values`.
+    const submitted =
+      record[transitions.field] === undefined
+        ? {}
+        : { [transitions.field]: values[transitions.field] };
+    const guard = transitionGuard(transitions, ctx.previous, submitted);
+    if (!guard.ok) {
+      errors.push({
+        field: transitions.field,
+        gate: "transition",
+        constraint: `transitions: ${describeTransitions(transitions).join("; ")}`,
+        message: guard.message,
+      });
+    }
+  }
+
   return {
     state: errors.length === 0 ? "valid" : "invalid",
     values,

package/src/validate/transitions.ts

@@ -0,0 +1,232 @@
+/**
+ * Declarative state transitions — the record-level layer of the constraint
+ * state machine.
+ *
+ * A resource opts in with a `transitions` block (on `resource()` options, or a
+ * `static transitions` on an entity class):
+ *
+ * ```ts
+ * transitions: {
+ *   field: "status",
+ *   states: ["scheduled", "boarding", "departed", "cancelled"],
+ *   initial: "scheduled",
+ *   on: {
+ *     board:  { from: "scheduled", to: "boarding" },
+ *     depart: { from: "boarding",  to: "departed" },
+ *     cancel: { from: ["scheduled", "boarding"], to: "cancelled",
+ *               set: { gate: null } },
+ *   },
+ * }
+ * ```
+ *
+ * The block compiles into the manifest verbatim (with `from` normalised to a
+ * list), and this module is the *shared executable form* of it: the same pure
+ * functions guard a form submit (`useForm(...).transition("board")`), the
+ * record machine (`runRecordMachine` with a `previous` row in context), and —
+ * re-implemented 1:1 in `rastack-api-core` — every server/WASM write. A write
+ * that jumps between states without a declared edge is rejected on every
+ * surface, which is what makes a transition "a backend function that is
+ * state-machine safe": the only way to move a record between states is a
+ * named edge, and the edge's `set` patches are applied by the engine.
+ */
+
+import type { TransitionEdgeModel, TransitionsModel } from "../compile/model";
+
+export type { TransitionEdgeModel, TransitionsModel } from "../compile/model";
+
+/** A transition available from a given state, ready for a UI action list. */
+export interface AvailableTransition {
+  name: string;
+  to: string;
+  set?: Record<string, unknown>;
+}
+
+/** The outcome of a transition guard or application. */
+export type TransitionResult =
+  | { ok: true; patch: Record<string, unknown> }
+  | { ok: false; message: string };
+
+/**
+ * Normalise a raw (authored) transitions block into the canonical model shape:
+ * `from` becomes a string list, non-string states are dropped, and anything
+ * structurally broken yields `undefined` (the compiler then reports it).
+ */
+export function normalizeTransitions(raw: unknown): TransitionsModel | undefined {
+  if (!raw || typeof raw !== "object") return undefined;
+  const block = raw as Record<string, unknown>;
+  if (typeof block.field !== "string" || !block.field) return undefined;
+  if (!Array.isArray(block.states)) return undefined;
+  const states = block.states.filter((s): s is string => typeof s === "string");
+  if (!states.length) return undefined;
+  if (!block.on || typeof block.on !== "object") return undefined;
+
+  const on: Record<string, TransitionEdgeModel> = {};
+  for (const [name, rawEdge] of Object.entries(block.on as Record<string, unknown>)) {
+    if (!rawEdge || typeof rawEdge !== "object") continue;
+    const edge = rawEdge as Record<string, unknown>;
+    const from = (Array.isArray(edge.from) ? edge.from : [edge.from]).filter(
+      (s): s is string => typeof s === "string",
+    );
+    if (!from.length || typeof edge.to !== "string") continue;
+    const model: TransitionEdgeModel = { from, to: edge.to };
+    if (edge.set && typeof edge.set === "object" && !Array.isArray(edge.set)) {
+      model.set = edge.set as Record<string, unknown>;
+    }
+    on[name] = model;
+  }
+
+  const model: TransitionsModel = { field: block.field, states, on };
+  if (typeof block.initial === "string") model.initial = block.initial;
+  return model;
+}
+
+/**
+ * Sanity-check a transitions block against its resource's fields. Returns
+ * human-readable problems (empty = valid); the compiler surfaces each as an
+ * error diagnostic, mirroring the circular-dependency check.
+ */
+export function transitionProblems(
+  transitions: TransitionsModel,
+  fields: Array<{ name: string }>,
+): string[] {
+  const problems: string[] = [];
+  const fieldNames = new Set(fields.map((f) => f.name));
+  const states = new Set(transitions.states);
+
+  if (!fieldNames.has(transitions.field)) {
+    problems.push(`transitions.field "${transitions.field}" is not a field`);
+  }
+  if (transitions.initial !== undefined && !states.has(transitions.initial)) {
+    problems.push(`initial state "${transitions.initial}" is not in states`);
+  }
+  for (const [name, edge] of Object.entries(transitions.on)) {
+    for (const from of edge.from) {
+      if (!states.has(from)) {
+        problems.push(`transition "${name}": from-state "${from}" is not in states`);
+      }
+    }
+    if (!states.has(edge.to)) {
+      problems.push(`transition "${name}": to-state "${edge.to}" is not in states`);
+    }
+    for (const key of Object.keys(edge.set ?? {})) {
+      if (key === transitions.field) {
+        problems.push(
+          `transition "${name}": set must not patch the state field itself`,
+        );
+      } else if (!fieldNames.has(key)) {
+        problems.push(`transition "${name}": set targets unknown field "${key}"`);
+      }
+    }
+  }
+  return problems;
+}
+
+/** The state a record is in — its state-field value, else the initial state. */
+export function currentState(
+  transitions: TransitionsModel,
+  record: Record<string, unknown> | undefined,
+): string | undefined {
+  const value = record?.[transitions.field];
+  if (value !== undefined && value !== null && value !== "") return String(value);
+  return transitions.initial;
+}
+
+/** Every transition that may fire from `state` — the form's action list. */
+export function allowedTransitions(
+  transitions: TransitionsModel,
+  state: unknown,
+): AvailableTransition[] {
+  const from = state === undefined || state === null ? transitions.initial : String(state);
+  if (from === undefined) return [];
+  return Object.entries(transitions.on)
+    .filter(([, edge]) => edge.from.includes(from))
+    .map(([name, edge]) => ({ name, to: edge.to, set: edge.set }));
+}
+
+/** The declared edge covering `from → to`, if any. */
+export function findTransition(
+  transitions: TransitionsModel,
+  from: string,
+  to: string,
+): { name: string; edge: TransitionEdgeModel } | undefined {
+  for (const [name, edge] of Object.entries(transitions.on)) {
+    if (edge.to === to && edge.from.includes(from)) return { name, edge };
+  }
+  return undefined;
+}
+
+/**
+ * Guard one write. `previous` is the persisted row (`undefined` = create).
+ * A create must start at the initial state; an update that changes the state
+ * field must follow a declared edge. Anything else passes untouched — the
+ * guard constrains only the state field.
+ */
+export function transitionGuard(
+  transitions: TransitionsModel,
+  previous: Record<string, unknown> | undefined,
+  next: Record<string, unknown>,
+): TransitionResult {
+  const value = next[transitions.field];
+
+  if (previous === undefined) {
+    // Create: absent state falls back to the initial default; a supplied state
+    // must *be* the initial state — records cannot be born mid-machine.
+    if (value === undefined || value === null || value === "") {
+      return { ok: true, patch: {} };
+    }
+    if (transitions.initial !== undefined && String(value) !== transitions.initial) {
+      return {
+        ok: false,
+        message: `${transitions.field}: new records start at "${transitions.initial}", not "${String(value)}"`,
+      };
+    }
+    return { ok: true, patch: {} };
+  }
+
+  // Update: an untouched (or unchanged) state field is not a transition.
+  if (value === undefined) return { ok: true, patch: {} };
+  const from = currentState(transitions, previous);
+  const to = String(value);
+  if (from === to) return { ok: true, patch: {} };
+
+  const match = from !== undefined && findTransition(transitions, from, to);
+  if (!match) {
+    return {
+      ok: false,
+      message: `${transitions.field}: no transition from "${String(from)}" to "${to}"`,
+    };
+  }
+  return { ok: true, patch: { ...match.edge.set } };
+}
+
+/**
+ * Fire a *named* transition from a record's current state: validates the edge
+ * is available and returns the full patch to write — the state change plus the
+ * edge's `set` effects. This is the client half of the backend function; the
+ * server re-derives the same patch from the same manifest.
+ */
+export function applyTransition(
+  transitions: TransitionsModel,
+  name: string,
+  record: Record<string, unknown> | undefined,
+): TransitionResult {
+  const edge = transitions.on[name];
+  if (!edge) {
+    return { ok: false, message: `unknown transition "${name}"` };
+  }
+  const state = currentState(transitions, record);
+  if (state === undefined || !edge.from.includes(state)) {
+    return {
+      ok: false,
+      message: `"${name}" is not available from "${String(state)}" (needs ${edge.from.join(" | ")})`,
+    };
+  }
+  return { ok: true, patch: { [transitions.field]: edge.to, ...edge.set } };
+}
+
+/** Human-readable edge list — `"board: scheduled → boarding"` — for UI hints. */
+export function describeTransitions(transitions: TransitionsModel): string[] {
+  return Object.entries(transitions.on).map(
+    ([name, edge]) => `${name}: ${edge.from.join(" | ")} → ${edge.to}`,
+  );
+}

package/test/components.spec.ts

@@ -383,4 +383,26 @@ describe("buildAutoFormModel — wiring a form hook into field descriptors", ()
     const model = buildAutoFormModel(form, { exclude: ["status"] });
     expect(model.fields.map((f) => f.name)).toEqual(["code", "active"]);
   });
+
+  it("feature-detects state-machine transitions off a useForm(Entity) result", () => {
+    // A form without transitions renders no actions.
+    expect(buildAutoFormModel(form).transitions).toEqual([]);
+
+    const transition = jest.fn();
+    const machineForm: AutoFormLike = {
+      ...form,
+      transitions: [
+        { name: "board", label: "Board", to: "boarding" },
+        { name: "cancel", to: "cancelled" }, // no label — humanised
+      ],
+      transition,
+    };
+    const model = buildAutoFormModel(machineForm);
+    expect(model.transitions.map((t) => [t.name, t.label, t.to])).toEqual([
+      ["board", "Board", "boarding"],
+      ["cancel", "Cancel", "cancelled"],
+    ]);
+    model.transitions[0].fire();
+    expect(transition).toHaveBeenCalledWith("board");
+  });
 });