rastack 0.0.48 → 0.0.50

package/hooks/form/entity-form.ts

@@ -0,0 +1,354 @@
+/**
+ * `useForm` — pass your type in, get the whole form out.
+ *
+ * ```tsx
+ * const form = useForm(Flight, { id });
+ *
+ * <AutoForm form={form} />
+ * form.transitions          // [{ name: "board", to: "boarding", … }] — from the current state
+ * form.transition("board")  // fire a declared edge: state change + `set` patches, then save
+ * ```
+ *
+ * The generic replacement for the generated `useUpdate{Model}Form` hooks:
+ * the entity reference resolves against the compiled manifest, the write
+ * JSON Schema is derived from the *same* `writeSchema()` the OpenAPI emitter
+ * uses (so the form validates exactly the contract the API enforces —
+ * datatypes, `maxLength`, `enum`, FK relations, the constraint state
+ * machine), the create/put/patch mutations are built from the URL convention,
+ * and — when the resource declares a `transitions` block — the form exposes
+ * the state machine as typed actions.
+ *
+ * `form.transition(name)` is the client half of the declarative backend
+ * function: it validates the edge against the record's current state, stages
+ * the state change plus the edge's `set` patches on top of the form values,
+ * and submits. The server (`rastack-api-core` — HTTP, Lambda, and in-browser
+ * WASM alike) re-derives and re-enforces the same edge from the same
+ * manifest, so an illegal jump is rejected even if a client bypasses the
+ * form. Transition *names* are typed: `useForm(Flight).transition(…)` only
+ * accepts the names `Flight` declares.
+ */
+
+import { useMemo } from "react";
+import { useSchemaForm } from "./form";
+import type {
+  FormProps,
+  FormStructure,
+  FormUpdate,
+  FormValuesType,
+} from "./interfaces";
+import { useGetQuery } from "../query/fetch";
+import { useUpdateQuery } from "../query/update";
+import type { IGetQueryResult } from "../query/interfaces";
+import {
+  EntityClass,
+  EntityRef,
+  EntityRow,
+  humanizeName,
+  isEntityRef,
+  ResolvedEntity,
+  resolveEntityRef,
+} from "../entity";
+import { useRastackManifest } from "../manifest";
+import type { EntityTypes, RegisteredEntityKey } from "../registry";
+import { writeSchema } from "../../src/compile/openapi";
+import type {
+  FieldModel,
+  Manifest,
+  ResourceModel,
+} from "../../src/compile/model";
+import {
+  allowedTransitions,
+  applyTransition,
+  currentState,
+} from "../../src/validate/transitions";
+import type { TransitionNamesOf } from "../../src/define";
+
+export interface UseEntityFormOptions<TRow> {
+  /** Editing an existing record: its id. Absent = a create form. */
+  id?: string | number;
+  /** Initial/override values, merged over defaults and the fetched record. */
+  formValues?: Partial<TRow>;
+  /** `"put"` to save with PUT; default is POST on create / PATCH on update. */
+  updateType?: FormUpdate;
+  onSuccess?: (row: TRow) => void;
+  /** Manifest override — tests, or callers outside `<RAStackProvider>`. */
+  manifest?: Manifest;
+}
+
+/** One transition available from the record's current state. */
+export interface FormTransition {
+  name: string;
+  /** Humanised name — a ready-made button label. */
+  label: string;
+  /** The state the transition enters. */
+  to: string;
+  /** The edge's `set` patches (applied alongside the state change). */
+  set?: Record<string, unknown>;
+}
+
+export interface EntityFormResult<TRow, TName extends string = string>
+  extends FormStructure<Partial<TRow>, Record<string, unknown>> {
+  /** The resolved entity — urls, manifest resource, state machine. */
+  entity: ResolvedEntity;
+  /** The persisted record being edited (id mode), once fetched. */
+  record: TRow | undefined;
+  isRecordLoading: boolean;
+  /** The record's current machine state (resources with `transitions`). */
+  state: string | undefined;
+  /** The transitions available from the current state — render as actions. */
+  transitions: FormTransition[];
+  /** Whether a named transition may fire from the current state. */
+  canTransition: (name: TName) => boolean;
+  /**
+   * Fire a declared transition: guard the edge, stage `{ [field]: to, ...set }`
+   * over the current form values, and save. Throws on an edge the state
+   * machine does not allow — the same rule the engine enforces on write.
+   */
+  transition: (name: TName) => void;
+}
+
+/** Form-friendly initial values straight from the manifest resource. */
+export function initialValuesFromResource(
+  resource: ResourceModel,
+): Record<string, unknown> {
+  const values: Record<string, unknown> = {};
+  for (const field of resource.fields) {
+    if (field.primaryKey) continue;
+    values[field.name] = initialFieldValue(field);
+  }
+  return values;
+}
+
+function initialFieldValue(field: FieldModel): unknown {
+  if (field.default !== undefined) return field.default;
+  if (field.type === "bool") return false;
+  return "";
+}
+
+/** The writable (non-PK) slice of a fetched record, for form seeding. */
+function writableValues(
+  resource: ResourceModel,
+  record: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  if (!record) return {};
+  const values: Record<string, unknown> = {};
+  for (const field of resource.fields) {
+    if (field.primaryKey) continue;
+    if (record[field.name] !== undefined) values[field.name] = record[field.name];
+  }
+  return values;
+}
+
+export function useEntityForm<TRow = any, TName extends string = string>(
+  entity: EntityRef<TRow>,
+  options: UseEntityFormOptions<TRow> = {},
+): EntityFormResult<TRow, TName> {
+  const contextManifest = useRastackManifest();
+  const manifest = options.manifest ?? contextManifest;
+  const resolvedEntity = useMemo(
+    () => resolveEntityRef(entity, manifest),
+    [entity, manifest],
+  );
+  const resource = resolvedEntity.resource;
+  if (!resource) {
+    throw new Error(
+      `useForm: the ${resolvedEntity.key} resource is not in the manifest — pass \`manifest\` to <RAStackProvider> (or in the hook's options)`,
+    );
+  }
+
+  const id = options.id !== undefined && options.id !== null ? String(options.id) : undefined;
+  const listQueryCacheKey = `${resolvedEntity.key}-list`;
+  const itemQueryCacheKey = `${resolvedEntity.key}-detail`;
+
+  // The persisted record (id mode) — seeds the form and anchors the state
+  // machine's "from" state.
+  const recordQuery: IGetQueryResult<any> = useGetQuery<
+    Record<string, unknown>,
+    any
+  >({
+    getUrl: resolvedEntity.detailUrl(id ?? ""),
+    queryKey: itemQueryCacheKey,
+    pathParameters: [],
+    requiredParams: [],
+    isAuthenticated: id !== undefined,
+    options: { params: {} },
+  });
+  const record = recordQuery.data as Record<string, unknown> | undefined;
+
+  // The same write schema the OpenAPI emitter publishes — derived from the
+  // manifest at runtime instead of imported from generated code.
+  const createSchema = useMemo(() => writeSchema(resource, false), [resource]);
+  const patchSchema = useMemo(() => writeSchema(resource, true), [resource]);
+
+  const createMutation = useUpdateQuery<any, any, any>({
+    postUrl: resolvedEntity.listUrl,
+    listQueryCacheKey,
+  });
+  const putMutation = useUpdateQuery<any, any, any>({
+    putUrl: (params: any) => resolvedEntity.detailUrl(params.id),
+    listQueryCacheKey,
+    itemQueryCacheKey,
+  });
+  const patchMutation = useUpdateQuery<any, any, any>({
+    patchUrl: (params: any) => resolvedEntity.detailUrl(params.id),
+    listQueryCacheKey,
+    itemQueryCacheKey,
+  });
+
+  const formValues = useMemo(
+    () => ({
+      ...initialValuesFromResource(resource),
+      ...writableValues(resource, record),
+      ...options.formValues,
+    }),
+    [resource, record, options.formValues],
+  );
+
+  const form = useSchemaForm({
+    id,
+    formValues: formValues as any,
+    updateType: options.updateType as any,
+    mutations: {
+      post: { mutation: createMutation, validation: createSchema },
+      put: { mutation: putMutation, validation: createSchema },
+      patch: { mutation: patchMutation, validation: patchSchema },
+    },
+    onSuccess: options.onSuccess as any,
+  });
+
+  // -- the state machine, as form actions ------------------------------------
+  const spec = resolvedEntity.transitions;
+  const state = spec
+    ? currentState(spec, record ?? (formValues as Record<string, unknown>))
+    : undefined;
+  const transitions: FormTransition[] = useMemo(
+    () =>
+      spec
+        ? allowedTransitions(spec, state).map((t) => ({
+            name: t.name,
+            label: humanizeName(t.name),
+            to: t.to,
+            set: t.set,
+          }))
+        : [],
+    [spec, state],
+  );
+
+  const canTransition = (name: TName): boolean =>
+    transitions.some((t) => t.name === name);
+
+  const transition = (name: TName): void => {
+    if (!spec) {
+      throw new Error(`useForm: ${resolvedEntity.key} declares no transitions`);
+    }
+    if (id === undefined) {
+      throw new Error(
+        `useForm: transitions fire on a persisted record — pass \`id\``,
+      );
+    }
+    const applied = applyTransition(spec, name, record ?? formValues);
+    if (!applied.ok) {
+      throw new Error(`useForm: ${applied.message}`);
+    }
+    // The transition *is* the save: current form values + the edge's patch,
+    // written through the normal update mutation. The engine re-checks the
+    // edge and re-applies `set` server-side — the client stages it so the
+    // optimistic UI and the persisted row agree.
+    const payload = {
+      ...(form.responseValues as Record<string, unknown>),
+      ...applied.patch,
+    };
+    const mutation = options.updateType === "put" ? putMutation : patchMutation;
+    mutation.mutate(
+      { params: { id }, payload },
+      options.onSuccess
+        ? { onSuccess: (row: any) => options.onSuccess!(row) }
+        : undefined,
+    );
+  };
+
+  return {
+    ...(form as FormStructure<Partial<TRow>, Record<string, unknown>>),
+    entity: resolvedEntity,
+    record: record as TRow | undefined,
+    isRecordLoading: id !== undefined && recordQuery.isLoading === true,
+    state,
+    transitions,
+    canTransition,
+    transition,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The public `useForm` — entity-first, legacy-props compatible
+// ---------------------------------------------------------------------------
+
+/**
+ * Pass your type to `useForm` (class, `resource()` value, or `"app.model"`),
+ * or the legacy explicit-props object (what generated form hooks call) — the
+ * argument shape picks the implementation. A call site's shape never changes
+ * between renders, so the dispatch is hook-order safe.
+ */
+// A registered "app.model" string infers its rows through the EntityTypes
+// registry (`rastack compile` emits rastack-env.d.ts) — no type argument.
+export function useForm<K extends RegisteredEntityKey>(
+  entity: K,
+  options?: UseEntityFormOptions<EntityTypes[K]>,
+): EntityFormResult<EntityTypes[K], string>;
+export function useForm<E extends EntityClass<any> | { app: string; model: string }>(
+  entity: E,
+  options?: UseEntityFormOptions<EntityRow<E>>,
+): EntityFormResult<EntityRow<E>, TransitionNamesOf<E>>;
+export function useForm<TRow = any>(
+  entity: string,
+  options?: UseEntityFormOptions<TRow>,
+): EntityFormResult<TRow, string>;
+// The legacy explicit-props signature — what the generated per-entity form
+// hooks call (with explicit type arguments), kept verbatim for compatibility.
+export function useForm<
+  TFormValues extends object,
+  TPostParams,
+  TPutParams,
+  TPatchParams,
+  TPostPayload,
+  TPutPayload,
+  TPatchPayload,
+  TPostResult,
+  TPutResult,
+  TPatchResult,
+  TFormUpdate extends FormUpdate,
+  TSourceId extends string | undefined,
+>(
+  props: FormProps<
+    TFormValues,
+    TPostParams,
+    TPutParams,
+    TPatchParams,
+    TPostPayload,
+    TPutPayload,
+    TPatchPayload,
+    TPostResult,
+    TPutResult,
+    TPatchResult,
+    TFormUpdate,
+    TSourceId
+  >,
+): FormStructure<
+  TFormValues,
+  FormValuesType<
+    TFormUpdate,
+    TSourceId,
+    TPutParams,
+    TPutPayload,
+    TPostParams,
+    TPostPayload,
+    TPatchParams,
+    TPatchPayload
+  >
+>;
+export function useForm(entityOrProps: any, options?: any): any {
+  if (isEntityRef(entityOrProps)) {
+    return useEntityForm(entityOrProps, options);
+  }
+  return useSchemaForm(entityOrProps);
+}

package/hooks/form/form.ts

@@ -11,7 +11,14 @@ import { formikJSONSchemaValidation } from "./validate-schema";
 import { getFieldMachine, getFieldStructure } from "./structure";
 import { describeMachine, runFieldMachine } from "../../src/validate";
 
-export function useForm<
+/**
+ * The schema-driven form core: Formik + AJV over an explicit `mutations`
+ * bundle (one mutation + write JSON Schema per HTTP method). The generic
+ * `useForm(Entity)` (see `./entity-form.ts`) derives that bundle from the
+ * manifest and delegates here, and the generated per-entity form hooks call
+ * it with compile-time `Deref*` schemas — one form brain either way.
+ */
+export function useSchemaForm<
   TFormValues extends object,
   TPostParams,
   TPutParams,

package/hooks/form/index.ts

@@ -1,4 +1,10 @@
-export { useForm } from "./form";
+export { useSchemaForm } from "./form";
+export { useForm, useEntityForm, initialValuesFromResource } from "./entity-form";
+export type {
+  UseEntityFormOptions,
+  EntityFormResult,
+  FormTransition,
+} from "./entity-form";
 export type {
   FormStructure,
   FormUpdateMethod,

package/hooks/index.ts

@@ -1,3 +1,7 @@
 export * from "./form";
 export * from "./query";
 export * from "./real-time";
+export * from "./entity";
+export * from "./data";
+export * from "./manifest";
+export * from "./registry";

package/hooks/manifest.ts

@@ -0,0 +1,41 @@
+/**
+ * The compiled manifest (`schema.rastack.json`) as React context — what lets
+ * `useData(Airport)` / `useForm(Flight)` resolve a plain TypeScript type to
+ * its resource at runtime with no generated code in between.
+ *
+ * `<RAStackProvider manifest={…}>` supplies it (in every mode — the manifest
+ * is required for the WASM engine anyway, and in `remote` mode it is the only
+ * piece of compiler output the client needs). Hooks read it with
+ * {@link useRastackManifest}; tests and one-off callers can bypass the context
+ * by passing `manifest` directly in a hook's options.
+ */
+
+import { createContext, createElement, useContext, useMemo } from "react";
+import type { ReactNode } from "react";
+import type { Manifest } from "../src/compile/model";
+
+export const RastackManifestContext = createContext<Manifest | undefined>(
+  undefined,
+);
+
+export interface RastackManifestProviderProps {
+  /** `schema.rastack.json` — parsed object or JSON string. */
+  manifest?: Manifest | object | string;
+  children?: ReactNode;
+}
+
+/** Provide the compiled manifest to every `useData`/`useForm` beneath it. */
+export function RastackManifestProvider(props: RastackManifestProviderProps) {
+  const { manifest, children } = props;
+  const value = useMemo<Manifest | undefined>(() => {
+    if (manifest === undefined || manifest === null) return undefined;
+    if (typeof manifest === "string") return JSON.parse(manifest) as Manifest;
+    return manifest as Manifest;
+  }, [manifest]);
+  return createElement(RastackManifestContext.Provider, { value }, children);
+}
+
+/** The compiled manifest, when a provider supplies one. */
+export function useRastackManifest(): Manifest | undefined {
+  return useContext(RastackManifestContext);
+}

package/hooks/registry.ts

@@ -0,0 +1,39 @@
+/**
+ * The type-level entity registry — what lets a bare string infer its rows:
+ *
+ * ```tsx
+ * const terminals = useData("airports.terminal");   // rows: Terminal[]
+ * ```
+ *
+ * TypeScript can't conjure an interface out of a string on its own, so the
+ * registry maps manifest keys (`"app.model"`) to your own types via ordinary
+ * declaration merging. **You don't write it by hand**: `rastack compile`
+ * emits `rastack-env.d.ts` alongside the manifest —
+ *
+ * ```ts
+ * declare module "rastack/hooks/registry" {
+ *   interface EntityTypes {
+ *     "airports.terminal": import("../resources/airports").Terminal;
+ *   }
+ * }
+ * ```
+ *
+ * — one entry per class/interface entity in the compiled graph, pointing at
+ * *your* declaration (types only, no runtime code, nothing to import). With
+ * the file in the program, `useData` / `useRecord` / `useForm` overloads
+ * resolve `"app.model"` arguments through {@link EntityTypes}; unregistered
+ * strings fall back to `any` (or an explicit `useData<ITerminal>(…)`
+ * argument, which always still works).
+ */
+
+/** `"app.model"` → row type. Populated by declaration merging — see above. */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface EntityTypes {}
+
+/** Every registered manifest key. `never` until the registry is augmented. */
+export type RegisteredEntityKey = Extract<keyof EntityTypes, string>;
+
+/** The row type behind a manifest key, else `any` for unregistered strings. */
+export type RowForKey<K extends string> = K extends keyof EntityTypes
+  ? EntityTypes[K]
+  : any;

package/package.json

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

package/provider/provider.tsx

@@ -8,6 +8,7 @@ import React, {
   useState,
 } from "react";
 import { API, configureApi, resetApi } from "../hooks/query/api";
+import { RastackManifestProvider } from "../hooks/manifest";
 import {
   RastackClient,
   RastackEngine,
@@ -227,7 +228,13 @@ export function RAStackProvider({
     [config.mode, status, config.identity],
   );
 
-  return <RastackContext.Provider value={client}>{children}</RastackContext.Provider>;
+  return (
+    <RastackContext.Provider value={client}>
+      <RastackManifestProvider manifest={config.manifest}>
+        {children}
+      </RastackManifestProvider>
+    </RastackContext.Provider>
+  );
 }
 
 function pickPersistence(

package/provider/types.ts

@@ -96,8 +96,13 @@ export interface RAStackProviderConfig {
    */
   maxOfflineMs?: number;
 
-  // -- local / s3 mode --
-  /** `schema.rastack.json` — object or JSON string. Required for WASM modes. */
+  // -- all modes --
+  /**
+   * `schema.rastack.json` — object or JSON string. Required for WASM modes
+   * (it drives the in-browser engine), and recommended in `remote` mode too:
+   * it is what lets the generic `useData(Entity)` / `useForm(Entity)` hooks
+   * resolve a plain TypeScript type to its resource at runtime.
+   */
   manifest?: object | string;
   /** `openapi.json` — object or JSON string. Optional (`/api/schema/`). */
   openapi?: object | string;

package/src/compile/analyze.ts

@@ -1,3 +1,4 @@
+import * as path from "path";
 import * as ts from "typescript";
 import {
   AccessModel,
@@ -9,6 +10,8 @@ import {
   SyncModel,
 } from "./model";
 import { resourceSourceFiles } from "./program";
+import { normalizeTransitions } from "../validate/transitions";
+import type { EntityTypeExport } from "./entities";
 
 /**
  * Statically analyse resource definitions and produce the canonical model.
@@ -23,14 +26,34 @@ export function analyze(
   program: ts.Program,
   fileNames: string[],
 ): ResourceModel[] {
+  return analyzeDsl(program, fileNames).resources;
+}
+
+/**
+ * Analyse the DSL surface, also collecting where each `resource()` const
+ * lives — `export const Flight = resource(…)` registers in the emitted
+ * `rastack-env.d.ts` as `RowOf<typeof Flight>`, so string references
+ * (`useData("airports.flight")`) infer rows for DSL resources too.
+ */
+export function analyzeDsl(
+  program: ts.Program,
+  fileNames: string[],
+): { resources: ResourceModel[]; types: EntityTypeExport[] } {
   const checker = program.getTypeChecker();
   const resources: ResourceModel[] = [];
+  const types: EntityTypeExport[] = [];
 
   for (const sourceFile of resourceSourceFiles(program, fileNames)) {
     ts.forEachChild(sourceFile, function walk(node) {
       if (isResourceCall(node)) {
         const model = analyzeResourceCall(node, checker);
-        if (model) resources.push(model);
+        if (model) {
+          resources.push(model);
+          const constExport = resourceConstExport(node);
+          if (constExport) {
+            types.push({ key: `${model.app}.${model.model}`, ...constExport });
+          }
+        }
       }
       ts.forEachChild(node, walk);
     });
@@ -40,7 +63,31 @@ export function analyze(
   resources.sort((a, b) =>
     a.app === b.app ? a.model.localeCompare(b.model) : a.app.localeCompare(b.app),
   );
-  return resources;
+  types.sort((a, b) => a.key.localeCompare(b.key));
+  return { resources, types };
+}
+
+/** The `const X = resource(…)` binding a resource call is assigned to. */
+function resourceConstExport(
+  call: ts.CallExpression,
+): Omit<EntityTypeExport, "key"> | undefined {
+  const decl = call.parent;
+  if (!ts.isVariableDeclaration(decl) || !ts.isIdentifier(decl.name)) {
+    return undefined;
+  }
+  const statement = decl.parent?.parent;
+  const exported =
+    !!statement &&
+    ts.isVariableStatement(statement) &&
+    !!ts.getModifiers(statement)?.some(
+      (m) => m.kind === ts.SyntaxKind.ExportKeyword,
+    );
+  return {
+    typeName: decl.name.text,
+    fileName: path.resolve(call.getSourceFile().fileName),
+    exported,
+    kind: "resourceConst",
+  };
 }
 
 function isResourceCall(node: ts.Node): node is ts.CallExpression {
@@ -84,7 +131,7 @@ function analyzeResourceCall(
   }
 
   const options = literalToValue(call.arguments[3]) ?? {};
-  return {
+  const resource: ResourceModel = {
     app,
     model,
     fields,
@@ -96,6 +143,28 @@ function analyzeResourceCall(
     permission: options.permission,
     access: normaliseAccess(options.access),
   };
+  applyTransitions(resource, options.transitions);
+  return resource;
+}
+
+/**
+ * Attach a normalised `transitions` block to a resource and derive what the
+ * machine implies about its state field: the `states` become the field's
+ * allowed-value set (`enum` in OpenAPI, the `member` gate in validation), and
+ * `initial` becomes its default when the field doesn't declare one.
+ */
+export function applyTransitions(resource: ResourceModel, raw: unknown): void {
+  const transitions = normalizeTransitions(raw);
+  if (!transitions) return;
+  resource.transitions = transitions;
+
+  const stateField = resource.fields.find((f) => f.name === transitions.field);
+  if (stateField && stateField.type !== "fk") {
+    stateField.options = [...transitions.states];
+    if (stateField.default === undefined && transitions.initial !== undefined) {
+      stateField.default = transitions.initial;
+    }
+  }
 }
 
 /**
@@ -171,9 +240,19 @@ function propertyName(name: ts.PropertyName): string | undefined {
  * Evaluate a *static literal* AST node (string/number/bool/null/array/object)
  * into a JS value. Anything non-literal (a function, an identifier) yields
  * `undefined` — the options and constraint blocks are always literals.
+ * Exported for the class-entity analyser, which reads `static transitions`
+ * blocks with the same evaluator.
  */
-function literalToValue(node: ts.Expression | undefined): any {
+export function literalToValue(node: ts.Expression | undefined): any {
   if (!node) return undefined;
+  // Look through `as const` / `satisfies` / parens — the value is unchanged.
+  if (
+    ts.isAsExpression(node) ||
+    ts.isSatisfiesExpression(node) ||
+    ts.isParenthesizedExpression(node)
+  ) {
+    return literalToValue(node.expression);
+  }
   if (ts.isStringLiteralLike(node)) return node.text;
   if (ts.isNumericLiteral(node)) return Number(node.text);
   if (node.kind === ts.SyntaxKind.TrueKeyword) return true;