Model Routes & Nav
Once every DB model gets its own table page, hand-wiring a router entry and a side-nav item for each new model is pure duplication — the .as file already knows the model's HTTP path, label and grouping. buildModelRoutes(models) from @atscript/ui turns a list of compiled model types into a declarative route registry: you map it to your router and nav once, and every model you add later shows up automatically.
import { buildModelRoutes } from "@atscript/ui";
import { atscriptModels } from "./models.gen"; // generated manifest
const routes = buildModelRoutes(atscriptModels);
// [
// { model: OrdersTable, path: "api/orders", label: "Orders",
// kind: "table", group: "Sales", order: 1 },
// { model: ActiveOrders, path: "active-orders", label: "Active Orders",
// kind: "view", group: "Sales", order: 2 },
// { model: AuditLogTable, path: "audit_log", label: "Audit log",
// kind: "table", hidden: true },
// ]The pipeline
.as models → manifest module → buildModelRoutes → your app
(@db.table, (atscriptModels, (TModelRoute[]) (router entries,
@db.http.path, generated by side-nav items)
@ui.nav.*) dbPlugin)- Annotate the models.
@db.table/@db.viewmake an interface a DB entity;@db.http.pathpins its HTTP mount;@ui.nav.*controls grouping, ordering and visibility in generated nav. - Generate the manifest.
dbPlugin({ manifest })inatscript.configemits a module exportingatscriptModels— every@db.table/@db.viewmodel in the project — regenerated on each atscript build, so the list never drifts from the schemas. - Build the registry.
buildModelRoutes(atscriptModels)derives a sortedTModelRoute[]— path, label, kind, group, order, hidden. - Map once. Feed the array to your router and your nav component. New model → new
.asfile → new page. No app code changes.
Step 1 — annotate the models
@db.table 'orders'
@db.http.path '/api/orders'
@meta.label 'Orders'
@ui.nav.group 'Sales'
@ui.nav.order 1
export interface OrdersTable {
@meta.id
@db.default.increment
id: number
// ... columns
}
@db.table 'audit_log'
@ui.nav.hidden // API-only — keep out of generated nav
export interface AuditLogTable {
// ...
}The three @ui.nav.* annotations are type-level (they sit on the interface, not on a prop) and describe how the declaring model appears in generated navigation:
| Annotation | Argument | Effect on the route |
|---|---|---|
@ui.nav.group 'name' | string | Sets route.group. Models sharing a value are meant to render under one nav section — grouping itself is the consumer's job. |
@ui.nav.order n | number | Sets route.order — the route's position in the sorted output (rule 6 in the contract). |
@ui.nav.hidden | — | Sets route.hidden = true — a flag for consumers, not a filter (rule 7 in the contract). |
They require uiPlugin() in atscript.config (the same plugin that registers every other @ui.* key — see Installation).
Step 2 — generate the model manifest
@atscript/db's plugin accepts a manifest option — a path where it writes a generated TypeScript module listing every DB model in the project:
// atscript.config.js
import ts from "@atscript/typescript";
import dbPlugin from "@atscript/db/plugin";
import uiPlugin from "@atscript/ui/plugin";
export default {
plugins: [ts(), dbPlugin({ manifest: "src/models.gen.ts" }), uiPlugin()],
files: ["src/**/*.as"],
};The generated file exports atscriptModels (every @db.table / @db.view model), plus dbTables, dbViews and modelsBySpace for narrower use. It's regenerated on every atscript build (npx asc, or automatically via unplugin-atscript during dev) — commit it or gitignore it like any other generated artifact.
Step 3 — build the registry
import { buildModelRoutes, type TModelRoute } from "@atscript/ui";
import { atscriptModels } from "./models.gen";
export const modelRoutes: TModelRoute[] = buildModelRoutes(atscriptModels);Each TModelRoute carries the original annotated type in model (hand it to <AsTableRoot>, createTableDef, or anything else that consumes atscript metadata) alongside the derived path, label, kind ('table' or 'view'), and the optional group / order / hidden from @ui.nav.*. Full shape in the API reference.
Step 4 — map to router and nav
A generic Vue Router mapping — written once:
// router.ts
import { createRouter, createWebHistory } from "vue-router";
import { modelRoutes } from "./model-routes";
export const router = createRouter({
history: createWebHistory(),
routes: modelRoutes
.filter((r) => !r.hidden)
.map((r) => ({
path: `/${r.path}`,
component: () => import("./pages/ModelTablePage.vue"),
props: { route: r },
})),
});The page component receives the route entry and renders the table from its model. When the model carries @db.http.path, the nav path and the moost-db HTTP mount coincide by design — one string drives both:
<!-- pages/ModelTablePage.vue -->
<script setup lang="ts">
import type { TModelRoute } from "@atscript/ui";
const props = defineProps<{ route: TModelRoute }>();
</script>
<template>
<AsTableRoot :url="`/${props.route.path}`" v-slot="{ state }">
<AsTable />
</AsTableRoot>
</template>And a side-nav that groups by @ui.nav.group:
<!-- SideNav.vue -->
<script setup lang="ts">
import type { TModelRoute } from "@atscript/ui";
import { modelRoutes } from "../model-routes";
const groups = new Map<string, TModelRoute[]>();
for (const r of modelRoutes) {
if (r.hidden) continue;
const key = r.group ?? "Other";
const list = groups.get(key);
if (list) list.push(r);
else groups.set(key, [r]);
}
</script>
<template>
<nav>
<section v-for="[group, items] in groups" :key="group">
<h3>{{ group }}</h3>
<RouterLink v-for="r in items" :key="r.path" :to="`/${r.path}`">
{{ r.label }}
</RouterLink>
</section>
</nav>
</template>The contract
buildModelRoutes is deterministic metadata derivation — these rules are the documented contract, not implementation trivia:
| # | Rule |
|---|---|
| 1 | Only DB entities are included. A model must carry @db.table, @db.view, or @db.view.for. Plain DTOs, workflow forms and other non-DB types in the input are skipped silently. |
| 2 | Path precedence: @db.http.path → string argument of @db.table / @db.view → the type's own id, as-is. First non-empty wins. The chain mirrors moost-db's controller prefix resolution, so the derived path equals the mount prefix of a token-bound @TableController(Model). |
| 3 | Paths are normalized — leading and trailing slashes stripped ('/api/orders/' → 'api/orders'), so a route is mountable under any prefix. A model whose resolved path is empty is omitted. |
| 4 | Label: @meta.label when present, else the last path segment humanized (activeOrders → Active Orders). |
| 5 | kind is 'view' for @db.view / @db.view.for models, 'table' otherwise. |
| 6 | Sorted by order ascending; routes without @ui.nav.order come last; ties and unordered routes keep input order (stable). |
| 7 | Hidden models are still returned with hidden: true. The helper only offers the list — deciding what to mount is the consumer's job, so a hidden model can still power an admin-only page or a deep link. |
DOs and DON'Ts
- DO prefer
@db.http.pathwhen the nav path must match the moost-db HTTP mount — one annotation then drives the server route, the client URL, and the nav entry. - DON'T hand-maintain a parallel route list for models — that's the duplication this helper removes. App-specific, non-model pages (dashboard, settings) stay in your regular route table.
See also
- API reference:
buildModelRoutes/TModelRoute— exact signatures. - Annotations Reference — the
@ui.nav.*entries among every other key the table stack reads. - Query Function — how the page behind each route talks to moost-db.
@db.table/@db.view/@db.http.pathsemantics: db.atscript.dev.