rastack 0.0.48 → 0.0.50

package/dist/validate/transitions.js

@@ -0,0 +1,199 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeTransitions = normalizeTransitions;
+exports.transitionProblems = transitionProblems;
+exports.currentState = currentState;
+exports.allowedTransitions = allowedTransitions;
+exports.findTransition = findTransition;
+exports.transitionGuard = transitionGuard;
+exports.applyTransition = applyTransition;
+exports.describeTransitions = describeTransitions;
+/**
+ * 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).
+ */
+function normalizeTransitions(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const block = raw;
+    if (typeof block.field !== "string" || !block.field)
+        return undefined;
+    if (!Array.isArray(block.states))
+        return undefined;
+    const states = block.states.filter((s) => typeof s === "string");
+    if (!states.length)
+        return undefined;
+    if (!block.on || typeof block.on !== "object")
+        return undefined;
+    const on = {};
+    for (const [name, rawEdge] of Object.entries(block.on)) {
+        if (!rawEdge || typeof rawEdge !== "object")
+            continue;
+        const edge = rawEdge;
+        const from = (Array.isArray(edge.from) ? edge.from : [edge.from]).filter((s) => typeof s === "string");
+        if (!from.length || typeof edge.to !== "string")
+            continue;
+        const model = { from, to: edge.to };
+        if (edge.set && typeof edge.set === "object" && !Array.isArray(edge.set)) {
+            model.set = edge.set;
+        }
+        on[name] = model;
+    }
+    const model = { 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.
+ */
+function transitionProblems(transitions, fields) {
+    const problems = [];
+    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. */
+function currentState(transitions, record) {
+    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. */
+function allowedTransitions(transitions, state) {
+    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. */
+function findTransition(transitions, from, to) {
+    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.
+ */
+function transitionGuard(transitions, previous, next) {
+    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.
+ */
+function applyTransition(transitions, name, record) {
+    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. */
+function describeTransitions(transitions) {
+    return Object.entries(transitions.on).map(([name, edge]) => `${name}: ${edge.from.join(" | ")} → ${edge.to}`);
+}

package/dist/wasm/rastack_wasm.js

@@ -375,7 +375,7 @@ function __wbg_get_imports() {
             return ret;
         },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 80, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 85, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm_bindgen_1a7aa9db5392c486___convert__closures_____invoke___wasm_bindgen_1a7aa9db5392c486___JsValue__core_7d5f0a2ba6a62c33___result__Result_____wasm_bindgen_1a7aa9db5392c486___JsError___true_);
             return ret;
         },

package/hooks/data.ts

@@ -0,0 +1,209 @@
+/**
+ * `useData` — pass your type in, get the data layer out.
+ *
+ * ```tsx
+ * const airports = useData(Airport);                 // a class
+ * const flights  = useData(Flight);                  // a resource() value
+ * const gates    = useData<ITerminal>("airports.terminal"); // an interface
+ *
+ * <DataTable query={airports} />
+ * airports.create.mutate({ params: {}, payload: { code: "LHR", name: "Heathrow" } });
+ * ```
+ *
+ * One generic hook replaces the generated `useList{Model}` /
+ * `usePost{Model}Create` / `useDelete{Model}` families: the entity reference
+ * resolves against the compiled manifest (see `./entity.ts`), the URLs follow
+ * the unchanged `/api/{app}/v1/{model}/` convention, and the result is the
+ * same `IListQuery` shape `<DataTable>` feature-detects — search, sorting and
+ * pagination included — plus typed `create` / `update` / `remove` mutations.
+ *
+ * `<RAStackProvider mode=…>` still decides where the API physically runs
+ * (HTTP, in-browser WASM, S3) by reconfiguring the shared axios client, so
+ * `useData` is transport-agnostic exactly like the generated hooks were.
+ * (Resources replicated with `sync: { mode: "local" }` keep their store-backed
+ * descriptor hooks — `useEntityList` et al. in `rastack/sync`; a store-backed
+ * `useData` dispatch is deferred, documented in `docs/typed-hooks.md`.)
+ */
+
+import { useMemo } from "react";
+import { useGetPaginatedQueryList } from "./query/list";
+import { useGetQuery } from "./query/fetch";
+import { useUpdateQuery } from "./query/update";
+import { useDeleteQuery } from "./query/delete";
+import type {
+  IDeleteQueryResult,
+  IGetQueryResult,
+  IListQuery,
+  IUpdateQueryResult,
+  ListQueryOptions,
+  ReturnedHeader,
+} from "./query/interfaces";
+import {
+  EntityClass,
+  EntityRef,
+  EntityResource,
+  EntityRow,
+  humanizeName,
+  ResolvedEntity,
+  resolveEntityRef,
+} from "./entity";
+import { useRastackManifest } from "./manifest";
+import type { EntityTypes, RegisteredEntityKey } from "./registry";
+import type { Manifest, ResourceModel } from "../src/compile/model";
+
+export interface UseDataOptions<TRow>
+  extends ListQueryOptions<Record<string, unknown>, TRow> {
+  /** Gate the query (replaces the generated hooks' auth wiring). Default on. */
+  enabled?: boolean;
+  /** Manifest override — tests, or callers outside `<RAStackProvider>`. */
+  manifest?: Manifest;
+}
+
+/**
+ * What `useData` returns: a DataTable-ready list query + typed mutations.
+ * `remove` is the DELETE mutation — it intentionally replaces react-query's
+ * cache-eviction `remove()` on the result (evicting the list cache by hand is
+ * not part of this surface; deleting records is).
+ */
+export interface UseDataResult<TRow>
+  extends Omit<IListQuery<Record<string, unknown>, TRow>, "remove"> {
+  /** The resolved entity — urls, manifest resource, transitions. */
+  entity: ResolvedEntity;
+  /** POST to the collection. `mutate({ params: {}, payload })`. */
+  create: IUpdateQueryResult<Record<string, unknown>, Partial<TRow>, TRow>;
+  /** PATCH one record. `mutate({ params: { id }, payload })`. */
+  update: IUpdateQueryResult<
+    { id: string | number } & Record<string, unknown>,
+    Partial<TRow>,
+    TRow
+  >;
+  /** DELETE one record. `mutate({ id })`. */
+  remove: IDeleteQueryResult<TRow>;
+}
+
+/** Column headers derived from the manifest (`admin.listDisplay`), if any. */
+function manifestHeader(
+  resource: ResourceModel | undefined,
+): ReturnedHeader[] | undefined {
+  const admin = resource?.admin;
+  const listDisplay =
+    admin && Array.isArray(admin.listDisplay) ? admin.listDisplay : undefined;
+  return listDisplay?.map((key) => ({ key, name: humanizeName(key) }));
+}
+
+// Rows are inferred from the reference itself — no type argument needed:
+// a registered "app.model" string resolves through the EntityTypes registry
+// (`rastack compile` emits rastack-env.d.ts), a class carries its own row
+// type, and a resource() value derives one from its fields. The trailing
+// generic overload keeps explicit `useData<ITerminal>("…")` (and
+// unregistered strings) working.
+export function useData<K extends RegisteredEntityKey>(
+  entity: K,
+  options?: UseDataOptions<EntityTypes[K]>,
+): UseDataResult<EntityTypes[K]>;
+export function useData<E extends EntityClass<any> | EntityResource>(
+  entity: E,
+  options?: UseDataOptions<EntityRow<E>>,
+): UseDataResult<EntityRow<E>>;
+export function useData<TRow = any>(
+  entity: EntityRef<TRow>,
+  options?: UseDataOptions<TRow>,
+): UseDataResult<TRow>;
+export function useData(
+  entity: EntityRef,
+  options?: UseDataOptions<any>,
+): UseDataResult<any> {
+  const contextManifest = useRastackManifest();
+  const manifest = options?.manifest ?? contextManifest;
+  const resolvedEntity = useMemo(
+    () => resolveEntityRef(entity, manifest),
+    [entity, manifest],
+  );
+  const listQueryCacheKey = `${resolvedEntity.key}-list`;
+  const itemQueryCacheKey = `${resolvedEntity.key}-detail`;
+
+  const query = useGetPaginatedQueryList<Record<string, unknown>, any>({
+    getUrl: resolvedEntity.listUrl,
+    queryKey: listQueryCacheKey,
+    pathParameters: [],
+    isAuthenticated: options?.enabled ?? true,
+    options: {
+      // `?search=` is the server convention for resources with `search`
+      // fields; harmless (ignored) otherwise.
+      searchKey: "search",
+      ...options,
+    },
+  });
+
+  const create = useUpdateQuery<Record<string, unknown>, any, any>({
+    postUrl: resolvedEntity.listUrl,
+    listQueryCacheKey,
+  });
+  const update = useUpdateQuery<
+    { id: string | number } & Record<string, unknown>,
+    any,
+    any
+  >({
+    patchUrl: (params) => resolvedEntity.detailUrl(params.id),
+    listQueryCacheKey,
+    itemQueryCacheKey,
+  });
+  const remove = useDeleteQuery<any>({
+    deleteUrl: (id) => resolvedEntity.detailUrl(id),
+    listQueryCacheKey,
+  });
+
+  return {
+    ...query,
+    header: query.header ?? manifestHeader(resolvedEntity.resource),
+    entity: resolvedEntity,
+    create,
+    update,
+    remove,
+  };
+}
+
+export interface UseRecordOptions {
+  enabled?: boolean;
+  manifest?: Manifest;
+}
+
+/** One record by id — the generic twin of the generated detail hooks. */
+export function useRecord<K extends RegisteredEntityKey>(
+  entity: K,
+  id: string | number | undefined,
+  options?: UseRecordOptions,
+): IGetQueryResult<EntityTypes[K]> & { entity: ResolvedEntity };
+export function useRecord<E extends EntityClass<any> | EntityResource>(
+  entity: E,
+  id: string | number | undefined,
+  options?: UseRecordOptions,
+): IGetQueryResult<EntityRow<E>> & { entity: ResolvedEntity };
+export function useRecord<TRow = any>(
+  entity: EntityRef<TRow>,
+  id: string | number | undefined,
+  options?: UseRecordOptions,
+): IGetQueryResult<TRow> & { entity: ResolvedEntity };
+export function useRecord(
+  entity: EntityRef,
+  id: string | number | undefined,
+  options?: UseRecordOptions,
+): IGetQueryResult<any> & { entity: ResolvedEntity } {
+  const contextManifest = useRastackManifest();
+  const manifest = options?.manifest ?? contextManifest;
+  const resolvedEntity = useMemo(
+    () => resolveEntityRef(entity, manifest),
+    [entity, manifest],
+  );
+
+  const query = useGetQuery<Record<string, unknown>, any>({
+    getUrl: resolvedEntity.detailUrl(id ?? ""),
+    queryKey: `${resolvedEntity.key}-detail`,
+    pathParameters: [],
+    requiredParams: [],
+    isAuthenticated: (options?.enabled ?? true) && id !== undefined && id !== null,
+    options: { params: {} },
+  });
+
+  return Object.assign(query, { entity: resolvedEntity });
+}

package/hooks/entity.ts

@@ -0,0 +1,222 @@
+/**
+ * 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 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 `rastack compile` emits (`rastack-env.d.ts`).
+ */
+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.
+  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,
+    );
+    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);
+}