Skip to content
GitHub

Strutvane 0.2 is still being built. These pages describe how it will work; anything marked "Coming in 0.2" doesn't exist yet. Release notes and support policy.

Controllers

View as Markdownllms.txt

A controller is a class whose methods (called actions) answer requests. Instead of writing every route’s code inside routes/api.ts, you point the route at a controller action, and keep related actions together: everything about posts in PostController.

Controllers live in app/http/controllers/, one per file, named post.controller.ts.

Terminal window
node strut make:controller ReportController

What you’ll see:

Created app/http/controllers/report.controller.ts

The new file:

app/http/controllers/report.controller.ts
import { Controller, type HttpContext } from '@strutvane/framework'
/** TODO: say what this controller is for. */
export class ReportController extends Controller {
// Add actions, then route them in routes/api.ts or routes/web.ts, for example:
// Route.get('/reports', [ReportController, 'index']).name('reports.index')
index(ctx: HttpContext): Response {
return ctx.json({ data: [] })
}
}

Route it:

routes/api.ts
Route.get('/reports', [ReportController, 'index']).name('reports.index'),

GET /api/reports answers { "data": [] }.

An action takes ctx (the request context) and returns a Response, or a Promise of one:

app/http/controllers/profile.controller.ts
import { Controller, type HttpContext } from '@strutvane/framework'
import { Post } from '../../models/post.ts'
export class ProfileController extends Controller {
/** GET /api/me */
show(ctx: HttpContext): Response {
return ctx.json({ data: ctx.requireUser() })
}
/** GET /api/me/posts?status=draft */
async posts(ctx: HttpContext): Promise<Response> {
const user = ctx.requireUser()
const status = ctx.query.get('status') ?? 'published'
const posts = await Post.query().where('author_id', user.id).where('status', status).get()
return ctx.json({ data: posts })
}
}

Why write the return type (: Response, : Promise<Response>)? Your routes file reads the controller’s types, and your controller may call route(), which reads the routes file. Writing the return type stops TypeScript from going round in that circle. Generated controllers always include it.

A new controller object is made for every request, so it’s safe to keep per-request values on this; they never leak to another user.

A controller that needs a service lists it in static inject; the container passes it to the constructor:

app/http/controllers/stats.controller.ts
import { ConnectionToken, Controller, type Connection, type HttpContext } from '@strutvane/framework'
/** Admin statistics. */
export class StatsController extends Controller {
static readonly inject = [ConnectionToken] as const
readonly #db: Connection
constructor(db: Connection) {
super()
this.#db = db
}
/** GET /api/admin/stats */
async show(ctx: HttpContext): Promise<Response> {
const [posts] = await this.#db.select('SELECT COUNT(*) AS "total" FROM "posts" WHERE "deleted_at" IS NULL')
const [authors] = await this.#db.select('SELECT COUNT(*) AS "total" FROM "authors"')
return ctx.json({ data: { posts: Number(posts?.['total'] ?? 0), authors: Number(authors?.['total'] ?? 0) } })
}
}

What you’ll see:

{ "data": { "posts": 5, "authors": 3 } }

If the inject list doesn’t match the constructor, it doesn’t compile. See Service Container.

ResourceController: a whole API in a few lines

Section titled “ResourceController: a whole API in a few lines”

For a model that needs the standard API, extend ResourceController and set two things: the model and the policy (who may do what; see Authorization).

app/http/controllers/author.controller.ts
import { ResourceController } from '@strutvane/framework'
import { Author } from '../../models/author.ts'
import { AuthorPolicy } from '../../policies/author.policy.ts'
/** Author profiles. */
export class AuthorController extends ResourceController<typeof Author> {
protected readonly model = Author
protected readonly policy = new AuthorPolicy()
}
routes/api.ts
Route.apiResource('authors', AuthorController),

That’s the whole controller. You get:

Request Action What it does Checks the policy’s
GET /api/authors index One page, with ?page, ?perPage, ?search, ?sort, ?filter[…] viewAny
GET /api/authors/{author} show The bound record view
POST /api/authors store Validate, check unique columns, create; 201 + Location create
PATCH /api/authors/{author} update Validate (every field optional), check uniques, save view, then update
DELETE /api/authors/{author} destroy Delete (soft delete when the table has deleted_at); 204 view, then delete

What you’ll see for GET /api/authors?search=ada&sort=-created_at:

{
"data": [{ "id": 1, "name": "Ada Admin", "email": "ada@example.test", "bio": null, "created_at": "2026-11-14T10:00:00.000Z" }],
"meta": { "page": 1, "perPage": 25, "total": 1, "lastPage": 1, "from": 1, "to": 1 }
}

Hidden columns (like api_token) are never returned.

Your own validation: storeRequest and updateRequest

Section titled “Your own validation: storeRequest and updateRequest”

By default, validation rules come from your migrations (required columns, lengths, enums) and the model’s fillable list. Point at your own form requests to take over:

app/http/controllers/post.controller.ts
export class PostController extends ResourceController<typeof Post> {
protected readonly model = Post
protected readonly policy = new PostPolicy()
protected override readonly storeRequest = new StorePostRequest()
protected override readonly updateRequest = new UpdatePostRequest()
}

Hook: indexConstraints(): which rows a user may list

Section titled “Hook: indexConstraints(): which rows a user may list”

index checks viewAny, but “may list posts” doesn’t mean “may see every post”. Narrow the list per user:

protected override indexConstraints(ctx: HttpContext): Constraint[] {
if (ctx.user?.is_admin === true) return []
const visible: Constraint[] = [{ column: 'status', equals: 'published' }]
if (ctx.user !== null) visible.push({ column: 'author_id', equals: ctx.user.id })
return [{ anyOf: visible }]
}

A constraint is { column, equals }, or { anyOf: [...] } for “any of these”. Constraints are combined with AND; anyOf means OR inside it.

What you’ll see: a guest gets only published posts; Alice also sees her own drafts; an admin sees everything. The meta.total matches what each person can see.

Hook: prepareForStore(): set values the client must not send

Section titled “Hook: prepareForStore(): set values the client must not send”

Some values come from the server, never from the request body, like who wrote a post:

protected override prepareForStore(values: Record<string, unknown>, ctx: HttpContext): Record<string, unknown> {
return { ...values, author_id: ctx.requireUser().id }
}

What you’ll see for POST /api/posts {"title":"Crème brûlée tips"} as Alice (id 3):

HTTP/1.1 201 Created
location: /api/posts/creme-brulee-tips
{"data":{"id":6,"title":"Crème brûlée tips","slug":"creme-brulee-tips","status":"draft","author_id":3, …}}

Sending author_id in the body is refused with 422 ("author_id" is not a field you can send here.), because it isn’t a field the request accepts.

Hook: prepareForUpdate(): adjust values before saving

Section titled “Hook: prepareForUpdate(): adjust values before saving”
protected override prepareForUpdate(values: Record<string, unknown>, post: Post, ctx: HttpContext): Record<string, unknown> {
return values['status'] === 'published' && post.status !== 'published' ? { ...values, published_at: now() } : values
}

visible(): “can’t see it” looks the same as “doesn’t exist”

Section titled “visible(): “can’t see it” looks the same as “doesn’t exist””

show, update and destroy start with this.visible(ctx): the bound record, if the policy’s view allows it. Otherwise it answers 404, exactly like a missing record.

Why not 403? A 403 on PATCH /api/posts/alice-draft would tell Bob that a draft with that slug exists. With visible(), hidden records can’t be discovered by guessing URLs. If Bob can see a post but may not change it, he still gets an honest 403.

Add your own actions next to the inherited ones. Use visible() and authorize() the same way:

app/http/controllers/post.controller.ts
import { authorize, now, ResourceController, route, type Constraint, type HttpContext } from '@strutvane/framework'
import { Post } from '../../models/post.ts'
import { PostPolicy } from '../../policies/post.policy.ts'
import { StorePostRequest, UpdatePostRequest } from '../requests/post.request.ts'
export class PostController extends ResourceController<typeof Post> {
protected readonly model = Post
protected readonly policy = new PostPolicy()
protected override readonly storeRequest = new StorePostRequest()
protected override readonly updateRequest = new UpdatePostRequest()
protected override prepareForStore(values: Record<string, unknown>, ctx: HttpContext): Record<string, unknown> {
return { ...values, author_id: ctx.requireUser().id }
}
/** POST /api/posts/{post:slug}/publish */
async publish(ctx: HttpContext): Promise<Response> {
const post = await this.visible(ctx) // 404 if they can't see it
await authorize(this.policy, 'update', ctx.user, post, 'post') // 403 if they can't change it
post.fill({ status: 'published' })
await post.save()
return ctx.json({ data: post, links: { self: route('posts.show', { post }) } })
}
}
routes/api.ts
Route.apiResource('posts', PostController, { bindBy: 'slug' })
.middlewareFor(['index', 'show'], 'auth:optional')
.middlewareFor(['store', 'update', 'destroy'], 'auth'),
Route.post('/posts/{post:slug}/publish', [PostController, 'publish']).name('posts.publish').middleware('auth'),

A controller can declare its own protections in static readonly middleware, Laravel’s $this->middleware('auth')->only(...):

app/http/controllers/comment.controller.ts
import { auth, Controller, throttle, type HttpContext } from '@strutvane/framework'
export class CommentController extends Controller {
static readonly middleware = [
auth({ except: ['index'] }), // reading is public
throttle({ params: ['20', '1'], only: ['store'] }), // 20 comments a minute
]
index(ctx: HttpContext): Response { return ctx.json({ data: [] }) }
store(ctx: HttpContext): Response { return ctx.json({ data: {} }, 201) }
}

What you’ll see in node strut route:list --security: auth on store but not on index, and throttle:20,1 on store. Every style (route, group, controller, wrapper) is explained in Middleware.

You want Use Write
A few custom endpoints a plain Controller make:controller ReportController
The standard 5 API actions for a model, with every safety check ResourceController make:controller PostController --model=Post
The standard actions, but every line in your file an owned resource controller make:controller PostController --api (or --resource for 7)
Nothing at all the generated API from node strut migrate —

The generated API already covers most tables; write a controller only when you need different behaviour. To take over one model’s API, write the controller, route it with Route.apiResource() in routes/api.ts, and opt that model out of the generated routes.

Coming in 0.2: single-action, singleton and nested controllers

Section titled “Coming in 0.2: single-action, singleton and nested controllers”
  • Single-action (invokable) controllers. Laravel’s __invoke controllers: a class with one action, routed without a method name. Until it lands, route [ExportController, 'handle'], or a closure.

    Route.post('/exports', [ExportController, 'handle']).name('exports.store'), // works today
  • Singleton resource controllers for things that exist once (a profile, a team’s settings): show, edit and update only, routed with Route.singleton('profile', ProfileController).

  • Nested, shallow resources: Route.apiResource('posts.comments', CommentController, { shallow: true }) gives CommentController the parent post on index and store, and short URLs for the rest.

See Routing for the URLs each one produces.

Call the app with a request and check the answer; no server is needed:

tests/feature/reports.test.ts
import { randomBytes } from 'node:crypto'
import { expect, test } from 'vitest'
import { client } from '@strutvane/framework/testing'
import { createApp } from '../../bootstrap/app.ts'
test('reports list is empty at first', async () => {
const app = createApp({ APP_ENV: 'testing', APP_KEY: `base64:${randomBytes(32).toString('base64')}`, DB_CONNECTION: 'sqlite' })
const response = await client(app).getJson('/api/reports')
response.assertStatus(200)
expect(response.json).toEqual({ data: [] })
})

What you’ll see with npm test: the test passes. See HTTP Tests.

Command Writes
node strut make:controller ReportController An empty controller with one index action
node strut make:controller PostController --model=Post (or -m Post) A ResourceController for Post (all five actions inherited) and a deny-all post.policy.ts
node strut make:controller PostController --api An owned controller with the 5 API actions written out, each calling authorize(), plus the policy
node strut make:controller PostController --resource (or -r) The 7 actions, including the create and edit form-page actions, plus the policy
add --force Overwrite an existing controller file

What you’ll see for --resource:

Terminal window
node strut make:controller CommentController --resource
Created app/http/controllers/comment.controller.ts
Created app/policies/comment.policy.ts (denies everyone but admins until you edit it)
Note: app/models/comment.ts doesn't exist yet. Create it with: node strut make:migration create_comments_table
Next: route it in routes/web.ts:
Route.resource('comments', CommentController)
and bind the model in bootstrap/app.ts: withRouting({ bindings: { comment: Comment } })

The generated policy denies everyone except admins, so a new endpoint is never open by accident. A generated controller compiles under strict TypeScript straight away and answers 403 for every action until you edit the policy.

“… serves resource routes but has no policy”

Section titled ““… serves resource routes but has no policy””
✖ PostController serves resource routes but has no policy.
→ Give it a `protected readonly policy = new PostPolicy()` and call authorize() in every action (node strut make:controller --resource writes this for you).

Why: a resource route without a policy would let anyone do anything.

Fix: add protected readonly policy = new PostPolicy().

✖ PostController@publsh doesn't exist (route /api/posts/{post:slug}/publish).
→ Add a publsh(ctx: HttpContext) method to PostController.

Fix: correct the method name in the route, or add the method.

“… would serve the internal … table over the API”

Section titled ““… would serve the internal … table over the API””
✖ UserController would serve the internal "users" table over the API.
→ Framework and identity tables (sessions, tokens, roles, jobs, users…) are never auto resources. Write a purpose-built controller with explicit fields instead.

Fix: extend Controller instead and return only the fields you mean to expose.

“–resource and –api can’t be used together”

Section titled ““–resource and –api can’t be used together””
✖ --resource and --api can't be used together.
→ Use --resource for 7 actions (with form pages) or --api for 5.

“… already exists, so nothing was written”

Section titled ““… already exists, so nothing was written””
✖ app/http/controllers/post.controller.ts already exists, so nothing was written.
→ Pick another name, or add --force to overwrite it (your changes in that file would be lost).
✖ "posts" is not a controller class name.
→ Use PascalCase ending in "Controller", for example: node strut make:controller PostsController
PostController@show returned nothing instead of a Response.
→ Return ctx.json(...), ctx.html(...) or ctx.noContent().

Fix: return ctx.json(...).

  • Validation: form requests for storeRequest and updateRequest.
  • Authorization: the policies every resource controller needs.
  • Responses: everything an action can return.