ArctonArcton
Enrutamiento

Path Parameters

Capturar segmentos dinámicos y wildcard, los tipos que Arcton infiere para ellos, y cómo se decodean los valores capturados.

Un segmento :name captura un segmento de path:

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/users/:id', ctx => ({ id: ctx.params.id }))

app.listen()

GET /users/42 retorna {"id":"42"}.

Los tipos vienen del path

Arcton lee el literal de la ruta y tipa ctx.params a partir de él. No hay ningún argumento genérico involucrado:

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/orgs/:orgId/repos/:repoId', ctx => {
  // ctx.params is { orgId: string; repoId: string }
  return { org: ctx.params.orgId, repo: ctx.params.repoId }
})

app.listen()

Leer un nombre que el path no declara es un error de compilación. Una ruta sin parámetros no tiene ninguna key de parámetro para leer.

La inferencia necesita un literal. Si el path viene de una variable tipada como string, ctx.params cae a Record<string, string>. Pasar el path en línea mantiene el tipo preciso.

Los valores de parámetro son strings

Cada valor capturado es un string, porque eso es lo que lleva una URL. Para trabajar con un número, conviértelo — o declara un schema y deja que la validation produzca el valor convertido:

import { Arcton } from '@arcton/core'
import * as v from 'valibot'

const app = Arcton()

app.get('/users/:id', {
  params: v.object({
    id: v.pipe(v.string(), v.transform(Number), v.number())
  }),
  handler: ctx => ({ id: ctx.params.id, type: typeof ctx.params.id })
})

app.listen()

GET /users/42 ahora retorna {"id":42,"type":"number"}. Ver Params and query.

Wildcards

Un segmento *name captura todo lo que queda del path, unido con /:

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/files/*path', ctx => ({ path: ctx.params.path }))

app.listen()
Requestctx.params.path
/files/readme.mdreadme.md
/files/docs/api/index.htmldocs/api/index.html

Un wildcard debe ser el último segmento del path, y necesita al menos un segmento para matchear: con solo /files/*path registrado, GET /files y GET /files/ producen un 404. Registra /files por separado si quieres responderla.

Como un wildcard acepta cualquier resto del path, valida el valor capturado antes de usarlo para acceder a algo en disco:

import { Arcton } from '@arcton/core'

const files: Record<string, string> = {
  'readme.md': '# Arcton',
  'docs/intro.md': 'Welcome'
}

const app = Arcton()

app.get('/files/*path', ctx => {
  const segments = ctx.params.path.split('/')

  if (segments.some(segment => segment === '..' || segment === '')) {
    return new Response('Invalid path', { status: 400 })
  }

  const content = files[ctx.params.path]
  if (content === undefined) {
    return new Response('Not found', { status: 404 })
  }

  return new Response(content, { headers: { 'content-type': 'text/plain' } })
})

app.listen()

Valores percent-encoded

Los valores capturados se decodean con percent-decoding; las partes estáticas del path se matchean tal como están escritas. GET /users/hello%20world da ctx.params.id === 'hello world'. Un valor cuya secuencia de escape es inválida se te entrega exactamente como llegó en vez de fallar el request.

Múltiples parámetros

Cualquier cantidad de segmentos dinámicos puede aparecer en un path, mientras sus nombres difieran:

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/:year/:month/:slug', ctx => ({
  year: ctx.params.year,
  month: ctx.params.month,
  slug: ctx.params.slug
}))

app.listen()

Un segmento dinámico y uno wildcard también pueden compartir un path, con el wildcard al final:

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/users/:id/files/*path', ctx => ({
  user: ctx.params.id,
  path: ctx.params.path
}))

app.listen()

Misma posición, mismo nombre

Las rutas que comparten un prefix deben coincidir en el nombre del parámetro en cada posición:

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/users/:id', ctx => ({ id: ctx.params.id }))
app.get('/users/:id/posts', ctx => ({ user: ctx.params.id }))

app.listen()

Escribir '/users/:userId/posts' junto con '/users/:id' tira un error al registrarse, porque una posición capturaría bajo dos nombres distintos. Ver Registration errors.

En esta página