Opciones de la solicitud

Todas las opciones de consulta de una solicitud de módulo, estilo o mapa, con sus valores y valores predeterminados, y qué ocurre cuando un valor no es válido o no se produce.

  • Disponibilidad: Experimental
  • Evidencia: Leído del código fuente
  • Referencia

Opciones

Las opciones son parámetros de consulta. Se aplican a las solicitudes de módulos, estilos y mapas. Una solicitud de recurso estático no acepta ninguna.

Opción Valores Obligatoria Predeterminado Significado
target browser, node Sí El entorno para el que se genera la salida
format esm, cjs, system Sí El formato de módulo de la salida
env production, development No production El modo de compilación
min true, false No true Si la salida está minificada
sourcemap inline, external, none No external Cómo se proporciona el source map
types true, false No false Agrega un encabezado Link a las declaraciones del módulo, cuando el servicio las produce
css true, false No false Agrega un encabezado Link a la hoja de estilos del módulo, cuando el servicio la sirve

Los valores predeterminados son los de la entrega publicada: producción, minificado, mapa externo. Un consumidor de desarrollo envía todos los valores de forma explícita.

Los valores no válidos son errores

Una opción mal escrita, desconocida, repetida o fuera de rango es 400 OPTION_INVALID. Nunca se reemplaza por un valor predeterminado, de modo que un consumidor que escribe mal development no puede recibir salida de producción sin darse cuenta.

JavaScriptinvalid-option.mjs
// An invalid option value is an error. It never falls back to a default, so a
// misspelled "development" cannot silently return production output.
const origin = process.env.CDN_ORIGIN ?? process.env.DEV_ORIGIN;
const request = '/m/@example/[email protected]/modules/text?target=browser&format=esm&env=develpment';

const response = await fetch(new URL(request, origin));
const { error } = await response.json();
console.log(`${response.status} ${error.code}: ${error.message}`);

if (response.status !== 400 || error.code !== 'OPTION_INVALID') process.exitCode = 1;

Todas estas solicitudes son OPTION_INVALID:

Text
?format=esm                          target is required
?target=browser&format=esm&env=dev   "dev" is not a value of env
?target=browser&format=esm&min=1     booleans are "true" or "false"
?target=browser&target=node&format=esm   an option appears twice
?target=browser&format=esm&debug=true    unknown option

Valores válidos que un servicio no produce

OPTION_UNSUPPORTED (400) significa que la solicitud es válida y que este servicio no puede producir esa salida en absoluto. No es lo mismo que una salida que falta:

Respuesta Significado Qué hacer
400 OPTION_UNSUPPORTED El servicio nunca produce esta salida. Un servidor de desarrollo responde así a format=cjs, sourcemap=external, types=true, css=true, a una combinación de env y min distinta de development/false y production/true, y a la salida de producción de un módulo que no compila un condicional de producción. La generación de Packages produce esm y system y nunca cjs, así que format=cjs tampoco es compatible en la entrega publicada, y tampoco sourcemap=inline. Solicita una salida que el servicio produzca.
404 OUTPUT_NOT_AVAILABLE Solo en la entrega publicada. El servicio podría tener esta salida, y no se preparó para este módulo. Prepara un release que la incluya. Reintentar el GET no cambia nada.

format=system selecciona la forma System.register del mismo módulo. Un servidor de desarrollo convierte su módulo ES al solicitarlo; la entrega publicada la sirve cuando el release se preparó en el modo de carga system. Consulta SystemJS.

La consulta canónica

La consulta canónica escribe las siete opciones de forma explícita y en este orden:

Text
target=browser&format=esm&env=production&min=true&sourcemap=external&types=false&css=false

Una solicitud puede omitir los valores predeterminados y usar cualquier orden. Los documentos que contienen URL, como un documento de resolución, siempre usan la consulta canónica, para que una salida tenga una sola forma de escribirse.

De las opciones a las condiciones

Las opciones seleccionan el condicional de un módulo de Packages. El target browser es la plataforma web, node es node, y env es el entorno:

JavaScript
import { Options } from '@beyond-js/artifact-api';

const options = new Options(new URLSearchParams('target=browser&format=esm'));
options.env; // 'production'
options.conditions; // { platform: 'web', environment: 'production' }
options.query; // the canonical query

Options.development; // { target: 'node', format: 'esm', env: 'development', min: 'false', sourcemap: 'inline' }

new Options(query) lanza un ContractError con el código OPTION_INVALID. Los nombres, los valores y los valores predeterminados de las opciones se leen del documento OpenAPI del paquete, de modo que el código y la especificación no pueden divergir.