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
-
moduleObjectThe 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
-
dependencyStringThe 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:
nameversioninstall
Parameters
-
objObjectThe 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
-
pluginObjectThe 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
-
dependencyStringThe dependency.
Returns
The plugin if resolved, otherwise undefined.
Matter.Plugin.toString
Returns a pretty printed plugin name and version.
Parameters
-
pluginObjectThe 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
-
rangeStringThe 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.