@salesforce/core

import { Dictionary, JsonMap, Nullable, Optional } from '@salesforce/ts-types'; import { PackageDir, ProjectJson as ProjectJsonSchema, PackagePackageDir } from '@salesforce/schemas'; import { ConfigFile } from './config/configFile'; import { ConfigContents } from './config/configStackTypes'; type NameAndFullPath = { /** * The [normalized](https://nodejs.org/api/path.html#path_path_normalize_path) path used as the package name. */ name: string; /** * The absolute path of the package. */ fullPath: string; }; export type NamedPackagingDir = PackagePackageDir & NameAndFullPath; export type NamedPackageDir = PackageDir & NameAndFullPath; export type ProjectJson = ConfigContents & ProjectJsonSchema; /** * The sfdx-project.json config object. This file determines if a folder is a valid sfdx project. * * *Note:* Any non-standard (not owned by Salesforce) properties stored in sfdx-project.json should * be in a top level property that represents your project. * Plugins should store their configuration @see SfProject.getPluginConfiguration and @see SfProject.setPluginConfiguration * * @example reading a standard property * ``` * const project = await SfProject.resolve(); * const projectJson = await project.resolveProjectConfig(); * const namespace = projectJson.get('namespace'); * ``` * * ``` * @example writing * const project = await SfProject.resolve(); * const projectJson = await project.resolveProjectConfig(); * projectJson.set('namespace', 'new'); * await projectJson.write(); * ``` * * **See** [force:project:create](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_ws_create_new.htm) */ export declare class SfProjectJson extends ConfigFile<ConfigFile.Options, ProjectJson> { /** json properties that are uppercase, or allow uppercase keys inside them */ static BLOCKLIST: string[]; static getFileName(): string; static getDefaultOptions(isGlobal?: boolean): ConfigFile.Options; read(): Promise<ProjectJson>; /** force a reread of the project contents if you know they may have been modified */ refreshSync(): SfProjectJson; readSync(): ProjectJson; write(): Promise<ProjectJson>; writeSync(): ProjectJson; getDefaultOptions(options?: ConfigFile.Options): ConfigFile.Options; /** * Validates sfdx-project.json against the schema. * * Set the `SFDX_PROJECT_JSON_VALIDATION` environment variable to `true` to throw an error when schema validation fails. * A warning is logged by default when the file is invalid. * * ***See*** [sfdx-project.schema.json] ((https://github.com/forcedotcom/schemas/blob/main/sfdx-project.schema.json) */ schemaValidate(): Promise<void>; /** * Returns the `packageDirectories` within sfdx-project.json, first reading * and validating the file if necessary. */ getPackageDirectories(): Promise<PackageDir[]>; /** * Validates sfdx-project.json against the schema. * * Set the `SFDX_PROJECT_JSON_VALIDATION` environment variable to `true` to throw an error when schema validation fails. * A warning is logged by default when the file is invalid. * * ***See*** [sfdx-project.schema.json] ((https://github.com/forcedotcom/schemas/blob/main/sfdx-project.schema.json) */ schemaValidateSync(): void; /** * Returns a read-only list of `packageDirectories` within sfdx-project.json, first reading * and validating the file if necessary. i.e. modifying this array will not affect the * sfdx-project.json file. */ getPackageDirectoriesSync(): NamedPackageDir[]; /** * Returns a read-only list of `packageDirectories` within sfdx-project.json, first reading * and validating the file if necessary. i.e. modifying this array will not affect the * sfdx-project.json file. * * There can be multiple packages in packageDirectories that point to the same directory. * This method only returns one packageDirectory entry per unique directory path. This is * useful when doing source operations based on directories but probably not as useful * for packaging operations that want to do something for each package entry. */ getUniquePackageDirectories(): NamedPackageDir[]; /** * Get a list of the unique package names from within sfdx-project.json. Use {@link SfProject.getUniquePackageDirectories} * for data other than the names. */ getUniquePackageNames(): string[]; /** * Has package directories defined in the project. */ hasPackages(): boolean; /** * Has multiple package directories (MPD) defined in the project. */ hasMultiplePackages(): boolean; /** * Has at least one package alias defined in the project. */ hasPackageAliases(): Promise<boolean>; /** * Get package aliases defined in the project. */ getPackageAliases(): Nullable<Dictionary<string>>; /** * Add a package alias to the project. * If the alias already exists, it will be overwritten. * * @param alias * @param id */ addPackageAlias(alias: string, id: string): void; /** * Add a package directory to the project. * If the package directory already exists, the new directory * properties will be merged with the existing properties. * * @param packageDir */ addPackageDirectory(packageDir: PackageDir): void; private doesPackageExist; private validateKeys; } /** * Represents an SFDX project directory. This directory contains a {@link SfProjectJson} config file as well as * a hidden .sfdx folder that contains all the other local project config files. * * ``` * const project = await SfProject.resolve(); * const projectJson = await project.resolveProjectConfig(); * console.log(projectJson.sfdcLoginUrl); * ``` */ export declare class SfProject { private path; private static instances; private projectConfig; private sfProjectJson; private sfProjectJsonGlobal; private packageDirectories?; private activePackage; private packageAliases; /** * Do not directly construct instances of this class -- use {@link SfProject.resolve} instead. * * @ignore */ protected constructor(path: string); /** * Clear the cache to force reading from disk. * * *NOTE: Only call this method if you must and you know what you are doing.* */ static clearInstances(): void; /** * Get a Project from a given path or from the working directory. * * @param path The path of the project. * * **Throws** *{@link SfError}{ name: 'InvalidProjectWorkspaceError' }* If the current folder is not located in a workspace. */ static resolve(path?: string): Promise<SfProject>; /** * Get a Project from a given path or from the working directory. * * @param path The path of the project. * * **Throws** *{@link SfError}{ name: 'InvalidProjectWorkspaceError' }* If the current folder is not located in a workspace. */ static getInstance(path?: string): SfProject; /** * Performs an upward directory search for an sfdx project file. Returns the absolute path to the project. * * @param dir The directory path to start traversing from. * * **Throws** *{@link SfError}{ name: 'InvalidProjectWorkspaceError' }* If the current folder is not located in a workspace. * * **See** {@link traverseForFile} * * **See** [process.cwd()](https://nodejs.org/api/process.html#process_process_cwd) */ static resolveProjectPath(dir?: string): Promise<string>; /** * Performs a synchronous upward directory search for an sfdx project file. Returns the absolute path to the project. * * @param dir The directory path to start traversing from. * * **Throws** *{@link SfError}{ name: 'InvalidProjectWorkspaceError' }* If the current folder is not located in a workspace. * * **See** {@link traverseForFileSync} * * **See** [process.cwd()](https://nodejs.org/api/process.html#process_process_cwd) */ static resolveProjectPathSync(dir?: string): string; /** shared method for resolve and getInstance. * Cannot be a module-level function because instances is private */ private static getMemoizedInstance; /** * Returns the project path. */ getPath(): string; /** * Get the sfdx-project.json config. The global sfdx-project.json is used for user defaults * that are not checked in to the project specific file. * * *Note:* When reading values from {@link SfProjectJson}, it is recommended to use * {@link SfProject.resolveProjectConfig} instead. * * @param isGlobal True to get the global project file, otherwise the local project config. */ retrieveSfProjectJson(isGlobal?: boolean): Promise<SfProjectJson>; /** * Get the sfdx-project.json config. The global sfdx-project.json is used for user defaults * that are not checked in to the project specific file. * * *Note:* When reading values from {@link SfProjectJson}, it is recommended to use * {@link SfProject.resolveProjectConfig} instead. * * This is the sync method of {@link SfProject.resolveSfProjectJson} * * @param isGlobal True to get the global project file, otherwise the local project config. */ getSfProjectJson(isGlobal?: boolean): SfProjectJson; /** * Returns a read-only list of `packageDirectories` within sfdx-project.json, first reading * and validating the file if necessary. i.e. modifying this array will not affect the * sfdx-project.json file. */ getPackageDirectories(): NamedPackageDir[]; /** * Returns a read-only list of `packageDirectories` within sfdx-project.json, first reading * and validating the file if necessary. i.e. modifying this array will not affect the * sfdx-project.json file. * * There can be multiple packages in packageDirectories that point to the same directory. * This method only returns one packageDirectory entry per unique directory path. This is * useful when doing source operations based on directories but probably not as useful * for packaging operations that want to do something for each package entry. */ getUniquePackageDirectories(): NamedPackageDir[]; /** * Get a list of the unique package names from within sfdx-project.json. Use {@link SfProject.getUniquePackageDirectories} * for data other than the names. */ getUniquePackageNames(): string[]; /** * Returns the package from a file path. * * @param path A file path. E.g. /Users/jsmith/projects/ebikes-lwc/force-app/apex/my-cls.cls */ getPackageFromPath(path: string): Optional<NamedPackageDir>; /** * Returns the package name, E.g. 'force-app', from a file path. * * @param path A file path. E.g. /Users/jsmith/projects/ebikes-lwc/force-app/apex/my-cls.cls */ getPackageNameFromPath(path: string): Optional<string>; /** * Returns the package directory. * * @param packageName Name of the package directory. E.g., 'force-app' */ getPackage(packageName: string): Optional<NamedPackageDir>; /** * Returns the package directory. * * @param packageName Name of the package directory. E.g., 'force-app' */ findPackage(predicate: (packageDir: NamedPackageDir) => boolean): Optional<NamedPackageDir>; /** * Returns the absolute path of the package directory ending with the path separator. * E.g., /Users/jsmith/projects/ebikes-lwc/force-app/ * * @param packageName Name of the package directory. E.g., 'force-app' */ getPackagePath(packageName: string): Optional<string>; /** * Has package directories defined in the project. */ hasPackages(): boolean; /** * Has multiple package directories (MPD) defined in the project. */ hasMultiplePackages(): boolean; /** * Get the currently activated package on the project. This has no implication on sfdx-project.json * but is useful for keeping track of package and source specific options in a process. */ getActivePackage(): Nullable<NamedPackageDir>; /** * Set the currently activated package on the project. This has no implication on sfdx-project.json * but is useful for keeping track of package and source specific options in a process. * * @param packageName The package name to activate. E.g. 'force-app' */ setActivePackage(packageName: Nullable<string>): void; /** * Get the project's default package directory defined in sfdx-project.json using first 'default: true' * found. The first entry is returned if no default is specified. */ getDefaultPackage(): NamedPackageDir; /** * The project config is resolved from local and global {@link SfProjectJson}, * {@link ConfigAggregator}, and a set of defaults. It is recommended to use * this when reading values from SfProjectJson. * * The global {@link SfProjectJson} is used to allow the user to provide default values they * may not want checked into their project's source. * * @returns A resolved config object that contains a bunch of different * properties, including some 3rd party custom properties. */ resolveProjectConfig(): Promise<JsonMap>; hasPackageAliases(): Promise<boolean>; /** * Returns a read-only list of `packageDirectories` within sfdx-project.json, first reading * and validating the file if necessary. i.e. modifying this array will not affect the * sfdx-project.json file. */ getPackageAliases(): Nullable<Dictionary<string>>; getPackageIdFromAlias(alias: string): Optional<string>; getAliasesFromPackageId(id: string): string[]; /** * retrieve the configuration for a named plugin from sfdx-project.json.plugins.pluginName * * @example * ``` * const project = await SfProject.resolve(); * const pluginConfig = await project.getPluginConfiguration('myPlugin'); * ``` * * optionally pass a type parameter for your plugin configuration's schema * */ getPluginConfiguration<T extends Record<string, unknown>>(pluginName: string): Promise<Readonly<T>>; /** * set the configuration for a named plugin from sfdx-project.json.plugins.pluginName, overwriting existing configuration * * @example * ``` * const project = await SfProject.resolve(); * const pluginConfig = await project.setPluginConfiguration('myPlugin', {foo: 'bar', myLimit: 25}); * ``` * * optionally pass a type parameter for your plugin configuration's schema * */ setPluginConfiguration<T extends Record<string, unknown>>(pluginName: string, config: T): Promise<void>; } /** differentiate between the Base PackageDir (path, maybe default) and the Packaging version (package and maybe a LOT of other fields) by whether is has the `package` property */ export declare const isPackagingDirectory: (packageDir: PackageDir) => packageDir is PackagePackageDir; /** differentiate between the Base PackageDir (path, maybe default) and the Packaging version (package and maybe a LOT of other fields) by whether is has the `package` property */ export declare const isNamedPackagingDirectory: (packageDir: NamedPackageDir) => packageDir is NamedPackagingDir; export {};