rastack 0.0.49 → 0.0.51

package/hooks/entity.ts

@@ -0,0 +1,228 @@
+/**
+ * Entity references — how `useData(...)` / `useForm(...)` know which resource
+ * a plain TypeScript type is, with **no generated hooks in between**.
+ *
+ * A hook accepts any of:
+ *
+ * - **the entity class itself** — `useData(Airport)`. Classes are values, so
+ *   the class *is* the reference; its name resolves against the manifest with
+ *   the same normalisation the compiler applies (`IFlight` → `flight`).
+ * - **a `resource()` definition** — `useData(Flight)`. The DSL value carries
+ *   `app`/`model` (and its literal-typed options, so transition names are
+ *   typed) at runtime.
+ * - **an `"app.model"` (or bare `"model"`) string** — the escape hatch for
+ *   interface entities, which have no runtime value:
+ *   `useData<Terminal>("airports.terminal")`.
+ * - **any `{ app, model }` object** — e.g. a sync `EntityDescriptor`.
+ *
+ * Resolution is a pure function over the compiled manifest
+ * (`schema.rastack.json`), which `<RAStackProvider manifest={…}>` supplies via
+ * context — the type system names the entity, the manifest carries its
+ * schema, and the codegen'd per-entity hook layer disappears.
+ */
+
+import type {
+  Manifest,
+  ResourceModel,
+  TransitionsModel,
+} from "../src/compile/model";
+import type { ResourceType, RowOf } from "../src/define";
+import { isResourceValue, resourceModel } from "../src/define/manifest";
+import type { EntityTypes } from "./registry";
+import { normalizeTransitions } from "../src/validate/transitions";
+
+/** A class used as an entity reference (`useData(Airport)`). */
+export type EntityClass<TRow = any> = new (...args: any[]) => TRow;
+
+/** A `resource()` definition used as an entity reference (`useData(Flight)`). */
+export type EntityResource = ResourceType<string, string, any, any>;
+
+/** Anything that can name an entity. */
+export type EntityRef<TRow = any> =
+  | string
+  | EntityClass<TRow>
+  | { app: string; model: string };
+
+/**
+ * The row type an entity reference implies — every reference form infers:
+ * classes carry it (`InstanceType`), `resource()` values derive it from their
+ * fields ({@link RowOf}), and `"app.model"` strings resolve through the
+ * {@link EntityTypes} registry — populated by a one-line hand-written
+ * `EntityTypesOf<…>` declaration, or by the `rastack-env.d.ts` that
+ * `rastack compile` emits. No path involves generated runtime code.
+ */
+export type EntityRow<E> =
+  E extends EntityClass<infer R>
+    ? R
+    : E extends EntityResource
+      ? RowOf<E>
+      : E extends keyof EntityTypes
+        ? EntityTypes[E]
+        : any;
+
+/** A reference resolved against the manifest — everything a hook needs. */
+export interface ResolvedEntity {
+  app: string;
+  model: string;
+  /** `"app.model"` — cache keys, sync store keys. */
+  key: string;
+  /** `/api/{app}/v1/{model}/` — the URL convention is unchanged. */
+  listUrl: string;
+  detailUrl: (id: string | number) => string;
+  /** The manifest resource (present whenever a manifest was available). */
+  resource?: ResourceModel;
+  /** The resource's state machine, when it declares one. */
+  transitions?: TransitionsModel;
+}
+
+/**
+ * The manifest model name a TypeScript type name maps to — the *same*
+ * normalisation the compiler applies (`entityNaming` in `compile/entities.ts`):
+ * a leading `I` prefix is stripped (`IFlight` → `Flight`) and the first letter
+ * lower-cased.
+ */
+export function entityModelName(typeName: string): string {
+  const stripped = /^I[A-Z]/.test(typeName) ? typeName.slice(1) : typeName;
+  return stripped.charAt(0).toLowerCase() + stripped.slice(1);
+}
+
+function resolved(
+  app: string,
+  model: string,
+  resource?: ResourceModel,
+  fallbackTransitions?: unknown,
+): ResolvedEntity {
+  const listUrl = `/api/${app}/v1/${model}/`;
+  return {
+    app,
+    model,
+    key: `${app}.${model}`,
+    listUrl,
+    detailUrl: (id) => `${listUrl}${id}/`,
+    resource,
+    transitions:
+      resource?.transitions ?? normalizeTransitions(fallbackTransitions),
+  };
+}
+
+function findByModel(manifest: Manifest, model: string): ResourceModel[] {
+  return manifest.resources.filter((r) => r.model === model);
+}
+
+/**
+ * Resolve an entity reference against the manifest. Throws a descriptive
+ * error on an unknown or ambiguous reference — resolution failures are
+ * authoring mistakes and should fail loudly, not degrade into 404s.
+ */
+export function resolveEntityRef(
+  ref: EntityRef,
+  manifest?: Manifest,
+): ResolvedEntity {
+  // `{ app, model }` — a `resource()` value, an EntityDescriptor, or a plain
+  // object. The manifest enriches it (fields, transitions) when available;
+  // a `resource()` value that a manifest doesn't cover is **its own
+  // manifest** — the definition carries its fields/options at runtime, so no
+  // compile step (and no provider config) is needed for the DSL path.
+  if (typeof ref === "object" && ref !== null) {
+    const { app, model } = ref as { app?: unknown; model?: unknown };
+    if (typeof app !== "string" || typeof model !== "string") {
+      throw new Error(
+        "useData/useForm: an object entity reference needs string `app` and `model` properties",
+      );
+    }
+    const resource =
+      manifest?.resources.find((r) => r.app === app && r.model === model) ??
+      (isResourceValue(ref) ? resourceModel(ref) : undefined);
+    const opts = (ref as { options?: { transitions?: unknown } }).options;
+    return resolved(app, model, resource, opts?.transitions);
+  }
+
+  // A class — the flagship form. Its name resolves like the compiler resolves
+  // it, and a `static transitions` block rides along as a manifest fallback.
+  if (typeof ref === "function") {
+    const name = ref.name;
+    if (!name) {
+      throw new Error("useData/useForm: anonymous classes cannot name an entity");
+    }
+    if (!manifest) {
+      throw new Error(
+        `useData/useForm: resolving the ${name} class needs the compiled manifest — pass \`manifest\` to <RAStackProvider> (or in the hook's options)`,
+      );
+    }
+    const model = entityModelName(name);
+    const matches = findByModel(manifest, model);
+    if (matches.length === 1) {
+      return resolved(
+        matches[0].app,
+        matches[0].model,
+        matches[0],
+        (ref as { transitions?: unknown }).transitions,
+      );
+    }
+    if (matches.length === 0) {
+      throw new Error(
+        `useData/useForm: no resource named "${model}" in the manifest — is ${name} part of the compiled resource graph (\`rastack compile\`)?`,
+      );
+    }
+    throw new Error(
+      `useData/useForm: "${model}" exists in ${matches.length} apps (${matches
+        .map((m) => `${m.app}.${m.model}`)
+        .join(", ")}) — pass the explicit "app.model" string instead`,
+    );
+  }
+
+  // A string — `"app.model"`, or a bare `"model"` resolved via the manifest.
+  if (typeof ref === "string" && ref) {
+    const dot = ref.indexOf(".");
+    if (dot > 0) {
+      const app = ref.slice(0, dot);
+      const model = ref.slice(dot + 1);
+      const resource = manifest?.resources.find(
+        (r) => r.app === app && r.model === model,
+      );
+      if (manifest && !resource) {
+        throw new Error(
+          `useData/useForm: no resource "${ref}" in the manifest`,
+        );
+      }
+      return resolved(app, model, resource);
+    }
+    if (!manifest) {
+      throw new Error(
+        `useData/useForm: resolving "${ref}" needs the compiled manifest — pass \`manifest\` to <RAStackProvider>, or use the full "app.model" form`,
+      );
+    }
+    const matches = findByModel(manifest, ref);
+    if (matches.length === 1) {
+      return resolved(matches[0].app, matches[0].model, matches[0]);
+    }
+    throw new Error(
+      matches.length === 0
+        ? `useData/useForm: no resource named "${ref}" in the manifest`
+        : `useData/useForm: "${ref}" exists in ${matches.length} apps — use the "app.model" form`,
+    );
+  }
+
+  throw new Error("useData/useForm: unsupported entity reference");
+}
+
+/** Whether a value is an entity reference (vs. legacy `useForm(props)`). */
+export function isEntityRef(value: unknown): value is EntityRef {
+  if (typeof value === "string" || typeof value === "function") return true;
+  return (
+    !!value &&
+    typeof value === "object" &&
+    typeof (value as { app?: unknown }).app === "string" &&
+    typeof (value as { model?: unknown }).model === "string"
+  );
+}
+
+/** `snake_or_camel` → `Snake or camel` — column/action labels. */
+export function humanizeName(key: string): string {
+  const spaced = key
+    .replace(/_/g, " ")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .toLowerCase()
+    .trim();
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}

package/hooks/form/entity-form.ts

@@ -0,0 +1,358 @@
+/**
+ * `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, ResourceModel } from "../../src/compile/model";
+import { toManifest, type ManifestInput } from "../../src/define/manifest";
+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>`.
+   * Accepts a compiled manifest or `resource()` definitions (array/module).
+   */
+  manifest?: ManifestInput;
+}
+
+/** 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 optionManifest = useMemo(
+    () => toManifest(options.manifest),
+    [options.manifest],
+  );
+  const manifest = optionManifest ?? 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";