Skip to content

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.

ts
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 ​

text
.as models          →  manifest module   →  buildModelRoutes  →  your app
(@db.table,            (atscriptModels,      (TModelRoute[])      (router entries,
 @db.http.path,         generated by                               side-nav items)
 @ui.nav.*)             dbPlugin)
  1. Annotate the models. @db.table / @db.view make an interface a DB entity; @db.http.path pins its HTTP mount; @ui.nav.* controls grouping, ordering and visibility in generated nav.
  2. Generate the manifest. dbPlugin({ manifest }) in atscript.config emits a module exporting atscriptModels — every @db.table / @db.view model in the project — regenerated on each atscript build, so the list never drifts from the schemas.
  3. Build the registry. buildModelRoutes(atscriptModels) derives a sorted TModelRoute[] — path, label, kind, group, order, hidden.
  4. Map once. Feed the array to your router and your nav component. New model → new .as file → new page. No app code changes.

Step 1 — annotate the models ​

atscript
@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:

AnnotationArgumentEffect on the route
@ui.nav.group 'name'stringSets route.group. Models sharing a value are meant to render under one nav section — grouping itself is the consumer's job.
@ui.nav.order nnumberSets 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:

js
// 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 ​

ts
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:

ts
// 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:

vue
<!-- 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:

vue
<!-- 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
1Only 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.
2Path 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).
3Paths 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.
4Label: @meta.label when present, else the last path segment humanized (activeOrders → Active Orders).
5kind is 'view' for @db.view / @db.view.for models, 'table' otherwise.
6Sorted by order ascending; routes without @ui.nav.order come last; ties and unordered routes keep input order (stable).
7Hidden 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.path when 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 ​

Released under the MIT License.