ArctonArcton
Referencia de la API

Tipos de Validación

Los contratos de tipo StandardSchemaV1 y BodyParser detrás de la validación de rutas y el parsing del body.

Resumen

Dos contratos a nivel de tipos hacen que la validación de requests y el parsing de body personalizado funcionen sin que Arcton dependa de una librería de schemas o parsing específica: StandardSchemaV1, la interfaz que deben implementar los schemas de params/query/body, y BodyParser, la forma de función que debe implementar un parser personalizado registrado con app.parser(). Ver Application para dónde se consumen ambos.

StandardSchemaV1

Propósito — una interfaz de schema neutral respecto al vendor (standardschema.dev) implementada por Zod 3.24+, Valibot, ArkType, y otras. Cualquier schema que la implemente puede pasarse como params, query, o body en la forma de llamada con route-options.

Firma

interface StandardSchemaV1<Input = unknown, Output = Input> {
  readonly '~standard': StandardSchemaV1.Props<Input, Output>
}

namespace StandardSchemaV1 {
  export interface Props<Input = unknown, Output = Input> {
    readonly version: 1
    readonly vendor: string
    readonly validate: (
      value: unknown
    ) => Result<Output> | Promise<Result<Output>>
    readonly types?: Types<Input, Output> | undefined
  }
  export interface Types<Input = unknown, Output = Input> {
    readonly input: Input
    readonly output: Output
  }
  export type Result<Output> = SuccessResult<Output> | FailureResult
  export interface SuccessResult<Output> {
    readonly value: Output
    readonly issues?: undefined
  }
  export interface FailureResult {
    readonly issues: ReadonlyArray<Issue>
  }
  export interface Issue {
    readonly message: string
    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined
  }
  export interface PathSegment {
    readonly key: PropertyKey
  }
  export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<
    Schema['~standard']['types']
  >['output']
}

Comportamiento — validate() retorna un SuccessResult ({ value }) o un FailureResult ({ issues }), de forma síncrona o vía una Promise. types es un campo phantom: nunca se popula en runtime, solo se lee a través de StandardSchemaV1.InferOutput<Schema> para que TypeScript pueda inferir el tipo de salida validado sin costo alguno en runtime. Cuando una ruta declara un schema, su InferOutput — no el input previo a la validación — es con lo que se tipan y completan ctx.params, ctx.query, o ctx.body; ver Context.

Errores — ninguno propio. Que validate() de un schema retorne { issues } corta la cadena del request con una respuesta 400; el array de issues se pasa directo al cliente.

Ejemplo

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

const app = Arcton()

app.post('/users/:id/orders', {
  body: v.object({
    item: v.pipe(v.string(), v.minLength(1)),
    quantity: v.pipe(v.number(), v.integer(), v.minValue(1))
  }),
  handler: ctx => ({
    userId: ctx.params.id,
    order: ctx.body
  })
})

app.listen()

Este fragmento muestra la interfaz directamente, sin una librería de schemas, implementándola a mano:

import type { StandardSchemaV1 } from '@arcton/contracts'

function positiveNumber(): StandardSchemaV1<unknown, number> {
  return {
    '~standard': {
      version: 1,
      vendor: 'example',
      validate(value) {
        const n = Number(value)
        return n > 0
          ? { value: n }
          : { issues: [{ message: 'must be a positive number' }] }
      }
    }
  }
}

StandardJSONSchemaV1

Propósito — una interfaz hermana de StandardSchemaV1 (Standard JSON Schema), implementada por un schema que además puede describirse a sí mismo como JSON Schema. Nada en @arcton/core lee esto — existe para que un paquete construido sobre Arcton, como @arcton/openapi, pueda generar documentación a partir de los mismos schemas con los que una ruta ya valida.

Firma

interface StandardJSONSchemaV1 {
  readonly '~standard': StandardJSONSchemaV1.Props
}

namespace StandardJSONSchemaV1 {
  export interface Props {
    readonly jsonSchema: Converter
  }
  export interface Converter {
    readonly input: (options: Options) => Record<string, unknown>
    readonly output: (options: Options) => Record<string, unknown>
  }
  export type Target =
    | 'draft-2020-12'
    | 'draft-07'
    | 'openapi-3.0'
    | ({} & string)
  export interface Options {
    readonly target: Target
    readonly libraryOptions?: Record<string, unknown> | undefined
  }
}

Comportamiento — comparte la misma key '~standard' que StandardSchemaV1, así que un schema que lo soporta se detecta por feature ('jsonSchema' in schema['~standard']), no por qué librería lo produjo. input y output son conversiones separadas porque pueden diferir — un schema con un transform acepta una forma y produce otra. Cualquiera de las dos puede lanzar cuando un schema no tiene representación en JSON Schema en absoluto (un Date crudo, por ejemplo); quien quiera documentación en vez de un error debe capturarlo él mismo. Zod 4.6+ y ArkType 2.2+ la implementan de forma nativa; Valibot todavía no — envuelve un schema con toStandardJsonSchema() de @valibot/to-json-schema para sumarse. Ver OpenAPI & Scalar.

Ejemplo

Este fragmento muestra la interfaz directamente, sin una librería de schemas, implementándola a mano:

import type { StandardJSONSchemaV1 } from '@arcton/contracts'

function jsonString(): StandardJSONSchemaV1 {
  return {
    '~standard': {
      jsonSchema: {
        input: () => ({ type: 'string' }),
        output: () => ({ type: 'string' })
      }
    }
  }
}

BodyParser

Propósito — la forma de función registrada con app.parser(mediaType, parser) para parsear el body de un request para un media type, sobrescribiendo o extendiendo los parsers built-in. Ver Application para parser() en sí.

Firma

type BodyParser = (request: Request) => unknown | Promise<unknown>

Parámetros

ParámetroTipoDescripción
requestRequestEl request entrante crudo — no ctx, ya que el parsing ocurre antes de que los params/query de un context sean relevantes.

Tipo de retorno — unknown | Promise<unknown>: el valor que deba convertirse en el input de validación del schema para la opción body de esa ruta.

Comportamiento — retornar undefined significa "no manejo esto", así que el runtime sigue buscando (y en última instancia responde 415 si nada más lo maneja). Cualquier otro valor cuenta como manejado, incluyendo false, 0, y ''. Un parser solo se consulta para una ruta que declare un schema body y liste el media type en content.

Errores — un parser que lanza (throw) se propaga como cualquier otro código de usuario (ver Uncaught errors); no se captura ni se convierte en un 400.

Ejemplo

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

const csvParser: BodyParser = async request => {
  const text = await request.text()
  const [header = '', ...rows] = text.trim().split('\n')
  const keys = header.split(',')
  return rows.map(row =>
    Object.fromEntries(keys.map((key, i) => [key, row.split(',')[i]]))
  )
}

const app = Arcton()

app.parser('text/csv', csvParser)

app.post('/import', {
  body: {
    content: { 'text/csv': v.array(v.record(v.string(), v.string())) }
  },
  handler: ctx => ({ imported: ctx.body.length, rows: ctx.body })
})

app.listen()

Ver Body parsers para la tabla de parsers built-in y cómo el schema body de una ruta selecciona uno.

En esta página