Routing

A router maps an intention to the code that answers it. Stone.js has one router, and it behaves identically wherever the app runs: the routes you write for a Node service are the routes that drive navigation in the browser. This section covers it end to end.

#The mental model

Every route is a pairing: a way to recognise an intention (a method and a path pattern) and a handler to run when it matches. The handler reads values off the event and returns data; it never touches a platform request object. That is what keeps the same routes valid across every context.

#Define a route

Group related routes under a controller with a base path, then bind methods to verbs and sub-paths. Both paradigms produce the same routes.

import { EventHandler, Get, Post } from '@stone-js/router'
import { IncomingHttpEvent } from '@stone-js/http-core'

@EventHandler('/tasks')                 // a controller: a base path + its routes
export class TaskController {
  constructor ({ tasks }: { tasks: TaskService }) { this.tasks = tasks }

  @Get('/')                             // GET /tasks
  list (event: IncomingHttpEvent) { return this.tasks.list() }

  @Post('/', { name: 'tasks.create' })  // POST /tasks, a named route
  create (event: IncomingHttpEvent) { return this.tasks.add(event.get<string>('title')) }
}

import { defineEventHandler, defineRoutes } from '@stone-js/router'

const TaskController = ({ tasks }) => ({
  list: () => tasks.list(),
  create: (event) => tasks.add(event.get('title'))
})

export const routes = defineRoutes([
  [defineEventHandler(TaskController, 'list'),   { path: '/tasks', method: 'GET' }],
  [defineEventHandler(TaskController, 'create'), { path: '/tasks', method: 'POST', name: 'tasks.create' }]
])

#What the section covers

Routing is large, so it is split into focused pages. Read them in order for a full tour, or jump to what you need: