Matter.Plugin
The Matter.Plugin
module contains functions for registering and installing plugins on modules.
Methods
Matter.Plugin.dependencies
Recursively finds all of a module's dependencies and returns a flat dependency graph.
Parameters
-
module
ObjectThe module.
Returns
A dependency graph.
Matter.Plugin.dependencyParse
Parses a dependency string into its components.
The dependency
is a string of the format 'module-name'
or 'module-name@version'
.
See documentation for Plugin.versionParse
for a description of the format.
This function can also handle dependencies that are already resolved (e.g. a module object).
Parameters
-
dependency
StringThe dependency of the format
'module-name'
or'module-name@version'
.
Returns
The dependency parsed into its components.
Matter.Plugin.isFor
Returns true
if plugin.for
is applicable to module
by comparing against module.name
and module.version
.
If plugin.for
is not specified then it is assumed to be applicable.
The value of plugin.for
is a string of the format 'module-name'
or 'module-name@version'
.
Returns
true
if plugin.for
is applicable to module
, otherwise false
.
Matter.Plugin.isPlugin
Returns true
if the object meets the minimum standard to be considered a plugin.
This means it must define the following properties:
name
version
install
Parameters
-
obj
ObjectThe obj to test.
Returns
true
if the object can be considered a plugin otherwise false
.
Matter.Plugin.isUsed
Returns true
if a plugin with the given name
been installed on module
.
Returns
true
if a plugin with the given name
been installed on module
, otherwise false
.
Matter.Plugin.register
Registers a plugin object so it can be resolved later by name.
Parameters
-
plugin
ObjectThe plugin to register.
Returns
The plugin.
Matter.Plugin.resolve
Resolves a dependency to a plugin object from the registry if it exists.
The dependency
may contain a version, but only the name matters when resolving.
Parameters
-
dependency
StringThe dependency.
Returns
The plugin if resolved, otherwise undefined
.
Matter.Plugin.toString
Returns a pretty printed plugin name and version.
Parameters
-
plugin
ObjectThe plugin.
Returns
Pretty printed plugin name and version.
Matter.Plugin.use
Installs the plugins by calling plugin.install
on each plugin specified in plugins
if passed, otherwise module.uses
.
For installing plugins on Matter
see the convenience function Matter.use
.
Plugins may be specified either by their name or a reference to the plugin object.
Plugins themselves may specify further dependencies, but each plugin is installed only once.
Order is important, a topological sort is performed to find the best resulting order of installation.
This sorting attempts to satisfy every dependency's requested ordering, but may not be exact in all cases.
This function logs the resulting status of each dependency in the console, along with any warnings.
- A green tick ✅ indicates a dependency was resolved and installed.
- An orange diamond 🔶 indicates a dependency was resolved but a warning was thrown for it or one if its dependencies.
- A red cross ❌ indicates a dependency could not be resolved. Avoid calling this function multiple times on the same module unless you intend to manually control installation order.
Parameters
Matter.Plugin.versionParse
Parses a version string into its components.
Versions are strictly of the format x.y.z
(as in semver).
Versions may optionally have a prerelease tag in the format x.y.z-alpha
.
Ranges are a strict subset of npm ranges.
Only the following range types are supported:
- Tilde ranges e.g.
~1.2.3
- Caret ranges e.g.
^1.2.3
- Greater than ranges e.g.
>1.2.3
- Greater than or equal ranges e.g.
>=1.2.3
- Exact version e.g.
1.2.3
- Any version
*
Parameters
-
range
StringThe version string.
Returns
The version range parsed into its components.
Matter.Plugin.versionSatisfies
Returns true
if version
satisfies the given range
.
See documentation for Plugin.versionParse
for a description of the format.
If a version or range is not specified, then any version (*
) is assumed to satisfy.
Returns
true
if version
satisfies range
, otherwise false
.