Query Parameters
Leer el query string desde el context, cómo se comportan las keys repetidas, y cómo validar el input del query.
Los query parameters llegan en ctx.query:
import { Arcton } from '@arcton/core'
const app = Arcton()
app.get('/search', ctx => ({
term: ctx.query.q,
page: ctx.query.page
}))
app.listen()GET /search?q=arcton&page=2 retorna {"term":"arcton","page":"2"}.
Los valores son strings, y pueden faltar
ctx.query es un Record<string, string>. Una key que no se envió es
undefined, así que maneja la ausencia explícitamente:
import { Arcton } from '@arcton/core'
const app = Arcton()
app.get('/search', ctx => {
const term = ctx.query.q ?? ''
const page = Number(ctx.query.page ?? '1')
return { term, page }
})
app.listen()Dos detalles que vale la pena conocer:
- Una key enviada sin valor es un string vacío:
?debugdactx.query.debug === ''. - Una key enviada más de una vez conserva el último valor:
?tag=a&tag=bdactx.query.tag === 'b'.
El query string se parsea la primera vez que algo lee ctx.query, así
que un handler que nunca lo toca no paga nada por eso.
Validar y convertir
Convertir a mano se vuelve repetitivo apenas una ruta toma más de un
parámetro. Un schema de query hace la conversión y el tipado en un solo
lugar:
import { Arcton } from '@arcton/core'
import * as v from 'valibot'
const app = Arcton()
app.get('/search', {
query: v.object({
q: v.string(),
page: v.optional(
v.pipe(v.string(), v.transform(Number), v.number()),
'1'
)
}),
handler: ctx => ({ term: ctx.query.q, page: ctx.query.page })
})
app.listen()ctx.query.page aquí es un number, y un request al que le falta q se
responde con 400 antes de que el handler corra. Ver
Params and query y
Validation errors.
Leer el query string crudo
ctx.request.url siempre está disponible cuando necesitas la URL en sí
— para keys repetidas que quieres conservar, por ejemplo:
import { Arcton } from '@arcton/core'
const app = Arcton()
app.get('/filter', ctx => {
const url = new URL(ctx.request.url)
const tags = url.searchParams.getAll('tag')
return { tags }
})
app.listen()GET /filter?tag=a&tag=b retorna {"tags":["a","b"]}.
Los query parameters no son parte del matching de rutas. /search y
/search?q=x llegan a la misma ruta, y dos rutas no pueden
distinguirse por su query string.