| 1 | import { FetchOptions } from './Fetcher';
|
| 2 | import { Project } from './Project';
|
| 3 | import { Report } from './Report';
|
| 4 | import { Descriptor, Locator, Package, DescriptorHash } from './types';
|
| 5 | export declare type MinimalResolveOptions = {
|
| 6 | project: Project;
|
| 7 | resolver: Resolver;
|
| 8 | };
|
| 9 | export declare type ResolveOptions = MinimalResolveOptions & {
|
| 10 | fetchOptions?: FetchOptions | null;
|
| 11 | report: Report;
|
| 12 | };
|
| 13 | /**
|
| 14 | * Resolvers are the components that do all the lifting needed in order to
|
| 15 | * produce a lockfile. In clear, they transfom the following:
|
| 16 | *
|
| 17 | * webpack@^4.0.0
|
| 18 | *
|
| 19 | * into this:
|
| 20 | *
|
| 21 | * webpack@4.28.0 | dependencies: ajv@^6.1.0, ajv-keyword@^3.1.0, ...
|
| 22 | *
|
| 23 | * In order to do this, they have three different data structures used to
|
| 24 | * represents the various states of the package resolution:
|
| 25 | *
|
| 26 | * - **Descriptors** contain a package name and a range (for example, using
|
| 27 | * the previous example, "^4.0.0" would be the range). This range might
|
| 28 | * point to multiple possible resolutions, so a descriptor alone isn't
|
| 29 | * enough to fetch the package data from its remote location.
|
| 30 | *
|
| 31 | * - **Locators** contain a package name and a reference that is used to
|
| 32 | * both uniquely identify a package and fetch it from its remote location.
|
| 33 | * To keep using the same example, "4.28.0" would be the reference. Note
|
| 34 | * that locators have a funny property: they also are valid descriptors!
|
| 35 | *
|
| 36 | * - **Packages** are locators that made it big. While locators are quite
|
| 37 | * small, package definitions are relatively fat and contain much more
|
| 38 | * information than their cousins - for example the dependency list of the
|
| 39 | * package.
|
| 40 | */
|
| 41 | export interface Resolver {
|
| 42 | /**
|
| 43 | * This function must return true if the specified descriptor is meant to be
|
| 44 | * turned into a locator by this resolver. The other functions (except its
|
| 45 | * locator counterpart) won't be called if it returns false.
|
| 46 | *
|
| 47 | * @param descriptor The descriptor that needs to be validated.
|
| 48 | * @param opts The resolution options.
|
| 49 | */
|
| 50 | supportsDescriptor(descriptor: Descriptor, opts: MinimalResolveOptions): boolean;
|
| 51 | /**
|
| 52 | * This function must return true if the specified locator is meant to be
|
| 53 | * turned into a package definition by this resolver. The other functions
|
| 54 | * (except its locator counterpart) won't be called if it returns false.
|
| 55 | *
|
| 56 | * @param locator The locator that needs to be validated.
|
| 57 | * @param opts The resolution options.
|
| 58 | */
|
| 59 | supportsLocator(locator: Locator, opts: MinimalResolveOptions): boolean;
|
| 60 | /**
|
| 61 | * This function indicates whether the package definition for the specified
|
| 62 | * locator must be kept between installs. You typically want to return true
|
| 63 | * for all packages that are cached, but return false for all packages that
|
| 64 | * hydrate packages directly from the filesystem (for example workspaces).
|
| 65 | *
|
| 66 | * Note that even packages returning false are stored within the lockfile!
|
| 67 | * The difference is that when a new install is done, all package definitions
|
| 68 | * that return false will be discarded and resolved again (their potential
|
| 69 | * cache data will be kept, though).
|
| 70 | *
|
| 71 | * @param locator The queried package.
|
| 72 | * @param opts The resolution options.
|
| 73 | */
|
| 74 | shouldPersistResolution(locator: Locator, opts: MinimalResolveOptions): boolean;
|
| 75 | /**
|
| 76 | * This function is called for each dependency present in the dependency list
|
| 77 | * of a package definition. If it returns a new descriptor, this new
|
| 78 | * descriptor will be used
|
| 79 | *
|
| 80 | * Note that `fromLocator` is not necessarily a locator that's supported by
|
| 81 | * the resolver. It simply is the locator of the package that depends on the
|
| 82 | * specified descriptor, regardless who owns it.
|
| 83 | *
|
| 84 | * A typical case where you will want to use this function is when your
|
| 85 | * resolver must support relative paths (for example the `link:` protocol).
|
| 86 | * In this situation, you'll want to store the `fromLocator` in the bound
|
| 87 | * descriptor in order to be able to access the right location during the
|
| 88 | * next steps of the resolution.
|
| 89 | *
|
| 90 | * @param descriptor The depended descriptor.
|
| 91 | * @param fromLocator The dependent locator.
|
| 92 | * @param opts The resolution options.
|
| 93 | */
|
| 94 | bindDescriptor(descriptor: Descriptor, fromLocator: Locator, opts: MinimalResolveOptions): Descriptor;
|
| 95 | /**
|
| 96 | * This function must return a set of other descriptors that must be
|
| 97 | * transformed into locators before the subject descriptor can be transformed
|
| 98 | * into a locator. This is typically only needed for transform packages, as
|
| 99 | * you need to know the original resolution in order to copy it.
|
| 100 | */
|
| 101 | getResolutionDependencies(descriptor: Descriptor, opts: MinimalResolveOptions): Array<Descriptor>;
|
| 102 | /**
|
| 103 | * This function will, given a descriptor, return the list of locators that
|
| 104 | * potentially satisfy it.
|
| 105 | *
|
| 106 | * The returned array must be sorted in such a way that the preferred
|
| 107 | * locators are first. This will cause the resolution algorithm to prioritize
|
| 108 | * them if possible (it doesn't guarantee that they'll end up being used).
|
| 109 | *
|
| 110 | * @param descriptor The source descriptor.
|
| 111 | * @param dependencies The resolution dependencies and their resolutions.
|
| 112 | * @param opts The resolution options.
|
| 113 | */
|
| 114 | getCandidates(descriptor: Descriptor, dependencies: Map<DescriptorHash, Package>, opts: ResolveOptions): Promise<Array<Locator>>;
|
| 115 | /**
|
| 116 | * This function will, given a descriptor and a list of locator references,
|
| 117 | * find out which of the references potentially satisfy the descriptor.
|
| 118 | *
|
| 119 | * This function is different from `getCandidates`, as `getCandidates` will
|
| 120 | * resolve the descriptor into a list of locators (potentially using the network),
|
| 121 | * while `getSatisfying` will statically compute which known references potentially
|
| 122 | * satisfy the target descriptor.
|
| 123 | *
|
| 124 | * Note that the parameter references aren't guaranteed to be supported by
|
| 125 | * the resolver, so they'll probably need to be filtered beforehand.
|
| 126 | *
|
| 127 | * The returned array must be sorted in such a way that the preferred
|
| 128 | * locators are first. This will cause the resolution algorithm to prioritize
|
| 129 | * them if possible (it doesn't guarantee that they'll end up being used).
|
| 130 | *
|
| 131 | * If the operation is unsupported by the resolver (i.e. if it can't be statically
|
| 132 | * determined which references satisfy the target descriptor), `null` should be returned.
|
| 133 | *
|
| 134 | * @param descriptor The target descriptor.
|
| 135 | * @param references The candidate references.
|
| 136 | * @param opts The resolution options.
|
| 137 | */
|
| 138 | getSatisfying(descriptor: Descriptor, references: Array<string>, opts: ResolveOptions): Promise<Array<Locator> | null>;
|
| 139 | /**
|
| 140 | * This function will, given a locator, return the full package definition
|
| 141 | * for the package pointed at.
|
| 142 | *
|
| 143 | * @param locator The source locator.
|
| 144 | * @param opts The resolution options.
|
| 145 | */
|
| 146 | resolve(locator: Locator, opts: ResolveOptions): Promise<Package>;
|
| 147 | }
|