README.md

@gasket/resolve

Essential module resolution and configuration management for gasket plugins and presets.

API Reference

Classes

Loader : Loader

Utility to load plugins, presets, and other modules with associated metadata

PackageIdentifier : PackageIdentifier

Utility class for working with package names and versions

Resolver : Resolver

Utility to help resolve and require modules

Functions

pluginIdentifier(name) ⇒ PackageIdentifier

Package identifier for work with plugin name

presetIdentifier(name) ⇒ PackageIdentifier

Package identifier for work with preset name

Typedefs

ModuleInfo : Object

Module with meta data

PluginInfo : ModuleInfo

Plugin module with meta data

PresetInfo : ModuleInfo

Preset module with meta data

PluginDesc : String

The package name with or without version of a plugin.

For example:

• @gasket/jest-plugin - fullName
• jest - shortName
• @gasket/jest-plugin@^1.2.3 - full with version
• jest@^1.2.3 - short with version

Not intended for use with non-plugin package descriptions. For example, the following patterns will not work:

• @gasket/jest

PresetDesc : String

The package name with or without version of a preset.

For example:

• @gasket/default-preset - fullName
• default - shortName
• @gasket/default-preset@^1.2.3 - full with version
• default@^1.2.3 - short with version

PluginName : String

The package name only of a plugin.

For example:

• @gasket/jest-plugin - fullName
• jest - shortName

PresetName : String

The package name only of a preset.

For example:

• @gasket/default-preset - fullName
• default - shortName

Loader : Loader

Utility to load plugins, presets, and other modules with associated metadata

Kind: global class
Extends: Resolver

• Loader : Loader
  • .getModuleInfo(module, moduleName, [meta]) ⇒ ModuleInfo
  • .loadModule(moduleName, [meta]) ⇒ ModuleInfo
  • .loadPlugin(module, [meta]) ⇒ PluginInfo
  • .loadPreset(module, [meta], [options]) ⇒ PresetInfo
  • .loadConfigured(config) ⇒ Object
  • .resolve(moduleName) ⇒ String
  • .require(moduleName) ⇒ Object
  • .tryResolve(moduleName) ⇒ String | null
  • .tryRequire(moduleName) ⇒ Object | null

loader.getModuleInfo(module, moduleName, [meta]) ⇒ ModuleInfo

Loads a module with additional metadata

Kind: instance method of Loader
Returns: ModuleInfo - module

Param	Type	Description
module	String	Module content
moduleName	String	Name of module to load
[meta]	Object	Additional meta data

loader.loadModule(moduleName, [meta]) ⇒ ModuleInfo

Loads a module with additional metadata

Kind: instance method of Loader
Returns: ModuleInfo - module

Param	Type	Description
moduleName	String	Name of module to load
[meta]	Object	Additional meta data

loader.loadPlugin(module, [meta]) ⇒ PluginInfo

Loads a plugin with additional metadata.

Kind: instance method of Loader
Returns: PluginInfo - module

Param	Type	Description
module	PluginName | Object	Name of module to load (or module content)
[meta]	Object	Additional meta data

loader.loadPreset(module, [meta], [options]) ⇒ PresetInfo

Loads a preset with additional metadata

Kind: instance method of Loader
Returns: PresetInfo - module

Param	Type	Description
module	PresetName	Name of module to load
[meta]	Object	Additional meta data
[options]	Boolean	Loading options
[options.shallow]	Boolean	Do not recursively load dependencies

loader.loadConfigured(config) ⇒ Object

Loads presets and plugins as configured. Plugins will be filtered and ordered as configuration with priority of:

• added plugins > preset plugins > nested preset plugins

Kind: instance method of Loader
Returns: Object - results

Param	Type	Description
config	Object	Presets and plugins to load
config.presets	Array.<PresetName>	Presets to load and add plugins from
config.add	Array.<PluginName> | Array.<module>	Names of plugins to load
config.remove	Array.<string>	Names of plugins to remove (from presets)

loader.resolve(moduleName) ⇒ String

Returns the resolved module filename

Kind: instance method of Loader
Overrides: resolve
Returns: String - filename of the module

Param	Type	Description
moduleName	String	name of the module

loader.require(moduleName) ⇒ Object

Returns the required module

Kind: instance method of Loader
Overrides: require
Returns: Object - module contents

Param	Type	Description
moduleName	String	name of the module

loader.tryResolve(moduleName) ⇒ String | null

Returns the resolved module filename, or null if not found

Kind: instance method of Loader
Overrides: tryResolve
Returns: String | null - filename of the module

Param	Type	Description
moduleName	String	name of the module

loader.tryRequire(moduleName) ⇒ Object | null

Returns the required module, or null if not found

Kind: instance method of Loader
Overrides: tryRequire
Returns: Object | null - module contents

Param	Type	Description
moduleName	String	name of the module

PackageIdentifier : PackageIdentifier

Utility class for working with package names and versions

Kind: global class

• PackageIdentifier : PackageIdentifier
  • new PackageIdentifier(rawName, suffix)
  • .fullName ⇒ string
  • .shortName ⇒ string
  • .name ⇒ string
  • .version ⇒ string
  • .full ⇒ string
  • .withVersion([defaultVersion]) ⇒ PackageIdentifier
  • .toString() ⇒ String

new PackageIdentifier(rawName, suffix)

Create a new package identifier instance

Param	Type	Description
rawName	String	Original input name of a package
suffix	String	suffix for special package names (-preset, or -plugin)

packageIdentifier.fullName ⇒ string

Get the full package name

Examples:

• @gasket/https-plugin@1.2.3 -> @gasket/https-plugin
• https -> @gasket/https-plugin

Kind: instance property of PackageIdentifier
Returns: string - fullName

packageIdentifier.shortName ⇒ string

Get the short package name

Examples:

• @gasket/https-plugin -> https
• https@1.2.3 -> https

Kind: instance property of PackageIdentifier
Returns: string - fullName

packageIdentifier.name ⇒ string

Get only the package name

Examples:

• @gasket/https-plugin@1.2.3 -> @gasket/https-plugin
• https@1.2.3 -> https

Kind: instance property of PackageIdentifier
Returns: string - fullName

packageIdentifier.version ⇒ string

Get only the package version

Examples:

• @gasket/https-plugin@1.2.3 -> 1.2.3
• @gasket/https-plugin -> ''

Kind: instance property of PackageIdentifier
Returns: string - fullName

packageIdentifier.full ⇒ string

Get the full package name with version

Examples:

• @gasket/https-plugin@1.2.3 -> @gasket/https-plugin@1.2.3
• https@1.2.3 -> @gasket/https-plugin@1.2.3

Kind: instance property of PackageIdentifier
Returns: string - fullName

packageIdentifier.withVersion([defaultVersion]) ⇒ PackageIdentifier

Returns new PackageIdentifier with version added to desc if missing

Examples:

• @gasket/https-plugin@1.2.3 -> @gasket/https-plugin@1.2.3
• @gasket/https-plugin -> @gasket/https-plugin@latest

Kind: instance method of PackageIdentifier
Returns: PackageIdentifier - identifier

Param	Type	Default	Description
[defaultVersion]	string	"latest"	the version name to add if missing

packageIdentifier.toString() ⇒ String

Output the original raw name for string concatenation.

Kind: instance method of PackageIdentifier
Returns: String - string

Resolver : Resolver

Utility to help resolve and require modules

Kind: global class

• Resolver : Resolver
  • new Resolver(options)
  • .resolve(moduleName) ⇒ String
  • .require(moduleName) ⇒ Object
  • .tryResolve(moduleName) ⇒ String | null
  • .tryRequire(moduleName) ⇒ Object | null

new Resolver(options)

Param	Type	Description
options	Object	Options
[options.resolveFrom]	String | Array.<String>	Path(s) to resolve modules from
[options.require]	require	Require instance to use

resolver.resolve(moduleName) ⇒ String

Returns the resolved module filename

Kind: instance method of Resolver
Returns: String - filename of the module

Param	Type	Description
moduleName	String	name of the module

resolver.require(moduleName) ⇒ Object

Returns the required module

Kind: instance method of Resolver
Returns: Object - module contents

Param	Type	Description
moduleName	String	name of the module

resolver.tryResolve(moduleName) ⇒ String | null

Returns the resolved module filename, or null if not found

Kind: instance method of Resolver
Returns: String | null - filename of the module

Param	Type	Description
moduleName	String	name of the module

resolver.tryRequire(moduleName) ⇒ Object | null

Returns the required module, or null if not found

Kind: instance method of Resolver
Returns: Object | null - module contents

Param	Type	Description
moduleName	String	name of the module

pluginIdentifier(name) ⇒ PackageIdentifier

Package identifier for work with plugin name

Kind: global function
Returns: PackageIdentifier - identifier

Param	Type	Description
name	PluginDesc	Name of the plugin package

pluginIdentifier.isValidFullName(maybeFullName) ⇒ boolean

Util method to check if a full name is valid

Examples:

• @gasket/https-plugin -> true
• @gasket/https-plugin@1.2.3 -> false
• https -> false

Kind: static method of pluginIdentifier
Returns: boolean - fullName

Param	Type	Description
maybeFullName	string	Name to check

presetIdentifier(name) ⇒ PackageIdentifier

Package identifier for work with preset name

Kind: global function
Returns: PackageIdentifier - identifier

Param	Type	Description
name	PresetDesc	Name of the preset package

presetIdentifier.isValidFullName(maybeFullName) ⇒ boolean

Util method to check if a full name is valid

Examples:

• @gasket/nextjs-preset -> true
• @gasket/nextjs-preset@1.2.3 -> false
• nextjs -> false

Kind: static method of presetIdentifier
Returns: boolean - fullName

Param	Type	Description
maybeFullName	string	Name to check

ModuleInfo : Object

Module with meta data

Kind: global typedef
Properties

Name	Type	Description
name	String	Name of preset
module	String	Actual module content
[package]	String	Package.json contents
[version]	String	Resolved version
[path]	String	Path to the root of package
[from]	String	Name of module which requires this module
[range]	String	Range by which this module was required

PluginInfo : ModuleInfo

Plugin module with meta data

Kind: global typedef

PresetInfo : ModuleInfo

Preset module with meta data

Kind: global typedef
Properties

Name	Type	Description
presets	Array.<PresetInfo>	Presets that this preset extends
plugins	Array.<PluginInfo>	Plugins this preset uses

PluginDesc : String

The package name with or without version of a plugin.

For example:

• @gasket/jest-plugin - fullName
• jest - shortName
• @gasket/jest-plugin@^1.2.3 - full with version
• jest@^1.2.3 - short with version

Not intended for use with non-plugin package descriptions. For example, the following patterns will not work:

• @gasket/jest

Kind: global typedef

PresetDesc : String

The package name with or without version of a preset.

For example:

• @gasket/default-preset - fullName
• default - shortName
• @gasket/default-preset@^1.2.3 - full with version
• default@^1.2.3 - short with version

Kind: global typedef

PluginName : String

The package name only of a plugin.

For example:

• @gasket/jest-plugin - fullName
• jest - shortName

Kind: global typedef

PresetName : String

The package name only of a preset.

For example:

• @gasket/default-preset - fullName
• default - shortName

Kind: global typedef