rastack 0.0.49 → 0.0.51

package/src/compile/index.ts

@@ -1,17 +1,27 @@
 import * as fs from "fs";
 import * as path from "path";
-import { analyze } from "./analyze";
-import { analyzeEntities, detectCycles, EntityDiagnostic } from "./entities";
+import { analyze, analyzeDsl } from "./analyze";
+import {
+  analyzeEntities,
+  detectCycles,
+  EntityDiagnostic,
+  EntityTypeExport,
+} from "./entities";
 import { buildManifest, manifestToJson } from "./manifest";
 import { Manifest, ResourceModel } from "./model";
 import { buildOpenApi, openApiToJson } from "./openapi";
 import { createProgram } from "./program";
+import { transitionProblems } from "../validate/transitions";
 
-export { analyze } from "./analyze";
+export { analyze, analyzeDsl } from "./analyze";
 export { analyzeEntities, detectCycles } from "./entities";
-export type { EntityAnalysis, EntityDiagnostic } from "./entities";
+export type {
+  EntityAnalysis,
+  EntityDiagnostic,
+  EntityTypeExport,
+} from "./entities";
 export { buildManifest } from "./manifest";
-export { buildOpenApi } from "./openapi";
+export { buildOpenApi, writeSchema } from "./openapi";
 export * from "./model";
 
 export interface CompileResult {
@@ -64,6 +74,8 @@ export function resolveResourceFiles(input: string): string[] {
 export interface ProjectAnalysis {
   resources: ResourceModel[];
   diagnostics: EntityDiagnostic[];
+  /** Where each entity's TS type lives — the `rastack-env.d.ts` registry input. */
+  types: EntityTypeExport[];
 }
 
 /**
@@ -78,24 +90,58 @@ export function analyzeProject(input: string): ProjectAnalysis {
   const files = resolveResourceFiles(input);
   const program = createProgram(files);
 
-  const fromDsl = analyze(program, files);
+  const fromDsl = analyzeDsl(program, files);
   const fromInterfaces = analyzeEntities(program, files);
 
-  const defined = new Set(fromDsl.map((r) => `${r.app}.${r.model}`));
+  const defined = new Set(fromDsl.resources.map((r) => `${r.app}.${r.model}`));
   const resources = [
-    ...fromDsl,
+    ...fromDsl.resources,
     ...fromInterfaces.resources.filter((r) => !defined.has(`${r.app}.${r.model}`)),
   ];
   resources.sort((a, b) =>
     a.app === b.app ? a.model.localeCompare(b.model) : a.app.localeCompare(b.app),
   );
 
+  // Registry entries follow the same merge rule as the resources: the DSL
+  // definition wins an `app.model` collision.
+  const types = [
+    ...fromDsl.types,
+    ...fromInterfaces.types.filter((t) => !defined.has(t.key)),
+  ].sort((a, b) => a.key.localeCompare(b.key));
+
   return {
     resources,
-    diagnostics: [...fromInterfaces.diagnostics, ...detectCycles(resources)],
+    types,
+    diagnostics: [
+      ...fromInterfaces.diagnostics,
+      ...detectCycles(resources),
+      ...detectTransitionProblems(resources),
+    ],
   };
 }
 
+/**
+ * Validate every resource's `transitions` block against its own fields and
+ * state set — an edge to an undeclared state, an unknown state field, or a
+ * `set` patch targeting a non-field are authoring errors, caught at compile
+ * time like a circular FK.
+ */
+export function detectTransitionProblems(
+  resources: ResourceModel[],
+): EntityDiagnostic[] {
+  const diagnostics: EntityDiagnostic[] = [];
+  for (const r of resources) {
+    if (!r.transitions) continue;
+    for (const problem of transitionProblems(r.transitions, r.fields)) {
+      diagnostics.push({
+        severity: "error",
+        message: `${r.app}.${r.model}: ${problem}`,
+      });
+    }
+  }
+  return diagnostics;
+}
+
 /** Analyse resource definitions into the canonical model (no file output). */
 export function analyzeResources(input: string): ResourceModel[] {
   return analyzeProject(input).resources;
@@ -103,7 +149,7 @@ export function analyzeResources(input: string): ResourceModel[] {
 
 /** Compile resource definitions to a manifest + OpenAPI, writing both to disk. */
 export function compile(input: string, outDir: string): CompileResult {
-  const { resources, diagnostics } = analyzeProject(input);
+  const { resources, diagnostics, types } = analyzeProject(input);
   const errors = diagnostics.filter((d) => d.severity === "error");
   if (errors.length) {
     throw new Error(errors.map((e) => e.message).join("\n"));
@@ -116,8 +162,59 @@ export function compile(input: string, outDir: string): CompileResult {
   const openapiPath = path.join(outDir, "openapi.json");
   fs.writeFileSync(manifestPath, manifestToJson(manifest), { flag: "w" });
   fs.writeFileSync(openapiPath, openApiToJson(openapi), { flag: "w" });
+  const files = [manifestPath, openapiPath];
 
-  return { manifest, openapi, files: [manifestPath, openapiPath], diagnostics };
+  const registryDts = buildEntityRegistryDts(types, outDir);
+  if (registryDts) {
+    const registryPath = path.join(outDir, "rastack-env.d.ts");
+    fs.writeFileSync(registryPath, registryDts, { flag: "w" });
+    files.push(registryPath);
+  }
+
+  return { manifest, openapi, files, diagnostics };
+}
+
+/**
+ * The `rastack-env.d.ts` the compiler emits beside the manifest: a types-only
+ * declaration-merge of `rastack/hooks/registry`'s `EntityTypes`, mapping every
+ * exported entity's `"app.model"` key to *your own* type — classes and
+ * interfaces directly, `resource()` consts through `RowOf<typeof X>`. With
+ * this file in the program, `useData("airports.terminal")` infers its rows
+ * with no type argument. Unexported declarations can't be imported and are
+ * skipped. Returns `undefined` when there is nothing to register.
+ */
+export function buildEntityRegistryDts(
+  types: EntityTypeExport[],
+  outDir: string,
+): string | undefined {
+  const entries = types.filter((t) => t.exported);
+  if (!entries.length) return undefined;
+
+  const lines = entries.map((t) => {
+    let rel = path
+      .relative(path.resolve(outDir), t.fileName)
+      .replace(/\\/g, "/")
+      .replace(/\.(tsx|ts)$/, "");
+    if (!rel.startsWith(".")) rel = `./${rel}`;
+    const type =
+      t.kind === "resourceConst"
+        ? `import("rastack/define").RowOf<typeof import("${rel}").${t.typeName}>`
+        : `import("${rel}").${t.typeName}`;
+    return `    "${t.key}": ${type};`;
+  });
+
+  return (
+    "// Generated by `rastack compile` — do not edit.\n" +
+    '// Maps manifest keys to your own entity types so `useData("app.model")` /\n' +
+    '// `useForm("app.model")` infer their rows with no type argument.\n' +
+    "// Types only: nothing to import, no runtime code.\n" +
+    'declare module "rastack/hooks/registry" {\n' +
+    "  interface EntityTypes {\n" +
+    `${lines.join("\n")}\n` +
+    "  }\n" +
+    "}\n" +
+    "export {};\n"
+  );
 }
 
 // -- introspection (replaces `manage.py rastack check|list|urls`) -----------

package/src/compile/model.ts

@@ -27,6 +27,12 @@ export interface FieldModel {
   primaryKey?: boolean;
   null?: boolean;
   default?: unknown;
+  /**
+   * The closed set of allowed values (the `member` gate / a `select` control).
+   * Stamped by the compiler — today from a `transitions` block, whose `states`
+   * become the state field's value set.
+   */
+  options?: Array<string | number>;
   /** Present iff `type === "fk"` — the resource this field points at. */
   relation?: RelationTarget;
 }
@@ -63,6 +69,39 @@ export interface AccessModel {
   adminGroups?: string[];
 }
 
+/**
+ * One edge of a resource's state machine: a named transition from one (or
+ * several) states to exactly one target state. `set` is the transition's
+ * *effect* — field patches the engine applies when the edge fires — which is
+ * what makes a transition a declarative backend function: declared once in
+ * TypeScript, compiled here, executed by `rastack-api-core` on every surface.
+ */
+export interface TransitionEdgeModel {
+  /** Source states this transition may fire from (normalised to a list). */
+  from: string[];
+  /** The state entered when the transition fires. */
+  to: string;
+  /** Field patches applied by the engine alongside the state change. */
+  set?: Record<string, unknown>;
+}
+
+/**
+ * A resource's declarative state machine, keyed off one state field. Compiled
+ * into the manifest and enforced on every write surface: the TS record machine
+ * (forms, `rastack import`) and `rastack-api-core` (server, Lambda, WASM) all
+ * reject a write that jumps between states without a declared edge.
+ */
+export interface TransitionsModel {
+  /** The field that carries the machine state. */
+  field: string;
+  /** Every state the field may hold (becomes the field's `options`). */
+  states: string[];
+  /** The state new records start in (becomes the field's default). */
+  initial?: string;
+  /** Named transitions — `on.board = { from: ["scheduled"], to: "boarding" }`. */
+  on: Record<string, TransitionEdgeModel>;
+}
+
 export interface ResourceModel {
   app: string;
   model: string;
@@ -74,6 +113,7 @@ export interface ResourceModel {
   ordering?: string[];
   permission?: string;
   access?: AccessModel;
+  transitions?: TransitionsModel;
 }
 
 export interface Manifest {

package/src/compile/openapi.ts

@@ -116,7 +116,15 @@ function readSchema(resource: ResourceModel): any {
   return { type: "object", properties, required };
 }
 
-function writeSchema(resource: ResourceModel, patched: boolean): any {
+/**
+ * The write JSON Schema for a resource — what the API accepts on
+ * create/update. Exported because the generic `useForm(Entity)` hook derives
+ * the *same* schema at runtime straight from the manifest, so a form
+ * validates against exactly the contract the emitted OpenAPI documents.
+ * Resources with a state machine carry it as `x-rastack-transitions`, the
+ * write-side twin of `x-rastack-relation`.
+ */
+export function writeSchema(resource: ResourceModel, patched: boolean): any {
   const properties: Record<string, any> = {};
   const required: string[] = [];
   for (const field of resource.fields) {
@@ -128,6 +136,9 @@ function writeSchema(resource: ResourceModel, patched: boolean): any {
   }
   const schema: any = { type: "object", properties };
   if (required.length) schema.required = required;
+  if (resource.transitions) {
+    schema["x-rastack-transitions"] = resource.transitions;
+  }
   return schema;
 }
 
@@ -156,6 +167,7 @@ function fieldProperty(field: FieldModel): any {
   }
   const base = scalarProperty(field.type);
   if (field.maxLength !== undefined) base.maxLength = field.maxLength;
+  if (field.options && field.options.length > 0) base.enum = [...field.options];
   if (field.null) base.nullable = true;
   return base;
 }

package/src/define/index.ts

@@ -23,19 +23,49 @@
  * ```
  */
 
-/** A scalar field. The literal `__rastackScalar` type is what the compiler reads. */
-export interface Scalar<T extends string> {
+/**
+ * Every constraint a scalar builder may be handed, merged — the shape the
+ * runtime value carries so a manifest can be assembled without the compiler.
+ */
+export interface ScalarFieldOptions {
+  maxLength?: number;
+  unique?: boolean;
+  primaryKey?: boolean;
+  default?: unknown;
+  null?: boolean;
+  autoNow?: boolean;
+  autoNowAdd?: boolean;
+}
+
+/**
+ * A scalar field. The literal `__rastackScalar` type is what the compiler
+ * reads; `Nullable` phantom-carries the `null: true` option so {@link RowOf}
+ * can add `| null` to the inferred row type. The authored options ride along
+ * on the runtime value too, so `manifestFromResources()` can build the same
+ * manifest `rastack compile` emits — with no compile step at all.
+ */
+export interface Scalar<T extends string, Nullable extends boolean = boolean> {
   readonly __rastackScalar: T;
+  readonly __rastackNullable?: Nullable;
+  /** The constraint options as authored — carried at runtime. */
+  readonly options?: ScalarFieldOptions;
 }
 
+/** Whether an options literal declares `null: true` (as a type). */
+type NullOf<O> = O extends { null: true } ? true : false;
+
 /**
  * A foreign-key field. `App`/`Model` are carried as string-literal type
- * arguments so the compiler can recover the relation target purely from types.
+ * arguments so the compiler can recover the relation target purely from
+ * types; the target thunk is *also* kept on the runtime value so
+ * `manifestFromResources()` can recover the relation with no compiler.
  */
 export interface Ref<App extends string, Model extends string> {
   readonly __rastackRef: true;
   readonly __app: App;
   readonly __model: Model;
+  /** The authored `() => Resource` thunk — carried at runtime. */
+  readonly target?: () => ResourceType<App, Model, any>;
 }
 
 export interface StringOptions {
@@ -65,39 +95,66 @@ export interface DateOptions {
 }
 
 /**
- * Field builders. Each returns a phantom value whose *type* encodes the field
- * kind; the runtime object is never used at compile time (the compiler analyses
- * the source, it does not execute it) but is real so the DSL is also usable at
- * runtime if a consumer wants it.
+ * Field builders. Each returns a value whose *type* encodes the field kind
+ * (what the compiler reads — it analyses the source, it does not execute it)
+ * and whose runtime shape keeps the authored options/target, so the same
+ * definition doubles as its own manifest via `manifestFromResources()`.
  */
 export const s = {
-  string(_opts?: StringOptions): Scalar<"string"> {
-    return { __rastackScalar: "string" } as Scalar<"string">;
+  string<const O extends StringOptions = StringOptions>(
+    opts?: O,
+  ): Scalar<"string", NullOf<O>> {
+    return { __rastackScalar: "string", options: opts } as Scalar<
+      "string",
+      NullOf<O>
+    >;
   },
-  int(_opts?: NumberOptions): Scalar<"int"> {
-    return { __rastackScalar: "int" } as Scalar<"int">;
+  int<const O extends NumberOptions = NumberOptions>(
+    opts?: O,
+  ): Scalar<"int", NullOf<O>> {
+    return { __rastackScalar: "int", options: opts } as Scalar<"int", NullOf<O>>;
   },
-  float(_opts?: NumberOptions): Scalar<"float"> {
-    return { __rastackScalar: "float" } as Scalar<"float">;
+  float<const O extends NumberOptions = NumberOptions>(
+    opts?: O,
+  ): Scalar<"float", NullOf<O>> {
+    return { __rastackScalar: "float", options: opts } as Scalar<
+      "float",
+      NullOf<O>
+    >;
   },
-  bool(_opts?: BoolOptions): Scalar<"bool"> {
-    return { __rastackScalar: "bool" } as Scalar<"bool">;
+  bool<const O extends BoolOptions = BoolOptions>(
+    opts?: O,
+  ): Scalar<"bool", NullOf<O>> {
+    return { __rastackScalar: "bool", options: opts } as Scalar<
+      "bool",
+      NullOf<O>
+    >;
   },
-  datetime(_opts?: DateOptions): Scalar<"datetime"> {
-    return { __rastackScalar: "datetime" } as Scalar<"datetime">;
+  datetime<const O extends DateOptions = DateOptions>(
+    opts?: O,
+  ): Scalar<"datetime", NullOf<O>> {
+    return { __rastackScalar: "datetime", options: opts } as Scalar<
+      "datetime",
+      NullOf<O>
+    >;
   },
-  uuid(_opts?: StringOptions): Scalar<"uuid"> {
-    return { __rastackScalar: "uuid" } as Scalar<"uuid">;
+  uuid<const O extends StringOptions = StringOptions>(
+    opts?: O,
+  ): Scalar<"uuid", NullOf<O>> {
+    return { __rastackScalar: "uuid", options: opts } as Scalar<
+      "uuid",
+      NullOf<O>
+    >;
   },
   /**
    * A foreign key. The target is `() => SomeResource`; the compiler resolves
-   * the relation from the *type* `Ref<App, Model>` this returns — it does not
-   * need to run the thunk.
+   * the relation from the *type* `Ref<App, Model>` this returns, and the
+   * runtime keeps the thunk so `manifestFromResources()` can resolve it too.
    */
   ref<A extends string, M extends string>(
-    _thunk: () => ResourceType<A, M, any>,
+    thunk: () => ResourceType<A, M, any>,
   ): Ref<A, M> {
-    return { __rastackRef: true } as Ref<A, M>;
+    return { __rastackRef: true, target: thunk } as Ref<A, M>;
   },
 };
 
@@ -132,6 +189,54 @@ export interface AccessOptions {
   adminGroups?: string[];
 }
 
+/**
+ * One edge of a resource's state machine. `from` is the state (or states) the
+ * transition may fire from, `to` the state it enters, and `set` the effect —
+ * field patches the engine applies alongside the state change. The block is
+ * static data: it compiles into the manifest and is enforced by
+ * `rastack-api-core` on every surface (server, Lambda, in-browser WASM), so a
+ * transition behaves as a declarative, typesafe backend function with no
+ * per-resource server code.
+ */
+export interface TransitionEdge {
+  from: string | readonly string[];
+  to: string;
+  set?: Record<string, string | number | boolean | null>;
+}
+
+/**
+ * A resource's declarative state machine, keyed off one state field:
+ *
+ * ```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" },
+ *   },
+ * }
+ * ```
+ *
+ * `states` becomes the field's allowed-value set (`enum` in OpenAPI, the
+ * `member` gate in the validation machine) and `initial` its default. A write
+ * that moves the field between states without a declared edge is rejected on
+ * every surface, and `useForm(Flight).transition("board")` exposes the edges
+ * as typed form actions.
+ */
+export interface TransitionsOptions {
+  /** The field carrying the machine state. */
+  field: string;
+  /** Every state the field may hold. */
+  states: readonly string[];
+  /** The state new records start in. */
+  initial?: string;
+  /** Named transitions. */
+  on: Record<string, TransitionEdge>;
+}
+
 export interface ResourceOptions {
   /** DRF-style search fields. */
   search?: string[];
@@ -145,33 +250,44 @@ export interface ResourceOptions {
   permission?: "authenticatedOrReadOnly" | "authenticated" | "public";
   /** Row-level security + physical tenant partitioning. */
   access?: AccessOptions;
+  /** Declarative state machine over one field, enforced on every write surface. */
+  transitions?: TransitionsOptions;
 }
 
 /**
  * A resource definition. `App`/`Model` are preserved as string-literal type
- * arguments so a {@link Ref} to this resource carries a recoverable target.
+ * arguments so a {@link Ref} to this resource carries a recoverable target,
+ * and the options object's literal type is preserved so downstream types can
+ * read the declared transition names (`useForm(Flight).transition("board")`
+ * only accepts names the resource actually declares).
  */
-export interface ResourceType<App extends string, Model extends string, F> {
+export interface ResourceType<
+  App extends string,
+  Model extends string,
+  F,
+  O extends ResourceOptions = ResourceOptions,
+> {
   readonly __rastack: "resource";
   readonly __app: App;
   readonly __model: Model;
   readonly app: App;
   readonly model: Model;
   readonly fields: F;
-  readonly options: ResourceOptions;
+  readonly options: O;
 }
 
-/** Define a resource. Capture app/model as literal types for FK inference. */
+/** Define a resource. Capture app/model (and options) as literal types. */
 export function resource<
   App extends string,
   Model extends string,
   F extends Record<string, AnyField>,
+  const O extends ResourceOptions = ResourceOptions,
 >(
   app: App,
   model: Model,
   fields: F,
-  options: ResourceOptions = {},
-): ResourceType<App, Model, F> {
+  options: O = {} as O,
+): ResourceType<App, Model, F, O> {
   return {
     __rastack: "resource",
     __app: app,
@@ -182,3 +298,91 @@ export function resource<
     options,
   };
 }
+
+/**
+ * The transition names an entity declares — from a `resource()` value's
+ * options, or from a class's `static transitions` block. Entities with no
+ * transitions resolve to `never`, so `form.transition(...)` is uncallable on
+ * them at the type level.
+ */
+export type TransitionNamesOf<E> = E extends {
+  options: { transitions: { on: infer On } };
+}
+  ? Extract<keyof On, string>
+  : E extends { transitions: { on: infer On } }
+    ? Extract<keyof On, string>
+    : E extends string
+      ? string // an `"app.model"` ref carries no type-level transition info
+      : never;
+
+// ---------------------------------------------------------------------------
+// Row inference — `useData(Flight)` knows its rows from the definition itself
+// ---------------------------------------------------------------------------
+
+type ScalarTsType<T extends string> = T extends "int" | "float"
+  ? number
+  : T extends "bool"
+    ? boolean
+    : string; // string / datetime / uuid all travel as strings
+
+/** The TypeScript value type one field of a `resource()` definition holds. */
+export type FieldValueOf<F> =
+  F extends Scalar<infer T, infer N>
+    ? N extends true
+      ? ScalarTsType<T> | null
+      : ScalarTsType<T>
+    : F extends Ref<string, string>
+      ? number | string // FK values are opaque ids
+      : unknown;
+
+/**
+ * The row type a `resource()` definition implies — what `useData(Flight)`
+ * infers with **no type argument**: each field's scalar kind maps to its TS
+ * type (`null: true` adds `| null`), FKs are ids, plus the server-assigned
+ * `id`. Classes carry their own row type, and interfaces resolve through the
+ * `EntityTypes` registry (`rastack/hooks/registry`), so every reference form
+ * infers.
+ */
+export type RowOf<R> =
+  R extends ResourceType<string, string, infer F, ResourceOptions>
+    ? { id: number | string } & { [K in keyof F]: FieldValueOf<F[K]> }
+    : never;
+
+/** The `"app.model"` registry key a `resource()` definition implies. */
+export type EntityKeyOf<R> =
+  R extends ResourceType<infer A, infer M, any, ResourceOptions>
+    ? `${A}.${M}`
+    : never;
+
+/**
+ * The `EntityTypes` registry entries a module of `resource()` definitions
+ * implies — the *hand-written* alternative to the `rastack-env.d.ts` that
+ * `rastack compile` emits. Point it at your resources module once and the
+ * registry tracks it forever, with no compile step in the loop:
+ *
+ * ```ts
+ * // rastack-env.d.ts — written once by you, never regenerated
+ * import type { EntityTypesOf } from "rastack/define";
+ * declare module "rastack/hooks/registry" {
+ *   interface EntityTypes
+ *     extends EntityTypesOf<typeof import("./resources/airports")> {}
+ * }
+ * ```
+ *
+ * Non-resource exports are dropped, so `typeof import("…")` over a whole
+ * module is safe. (Class entities carry their own row type — they never need
+ * the registry; interfaces still register via the compile-emitted file.)
+ */
+export type EntityTypesOf<M> = {
+  [K in keyof M as EntityKeyOf<M[K]>]: RowOf<M[K]>;
+};
+
+// The runtime manifest builder — a resource() definition is its own manifest.
+export {
+  isResourceValue,
+  manifestFromResources,
+  resourceModel,
+  toManifest,
+} from "./manifest";
+export type { AnyResourceValue, ManifestInput } from "./manifest";
+export type { Manifest, ResourceModel } from "../compile/model";