[6a3a178] | 1 | /// <amd-module name="@angular/compiler-cli/ngcc/src/packages/configuration" />
|
---|
| 2 | import { AbsoluteFsPath, PathManipulation, ReadonlyFileSystem } from '../../../src/ngtsc/file_system';
|
---|
| 3 | import { PackageJsonFormatPropertiesMap } from './entry_point';
|
---|
| 4 | /**
|
---|
| 5 | * The format of a project level configuration file.
|
---|
| 6 | */
|
---|
| 7 | export interface NgccProjectConfig {
|
---|
| 8 | /**
|
---|
| 9 | * The packages that are configured by this project config.
|
---|
| 10 | */
|
---|
| 11 | packages?: {
|
---|
| 12 | [packagePath: string]: RawNgccPackageConfig | undefined;
|
---|
| 13 | };
|
---|
| 14 | /**
|
---|
| 15 | * Options that control how locking the process is handled.
|
---|
| 16 | */
|
---|
| 17 | locking?: ProcessLockingConfiguration;
|
---|
| 18 | /**
|
---|
| 19 | * Name of hash algorithm used to generate hashes of the configuration.
|
---|
| 20 | *
|
---|
| 21 | * Defaults to `sha256`.
|
---|
| 22 | */
|
---|
| 23 | hashAlgorithm?: string;
|
---|
| 24 | }
|
---|
| 25 | /**
|
---|
| 26 | * Options that control how locking the process is handled.
|
---|
| 27 | */
|
---|
| 28 | export interface ProcessLockingConfiguration {
|
---|
| 29 | /**
|
---|
| 30 | * The number of times the AsyncLocker will attempt to lock the process before failing.
|
---|
| 31 | * Defaults to 500.
|
---|
| 32 | */
|
---|
| 33 | retryAttempts?: number;
|
---|
| 34 | /**
|
---|
| 35 | * The number of milliseconds between attempts to lock the process.
|
---|
| 36 | * Defaults to 500ms.
|
---|
| 37 | * */
|
---|
| 38 | retryDelay?: number;
|
---|
| 39 | }
|
---|
| 40 | /**
|
---|
| 41 | * The raw format of a package level configuration (as it appears in configuration files).
|
---|
| 42 | */
|
---|
| 43 | export interface RawNgccPackageConfig {
|
---|
| 44 | /**
|
---|
| 45 | * The entry-points to configure for this package.
|
---|
| 46 | *
|
---|
| 47 | * In the config file the keys are paths relative to the package path.
|
---|
| 48 | */
|
---|
| 49 | entryPoints?: {
|
---|
| 50 | [entryPointPath: string]: NgccEntryPointConfig;
|
---|
| 51 | };
|
---|
| 52 | /**
|
---|
| 53 | * A collection of regexes that match deep imports to ignore, for this package, rather than
|
---|
| 54 | * displaying a warning.
|
---|
| 55 | */
|
---|
| 56 | ignorableDeepImportMatchers?: RegExp[];
|
---|
| 57 | }
|
---|
| 58 | /**
|
---|
| 59 | * Configuration options for an entry-point.
|
---|
| 60 | *
|
---|
| 61 | * The existence of a configuration for a path tells ngcc that this should be considered for
|
---|
| 62 | * processing as an entry-point.
|
---|
| 63 | */
|
---|
| 64 | export interface NgccEntryPointConfig {
|
---|
| 65 | /** Do not process (or even acknowledge the existence of) this entry-point, if true. */
|
---|
| 66 | ignore?: boolean;
|
---|
| 67 | /**
|
---|
| 68 | * This property, if provided, holds values that will override equivalent properties in an
|
---|
| 69 | * entry-point's package.json file.
|
---|
| 70 | */
|
---|
| 71 | override?: PackageJsonFormatPropertiesMap;
|
---|
| 72 | /**
|
---|
| 73 | * Normally, ngcc will skip compilation of entrypoints that contain imports that can't be resolved
|
---|
| 74 | * or understood. If this option is specified, ngcc will proceed with compiling the entrypoint
|
---|
| 75 | * even in the face of such missing dependencies.
|
---|
| 76 | */
|
---|
| 77 | ignoreMissingDependencies?: boolean;
|
---|
| 78 | /**
|
---|
| 79 | * Enabling this option for an entrypoint tells ngcc that deep imports might be used for the files
|
---|
| 80 | * it contains, and that it should generate private re-exports alongside the NgModule of all the
|
---|
| 81 | * directives/pipes it makes available in support of those imports.
|
---|
| 82 | */
|
---|
| 83 | generateDeepReexports?: boolean;
|
---|
| 84 | }
|
---|
| 85 | interface VersionedPackageConfig extends RawNgccPackageConfig {
|
---|
| 86 | versionRange: string;
|
---|
| 87 | }
|
---|
| 88 | /**
|
---|
| 89 | * The internal representation of a configuration file. Configured packages are transformed into
|
---|
| 90 | * `ProcessedNgccPackageConfig` when a certain version is requested.
|
---|
| 91 | */
|
---|
| 92 | export declare class PartiallyProcessedConfig {
|
---|
| 93 | /**
|
---|
| 94 | * The packages that are configured by this project config, keyed by package name.
|
---|
| 95 | */
|
---|
| 96 | packages: Map<string, VersionedPackageConfig[]>;
|
---|
| 97 | /**
|
---|
| 98 | * Options that control how locking the process is handled.
|
---|
| 99 | */
|
---|
| 100 | locking: ProcessLockingConfiguration;
|
---|
| 101 | /**
|
---|
| 102 | * Name of hash algorithm used to generate hashes of the configuration.
|
---|
| 103 | *
|
---|
| 104 | * Defaults to `sha256`.
|
---|
| 105 | */
|
---|
| 106 | hashAlgorithm: string;
|
---|
| 107 | constructor(projectConfig: NgccProjectConfig);
|
---|
| 108 | private splitNameAndVersion;
|
---|
| 109 | /**
|
---|
| 110 | * Registers the configuration for a particular version of the provided package.
|
---|
| 111 | */
|
---|
| 112 | private addPackageConfig;
|
---|
| 113 | /**
|
---|
| 114 | * Finds the configuration for a particular version of the provided package.
|
---|
| 115 | */
|
---|
| 116 | findPackageConfig(packageName: string, version: string | null): VersionedPackageConfig | null;
|
---|
| 117 | /**
|
---|
| 118 | * Converts the configuration into a JSON representation that is used to compute a hash of the
|
---|
| 119 | * configuration.
|
---|
| 120 | */
|
---|
| 121 | toJson(): string;
|
---|
| 122 | }
|
---|
| 123 | /**
|
---|
| 124 | * The default configuration for ngcc.
|
---|
| 125 | *
|
---|
| 126 | * This is the ultimate fallback configuration that ngcc will use if there is no configuration
|
---|
| 127 | * for a package at the package level or project level.
|
---|
| 128 | *
|
---|
| 129 | * This configuration is for packages that are "dead" - i.e. no longer maintained and so are
|
---|
| 130 | * unlikely to be fixed to work with ngcc, nor provide a package level config of their own.
|
---|
| 131 | *
|
---|
| 132 | * The fallback process for looking up configuration is:
|
---|
| 133 | *
|
---|
| 134 | * Project -> Package -> Default
|
---|
| 135 | *
|
---|
| 136 | * If a package provides its own configuration then that would override this default one.
|
---|
| 137 | *
|
---|
| 138 | * Also application developers can always provide configuration at their project level which
|
---|
| 139 | * will override everything else.
|
---|
| 140 | *
|
---|
| 141 | * Note that the fallback is package based not entry-point based.
|
---|
| 142 | * For example, if a there is configuration for a package at the project level this will replace all
|
---|
| 143 | * entry-point configurations that may have been provided in the package level or default level
|
---|
| 144 | * configurations, even if the project level configuration does not provide for a given entry-point.
|
---|
| 145 | */
|
---|
| 146 | export declare const DEFAULT_NGCC_CONFIG: NgccProjectConfig;
|
---|
| 147 | /**
|
---|
| 148 | * The processed package level configuration as a result of processing a raw package level config.
|
---|
| 149 | */
|
---|
| 150 | export declare class ProcessedNgccPackageConfig implements Omit<RawNgccPackageConfig, 'entryPoints'> {
|
---|
| 151 | /**
|
---|
| 152 | * The absolute path to this instance of the package.
|
---|
| 153 | * Note that there may be multiple instances of a package inside a project in nested
|
---|
| 154 | * `node_modules/`. For example, one at `<project-root>/node_modules/some-package/` and one at
|
---|
| 155 | * `<project-root>/node_modules/other-package/node_modules/some-package/`.
|
---|
| 156 | */
|
---|
| 157 | packagePath: AbsoluteFsPath;
|
---|
| 158 | /**
|
---|
| 159 | * The entry-points to configure for this package.
|
---|
| 160 | *
|
---|
| 161 | * In contrast to `RawNgccPackageConfig`, the paths are absolute and take the path of the specific
|
---|
| 162 | * instance of the package into account.
|
---|
| 163 | */
|
---|
| 164 | entryPoints: Map<AbsoluteFsPath, NgccEntryPointConfig>;
|
---|
| 165 | /**
|
---|
| 166 | * A collection of regexes that match deep imports to ignore, for this package, rather than
|
---|
| 167 | * displaying a warning.
|
---|
| 168 | */
|
---|
| 169 | ignorableDeepImportMatchers: RegExp[];
|
---|
| 170 | constructor(fs: PathManipulation, packagePath: AbsoluteFsPath, { entryPoints, ignorableDeepImportMatchers, }: RawNgccPackageConfig);
|
---|
| 171 | }
|
---|
| 172 | /**
|
---|
| 173 | * Ngcc has a hierarchical configuration system that lets us "fix up" packages that do not
|
---|
| 174 | * work with ngcc out of the box.
|
---|
| 175 | *
|
---|
| 176 | * There are three levels at which configuration can be declared:
|
---|
| 177 | *
|
---|
| 178 | * * Default level - ngcc comes with built-in configuration for well known cases.
|
---|
| 179 | * * Package level - a library author publishes a configuration with their package to fix known
|
---|
| 180 | * issues.
|
---|
| 181 | * * Project level - the application developer provides a configuration that fixes issues specific
|
---|
| 182 | * to the libraries used in their application.
|
---|
| 183 | *
|
---|
| 184 | * Ngcc will match configuration based on the package name but also on its version. This allows
|
---|
| 185 | * configuration to provide different fixes to different version ranges of a package.
|
---|
| 186 | *
|
---|
| 187 | * * Package level configuration is specific to the package version where the configuration is
|
---|
| 188 | * found.
|
---|
| 189 | * * Default and project level configuration should provide version ranges to ensure that the
|
---|
| 190 | * configuration is only applied to the appropriate versions of a package.
|
---|
| 191 | *
|
---|
| 192 | * When getting a configuration for a package (via `getConfig()`) the caller should provide the
|
---|
| 193 | * version of the package in question, if available. If it is not provided then the first available
|
---|
| 194 | * configuration for a package is returned.
|
---|
| 195 | */
|
---|
| 196 | export declare class NgccConfiguration {
|
---|
| 197 | private fs;
|
---|
| 198 | private defaultConfig;
|
---|
| 199 | private projectConfig;
|
---|
| 200 | private cache;
|
---|
| 201 | readonly hash: string;
|
---|
| 202 | readonly hashAlgorithm: string;
|
---|
| 203 | constructor(fs: ReadonlyFileSystem, baseDir: AbsoluteFsPath);
|
---|
| 204 | /**
|
---|
| 205 | * Get the configuration options for locking the ngcc process.
|
---|
| 206 | */
|
---|
| 207 | getLockingConfig(): Required<ProcessLockingConfiguration>;
|
---|
| 208 | /**
|
---|
| 209 | * Get a configuration for the given `version` of a package at `packagePath`.
|
---|
| 210 | *
|
---|
| 211 | * @param packageName The name of the package whose config we want.
|
---|
| 212 | * @param packagePath The path to the package whose config we want.
|
---|
| 213 | * @param version The version of the package whose config we want, or `null` if the package's
|
---|
| 214 | * package.json did not exist or was invalid.
|
---|
| 215 | */
|
---|
| 216 | getPackageConfig(packageName: string, packagePath: AbsoluteFsPath, version: string | null): ProcessedNgccPackageConfig;
|
---|
| 217 | private getRawPackageConfig;
|
---|
| 218 | private loadProjectConfig;
|
---|
| 219 | private loadPackageConfig;
|
---|
| 220 | private evalSrcFile;
|
---|
| 221 | private computeHash;
|
---|
| 222 | }
|
---|
| 223 | export {};
|
---|