Module: lib/bundler/graph

Builds the module graph an Avenx application actually has.

The invariant this file exists to establish

avenx build reports success  =>  every import in the application resolved,
                                 and every name it imported is exported

The concatenator could not state anything of the kind. It had no graph: it read a directory, appended text, and deleted the imports it did not recognise. An import that named nothing and an import that named a real package produced the same output — none — so "the build succeeded" carried no information about whether the application could start.

Here, loading a module means resolving each of its specifiers. A specifier that resolves to nothing throws, with the importer and the reason. Nothing is skipped, and there is no path through this file that drops an edge.

Binding validation

Real ES modules are checked further: import { formt } from './format.js' fails at link time in a browser, so it fails here, with the near-miss suggested. CommonJS modules are exempt because their exports are a runtime object rather than a declaration — claiming to know them statically would produce confident false positives, which is worse than not checking.

Cycles

Cycles are legal ES modules and the runtime contains one (reactive/watcher.js ↔ trace/reactive.js), so refusing them is not an option. They are detected, recorded per edge, and handed to the emitter, which reproduces the only guarantee the language itself makes across a cycle: function declarations hoist, so a cyclic import of a function works and a cyclic import of a class or a const is a temporal dead zone. The emitter mirrors that exactly rather than inventing a weaker rule.

Source:

Classes

BindingError
DynamicImportError
ModuleGraph

Methods

(static) buildGraph(options) → {Object}

Builds a graph from one or more entry modules.

Parameters:
Name Type Description
options object

Build options.

Properties
Name Type Attributes Description
entries Array:.<string:>

Resolved entry module ids.
resolver Resolver

Specifier resolution.
validate boolean <optional>

Whether to check imported names exist.
Source:
Throws:

When the application does not link.

Type
ResolveError | BindingError
Returns:

The graph and its emission order.

Type
Object

(static) detectFormat(record, source, file) → {'esm'|'cjs'}

Detects whether a source is CommonJS rather than an ES module.

ES syntax wins outright: a file with import or export declarations is a module regardless of what else it contains. Only when there are none does a module.exports, exports.x or require( marker make it CommonJS.

Parameters:
Name Type Description
record object

The parsed module record.
source string

The module source.
file string

The module path, for extension hints.
Source:
Returns:

The module format.

Type
'esm' | 'cjs'

(inner) collectRequires(source) → {Array:.<string:>}

Finds the static require() specifiers in a CommonJS module.

A CommonJS dependency is as real as an ES one, so it belongs in the graph. Only literal specifiers are collected: require(name) with a computed argument cannot be resolved at build time by anyone, and pretending otherwise would produce a confident wrong answer.

Parameters:
Name Type Description
source string

The module source.
Source:
Returns:

Distinct specifiers, in source order.

Type
Array:.<string:>

(inner) edgeKey(from, to) → {string}

Keys an edge for the cyclic-edge set.

A NUL separator rather than a space, because module ids are file paths and a path may legitimately contain spaces.

Parameters:
Name Type Description
from string

Importing module id.
to string

Imported module id.
Source:
Returns:

The edge key.

Type
string

(inner) suggest(name, candidates) → {string}

Suggests the closest name to a missing one, for a diagnostic.

Parameters:
Name Type Description
name string

The name that was not found.
candidates Array:.<string:>

Names that do exist.
Source:
Returns:

A suggestion clause, or an empty string.

Type
string

Type Definitions

GraphModule

One module in the graph.

Type:
  • object
Properties:
Name Type Description
id string

Resolved module id.
source string

Module source.
format 'esm' | 'cjs'

How the module declares its exports.
record object

The parsed module structure.
resolved Map:.<string:, string:>

Specifier to resolved module id.
virtual boolean

Whether the compiler generated this module.
exportNames Set:.<string:>

Every name the module exports.
external boolean

Whether the module came from node_modules.
Source: