rastack 0.0.49 → 0.0.51

package/src/plugin/index.ts

@@ -0,0 +1,243 @@
+/**
+ * `rastack/plugin` — the schema compiles itself inside your dev server.
+ *
+ * Class and interface entities are pure types, so the manifest has to be
+ * derived by the TypeScript checker — but not by a command you run. Add the
+ * plugin to the bundler you already use and the whole `rastack compile`
+ * pass disappears into the dev loop:
+ *
+ * ```ts
+ * // vite.config.ts
+ * import { rastackPlugin } from "rastack/plugin";
+ * export default defineConfig({
+ *   plugins: [rastackPlugin({ resourcesDir: "src/entities" })],
+ * });
+ * ```
+ *
+ * ```tsx
+ * // app — the manifest is a live import, recompiled on every save
+ * import manifest from "virtual:rastack-manifest";
+ * <RAStackProvider mode="local" manifest={manifest}>…</RAStackProvider>
+ * ```
+ *
+ * What it does on your behalf, on every relevant file save:
+ * - recompiles the entity graph (classes, interfaces, `resource()` calls);
+ * - serves the manifest as the `virtual:rastack-manifest` module and
+ *   hot-invalidates it;
+ * - rewrites `.rastack/rastack-env.d.ts` (string-key row types) and
+ *   `schema.rastack.json`/`openapi.json`, so the committed artifacts and the
+ *   registry never go stale;
+ * - on a broken in-progress edit, reports the error and keeps serving the
+ *   last good manifest.
+ *
+ * The plugin object is Vite/Rollup-compatible (Vite-specific hooks are
+ * ignored by plain Rollup). For dev servers with other plugin systems
+ * (Next/webpack, Metro/Expo), `startRastackWatcher` does the same
+ * recompile-on-save against the filesystem — call it once from your config —
+ * and `rastack dev` remains the zero-config path.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import {
+  createSchemaState,
+  isEntitySource,
+  registerModuleCode,
+  RESOLVED_MANIFEST_ID,
+  VIRTUAL_MANIFEST_ID,
+  VIRTUAL_REGISTER_ID,
+  type RastackPluginOptions,
+  type SchemaState,
+} from "./core";
+
+export {
+  createSchemaState,
+  GLOBAL_MANIFEST_KEY,
+  isEntitySource,
+  manifestModuleCode,
+  registerModuleCode,
+  resolveOptions,
+  RESOLVED_MANIFEST_ID,
+  runCompile,
+  VIRTUAL_MANIFEST_ID,
+  VIRTUAL_REGISTER_ID,
+  virtualModuleDts,
+} from "./core";
+export type {
+  RastackPluginOptions,
+  ResolvedPluginOptions,
+  SchemaState,
+} from "./core";
+
+/** One HTML tag descriptor in Vite's `transformIndexHtml` shape. */
+export interface HtmlTagDescriptor {
+  tag: string;
+  attrs?: Record<string, string>;
+  children?: string;
+  injectTo?: "head" | "head-prepend" | "body" | "body-prepend";
+}
+
+/** The minimal bundler-plugin surface we emit (Vite superset of Rollup). */
+export interface RastackBundlerPlugin {
+  name: string;
+  buildStart(): void;
+  resolveId(id: string): string | undefined;
+  load(id: string): string | undefined;
+  watchChange(id: string): void;
+  /**
+   * Vite-only: auto-register the schema. Injects a module script that sets
+   * `globalThis.__RASTACK_MANIFEST__` before the app boots, so the provider
+   * and hooks need no `manifest` wiring at all. Object form with
+   * `order: "pre"` — the tag must be injected *before* Vite scans the HTML
+   * entry, or the build ships the virtual import verbatim.
+   */
+  transformIndexHtml: {
+    order: "pre";
+    handler(html: string, ctx?: { server?: unknown }): HtmlTagDescriptor[];
+  };
+  /** Vite-only: recompile + hot-invalidate the virtual manifest module. */
+  handleHotUpdate(ctx: {
+    file: string;
+    server: {
+      moduleGraph: {
+        getModuleById(id: string): unknown;
+        invalidateModule(mod: any): void;
+      };
+    };
+    modules: unknown[];
+  }): unknown[] | void;
+  /** The live schema state — exposed for tests and advanced callers. */
+  api: SchemaState;
+}
+
+/**
+ * The bundler plugin. Works as-is in Vite and Rollup; the returned object is
+ * plain data + closures, so any bundler with resolve/load/watch hooks can
+ * adapt it.
+ */
+export function rastackPlugin(
+  options: RastackPluginOptions = {},
+): RastackBundlerPlugin {
+  const state = createSchemaState(options);
+
+  return {
+    name: "rastack",
+
+    buildStart() {
+      // Compile eagerly so authoring errors surface at server start, and the
+      // artifacts (env.d.ts, schema.rastack.json) exist before first load.
+      state.manifest();
+    },
+
+    resolveId(id: string) {
+      if (id === VIRTUAL_MANIFEST_ID) return RESOLVED_MANIFEST_ID;
+      if (id === VIRTUAL_REGISTER_ID) return VIRTUAL_REGISTER_ID;
+      return undefined;
+    },
+
+    load(id: string) {
+      if (id === RESOLVED_MANIFEST_ID) return state.code();
+      if (id === VIRTUAL_REGISTER_ID) return registerModuleCode();
+      return undefined;
+    },
+
+    watchChange(id: string) {
+      if (isEntitySource(id, state.options)) state.invalidate();
+    },
+
+    handleHotUpdate(ctx) {
+      if (!isEntitySource(ctx.file, state.options)) return;
+      state.invalidate();
+      const mod = ctx.server.moduleGraph.getModuleById(RESOLVED_MANIFEST_ID);
+      if (mod) {
+        ctx.server.moduleGraph.invalidateModule(mod);
+        return [...ctx.modules, mod];
+      }
+    },
+
+    transformIndexHtml: {
+      order: "pre",
+      handler(_html: string, ctx?: { server?: unknown }) {
+        // Dev serves resolved ids at /@id/<id>; build gets an inline module
+        // script that (because this runs `pre`, before Vite scans the HTML
+        // entry) is bundled, its import resolving back through
+        // resolveId/load above.
+        const attrs: Record<string, string> = { type: "module" };
+        const tag: HtmlTagDescriptor = ctx?.server
+          ? {
+              tag: "script",
+              attrs: { ...attrs, src: `/@id/${VIRTUAL_REGISTER_ID}` },
+            }
+          : {
+              tag: "script",
+              attrs,
+              children: `import ${JSON.stringify(VIRTUAL_REGISTER_ID)};`,
+            };
+        return [{ ...tag, injectTo: "head-prepend" }];
+      },
+    },
+
+    api: state,
+  };
+}
+
+/** Alias so `import { rastack } from "rastack/plugin"` reads naturally. */
+export const rastack = rastackPlugin;
+
+export interface RastackWatcher {
+  /** Stop watching. */
+  close(): void;
+  /** The live schema state (same object the recompiles flow through). */
+  state: SchemaState;
+}
+
+/**
+ * The plugin for everything that isn't Rollup-shaped: watch the resources
+ * directory and rewrite the artifacts (`schema.rastack.json`,
+ * `openapi.json`, `rastack-env.d.ts`) on every save. Call once from any
+ * Node-side config (next.config.js, metro.config.js, a dev script):
+ *
+ * ```js
+ * // next.config.js
+ * const { startRastackWatcher } = require("rastack/plugin");
+ * if (process.env.NODE_ENV === "development") startRastackWatcher();
+ * ```
+ *
+ * The app then imports `.rastack/schema.rastack.json` directly (a plain JSON
+ * import every bundler hot-reloads) instead of the virtual module.
+ */
+export function startRastackWatcher(
+  options: RastackPluginOptions = {},
+): RastackWatcher {
+  const state = createSchemaState(options);
+  state.manifest(); // initial compile (writes the artifacts)
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const watcher = fs.watch(
+    state.options.resourcesDir,
+    { recursive: true },
+    (_event, filename) => {
+      // fs.watch reports paths relative to the watched directory.
+      const file = filename
+        ? path.join(state.options.resourcesDir, String(filename))
+        : undefined;
+      if (!file || !isEntitySource(file, state.options)) {
+        return;
+      }
+      state.invalidate();
+      // Debounce bursts (editors write twice, git checkouts touch many files).
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => {
+        state.manifest();
+      }, 100);
+    },
+  );
+
+  return {
+    close: () => {
+      if (timer) clearTimeout(timer);
+      watcher.close();
+    },
+    state,
+  };
+}

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");
+  });
 });