rastack 0.0.49 → 0.0.51

package/dist/validate/adapters.js

@@ -36,6 +36,8 @@ function specFromManifestField(field) {
         spec.maxLength = field.maxLength;
     if (field.unique)
         spec.unique = true;
+    if (field.options && field.options.length > 0)
+        spec.options = field.options;
     if (field.default !== undefined)
         spec.default = field.default;
     if (field.type === "fk" && field.relation)

package/dist/validate/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./machine";
 export * from "./adapters";
+export * from "./transitions";

package/dist/validate/index.js

@@ -16,3 +16,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./machine"), exports);
 __exportStar(require("./adapters"), exports);
+__exportStar(require("./transitions"), exports);

package/dist/validate/machine.d.ts

@@ -34,7 +34,15 @@
  * single keystroke — passes through them untouched, exactly like the server,
  * where uniqueness and FK existence are checked against the table, not the
  * payload.
+ *
+ * Record machines add one **record-level** gate on top of the per-field
+ * chains: `transition`. A resource that declares a `transitions` block gets
+ * its state-field writes guarded against the declared edges (with the
+ * persisted row supplied via `ctx.previous`), so an illegal state jump fails
+ * a form, an import row, and a server write with the same message — see
+ * `./transitions.ts`.
  */
+import type { TransitionsModel } from "../compile/model";
 /** The `{ app, model }` a foreign-key field points at. */
 export interface SpecRelation {
     app: string;
@@ -107,6 +115,12 @@ export interface ValidationContext {
     seen?: Map<string, Set<string>>;
     /** Resolve whether a FK value exists on the target resource (the `resolved` gate). */
     resolveRelation?: (relation: SpecRelation, value: unknown) => boolean;
+    /**
+     * The persisted row this record updates (the record-level `transition`
+     * guard). Absent = create semantics: the state field must hold the initial
+     * state. Only consulted by record machines compiled with a transitions block.
+     */
+    previous?: Record<string, unknown>;
 }
 /** The result of running a value through a field machine. */
 export interface FieldRun {
@@ -144,11 +158,18 @@ export declare function runFieldMachine(machine: FieldMachine, rawValue: unknown
 /** A record machine is the composition of its fields' machines. */
 export interface RecordMachine {
     fields: FieldMachine[];
+    /**
+     * The resource's declarative state machine, when it declares one. Runs as a
+     * record-level gate after the per-field gates: a write that moves the state
+     * field without a declared edge fails at the `transition` gate.
+     */
+    transitions?: TransitionsModel;
 }
 /** One field's failure inside a record run. */
 export interface RecordError {
     field: string;
-    gate: FieldState;
+    /** The gate that rejected the value — a field gate, or the record-level `transition` gate. */
+    gate: FieldState | "transition";
     constraint: string;
     message: string;
 }
@@ -161,7 +182,7 @@ export interface RecordRun {
     fields: Record<string, FieldRun>;
     errors: RecordError[];
 }
-export declare function compileRecordMachine(specs: FieldSpec[]): RecordMachine;
+export declare function compileRecordMachine(specs: FieldSpec[], transitions?: TransitionsModel): RecordMachine;
 export declare function runRecordMachine(machine: RecordMachine, record: Record<string, unknown>, ctx?: ValidationContext): RecordRun;
 /**
  * Build the dataset-level context for a record machine: a seen-set per

package/dist/validate/machine.js

@@ -35,6 +35,13 @@
  * single keystroke — passes through them untouched, exactly like the server,
  * where uniqueness and FK existence are checked against the table, not the
  * payload.
+ *
+ * Record machines add one **record-level** gate on top of the per-field
+ * chains: `transition`. A resource that declares a `transitions` block gets
+ * its state-field writes guarded against the declared edges (with the
+ * persisted row supplied via `ctx.previous`), so an illegal state jump fails
+ * a form, an import row, and a server write with the same message — see
+ * `./transitions.ts`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GATE_ORDER = void 0;
@@ -44,6 +51,7 @@ exports.runFieldMachine = runFieldMachine;
 exports.compileRecordMachine = compileRecordMachine;
 exports.runRecordMachine = runRecordMachine;
 exports.createDatasetContext = createDatasetContext;
+const transitions_1 = require("./transitions");
 /** The intermediate (gate) states, in canonical machine order. */
 exports.GATE_ORDER = [
     "present",
@@ -300,8 +308,11 @@ function runFieldMachine(machine, rawValue, ctx = EMPTY_CTX) {
     path.push("valid");
     return { state: "valid", path, value };
 }
-function compileRecordMachine(specs) {
-    return { fields: specs.map(compileFieldMachine) };
+function compileRecordMachine(specs, transitions) {
+    const machine = { fields: specs.map(compileFieldMachine) };
+    if (transitions)
+        machine.transitions = transitions;
+    return machine;
 }
 function runRecordMachine(machine, record, ctx = EMPTY_CTX) {
     const fields = {};
@@ -316,6 +327,28 @@ function runRecordMachine(machine, record, ctx = EMPTY_CTX) {
             errors.push({ field: name, ...run.failed });
         }
     }
+    // The record-level `transition` gate: with the per-field gates passed, a
+    // state-field change must follow a declared edge (against `ctx.previous`;
+    // no previous row = create semantics). A field-level failure on the state
+    // field already explains itself, so the gate only runs when that field is
+    // clean — one error per cause, like every other gate.
+    const transitions = machine.transitions;
+    if (transitions && !fields[transitions.field]?.failed) {
+        // Guard against what was actually submitted: an absent state field is not
+        // a transition, but the field machine defaults it in `values`.
+        const submitted = record[transitions.field] === undefined
+            ? {}
+            : { [transitions.field]: values[transitions.field] };
+        const guard = (0, transitions_1.transitionGuard)(transitions, ctx.previous, submitted);
+        if (!guard.ok) {
+            errors.push({
+                field: transitions.field,
+                gate: "transition",
+                constraint: `transitions: ${(0, transitions_1.describeTransitions)(transitions).join("; ")}`,
+                message: guard.message,
+            });
+        }
+    }
     return {
         state: errors.length === 0 ? "valid" : "invalid",
         values,

package/dist/validate/transitions.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Declarative state transitions — the record-level layer of the constraint
+ * state machine.
+ *
+ * A resource opts in with a `transitions` block (on `resource()` options, or a
+ * `static transitions` on an entity class):
+ *
+ * ```ts
+ * transitions: {
+ *   field: "status",
+ *   states: ["scheduled", "boarding", "departed", "cancelled"],
+ *   initial: "scheduled",
+ *   on: {
+ *     board:  { from: "scheduled", to: "boarding" },
+ *     depart: { from: "boarding",  to: "departed" },
+ *     cancel: { from: ["scheduled", "boarding"], to: "cancelled",
+ *               set: { gate: null } },
+ *   },
+ * }
+ * ```
+ *
+ * The block compiles into the manifest verbatim (with `from` normalised to a
+ * list), and this module is the *shared executable form* of it: the same pure
+ * functions guard a form submit (`useForm(...).transition("board")`), the
+ * record machine (`runRecordMachine` with a `previous` row in context), and —
+ * re-implemented 1:1 in `rastack-api-core` — every server/WASM write. A write
+ * that jumps between states without a declared edge is rejected on every
+ * surface, which is what makes a transition "a backend function that is
+ * state-machine safe": the only way to move a record between states is a
+ * named edge, and the edge's `set` patches are applied by the engine.
+ */
+import type { TransitionEdgeModel, TransitionsModel } from "../compile/model";
+export type { TransitionEdgeModel, TransitionsModel } from "../compile/model";
+/** A transition available from a given state, ready for a UI action list. */
+export interface AvailableTransition {
+    name: string;
+    to: string;
+    set?: Record<string, unknown>;
+}
+/** The outcome of a transition guard or application. */
+export type TransitionResult = {
+    ok: true;
+    patch: Record<string, unknown>;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Normalise a raw (authored) transitions block into the canonical model shape:
+ * `from` becomes a string list, non-string states are dropped, and anything
+ * structurally broken yields `undefined` (the compiler then reports it).
+ */
+export declare function normalizeTransitions(raw: unknown): TransitionsModel | undefined;
+/**
+ * Sanity-check a transitions block against its resource's fields. Returns
+ * human-readable problems (empty = valid); the compiler surfaces each as an
+ * error diagnostic, mirroring the circular-dependency check.
+ */
+export declare function transitionProblems(transitions: TransitionsModel, fields: Array<{
+    name: string;
+}>): string[];
+/** The state a record is in — its state-field value, else the initial state. */
+export declare function currentState(transitions: TransitionsModel, record: Record<string, unknown> | undefined): string | undefined;
+/** Every transition that may fire from `state` — the form's action list. */
+export declare function allowedTransitions(transitions: TransitionsModel, state: unknown): AvailableTransition[];
+/** The declared edge covering `from → to`, if any. */
+export declare function findTransition(transitions: TransitionsModel, from: string, to: string): {
+    name: string;
+    edge: TransitionEdgeModel;
+} | undefined;
+/**
+ * Guard one write. `previous` is the persisted row (`undefined` = create).
+ * A create must start at the initial state; an update that changes the state
+ * field must follow a declared edge. Anything else passes untouched — the
+ * guard constrains only the state field.
+ */
+export declare function transitionGuard(transitions: TransitionsModel, previous: Record<string, unknown> | undefined, next: Record<string, unknown>): TransitionResult;
+/**
+ * Fire a *named* transition from a record's current state: validates the edge
+ * is available and returns the full patch to write — the state change plus the
+ * edge's `set` effects. This is the client half of the backend function; the
+ * server re-derives the same patch from the same manifest.
+ */
+export declare function applyTransition(transitions: TransitionsModel, name: string, record: Record<string, unknown> | undefined): TransitionResult;
+/** Human-readable edge list — `"board: scheduled → boarding"` — for UI hints. */
+export declare function describeTransitions(transitions: TransitionsModel): string[];

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