BREAKING CHANGE: By default, this will add import assertions to all external .json file imports in the output.

This PR contains:

• bugfix
• feature
• refactor
• documentation
• other

Are tests included?

• yes (bugfixes and features will not be merged without tests)
• no

Breaking Changes?

• yes (breaking changes will not be merged unless absolutely necessary)
• no

List any relevant issue numbers:

• resolves assert { type: 'json' } results in "Error: Unexpected token" #4530
• resolves Plan for import assertions and non-JS module types #3799

Description

This PR adds basic support for import assertions to Rollup.

• In input files, arbitrary import assertions are allowed. However, there will be a non-blocking warning if the same module is imported with conflicting assertions.
• In ESM output by default for external modules, all assertions from the input are preserved. In case of conflicting assertions, the import assertions of the first import are used.
• While there is also a warning if there are conflicting import assertions for bundled modules, they do not have any effect on the generated output. They can however be inspected by plugins via this.getModuleInfo.
• Furthermore, there is a new output.externalImportAssertions option that allows to disabled assertions in the output.
• For plugins, assertions are now passed in as a parameter to resolveId and resolveDynamicImport. If plugins do not return a value for assertions in their resolveId hook, the assertions from the actual import are used, otherwise they can override assertions at this point. For symmetry with other module options, they can also be changed in the load and transform hooks. In this.resolve, you can now also pass assertions that will be forwarded to resolveId.

output.externalImportAssertions

Type: boolean
CLI: --externalImportAssertions/--no-externalImportAssertions
Default: true

Whether to add import assertions to external imports in the output if the output format is es. By default, assertions are taken from the input files, but plugins can add or remove assertions later. E.g. import "foo" assert {type: "json"} will cause the same import to appear in the output unless the option is set to false. Note that all imports of a module need to have consistent assertions, otherwise a warning is emitted.

resolveId

Type: (source: string, importer: string | undefined, options: {isEntry: boolean, assertions: {[key: string]: string}, custom?: {[plugin: string]: any}}) => string | false | null | {id: string, external?: boolean | "relative" | "absolute", assertions?: {[key: string]: string} | null, meta?: {[plugin: string]: any} | null, moduleSideEffects?: boolean | "no-treeshake" | null, syntheticNamedExports?: boolean | string | null}

…

assertions tells you which import assertions were present in the import. I.e. import "foo" assert {type: "json"} will pass along assertions: {type: "json"}.

…

If you return a value for assertions for an external module, this will determine how imports of this module will be rendered when generating "es" output. E.g. {id: "foo", external: true, assertions: {type: "json"}} will cause imports of this module appear as import "foo" assert {type: "json"}. If you do not pass a value, the value of the assertions input parameter will be used. Pass an empty object to remove any assertions. While assertions do not influence rendering for bundled modules, they still need to be consistent across all imports of a module, otherwise a warning is emitted. The load and transform hooks can override this.

resolveDynamicImport

Type: (specifier: string | ESTree.Node, importer: string, {assertions: {[key: string]: string}}) => string | false | null | {id: string, external?: boolean | "relative" | "absolute", assertions?: {[key: string]: string} | null, meta?: {[plugin: string]: any} | null, moduleSideEffects?: boolean | "no-treeshake" | null, syntheticNamedExports?: boolean | string | null}

…

assertions tells you which import assertions were present in the import. I.e. import("foo", {assert: {type: "json"}}) will pass along assertions: {type: "json"}.

load

Type: (id: string) => string | null | {code: string, map?: string | SourceMap, ast? : ESTree.Program, assertions?: {[key: string]: string} | null, meta?: {[plugin: string]: any} | null, moduleSideEffects?: boolean | "no-treeshake" | null, syntheticNamedExports?: boolean | string | null}

…

assertions contain the import assertions that were used when this module was imported. At the moment, they do not influence rendering for bundled modules but rather serve documentation purposes. If null is returned or the flag is omitted, then assertions will be determined by the first resolveId hook that resolved this module, or the assertions present in the first import of this module. The transform hook can override this.

shouldTransformCachedModule

Type: ({id: string, code: string, ast: ESTree.Program, resolvedSources: {[source: string]: ResolvedId}, assertions: {[key: string]: string}, meta: {[plugin: string]: any}, moduleSideEffects: boolean | "no-treeshake", syntheticNamedExports: boolean | string}) => boolean

transform

Type: (code: string, id: string) => string | null | {code?: string, map?: string | SourceMap, ast? : ESTree.Program, assertions?: {[key: string]: string} | null, meta?: {[plugin: string]: any} | null, moduleSideEffects?: boolean | "no-treeshake" | null, syntheticNamedExports?: boolean | string | null}

…

assertions contain the import assertions that were used when this module was imported. At the moment, they do not influence rendering for bundled modules but rather serve documentation purposes. If null is returned or the flag is omitted, then assertions will be determined by the load hook that loaded this module, the first resolveId hook that resolved this module, or the assertions present in the first import of this module.

this.getModuleInfo

Type: (moduleId: string) => (ModuleInfo | null)

Returns additional information about the module in question in the form

type ModuleInfo = {
  id: string; // the id of the module, for convenience
  code: string | null; // the source code of the module, `null` if external or not yet available
  ast: ESTree.Program; // the parsed abstract syntax tree if available
  hasDefaultExport: boolean | null; // is there a default export, `null` if external or not yet available
  isEntry: boolean; // is this a user- or plugin-defined entry point
  isExternal: boolean; // for external modules that are referenced but not included in the graph
  isIncluded: boolean | null; // is the module included after tree-shaking, `null` if external or not yet available
  importedIds: string[]; // the module ids statically imported by this module
  importedIdResolutions: ResolvedId[]; // how statically imported ids were resolved, for use with this.load
  importers: string[]; // the ids of all modules that statically import this module
  dynamicallyImportedIds: string[]; // the module ids imported by this module via dynamic import()
  dynamicallyImportedIdResolutions: ResolvedId[]; // how ids imported via dynamic import() were resolved
  dynamicImporters: string[]; // the ids of all modules that import this module via dynamic import()
  implicitlyLoadedAfterOneOf: string[]; // implicit relationships, declared via this.emitFile
  implicitlyLoadedBefore: string[]; // implicit relationships, declared via this.emitFile
  assertions: { [key: string]: string }; // import assertions for this module
  meta: { [plugin: string]: any }; // custom module meta-data
  moduleSideEffects: boolean | 'no-treeshake'; // are imports of this module included if nothing is imported from it
  syntheticNamedExports: boolean | string; // final value of synthetic named exports
};

type ResolvedId = {
  id: string; // the id of the imported module
  external: boolean | 'absolute'; // is this module external, "absolute" means it will not be rendered as relative in the module
  assertions: { [key: string]: string }; // import assertions for this import
  meta: { [plugin: string]: any }; // custom module meta-data when resolving the module
  moduleSideEffects: boolean | 'no-treeshake'; // are side effects of the module observed, is tree-shaking enabled
  syntheticNamedExports: boolean | string; // does the module allow importing non-existing named exports
};

this.resolve

Type: (source: string, importer?: string, options?: {skipSelf?: boolean, isEntry?: boolean, assertions?: {[key: string]: string}, custom?: {[plugin: string]: any}}) => Promise<{id: string, external: boolean | "absolute", assertions: {[key: string]: string}, meta: {[plugin: string]: any} | null, moduleSideEffects: boolean | "no-treeshake", syntheticNamedExports: boolean | string>

…

If you pass an object for assertions, it will simulate resolving an import with an assertion, e.g. assertions: {type: "json"} simulates resolving import "foo" assert {type: "json"}. This will be passed to any resolveId hooks handling this call and may ultimately become part of the returned object.

this.load

Type: ({id: string, resolveDependencies?: boolean, assertions?: {[key: string]: string} | null, meta?: {[plugin: string]: any} | null, moduleSideEffects?: boolean | "no-treeshake" | null, syntheticNamedExports?: boolean | string | null}) => Promise<ModuleInfo>