rastack 0.0.48 → 0.0.50

package/test/typed-hooks.spec.ts

@@ -0,0 +1,407 @@
+/**
+ * The pure cores behind `useData(Entity)` / `useForm(Entity)`: resolving a
+ * plain TypeScript type to its manifest resource, deriving the write schema
+ * (and its form field structures) from the manifest at runtime, and the
+ * type-level transition names. The React shells around these are thin; the
+ * decisions all live here.
+ */
+
+import { mkdirSync, readFileSync, rmSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import {
+  entityModelName,
+  humanizeName,
+  isEntityRef,
+  resolveEntityRef,
+} from "../hooks/entity";
+import { useData } from "../hooks/data";
+import type { RowForKey } from "../hooks/registry";
+import { compile } from "../src/compile";
+import { initialValuesFromResource } from "../hooks/form/entity-form";
+import { getFieldMachine, getFieldStructure } from "../hooks/form/structure";
+import { writeSchema } from "../src/compile/openapi";
+import type { Manifest, ResourceModel } from "../src/compile/model";
+import { resource, s, type TransitionNamesOf } from "../src/define";
+import { runFieldMachine } from "../src/validate";
+
+const airport: ResourceModel = {
+  app: "airports",
+  model: "airport",
+  fields: [
+    { name: "code", type: "string", maxLength: 3, unique: true },
+    { name: "name", type: "string", maxLength: 120 },
+  ],
+  relations: [],
+  admin: { listDisplay: ["code", "name"] },
+};
+
+const flight: ResourceModel = {
+  app: "airports",
+  model: "flight",
+  fields: [
+    { name: "number", type: "string", maxLength: 8 },
+    {
+      name: "status",
+      type: "string",
+      options: ["scheduled", "boarding", "departed"],
+      default: "scheduled",
+    },
+    { name: "active", type: "bool" },
+    { name: "airport", type: "fk", relation: { app: "airports", model: "airport" } },
+  ],
+  relations: [{ field: "airport", target: "airports.airport", kind: "fk" }],
+  transitions: {
+    field: "status",
+    states: ["scheduled", "boarding", "departed"],
+    initial: "scheduled",
+    on: {
+      board: { from: ["scheduled"], to: "boarding" },
+      depart: { from: ["boarding"], to: "departed" },
+    },
+  },
+};
+
+const manifest: Manifest = { version: 1, resources: [airport, flight] };
+
+describe("resolveEntityRef — a type names its resource", () => {
+  it("resolves a class by its (compiler-normalised) name", () => {
+    class Airport {
+      code!: string;
+    }
+    const resolved = resolveEntityRef(Airport, manifest);
+    expect(resolved).toMatchObject({
+      app: "airports",
+      model: "airport",
+      key: "airports.airport",
+      listUrl: "/api/airports/v1/airport/",
+    });
+    expect(resolved.detailUrl(7)).toBe("/api/airports/v1/airport/7/");
+    expect(resolved.resource).toBe(airport);
+  });
+
+  it("strips the generated `I` prefix, like the compiler does", () => {
+    expect(entityModelName("IFlight")).toBe("flight");
+    expect(entityModelName("Flight")).toBe("flight");
+    expect(entityModelName("Item")).toBe("item"); // `It` is not an I-prefix… but `Item` is I+tem
+  });
+
+  it("resolves a `resource()` value directly — manifest optional", () => {
+    const Flight = resource("airports", "flight", {
+      number: s.string({ maxLength: 8 }),
+    });
+    expect(resolveEntityRef(Flight, manifest).resource).toBe(flight);
+    // Without a manifest the URLs still resolve (the DSL value carries app/model)…
+    const bare = resolveEntityRef(Flight);
+    expect(bare.listUrl).toBe("/api/airports/v1/flight/");
+    expect(bare.resource).toBeUndefined();
+  });
+
+  it("carries a resource()'s transitions even without a manifest", () => {
+    const Flight = resource(
+      "airports",
+      "flight",
+      { status: s.string({ maxLength: 20 }) },
+      {
+        transitions: {
+          field: "status",
+          states: ["scheduled", "boarding"],
+          on: { board: { from: "scheduled", to: "boarding" } },
+        },
+      },
+    );
+    const resolved = resolveEntityRef(Flight);
+    expect(resolved.transitions).toMatchObject({
+      on: { board: { from: ["scheduled"], to: "boarding" } },
+    });
+  });
+
+  it('resolves "app.model" and bare "model" strings', () => {
+    expect(resolveEntityRef("airports.flight", manifest).resource).toBe(flight);
+    expect(resolveEntityRef("flight", manifest).model).toBe("flight");
+    expect(() => resolveEntityRef("airports.spaceship", manifest)).toThrow(
+      /no resource "airports.spaceship"/,
+    );
+  });
+
+  it("fails loudly on ambiguity and missing manifests", () => {
+    const two: Manifest = {
+      version: 1,
+      resources: [flight, { ...flight, app: "cargo" }],
+    };
+    expect(() => resolveEntityRef("flight", two)).toThrow(/"app.model"/);
+    class Flight {
+      number!: string;
+    }
+    expect(() => resolveEntityRef(Flight, two)).toThrow(/airports\.flight, cargo\.flight/);
+    expect(() => resolveEntityRef(Flight)).toThrow(/manifest/);
+  });
+
+  it("classifies entity refs vs. legacy form props", () => {
+    expect(isEntityRef("airports.flight")).toBe(true);
+    expect(isEntityRef(class A {})).toBe(true);
+    expect(isEntityRef({ app: "a", model: "b" })).toBe(true);
+    expect(isEntityRef({ formValues: {}, mutations: {} })).toBe(false);
+  });
+});
+
+describe("useForm(Entity) — the manifest-derived form core", () => {
+  it("derives form-friendly initial values from the resource", () => {
+    expect(initialValuesFromResource(flight)).toEqual({
+      number: "",
+      status: "scheduled", // the machine's initial state, via the field default
+      active: false,
+      airport: "",
+    });
+  });
+
+  it("derives the same write schema the OpenAPI contract publishes", () => {
+    const schema = writeSchema(flight, false);
+    expect(schema.properties.status.enum).toEqual([
+      "scheduled",
+      "boarding",
+      "departed",
+    ]);
+    expect(schema.properties.airport["x-rastack-relation"]).toEqual({
+      app: "airports",
+      model: "airport",
+    });
+    expect(schema["x-rastack-transitions"]).toBe(flight.transitions);
+  });
+
+  it("renders the state field as a select and runs its member gate", () => {
+    const schema = writeSchema(flight, false);
+
+    const structure = getFieldStructure(schema, "status");
+    expect(structure.type).toBe("select");
+    expect(structure.options).toEqual([
+      { label: "scheduled", value: "scheduled" },
+      { label: "boarding", value: "boarding" },
+      { label: "departed", value: "departed" },
+    ]);
+
+    const machine = getFieldMachine(schema, "status")!;
+    expect(machine.states).toContain("member");
+    expect(runFieldMachine(machine, "boarding").state).toBe("valid");
+    expect(runFieldMachine(machine, "teleported").state).toBe("invalid");
+  });
+
+  it("humanises transition names into button labels", () => {
+    expect(humanizeName("board")).toBe("Board");
+    expect(humanizeName("close_out")).toBe("Close out");
+    expect(humanizeName("markShipped")).toBe("Mark shipped");
+  });
+});
+
+describe("TransitionNamesOf — transition names are literal types", () => {
+  it("reads names from a resource()'s options and a class's static block", () => {
+    const Flight = resource(
+      "airports",
+      "flight",
+      { status: s.string({ maxLength: 20 }) },
+      {
+        transitions: {
+          field: "status",
+          states: ["scheduled", "boarding", "departed"],
+          initial: "scheduled",
+          on: {
+            board: { from: "scheduled", to: "boarding" },
+            depart: { from: "boarding", to: "departed" },
+          },
+        },
+      },
+    );
+    type FlightNames = TransitionNamesOf<typeof Flight>;
+    const boardName: FlightNames = "board";
+    const departName: FlightNames = "depart";
+    // @ts-expect-error — "explode" is not a declared transition
+    const bad: FlightNames = "explode";
+    expect([boardName, departName, bad]).toBeDefined();
+
+    class Order {
+      status = "draft";
+      static transitions = {
+        field: "status",
+        states: ["draft", "placed"],
+        initial: "draft",
+        on: { place: { from: "draft", to: "placed" } },
+      };
+    }
+    type OrderNames = TransitionNamesOf<typeof Order>;
+    const placeName: OrderNames = "place";
+    expect(placeName).toBe("place");
+
+    class Plain {
+      name!: string;
+    }
+    type None = TransitionNamesOf<typeof Plain>; // resolves to never
+    const nothing: None[] = [];
+    expect(nothing).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Row inference — no type argument needed
+// ---------------------------------------------------------------------------
+
+// What `rastack compile` emits as rastack-env.d.ts (declaration merging into
+// the registry) — hand-rolled here so the inference is exercised in-test.
+declare module "../hooks/registry" {
+  interface EntityTypes {
+    "airports.terminal": { id: number; label: string; airport: number };
+  }
+}
+
+describe("row inference — the type argument is not needed", () => {
+  it("a registered \"app.model\" string resolves its row type", () => {
+    type TerminalRow = RowForKey<"airports.terminal">;
+    const row: TerminalRow = { id: 1, label: "T1", airport: 2 };
+    // @ts-expect-error — `label` is required on the registered row type
+    const missing: TerminalRow = { id: 1, airport: 2 };
+    expect([row, missing]).toBeDefined();
+  });
+
+  it("a resource() value derives its row type from its fields", () => {
+    const Flight = resource("airports", "flight", {
+      number: s.string({ maxLength: 8 }),
+      seats: s.int(),
+      gate: s.string({ maxLength: 5, null: true }),
+      active: s.bool(),
+    });
+    type FlightRow = import("../src/define").RowOf<typeof Flight>;
+    const row: FlightRow = {
+      id: 1,
+      number: "BA1",
+      seats: 180,
+      gate: null, // `null: true` → `string | null`
+      active: true,
+    };
+    // @ts-expect-error — `seats` is a number
+    const wrong: FlightRow = { ...row, seats: "lots" };
+    // @ts-expect-error — `number` is not nullable
+    const wrongNull: FlightRow = { ...row, number: null };
+    expect([row, wrong, wrongNull]).toBeDefined();
+  });
+
+  // Type-level only — never executed (useData is a React hook).
+  function _typeOnly() {
+    const terminals = useData("airports.terminal");
+    const rows: Array<{ id: number; label: string; airport: number }> | undefined =
+      terminals.data;
+    // @ts-expect-error — rows are Terminal-shaped, not Airport-shaped
+    const wrong: Array<{ code: string }> | undefined = terminals.data;
+    return { rows, wrong };
+  }
+
+  it("keeps the explicit generic and unregistered strings working", () => {
+    expect(typeof _typeOnly).toBe("function");
+    function _fallbacks() {
+      interface IGate {
+        id: number;
+        number: string;
+      }
+      const explicit = useData<IGate>("airports.gate"); // unregistered → explicit
+      const gates: IGate[] | undefined = explicit.data;
+      const loose = useData("airports.gate"); // unregistered, no generic → any
+      const anything: undefined | Array<{ whatever: boolean }> = loose.data;
+      return { gates, anything };
+    }
+    expect(typeof _fallbacks).toBe("function");
+  });
+});
+
+describe("rastack compile — the emitted rastack-env.d.ts registry", () => {
+  const workRoot = join(__dirname, "registry-fixtures");
+  const resourcesDir = join(workRoot, "resources");
+  const outDir = join(workRoot, ".rastack");
+
+  beforeAll(() => {
+    mkdirSync(resourcesDir, { recursive: true });
+    writeFileSync(
+      join(resourcesDir, "entities.ts"),
+      `
+export class Airport {
+  code!: string;
+  name!: string;
+}
+
+// Not exported — cannot be imported by the registry, so it is skipped.
+class Secret {
+  token!: string;
+}
+export const _root = [Airport, Secret];
+
+export interface Terminal {
+  id: number;
+  label: string;
+}
+`,
+    );
+    writeFileSync(
+      join(resourcesDir, "flights.ts"),
+      `
+import { resource, s } from "rastack/define";
+
+export const Flight = resource("airports", "flight", {
+  number: s.string({ maxLength: 8 }),
+});
+`,
+    );
+    // The dotted string argument roots the Terminal interface — no type
+    // argument, no JSDoc tag.
+    writeFileSync(
+      join(workRoot, "screen.tsx"),
+      `
+export function Screen() {
+  const terminals = useData("entities.terminal");
+  return terminals;
+}
+declare function useData(key: string): unknown;
+`,
+    );
+  });
+
+  afterAll(() => {
+    rmSync(workRoot, { recursive: true, force: true });
+  });
+
+  it("roots interfaces from dotted string hook arguments and registers every exported entity", () => {
+    const result = compile(workRoot, outDir);
+
+    // The string argument rooted the interface into the manifest…
+    expect(
+      result.manifest.resources.some(
+        (r) => r.app === "entities" && r.model === "terminal",
+      ),
+    ).toBe(true);
+
+    // …and the registry maps keys to the caller's own types.
+    const envPath = join(outDir, "rastack-env.d.ts");
+    expect(result.files).toContain(envPath);
+    const dts = readFileSync(envPath, "utf8");
+    expect(dts).toContain('declare module "rastack/hooks/registry"');
+    expect(dts).toContain(
+      '"entities.airport": import("../resources/entities").Airport;',
+    );
+    expect(dts).toContain(
+      '"entities.terminal": import("../resources/entities").Terminal;',
+    );
+    // DSL consts register through RowOf so string refs infer for them too.
+    expect(dts).toContain(
+      '"airports.flight": import("rastack/define").RowOf<typeof import("../resources/flights").Flight>;',
+    );
+    // Unexported declarations are skipped.
+    expect(dts).not.toContain("Secret");
+  });
+
+  it("emits no registry when nothing is exported", () => {
+    const emptyDir = join(workRoot, "empty");
+    mkdirSync(join(emptyDir, "src"), { recursive: true });
+    writeFileSync(
+      join(emptyDir, "src", "none.ts"),
+      `export const nothing = 1;\n`,
+    );
+    const out = join(emptyDir, "out");
+    compile(emptyDir, out);
+    expect(existsSync(join(out, "rastack-env.d.ts"))).toBe(false);
+  });
+});

package/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;
         },