ORM Studio

Intent View

A live view in Axil Studio of whether the running app keeps the contracts its decorators declare - intent mode, violations, SLOs, circuit breakers and enforced decorators - set up with intentEndpoint().

6 min readUpdated DocumentationEdit this page
On this page8

The Intent view shows, live, whether the running app keeps the contracts declared by its decorators. It reads the report that @axiljs/runtime publishes and refreshes every 2 seconds while the view is open.

Note

New in 0.3.5. Open it from the sidebar (Tools group), the command palette, or with g i.

What it shows

  • Header: the intent mode as a badge (enforce, warn or off), where the report came from (in-process or from app), when it was last updated, and a Refresh button.
  • Summary cards: the number of violations with the time and decorator of the last one, how many SLOs are meeting their objective, how many circuits are tracked and how many are open or half-open, and how many decorators are enforced. A card is highlighted when something needs attention.
  • Violations: newest first, with time, decorator, target, detail, request ID and tenant ID. The newest 200 are shown; the runtime keeps up to 500.
  • Service level objectives: one row per tSlo method with the percentile, observed and target latency, error rate and error budget, the number of samples, and the status (meeting, or breaching with latency, errors or both). A method appears after its first call.
  • Circuit breakers: every tCircuitBreaker method with its state (closed, open, half-open). A method appears after its first call.
  • Enforced decorators: every registered interceptor with its order, outermost first.

Polling pauses while the browser tab is hidden and resumes when it becomes visible again. If a refresh fails after data has been shown, the last data stays on screen with a "Live updates paused" notice.

Setup

Under axil run your app runs in a child process, so Studio cannot read the runtime's state directly. The app has to serve its report on a development-only endpoint:

TypeScript
TS
1import '@axiljs/runtime'
2import { wire } from '@axiljs/runtime'
3import { intentEndpoint } from '@axiljs/studio'
4
5wire(OrderService)          // executes the t* decorators on its methods
6app.use(intentEndpoint())   // serves GET /__axil/studio/intent to Studio

Until the endpoint is reachable, the view shows "Intent reporting is not enabled" with the reason and this snippet, ready to copy.

intentEndpoint(options?)

OptionDefaultDescription
path/__axil/studio/intentPath to answer on. Studio's intentPath setting must match
enabledNODE_ENV !== 'production'Serve the report; when disabled the handler does nothing

The endpoint is safe to leave in the code:

  • It answers only GET and HEAD on its path.
  • It answers only requests from a loopback address (127.x.x.x, ::1).
  • It is a no-op when NODE_ENV is production, unless you pass enabled: true.
  • Every other request goes to next().

It works as AxilJS middleware (app.use(intentEndpoint())) and as a plain node:http handler, where it returns true when it answered the request.

Keeping Studio a dev dependency

@axiljs/studio is usually a devDependency, so a production install with npm ci --omit=dev does not have it. The endpoint lives in a module with no imports, @axiljs/studio/dist/intent, which can be loaded on its own behind a development check. The saas-api and high-scale-api templates (0.3.6) do it this way in src/dev/studio-intent.ts:

TypeScript
TS
1import { createRequire } from 'node:module'
2import type { MiddlewareFn } from '@axiljs/core'
3
4export function studioIntentEndpoint(): MiddlewareFn | undefined {
5  if (process.env.NODE_ENV !== 'production') {
6    try {
7      const require = createRequire(import.meta.url)
8      const studio  = require('@axiljs/studio/dist/intent') as { intentEndpoint(): MiddlewareFn }
9      return studio.intentEndpoint()
10    } catch {
11      // Studio is not installed (dev dependencies omitted): nothing to serve
12    }
13  }
14  return undefined
15}
TypeScript
TS
const intent = studioIntentEndpoint()
if (intent) app.use(intent)

Data flow

runtimeReport() in @axiljs/runtime
globalThis[Symbol.for('axiljs.runtime.report')] in your app
intentEndpoint() at GET /__axil/studio/intent
Studio GET /api/studio/intent
Intent view
Your app runs as a child of axil run and Studio listens on the app port + 1. intentEndpoint() answers on loopback in development only; the Intent view polls every 2 s.
  1. @axiljs/runtime publishes runtimeReport() on globalThis[Symbol.for('axiljs.runtime.report')]. Studio never imports the runtime.
  2. The browser polls GET /api/studio/intent on the Studio server.
  3. If the runtime is loaded in Studio's own process (Studio started programmatically inside the app), Studio reads the report directly and no endpoint is needed.
  4. Otherwise Studio requests http://localhost:<appPort> plus intentPath from the app, with a 1.5 second timeout.

GET /api/studio/intent

Returns the report with available: true:

JSON
JSON
1{
2  "available": true,
3  "source": "app",
4  "mode": "enforce",
5  "enforced": [{ "decorator": "tDeprecated", "order": 50 }, { "decorator": "tSlo", "order": 60 }],
6  "violations": [
7    {
8      "decorator": "tTenantIsolated",
9      "target": "Invoices.list",
10      "detail": "returned data of tenant 'globex' to tenant 'acme'",
11      "requestId": "8f9b6c1e-4c1d-4c8e-9a51-2a7d3f0b6e11",
12      "tenantId": "acme",
13      "timestamp": "2026-11-17T10:15:00.000Z"
14    }
15  ],
16  "slo": [],
17  "circuits": { "Pricing.price": "CLOSED" },
18  "generatedAt": "2026-11-17T10:15:02.000Z"
19}

or { "available": false, "reason": "..." }. The reason tells you what to fix:

ReasonCause
The app does not serve /__axil/studio/intent. Add app.use(intentEndpoint()) from @axiljs/studio in development.The app answered 404
Could not reach the app at http://localhost:3000. Is it running?The app is not running or not on the expected port
The app at http://localhost:3000 did not answer /__axil/studio/intent within 1.5 sThe request timed out
@axiljs/runtime is not loaded in this process. ...The endpoint answered, but the app never imported @axiljs/runtime
The app answered /__axil/studio/intent with HTTP 403 (or another status)Something in front of the endpoint refused the request

Warning

If middleware registered before intentEndpoint() answers or rejects the request (for example authentication applied to every route), Studio receives that response instead of the report. Register the endpoint before such middleware.

Configuration

When Studio is started programmatically, the intentPath option sets the path it requests from the app (default /__axil/studio/intent). It must match intentEndpoint({ path }). See Configuration.

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY