@orieljs/framework 0.1.0-alpha.6 → 0.1.0-alpha.8

package/docs/routing.md

@@ -0,0 +1,738 @@
+# Routing
+
+Routes map a URL and an HTTP method to a closure or a controller action. Once `route:types` has run, TypeScript
+checks every link to a named route.
+
+## Basic routing
+
+A basic route takes a URI and a closure:
+
+```ts title="routes/web.ts"
+import { Route } from '@orieljs/framework'
+
+Route.get('/greeting', () => 'Hello World')
+```
+
+A string, a number or a boolean is sent as HTML, `null` and `undefined` as an empty 204 response, and an object, an
+array or a model as JSON. Return a view, a redirect or a `Response` for anything else: [Responses](responses.md) has
+the list.
+
+### The default route files
+
+Your routes live in the `routes` folder, and `bootstrap/app.ts` names the files to load. `routes/web.ts` is for your
+pages: its routes are in the `web` [middleware group](middleware.md#middleware-groups), which gives them cookies, the
+session and [CSRF protection](csrf.md). The kits with pages split their routes over three files, loaded in this order:
+
+```ts
+Application.configure({ basePath: '.' }).withRouting({
+  web: ['routes/web.ts', 'routes/settings.ts', 'routes/auth.ts'],
+  console: 'routes/console.ts',
+  health: '/up',
+})
+```
+
+> [!WARNING]
+> List every route file in `withRouting()` rather than importing one from another. Each listed file is loaded again
+> for every application your tests create; a file imported from another is loaded once per process, so its routes
+> would be missing from the second application.
+
+A route file usually calls the `Route` facade at its top level. It may also export a default function, which is
+called with the router.
+
+#### API routes
+
+If your application also offers a stateless API, `install:api` adds one:
+
+```sh
+node oriel install:api
+```
+
+It writes `routes/api.ts` and adds it to `withRouting()` in `bootstrap/app.ts`:
+
+```ts title="routes/api.ts"
+import { request, Route } from '@orieljs/framework'
+
+Route.get('/user', () => request().user()).middleware('auth:token')
+```
+
+The routes in `routes/api.ts` are in the `api` middleware group, which has no session, no cookie encryption and no CSRF
+check, and their URIs start with `/api`. `auth:token` signs the user in from a personal access token, whose table is in
+a new app's migrations ([API tokens](authentication.md#api-tokens) covers them). The API starter kit has its own
+`routes/api.ts`, with its token routes.
+
+### Available router methods
+
+There is a method for each HTTP verb:
+
+```ts
+declare const handler: () => string
+// ---cut---
+Route.get('/posts', handler)
+Route.post('/posts', handler)
+Route.put('/posts/{id}', handler)
+Route.patch('/posts/{id}', handler)
+Route.delete('/posts/{id}', handler)
+Route.options('/posts', handler)
+```
+
+`match()` takes several verbs, and `any()` answers them all:
+
+```ts
+declare const handler: () => string
+// ---cut---
+Route.match(['get', 'post'], '/search', handler)
+Route.any('/webhook', handler)
+```
+
+A `GET` route answers `HEAD` too, with the same status and headers and no body. A request whose method the URI
+doesn't accept gets a 405 with an `Allow` header listing the methods it does, and an `OPTIONS` request to a URI with
+no `OPTIONS` route gets a 200 with that header.
+
+> [!NOTE]
+> Laravel tries routes in the order you define them, so `/posts/create` has to come before `/posts/{post}`. Oriel
+> tries the most specific route first, so the order of your routes doesn't decide which one answers: segment by
+> segment, fixed text before a parameter, and a parameter before an optional one. Routes of the same shape keep the
+> order you defined them in, and fallback routes always come last.
+
+#### Dependency injection
+
+A route's closure receives its route parameters and nothing else. The current request comes from the `request()`
+helper, which works anywhere in your code while a request is handled:
+
+```ts
+Route.get('/users', () => {
+  const page = request().integer('page', 1)
+
+  return User.query().forPage(page).get()
+})
+```
+
+> [!NOTE]
+> Laravel injects the request, and any class you type-hint, into a route's closure. TypeScript types are gone when
+> your app runs, so Oriel can't see them: it passes only the route parameters. Take the request from `request()`,
+> and a service from `inject()` or its [facade](facades.md). [Requests](requests.md) covers the request, and
+> [Injecting with `inject()`](container.md#injecting-with-inject) the services.
+
+#### CSRF protection
+
+An HTML form that posts to a route in the `web` group must send the CSRF token, or the request is refused with a
+419. `csrfField()` writes the hidden field:
+
+```tsx title="resources/views/profile.tsx"
+import { csrfField } from '@orieljs/framework'
+
+export default function Profile() {
+  return (
+    <form method="post" action="/profile">
+      {csrfField()}
+      <button type="submit">Save</button>
+    </form>
+  )
+}
+```
+
+[CSRF protection](csrf.md) explains the token and the other ways to send it.
+
+### Redirect routes
+
+A route that only redirects needs no closure. `Route.redirect()` answers every verb with a 302, or the status you
+give it, and `Route.permanentRedirect()` with a 301:
+
+```ts
+Route.redirect('/here', '/there')
+Route.redirect('/here', '/there', 301)
+Route.permanentRedirect('/old-blog', '/blog')
+```
+
+The target may use the route's parameters: `Route.redirect('/posts/{id}', '/articles/{id}')`.
+
+### View routes
+
+`Route.view()` shows a view, with the data you give it and the route's parameters:
+
+```ts
+Route.view('/welcome', 'welcome')
+Route.view('/welcome', 'welcome', { name: 'Taylor' })
+```
+
+`Route.inertia()` does the same for an Inertia page, with its props:
+
+```ts
+Route.inertia('/settings/appearance', 'Settings/Appearance')
+```
+
+### Resource routes
+
+`Route.resource()` registers the seven routes of a resource controller in one line, and `Route.apiResource()` the
+five an API needs, without the pages for its forms:
+
+```ts
+declare class PhotoController {}
+// ---cut---
+Route.resource('photos', PhotoController)
+Route.apiResource('photos', PhotoController)
+```
+
+[Controllers](controllers.md#resource-controllers) lists their URIs, names and options.
+
+### Listing your routes
+
+`route:list` shows every route with its methods, URI, name and action, sorted by URI:
+
+```sh
+node oriel route:list
+```
+
+Filter it by method, by part of the name or by part of the URI, or leave out the URIs that contain a text:
+
+```sh
+node oriel route:list --method=post
+node oriel route:list --name=posts
+node oriel route:list --path=admin --except-path=admin/reports
+```
+
+`--reverse` reverses the order, and `--json` prints the routes as JSON, with each route's middleware.
+
+### Routing customization
+
+`withRouting()` in `bootstrap/app.ts` loads your routes once every service provider has booted, so a pattern or a
+binding you set in a [provider's](providers.md) `boot()` is in place when your route files run:
+
+```ts title="bootstrap/app.ts"
+import { dirname } from 'node:path'
+import { Application } from '@orieljs/framework'
+import providers from './providers'
+
+export function createApplication(): Promise<Application> {
+  return Application.configure({ basePath: dirname(import.meta.dirname) })
+    .withRouting({ web: 'routes/web.ts', console: 'routes/console.ts', health: '/up' })
+    .withProviders(providers)
+    .create()
+}
+```
+
+`web` and `api` take one file or a list, `console` names the file of your closure commands, and `health` the URI of
+the health check page, which answers 200 when your app is up. `apiPrefix` changes the API routes' prefix from `api`:
+
+```ts
+Application.configure({ basePath: '.' }).withRouting({ api: 'routes/api.ts', apiPrefix: 'api/admin' })
+```
+
+## Route parameters
+
+### Required parameters
+
+Capture a segment of the URI with braces:
+
+```ts
+Route.get('/user/{id}', (id: string) => `User ${id}`)
+```
+
+A route may have as many parameters as it needs. The action receives them in the order they appear in the URI, so
+the names in your function don't have to match:
+
+```ts
+Route.get('/teams/{team}/members/{member}', (teamId: string, memberId: string) => {
+  return { teamId, memberId }
+})
+```
+
+A parameter's name is letters, digits and underscores. A parameter named after one of your models receives the model
+rather than the text (see [Route model binding](#route-model-binding)), so `{team}` stays a string only while your
+app has no `Team` model.
+
+#### Parameters and dependency injection
+
+Nothing but the route's parameters is passed to the action, whatever else it needs. Read the rest from the request:
+
+```ts
+Route.get('/user/{id}', (id: string) => {
+  const tab = request().query('tab', 'profile')
+
+  return `User ${id}, ${tab}`
+})
+```
+
+### Optional parameters
+
+Add a `?` to make a parameter optional. When the segment is missing, the parameter is `undefined`, so give it a
+default:
+
+```ts
+Route.get('/user/{name?}', (name?: string) => name ?? 'Guest')
+
+Route.get('/user/{name?}', (name = 'John') => name)
+```
+
+### Regular expression constraints
+
+`where()` constrains a parameter with a regular expression. A URI whose segment doesn't match gets a 404:
+
+```ts
+Route.get('/user/{name}', (name: string) => name).where('name', '[A-Za-z]+')
+
+Route.get('/user/{id}', (id: string) => id).where('id', '[0-9]+')
+
+Route.get('/user/{id}/{name}', (id: string, name: string) => ({ id, name })).where({ id: '[0-9]+', name: '[a-z]+' })
+```
+
+The common patterns have their own methods, which take one parameter or a list:
+
+```ts
+Route.get('/user/{id}/{name}', (id: string, name: string) => ({ id, name }))
+  .whereNumber('id')
+  .whereAlpha('name')
+
+Route.get('/user/{name}', (name: string) => name).whereAlphaNumeric('name')
+Route.get('/user/{id}', (id: string) => id).whereUuid('id')
+Route.get('/user/{id}', (id: string) => id).whereUlid('id')
+Route.get('/category/{category}', (category: string) => category).whereIn('category', ['movie', 'song', 'painting'])
+```
+
+`whereIn()` matches each value as written, so a value such as `c++` isn't read as a pattern.
+
+#### Global constraints
+
+A pattern that every route should share goes in a [service provider's](providers.md#the-boot-method) `boot()`, with
+`Route.pattern()`:
+
+```ts title="app/Providers/AppServiceProvider.ts"
+import { Route, ServiceProvider } from '@orieljs/framework'
+
+export class AppServiceProvider extends ServiceProvider {
+  override boot(): void {
+    Route.pattern('id', '[0-9]+')
+  }
+}
+```
+
+From then on, every `{id}` must be a number. A route's own `where()` wins over the global pattern.
+
+#### Encoded forward slashes
+
+A parameter matches anything but a `/`. To let it match the rest of the path, slashes included, constrain it with
+`.*`:
+
+```ts
+Route.get('/search/{search}', (search: string) => search).where('search', '.*')
+```
+
+Parameters arrive decoded: `/search/a%2Fb` gives `a/b`.
+
+## Named routes
+
+A name lets you build a route's URL, or redirect to it, without writing the URI again:
+
+```ts
+Route.get('/user/profile', () => view('profile')).name('profile')
+```
+
+Controller actions take names the same way:
+
+```ts
+Route.get('/posts/{post}', [PostController, 'show']).name('posts.show')
+```
+
+> [!WARNING]
+> Give each route its own name. When two routes share one, the last one defined wins.
+
+#### Generating URLs to named routes
+
+`route()` builds the URL of a named route, and `redirect().route()` a redirect to it:
+
+```ts
+const url = route('profile')
+
+const response = redirect().route('profile')
+```
+
+A route's parameters go in an object. Any key the route doesn't use is added to the query string:
+
+```ts
+Route.get('/user/{id}/profile', (id: string) => id).name('profile')
+
+route('profile', { id: 1, photos: 'yes' })
+// http://localhost:8000/user/1/profile?photos=yes
+```
+
+You can also pass a single value for a route's first parameter, or a list of values in the URI's order. A model
+fills a parameter with its route key, or with the column a `{post:slug}` parameter names:
+
+```ts
+declare const post: Post
+// ---cut---
+route('posts.show', post)
+route('posts.show', [post])
+route('posts.show', { post, page: 2 })
+```
+
+`route()` returns an absolute URL on the current request's host, or on `app.url` outside a request. Pass `false` as
+its third argument for a path:
+
+```ts
+declare const post: Post
+// ---cut---
+route('posts.show', post, false) // /posts/1
+```
+
+An optional parameter you leave out is dropped from the URL. A required one is an error: "Missing required parameter
+for [Route: posts.show] [URI: posts/{post}] [Missing parameter: post].".
+
+#### Typed route parameters
+
+`route:types` reads your routes and writes their names and parameters for TypeScript:
+
+```sh
+node oriel route:types
+```
+
+From then on, `route()` and `redirect().route()` accept only names that exist, and want the parameters each route
+defines: a renamed route or a missing parameter fails the type check everywhere it is linked to.
+
+```ts
+declare const post: Post
+// @filename: types/routes.d.ts
+declare module '@orieljs/framework' {
+  interface RouteList {
+    'posts.show': { post: unknown }
+  }
+}
+declare module '@orieljs/framework/contracts' {
+  interface RouteList {
+    'posts.show': { post: unknown }
+  }
+}
+export {}
+// ---cut---
+route('posts.show', post)
+route('posts.show', { post: post.id, page: 2 })
+
+// @ts-expect-error: no route is named post.show
+route('post.show', post)
+
+// @ts-expect-error: the route needs its post
+route('posts.show')
+
+// @ts-expect-error: getKey() is unknown; pass the model or post.id
+route('posts.show', { post: post.getKey() })
+```
+
+A parameter takes a string, a number, a boolean or a model. A model's `getKey()` is typed `unknown`, so pass the
+model itself or its typed `id`.
+
+`route:types` writes two files, both ignored by git: `types/routes.d.ts` for your server code, and
+`resources/js/oriel/routes.ts` for your pages. `--server` and `--output` write them somewhere else. The Inertia and
+API starter kits run it in `npm run typecheck`. The Inertia kits' Vite plugin also runs it when Vite starts, and again
+whenever a file in `routes/` or `app/Http/Controllers/` changes while `npm run dev` runs. In the Live kit, run it
+yourself. Until the first run, any name is accepted.
+
+#### Route URLs in your pages
+
+Your [Inertia](inertia.md#links-and-the-route-helper) pages build URLs with the same `route()`, from your adapter. It
+takes the same names and parameters, and returns a path. The browser's route table leaves out the routes that
+`types.except_routes` in `config/inertia.ts` names, with `*` as a wildcard. Unless you set it, it leaves out `live.*`,
+Live's own routes.
+
+```tsx tab="React" title="resources/js/components/PostLink.tsx"
+import { Link, route } from '@orieljs/inertia-react'
+
+export function PostLink({ id, title }: { id: number; title: string }) {
+  return <Link href={route('posts.show', { post: id })}>{title}</Link>
+}
+```
+```vue tab="Vue" title="resources/js/components/PostLink.vue"
+<script setup lang="ts">
+import { Link, route } from '@orieljs/inertia-vue'
+
+defineProps<{ id: number; title: string }>()
+</script>
+
+<template>
+  <Link :href="route('posts.show', { post: id })">{{ title }}</Link>
+</template>
+```
+```svelte tab="Svelte" title="resources/js/components/PostLink.svelte"
+<script lang="ts">
+  import { Link, route } from '@orieljs/inertia-svelte'
+
+  let { id, title }: { id: number; title: string } = $props()
+</script>
+
+<Link href={route('posts.show', { post: id })}>{title}</Link>
+```
+```tsx tab="Solid" title="resources/js/components/PostLink.tsx"
+import { Link, route } from '@orieljs/inertia-solid'
+
+export function PostLink(props: { id: number; title: string }) {
+  return <Link href={route('posts.show', { post: props.id })}>{props.title}</Link>
+}
+```
+```ts tab="Angular" title="resources/js/components/PostLink.component.ts"
+import { Component, computed, input } from '@angular/core'
+import { Link, route } from '@orieljs/inertia-angular'
+
+@Component({
+  selector: 'app-post-link',
+  imports: [Link],
+  template: `<a oLink [href]="href()">{{ title() }}</a>`,
+})
+export class PostLink {
+  readonly id = input.required<number>()
+  readonly title = input.required<string>()
+  readonly href = computed(() => route('posts.show', { post: this.id() }))
+}
+```
+
+#### Inspecting the current route
+
+`request().routeIs()` tells you whether the current request matched a route of that name. It takes several names,
+and `*` as a wildcard:
+
+```ts
+if (request().routeIs('admin.*')) {
+  // ...
+}
+```
+
+## Route groups
+
+A group shares middleware, a controller, a URI prefix or a name prefix between its routes. Groups can be nested: a
+nested group adds its middleware after its parent's, and its prefixes after its parent's prefixes.
+
+### Middleware
+
+`middleware()` before `group()` gives every route in the group its middleware, which run in the order you list them,
+except that `auth` and `guest` run first ([Sorting middleware](middleware.md#sorting-middleware) has the rule):
+
+```ts
+Route.middleware(['auth', 'verified']).group(() => {
+  Route.get('/dashboard', () => view('dashboard')).name('dashboard')
+  Route.get('/settings', () => view('settings')).name('settings')
+})
+```
+
+For a single route, chain the route's own `middleware()`: `Route.get('/profile', handler).middleware('auth')`.
+
+### Controllers
+
+When every route of a group calls the same [controller](controllers.md), name it once with `controller()`. Each route
+then gives only the method's name:
+
+```ts title="routes/web.ts"
+import { Route } from '@orieljs/framework'
+import { PostController } from '../app/Http/Controllers/PostController'
+
+Route.controller(PostController).group(() => {
+  Route.get('/posts', 'index')
+  Route.get('/posts/{post}', 'show')
+  Route.post('/posts', 'store')
+})
+```
+
+Inside a controller group, the method's name is a plain string, which TypeScript doesn't check: a misspelt one is a
+500 ("Method PostController::shwo does not exist.") when the route is called. Outside a group, the
+`[PostController, 'index']` form is checked.
+
+### Route prefixes
+
+`prefix()` adds a segment in front of each URI in the group:
+
+```ts
+Route.prefix('admin').group(() => {
+  Route.get('/users', () => 'Users') // matches /admin/users
+})
+```
+
+### Route name prefixes
+
+`name()` adds a prefix to each route's name. It is added as written, so end it with a `.`:
+
+```ts
+Route.name('admin.').group(() => {
+  Route.get('/users', () => 'Users').name('users') // named admin.users
+})
+```
+
+## Route model binding
+
+A route often looks a model up by the ID in its URI. Route model binding does it for you: the action receives the
+model rather than the ID.
+
+### Implicit binding
+
+When a parameter is named after one of your models, its segment is that model's route key. `{user}` finds the
+`User` whose `id` matches the segment, or answers 404 before your code runs:
+
+```ts title="routes/web.ts"
+import { Route } from '@orieljs/framework'
+import type { User } from '../app/Models/User'
+
+Route.get('/users/{user}', (user: User) => user.email)
+```
+
+The name is matched to a model in `app/Models` by its StudlyCase form: `{post}` is `Post`, `{blog_post}` and
+`{blogPost}` are `BlogPost`. A parameter that names no model stays a string.
+
+> [!NOTE]
+> Laravel finds the model from the parameter's type hint. TypeScript types are gone when your app runs, so Oriel finds
+> it from the parameter's name in the URI.
+
+Binding works the same for controller actions:
+
+```ts title="app/Http/Controllers/PostController.ts"
+import { view } from '@orieljs/framework'
+import type { Post } from '../../Models/Post'
+import { Controller } from './Controller'
+
+export class PostController extends Controller {
+  show(post: Post) {
+    return view('posts.show', { post })
+  }
+}
+```
+
+#### Soft deleted models
+
+A soft deleted model isn't found, so its route answers 404. There is no `withTrashed()` on routes.
+
+#### Customizing the key
+
+Name a column after a colon to look the model up by that column:
+
+```ts
+Route.get('/posts/{post:slug}', (post: Post) => view('posts.show', { post }))
+```
+
+To use a column for every route of a model, override `getRouteKeyName()` on the model. `route()` then fills the
+parameter from that column too:
+
+```ts title="app/Models/Post.ts"
+import { Model } from '@orieljs/framework'
+
+export class Post extends Model {
+  override getRouteKeyName(): string {
+    return 'slug'
+  }
+}
+```
+
+### Explicit binding
+
+A parameter that isn't named after its model is bound with `Route.model()`, in a [service
+provider's](providers.md#the-boot-method) `boot()`:
+
+```ts title="app/Providers/AppServiceProvider.ts"
+import { Route, ServiceProvider } from '@orieljs/framework'
+import { User } from '../Models/User'
+
+export class AppServiceProvider extends ServiceProvider {
+  override boot(): void {
+    Route.model('author', User)
+  }
+}
+```
+
+Every `{author}` parameter is now a `User`, found by its route key, and a missing one is a 404:
+
+```ts
+Route.get('/posts/by/{author}', (author: User) => author.posts().get())
+```
+
+#### Customizing the resolution logic
+
+`Route.bind()` resolves a parameter however you like. The callback receives the segment, and the action receives
+what it returns:
+
+```ts title="app/Providers/AppServiceProvider.ts"
+import { Route, ServiceProvider } from '@orieljs/framework'
+import { User } from '../Models/User'
+
+export class AppServiceProvider extends ServiceProvider {
+  override boot(): void {
+    Route.bind('member', (value) => User.where('name', value).firstOrFail())
+  }
+}
+```
+
+A `Route.bind()` callback comes first, then `Route.model()`, then binding by name. To change how a model is found on
+every route, override the model's `resolveRouteBinding(value, field)`, which returns the model or `undefined`, or its
+`resolveRouteBindingQuery(query, value, field)`, which returns the query that finds it. Inside that override,
+TypeScript can't tell which columns the model has, so every column name is a type error there: a condition such as
+`whereNotNull('published_at')` runs, but doesn't type-check.
+
+## Fallback routes
+
+`Route.fallback()` answers any `GET` request that no other route matched, in place of the 404 page. It is always
+tried last, wherever you define it, and when it sits in `routes/web.ts`, the `web` middleware run for it:
+
+```ts
+Route.fallback(() => view('errors.not-found'))
+```
+
+Inside a group with a prefix, a fallback answers only the URIs under that prefix. A `POST` to an unknown URI is still
+a 404.
+
+## Rate limiting
+
+### Attaching rate limiters to routes
+
+The `throttle` middleware limits how often a client may call a route. Its parameters are the number of requests and
+the window in minutes:
+
+```ts
+declare const handler: () => string
+// ---cut---
+Route.middleware('throttle:60,1').group(() => {
+  Route.post('/audio', handler)
+  Route.post('/video', handler)
+})
+```
+
+It counts per signed-in user, on any route, and per IP address for a guest. The counts are kept in your
+cache's default store, or in the store that a `limiter` key in `config/cache.ts` names. Each response carries
+`X-RateLimit-Limit` and `X-RateLimit-Remaining` headers. Past the limit, the route answers 429 ("Too Many Attempts.")
+with `Retry-After`, the seconds to wait, and `X-RateLimit-Reset`, the Unix time the window ends.
+
+Every route behind `throttle` adds to the same count for a client, whatever its numbers. To count a group of routes
+on its own, give `throttle` a third parameter, a prefix for its key: `throttle:10,1,uploads`.
+
+> [!WARNING]
+> Laravel's named rate limiters (`RateLimiter::for()`) aren't in Oriel: give `throttle` its numbers directly.
+
+## Form method spoofing
+
+HTML forms can only send `GET` and `POST`. To reach a `PUT`, `PATCH` or `DELETE` route from a form, post it with a
+hidden `_method` field, which `methodField()` writes:
+
+```tsx title="resources/views/posts/edit.tsx"
+import { csrfField, methodField } from '@orieljs/framework'
+import type { Post } from '../../../app/Models/Post'
+
+export default function Edit({ post }: { post: Post }) {
+  return (
+    <form method="post" action={`/posts/${post.id}`}>
+      {methodField('PUT')}
+      {csrfField()}
+      <button type="submit">Update</button>
+    </form>
+  )
+}
+```
+
+The `X-HTTP-Method-Override` header does the same for a script. Only a `POST` can be spoofed, and never as `GET` or
+`HEAD`.
+
+## Accessing the current route
+
+The `Route` [facade](facades.md) tells you which route is handling the current request, and the request gives you its
+parameters:
+
+```ts
+const current = Route.current() // the route, or undefined outside a request
+const name = Route.currentRouteName() // 'posts.show'
+const post = request().route('post') // the bound Post
+const parameters = request().route() // every parameter, by name
+```
+
+`Route.has('login')` tells you whether a route of that name exists, as a new app's welcome page does to show its login
+link.