Request options

Every query option of a module, style or map request, with its values and defaults, and what happens when a value is invalid or not produced.

  • Availability: Experimental
  • Evidence: Read from source
  • Reference

Options

Options are query parameters. They apply to module, style and map requests. An asset request takes none.

Option Values Required Default Meaning
target browser, node Yes The environment the output is built for
format esm, cjs, system Yes The module format of the output
env production, development No production The build mode
min true, false No true Whether the output is minified
sourcemap inline, external, none No external How the source map is provided
types true, false No false Adds a Link header to the declarations of the module, when the service produces them
css true, false No false Adds a Link header to the stylesheet of the module, when the service serves it

The defaults are those of published delivery: production, minified, external map. A development consumer sends every value explicitly.

Invalid values are errors

An option that is misspelled, unknown, repeated or out of range is 400 OPTION_INVALID. It never falls back to a default, so a consumer that misspells development cannot silently receive production output.

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;

These requests are all 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

Valid values a service does not produce

OPTION_UNSUPPORTED (400) means the request is valid and this service cannot produce that output at all. It is different from a miss:

Answer Meaning What to do
400 OPTION_UNSUPPORTED The service never produces this output. A development server answers this for format=cjs, sourcemap=external, types=true, css=true, a mix of env and min other than development/false and production/true, and production output of a module that builds no production conditional. Packages generation produces esm and system and never cjs, so format=cjs is unsupported on published delivery too, and so is sourcemap=inline. Request an output the service produces.
404 OUTPUT_NOT_AVAILABLE Published delivery only. The service could hold this output, and it was not prepared for this module. Prepare a release that includes it. Retrying the GET changes nothing.

format=system selects the System.register form of the same module. A development server converts its ES module on request; published delivery serves it when the release was prepared in the system loader mode. See SystemJS.

The canonical query

The canonical query writes all seven options explicitly, in this order:

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

A request may omit defaults and use any order. Documents that carry URLs, such as a resolution document, always use the canonical query, so that one output has one spelling.

From options to conditions

Options select the conditional of a Packages module. The browser target is the web platform, node is node, and env is the environment:

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) throws a ContractError with the code OPTION_INVALID. Option names, values and defaults are read from the OpenAPI document of the package, so the code and the specification cannot drift apart.