rastack 0.0.50 → 0.0.51

package/test/runtime-manifest.spec.ts

@@ -0,0 +1,309 @@
+/**
+ * The runtime manifest builder — `resource()` definitions are their own
+ * manifest, no `rastack compile` step required.
+ *
+ * The headline test is **parity**: the same definitions, authored once as
+ * source (compiled by the real compiler) and once as runtime values
+ * (assembled by `manifestFromResources`), must produce the identical
+ * manifest. That equivalence is what makes the compile step optional for the
+ * DSL path. Around it: the provider-input normalisation (`toManifest`),
+ * manifest-free entity resolution in the hooks, and the hand-written
+ * `EntityTypesOf` registry types.
+ */
+
+import { mkdirSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import { compile } from "../src/compile";
+import {
+  isResourceValue,
+  manifestFromResources,
+  resource,
+  resourceModel,
+  s,
+  toManifest,
+  type EntityKeyOf,
+  type EntityTypesOf,
+} from "../src/define";
+import { resolveEntityRef } from "../hooks/entity";
+import { initialValuesFromResource } from "../hooks/form/entity-form";
+import { writeSchema } from "../src/compile/openapi";
+import type { Manifest } from "../src/compile/model";
+
+// ---------------------------------------------------------------------------
+// The same definitions twice — as source for the compiler, and as runtime
+// values for manifestFromResources. Keep the two in sync: the parity test
+// exists to prove the two paths agree for identical input.
+// ---------------------------------------------------------------------------
+
+const FIXTURE_SOURCE = `
+import { resource, s } from "rastack/define";
+
+export const Airport = resource(
+  "airports",
+  "airport",
+  {
+    code: s.string({ maxLength: 3, unique: true }),
+    name: s.string({ maxLength: 120 }),
+    open: s.bool({ default: true }),
+    elevation: s.int({ null: true }),
+  },
+  {
+    search: ["code", "name"],
+    ordering: ["code"],
+    admin: { listDisplay: ["code", "name"] },
+    permission: "authenticatedOrReadOnly",
+  },
+);
+
+export const Terminal = resource("airports", "terminal", {
+  airport: s.ref(() => Airport),
+  label: s.string({ maxLength: 20 }),
+});
+
+export const Flight = resource(
+  "airports",
+  "flight",
+  {
+    number: s.string({ maxLength: 8 }),
+    status: s.string({ maxLength: 20 }),
+    owner_id: s.int(),
+  },
+  {
+    search: ["number"],
+    sync: { mode: "local", scope: "owner_id={user.id}", confirmed: ["update"] },
+    access: { ownerField: "owner_id", scope: "owner", adminGroups: ["staff"] },
+    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" },
+      },
+    },
+  },
+);
+`;
+
+const Airport = resource(
+  "airports",
+  "airport",
+  {
+    code: s.string({ maxLength: 3, unique: true }),
+    name: s.string({ maxLength: 120 }),
+    open: s.bool({ default: true }),
+    elevation: s.int({ null: true }),
+  },
+  {
+    search: ["code", "name"],
+    ordering: ["code"],
+    admin: { listDisplay: ["code", "name"] },
+    permission: "authenticatedOrReadOnly",
+  },
+);
+
+const Terminal = resource("airports", "terminal", {
+  airport: s.ref(() => Airport),
+  label: s.string({ maxLength: 20 }),
+});
+
+const Flight = resource(
+  "airports",
+  "flight",
+  {
+    number: s.string({ maxLength: 8 }),
+    status: s.string({ maxLength: 20 }),
+    owner_id: s.int(),
+  },
+  {
+    search: ["number"],
+    sync: { mode: "local", scope: "owner_id={user.id}", confirmed: ["update"] },
+    access: { ownerField: "owner_id", scope: "owner", adminGroups: ["staff"] },
+    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" },
+      },
+    },
+  },
+);
+
+/** The manifest as it would be serialised — what every consumer reads. */
+function asJson(manifest: Manifest): unknown {
+  return JSON.parse(JSON.stringify(manifest));
+}
+
+describe("manifestFromResources — parity with rastack compile", () => {
+  const workRoot = join(__dirname, "runtime-manifest-fixtures");
+  const resourcesDir = join(workRoot, "resources");
+  const outDir = join(workRoot, ".rastack");
+
+  beforeAll(() => {
+    mkdirSync(resourcesDir, { recursive: true });
+    writeFileSync(join(resourcesDir, "airline.ts"), FIXTURE_SOURCE);
+  });
+
+  afterAll(() => {
+    rmSync(workRoot, { recursive: true, force: true });
+  });
+
+  it("produces the exact manifest the compiler emits for the same definitions", () => {
+    const compiled = compile(workRoot, outDir).manifest;
+    const runtime = manifestFromResources(Airport, Terminal, Flight);
+    expect(asJson(runtime)).toEqual(asJson(compiled));
+
+    // Belt and braces: the interesting derived bits are actually present.
+    const flight = runtime.resources.find((r) => r.model === "flight")!;
+    expect(flight.transitions?.initial).toBe("scheduled");
+    const status = flight.fields.find((f) => f.name === "status")!;
+    expect(status.options).toEqual([
+      "scheduled",
+      "boarding",
+      "departed",
+      "cancelled",
+    ]);
+    expect(status.default).toBe("scheduled"); // machine initial → field default
+    const terminal = runtime.resources.find((r) => r.model === "terminal")!;
+    expect(terminal.relations).toEqual([
+      { field: "airport", target: "airports.airport", kind: "fk" },
+    ]);
+  });
+
+  it("orders resources like the compiler (app, then model)", () => {
+    const runtime = manifestFromResources(Flight, Terminal, Airport);
+    expect(runtime.resources.map((r) => r.model)).toEqual([
+      "airport",
+      "flight",
+      "terminal",
+    ]);
+  });
+
+  it("rejects an s.ref whose runtime target is missing", () => {
+    const broken = {
+      __rastack: "resource",
+      app: "airports",
+      model: "gate",
+      fields: { terminal: { __rastackRef: true } },
+      options: {},
+    } as any;
+    expect(() => resourceModel(broken)).toThrow(/target thunk/);
+  });
+});
+
+describe("toManifest — everything a provider may be handed", () => {
+  const expected = asJson(manifestFromResources(Airport, Terminal));
+
+  it("passes a compiled manifest through (object and JSON string)", () => {
+    const compiledShape = manifestFromResources(Airport, Terminal);
+    expect(toManifest(compiledShape)).toBe(compiledShape);
+    expect(asJson(toManifest(JSON.stringify(compiledShape))!)).toEqual(expected);
+  });
+
+  it("builds from an array of resource() values", () => {
+    expect(asJson(toManifest([Airport, Terminal])!)).toEqual(expected);
+  });
+
+  it("builds from a module namespace of resource() exports", () => {
+    const moduleNamespace = { Airport, Terminal, unrelated: 42, helper: () => 0 };
+    expect(asJson(toManifest(moduleNamespace)!)).toEqual(expected);
+  });
+
+  it("builds from a single resource() value and handles empties", () => {
+    const single = toManifest(Airport)!;
+    expect(single.resources.map((r) => r.model)).toEqual(["airport"]);
+    expect(toManifest(undefined)).toBeUndefined();
+    expect(toManifest(null)).toBeUndefined();
+  });
+
+  it("classifies resource() values", () => {
+    expect(isResourceValue(Airport)).toBe(true);
+    expect(isResourceValue({ app: "a", model: "b" })).toBe(false);
+    expect(isResourceValue("airports.airport")).toBe(false);
+  });
+});
+
+describe("hooks without a manifest — the definition is its own manifest", () => {
+  it("resolveEntityRef synthesises the resource from a resource() value", () => {
+    const resolved = resolveEntityRef(Flight); // no manifest anywhere
+    expect(resolved.listUrl).toBe("/api/airports/v1/flight/");
+    expect(resolved.resource).toBeDefined();
+    expect(resolved.resource!.relations).toEqual([]);
+    expect(resolved.transitions?.on.board).toEqual({
+      from: ["scheduled"],
+      to: "boarding",
+    });
+    // A supplied manifest still wins — the synthesised model is the fallback.
+    const manifest = manifestFromResources(Flight);
+    expect(resolveEntityRef(Flight, manifest).resource).toBe(
+      manifest.resources[0],
+    );
+  });
+
+  it("feeds the same write schema and form defaults the compiled path does", () => {
+    const resolved = resolveEntityRef(Flight);
+    const schema = writeSchema(resolved.resource!, false);
+    expect(schema.properties.status.enum).toEqual([
+      "scheduled",
+      "boarding",
+      "departed",
+      "cancelled",
+    ]);
+    expect(schema["x-rastack-transitions"]).toBe(resolved.resource!.transitions);
+    expect(initialValuesFromResource(resolved.resource!)).toEqual({
+      number: "",
+      status: "scheduled",
+      owner_id: "",
+    });
+  });
+
+  it("synthesises FK relations through the runtime target thunk", () => {
+    const resolved = resolveEntityRef(Terminal);
+    expect(resolved.resource!.relations).toEqual([
+      { field: "airport", target: "airports.airport", kind: "fk" },
+    ]);
+    const schema = writeSchema(resolved.resource!, false);
+    expect(schema.properties.airport["x-rastack-relation"]).toEqual({
+      app: "airports",
+      model: "airport",
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// EntityTypesOf — the hand-written registry, typed from the module itself
+// ---------------------------------------------------------------------------
+
+describe("EntityTypesOf — string-key row types with no codegen", () => {
+  it("derives keys and rows from a resources module", () => {
+    const moduleShape = { Airport, Terminal, Flight, notAResource: 42 };
+    type Registry = EntityTypesOf<typeof moduleShape>;
+
+    // The declaration-merging pattern the docs recommend must compile:
+    // an interface extending the mapped type.
+    interface Merged extends EntityTypesOf<typeof moduleShape> {}
+
+    const key: EntityKeyOf<typeof Airport> = "airports.airport";
+    const row: Registry["airports.airport"] = {
+      id: 1,
+      code: "LHR",
+      name: "Heathrow",
+      open: true,
+      elevation: null, // `null: true` → number | null
+    };
+    const merged: Merged["airports.terminal"] = {
+      id: 2,
+      airport: 1,
+      label: "T5",
+    };
+    // @ts-expect-error — `open` is a boolean
+    const wrong: Registry["airports.airport"] = { ...row, open: "yes" };
+    // @ts-expect-error — non-resource exports contribute no registry keys
+    const nope: Registry["notAResource"] = 42;
+    expect([key, row, merged, wrong, nope]).toBeDefined();
+  });
+});

package/test/typed-hooks.spec.ts

@@ -90,10 +90,15 @@ describe("resolveEntityRef — a type names its resource", () => {
       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)…
+    // Without a manifest the value is *its own* manifest: URLs resolve and
+    // the resource model is synthesised from the definition's runtime shape.
     const bare = resolveEntityRef(Flight);
     expect(bare.listUrl).toBe("/api/airports/v1/flight/");
-    expect(bare.resource).toBeUndefined();
+    expect(bare.resource).toMatchObject({
+      app: "airports",
+      model: "flight",
+      fields: [{ name: "number", type: "string", maxLength: 8 }],
+    });
   });
 
   it("carries a resource()'s transitions even without a manifest", () => {