Skip to main content

FileResolver

Resolvers are the components that do all the lifting needed in order to produce a lockfile. In clear, they transfom the following:

webpack@^4.0.0

into this:

webpack@4.28.0 | dependencies: ajv@^6.1.0, ajv-keyword@^3.1.0, ...

In order to do this, they have three different data structures used to represents the various states of the package resolution:

  • Descriptors contain a package name and a range (for example, using the previous example, "^4.0.0" would be the range). This range might point to multiple possible resolutions, so a descriptor alone isn't enough to fetch the package data from its remote location.
  • Locators contain a package name and a reference that is used to both uniquely identify a package and fetch it from its remote location. To keep using the same example, "4.28.0" would be the reference. Note that locators have a funny property: they also are valid descriptors!
  • Packages are locators that made it big. While locators are quite small, package definitions are relatively fat and contain much more information than their cousins - for example the dependency list of the package.

Implements

Index

Constructors

Methods

Constructors

constructor

Methods

bindDescriptor

  • This function is called for each dependency present in the dependency list of a package definition. If it returns a new descriptor, this new descriptor will be used

    Note that fromLocator is not necessarily a locator that's supported by the resolver. It simply is the locator of the package that depends on the specified descriptor, regardless who owns it.

    A typical case where you will want to use this function is when your resolver must support relative paths (for example the link: protocol). In this situation, you'll want to store the fromLocator in the bound descriptor in order to be able to access the right location during the next steps of the resolution.

    Parameters

    Returns Descriptor

getCandidates

  • This function will, given a descriptor, return the list of locators that potentially satisfy it.

    The returned array must be sorted in such a way that the preferred locators are first. This will cause the resolution algorithm to prioritize them if possible (it doesn't guarantee that they'll end up being used).

    Parameters

    • descriptor: Descriptor

      The source descriptor.

    • dependencies: unknown

      The resolution dependencies and their resolutions.

    • opts: ResolveOptions

      The resolution options.

    Returns Promise<Locator[]>

getResolutionDependencies

  • This function must return a set of other descriptors that must be transformed into locators before the subject descriptor can be transformed into a locator. This is typically only needed for transform packages, as you need to know the original resolution in order to copy it.

    Parameters

    Returns {}

    getSatisfying

    • This function will, given a descriptor and a list of locators, find out which of the locators potentially satisfy the descriptor.

      This function is different from getCandidates, as getCandidates will resolve the descriptor into a list of locators (potentially using the network), while getSatisfying will statically compute which known references potentially satisfy the target descriptor.

      Note that the parameter references aren't guaranteed to be supported by the resolver, so they'll probably need to be filtered beforehand.

      The returned array should be sorted in such a way that the preferred locators are first. This will cause the resolution algorithm to prioritize them if possible (it doesn't guarantee that they'll end up being used). If the resolver is unable to provide a definite order (for example like the file: protocol resolver, where ordering references would make no sense), the sorted field should be set to false.

      Parameters

      • descriptor: Descriptor

        The target descriptor.

      • dependencies: Record<string, Package>

        The resolution dependencies and their resolutions.

      • locators: Locator[]

        The candidate locators.

      • opts: ResolveOptions

        The resolution options.

      Returns Promise<{ locators: Locator[]; sorted: boolean }>

    resolve

    • This function will, given a locator, return the full package definition for the package pointed at.

      Parameters

      Returns Promise<{ bin: Map<string, PortablePath>; conditions: null | string; dependencies: Map<IdentHash, Descriptor>; dependenciesMeta: Map<string, Map<null | string, DependencyMeta>>; identHash: IdentHash; languageName: string; linkType: LinkType; locatorHash: LocatorHash; name: string; peerDependencies: Map<IdentHash, Descriptor>; peerDependenciesMeta: Map<string, PeerDependencyMeta>; reference: string; scope: null | string; version: string }>

    shouldPersistResolution

    • This function indicates whether the package definition for the specified locator must be kept between installs. You typically want to return true for all packages that are cached, but return false for all packages that hydrate packages directly from the filesystem (for example workspaces).

      Note that even packages returning false are stored within the lockfile! The difference is that when a new install is done, all package definitions that return false will be discarded and resolved again (their potential cache data will be kept, though).

      Parameters

      Returns boolean

    supportsDescriptor

    • This function must return true if the specified descriptor is meant to be turned into a locator by this resolver. The other functions (except its locator counterpart) won't be called if it returns false.

      Parameters

      Returns boolean

    supportsLocator

    • This function must return true if the specified locator is meant to be turned into a package definition by this resolver. The other functions (except its locator counterpart) won't be called if it returns false.

      Parameters

      Returns boolean