lib/models/package-info-cache/index.js:23

PackageInfoCache

Class that stores entries that are either PackageInfo or NodeModulesList objects. The entries are stored in a map keyed by real directory path.

Method Summary

Public Methods
public
assert(description, condition)

Verify that a certain condition is met, or throw an error if otherwise.
public
contains(path):

Indicate if an entry for a given path exists in the cache.
public
deprecate(description, condition, options)

Display a deprecation message.
public
getEntry(path): PackageInfo

Retrieve an entry from the cache.
public
hasErrors( ):

Indicates if there is at least one error in any object in the cache.
public
loadAddon(addonInstance): PackageInfo

Do the actual processing of the root directory of an addon, when the addon object already exists (i.e. the addon is acting as the root object of a tree, like project does). We need the object in order to find the internal addons. _readPackage takes care of the general processing of the root directory and common locations for addons, filling the cache with each.
public
loadProject(projectInstance): PackageInfo

Process the root directory of a project, given a Project object (we need the object in order to find the internal addons). _readPackage takes care of the general processing of the root directory and common locations for addons, filling the cache with each. Once it returns, we take care of the locations for addons that are specific to projects, not other packages (e.g. internal addons, cli root).
public
reloadProjects( ):

To support the project.reloadPkg method, we need the ability to flush the cache and reload from the updated package.json. There are some issues with doing this:
public
showErrors( )

Gather all the errors in the PIC and any cached objects, then dump them out to the ui-console.
Private Methods
private
_addEntry( )

Add an entry to the cache.
private
_clear( )

Clear the cache information.
private
_readModulesList(nodeModulesDir)

Process a directory of modules in a given package directory.
private
_readPackage(pkgDir, isRoot,)

Given a directory that supposedly contains a package, create a PackageInfo object and try to fill it out, EVEN IF the package.json is not readable. Errors will then be stored in the PackageInfo for anything with the package that might be wrong. Because it's possible that the path given to the packageDir is not actually valid, we'll just use the path.resolve() version of that path to search for the path in the cache, before trying to get the 'real' path (which also then resolves links). The cache itself is keyed on either the realPath, if the packageDir is actually a real valid directory path, or the normalized path (before path.resolve()), if it is not.
private
_resolveDependencies( )

Resolve the node_module dependencies across all packages after they have been loaded into the cache, because we don't know when a particular package will enter the cache.
private
_showObjErrors( )

Dump all the errors for a single object in the cache out to the ui-console.

Public Methods

lib/debug/assert.js:3

public assert(description, condition)

Verify that a certain condition is met, or throw an error if otherwise.

This is useful for communicating expectations in the code to other human readers as well as catching bugs that accidentally violate these expectations.

const { assert } = require('ember-cli/lib/debug');

// Test for truthiness:
assert('Must pass a string.', typeof str === 'string');

// Fail unconditionally:
assert('This code path should never run.');

Parameters:

Name Type Attribute Description
description String

Describes the condition. This will become the message of the error thrown if the assertion fails.
condition Any

Must be truthy for the assertion to pass. If falsy, an error will be thrown.

Indicate if an entry for a given path exists in the cache.

Parameters:

Name Type Attribute Description
path String

the real path to check for in the cache.

Return:

true if the entry is present for the given path, false otherwise.
lib/debug/deprecate.js:7

public deprecate(description, condition, options)

Display a deprecation message.

const { deprecate } = require('ember-cli/lib/debug');

deprecate('The foo method is deprecated.', false, {
  for: 'ember-cli',
  id: 'ember-cli.foo-method',
  since: {
    available: '4.1.0',
    enabled: '4.2.0',
  },
  until: '5.0.0',
  url: 'https://example.com',
});

Parameters:

Name Type Attribute Description
description String

Describes the deprecation.
condition Any

If falsy, the deprecation message will be displayed.
options Object

An object including the deprecation's details:

  • for The library that the deprecation is for
  • id The deprecation's unique id
  • since.available A SemVer version indicating when the deprecation was made available
  • since.enabled A SemVer version indicating when the deprecation was enabled
  • until A SemVer version indicating until when the deprecation will be active
  • url A URL that refers to additional information about the deprecation

Retrieve an entry from the cache.

Parameters:

Name Type Attribute Description
path String

the real path whose PackageInfo or NodeModulesList is desired.

Return:

PackageInfo

or {NodeModulesList} the desired entry.

Indicates if there is at least one error in any object in the cache.

Return:

true if there are any errors in the cache, for any entries, else false.
lib/models/package-info-cache/index.js:228

public loadAddon(addonInstance): PackageInfo

Do the actual processing of the root directory of an addon, when the addon object already exists (i.e. the addon is acting as the root object of a tree, like project does). We need the object in order to find the internal addons. _readPackage takes care of the general processing of the root directory and common locations for addons, filling the cache with each.

Once all the addon processing is done, go back through all cache entries to create references between the packageInfo objects.

Parameters:

Name Type Attribute Description
addonInstance Object

the instance of the Addon object to load package data about into the cache.

Return:

PackageInfo

the PackageInfo object for the given Addon object. Note that if the addon path is already in the cache, that will be returned. No copy is made.
lib/models/package-info-cache/index.js:146

public loadProject(projectInstance): PackageInfo

Process the root directory of a project, given a Project object (we need the object in order to find the internal addons). _readPackage takes care of the general processing of the root directory and common locations for addons, filling the cache with each. Once it returns, we take care of the locations for addons that are specific to projects, not other packages (e.g. internal addons, cli root).

Once all the project processing is done, go back through all cache entries to create references between the packageInfo objects.

Parameters:

Name Type Attribute Description
projectInstance Object

the instance of the Project object to load package data about into the cache.

Return:

PackageInfo

the PackageInfo object for the given Project object. Note that if the project path is already in the cache, that will be returned. No copy is made.
lib/models/package-info-cache/index.js:203

public reloadProjects( ):

To support the project.reloadPkg method, we need the ability to flush the cache and reload from the updated package.json. There are some issues with doing this:

  • Because of the possible relationship between projects and their addons due to symlinks, it's not trivial to flush only the data related to a given project.
  • If an 'ember-build-cli.js' dynamically adds new projects to the cache, we will not necessarily get called again to redo the loading of those projects. The solution, implemented here:
  • Keep track of the Project objects whose packages are loaded into the cache.
  • If a project is reloaded, flush the cache, then do loadPackage again for all the known Projects.

Return:

null

Gather all the errors in the PIC and any cached objects, then dump them out to the ui-console.

Private Methods

lib/models/package-info-cache/index.js:299

private _addEntry( )

Add an entry to the cache.

lib/models/package-info-cache/index.js:36

private _clear( )

Clear the cache information.

lib/models/package-info-cache/index.js:585

private _readModulesList(nodeModulesDir)

Process a directory of modules in a given package directory.

We will allow cache entries for node_modules that actually have no contents, just so we don't have to hit the file system more often than necessary--it's much quicker to check an in-memory object. object.

Note: only a NodeModulesList or null is returned.

Parameters:

Name Type Attribute Description
nodeModulesDir String

the path of the node_modules directory to read the package.json from and process the contents and create a new cache entry or entries.
lib/models/package-info-cache/index.js:395

private _readPackage(pkgDir, isRoot,)

Given a directory that supposedly contains a package, create a PackageInfo object and try to fill it out, EVEN IF the package.json is not readable. Errors will then be stored in the PackageInfo for anything with the package that might be wrong. Because it's possible that the path given to the packageDir is not actually valid, we'll just use the path.resolve() version of that path to search for the path in the cache, before trying to get the 'real' path (which also then resolves links). The cache itself is keyed on either the realPath, if the packageDir is actually a real valid directory path, or the normalized path (before path.resolve()), if it is not.

NOTE: the cache is also used to store the NULL_PROJECT project object, which actually has no package.json or other files, but does have an empty package object. Because of that, and to speed up processing, loadProject() will pass in both the package root directory path and the project's package object, if there is one. If the package object is present, we will use that in preference to trying to find a package.json file.

If there is no package object, and there is no package.json or the package.json is bad or the package is an addon with no main, the only thing we can do is return an ErrorEntry to the caller. Once past all those problems, if any error occurs with any of the contents of the package, they'll be cached in the PackageInfo itself.

In summary, only PackageInfo or ErrorEntry will be returned.

Parameters:

Name Type Attribute Description
pkgDir String

the path of the directory to read the package.json from and process the contents and create a new cache entry or entries.
isRoot, Boolean

for when this is to be considered the root package, whose dependencies we must all consider for discovery.
lib/models/package-info-cache/index.js:262

private _resolveDependencies( )

Resolve the node_module dependencies across all packages after they have been loaded into the cache, because we don't know when a particular package will enter the cache.

Since loadProject can be called multiple times for different projects, we don't want to reprocess any packages that happen to be common between them. We'll handle this by marking any packageInfo once it has been processed here, then ignore it in any later processing.

lib/models/package-info-cache/index.js:80

private _showObjErrors( )

Dump all the errors for a single object in the cache out to the ui-console.

Special case: because package-info-cache also creates PackageInfo objects for entries that do not actually exist (to allow simplifying the code), if there's a case where an object has only the single error ERROR_PACKAGE_DIR_MISSING, do not print anything. The package will have been found as a reference from some other addon or the root project, and we'll print a reference error there. Having both is just confusing to users.