@salesforce/packaging/lib/utils/packageUtils.d.ts

Packaging library for the Salesforce packaging platform

import { Connection, ScratchOrgInfo, SfdcUrl, SfError, SfProject } from '@salesforce/core';
import { NamedPackageDir } from '@salesforce/core/project';
import { Many, Optional } from '@salesforce/ts-types';
import type { SaveError } from '@jsforce/jsforce-node';
import { Duration } from '@salesforce/kit';
import { PackageDescriptorJson, PackageType, PackagingSObjects } from '../interfaces';
export declare const VERSION_NUMBER_SEP = ".";
export type IdRegistryValue = {
    prefix: string;
    label: string;
};
export type IdRegistry = {
    [key: string]: IdRegistryValue;
};
export declare const INSTALL_URL_BASE: SfdcUrl;
export declare const BY_LABEL: IdRegistry;
/**
 * A function to generate a unique id and return it in the context of a template, if supplied.
 *
 * A template is a string that can contain `${%s}` to be replaced with a unique id.
 * If the template contains the "%s" placeholder, it will be replaced with the unique id otherwise the id will be appended to the template.
 *
 * @param options an object with the following properties:
 * - template: a template string.
 * - length: the length of the unique id as presented in hexadecimal.
 */
export declare function uniqid(options?: {
    template?: string;
    length?: number;
}): string;
export declare function validateId(idObj: Many<IdRegistryValue>, value: string | undefined): void;
export declare function validateIdNoThrow(idObj: Many<IdRegistryValue>, value: string): IdRegistryValue | boolean;
export declare function applyErrorAction(err: Error & {
    action?: string;
}): Error;
export declare function massageErrorMessage(err: Error): Error;
/**
 * Given a subscriber package version ID (04t) or package version ID (05i), return the package version ID (05i)
 *
 * @param versionId The subscriber package version ID
 * @param connection For tooling query
 */
export declare function getPackageVersionId(versionId: string, connection: Connection): Promise<string | undefined>;
export declare function escapeInstallationKey(key: string): string;
/**
 * Get the ContainerOptions for the specified Package2 (0Ho) IDs.
 *
 * @return Map of 0Ho id to container option api value
 * @param packageIds The list of package IDs
 * @param connection For tooling query
 */
export declare function getContainerOptions(packageIds: string | undefined | Array<string | undefined>, connection: Connection): Promise<Map<string, PackageType>>;
/**
 * Given a list of subscriber package version IDs (04t), return the associated version strings (e.g., Major.Minor.Patch.Build)
 *
 * @return Map of subscriberPackageVersionId to versionString
 * @param subscriberPackageVersionIds
 * @param connection For tooling query
 */
export declare function getPackageVersionStrings(subscriberPackageVersionIds: string[], connection: Connection): Promise<Map<string, string>>;
/**
 * For queries with an IN condition, determine if the WHERE clause will exceed
 * SOQL's 4000 character limit.  Perform multiple queries as needed to stay below the limit.
 *
 * @return concatenated array of records returned from the resulting query(ies)
 * @param query The full query to execute containing the replaceToken param in its IN clause
 * @param items The IN clause items.  A length-appropriate single-quoted comma-separated string chunk will be made from the items.
 * @param replaceToken A placeholder in the query's IN condition that will be replaced with the chunked items
 * @param connection For tooling query
 */
export declare function queryWithInConditionChunking<T extends Record<string, unknown> = Record<string, unknown>>(query: string, items: string[], replaceToken: string, connection: Connection): Promise<T[]>;
export declare function getPackageVersionNumber(package2VersionObj: PackagingSObjects.Package2Version, includeBuild?: boolean): string;
/**
 * Generate package alias json entry for this package version that can be written to sfdx-project.json
 *
 * @param connection
 * @param project SfProject instance for the project
 * @param packageVersionId 04t id of the package to create the alias entry for
 * @param packageVersionNumber that will be appended to the package name to form the alias
 * @param branch
 * @param packageId the 0Ho id
 * @private
 */
export declare function generatePackageAliasEntry(connection: Connection, project: SfProject, packageVersionId: string, packageVersionNumber: string, branch: string, packageId: string): Promise<[string, string]>;
export declare function combineSaveErrors(sObject: string, crudOperation: string, errors: SaveError[]): SfError;
/**
 * Returns a Duration object from param duration when it is a number, otherwise return itself
 *
 * @param duration = number to be converted to a Duration or Duration object
 * @param unit = (Default Duration.Unit.MILLISECONDS) Duration unit of number - See @link {Duration.Unit} for valid values
 */
export declare function numberToDuration(duration: number | Duration | undefined, unit?: Duration.Unit): Duration;
/**
 * Zips directory to given zipfile.
 *
 * @param dir directory to zip
 * @param zipfile path to the zip file to create
 */
export declare function zipDir(dir: string, zipfile: string): Promise<void>;
export declare function copyDir(src: string, dest: string): void;
/**
 * Parse and copy properties from both of these arguments into a new object
 *
 * @param packageDescriptorJson
 * @param definitionFileJson
 * @returns the resulting object with specific properties
 * overridden from definition file based on case-insensitive matches.
 */
export declare function copyDescriptorProperties(packageDescriptorJson: PackageDescriptorJson, definitionFileJson: ScratchOrgInfo): PackageDescriptorJson;
/**
 * Resolve descriptor permissions for build/test execution.
 *
 * When {@link codecoverage} is true, converts {@link apexTestAccess} settings into
 * permissionSetNames and permissionSetLicenseDeveloperNames.
 * Always converts {@link packageMetadataAccess} settings into
 * packageMetadataPermissionSetNames and packageMetadataPermissionSetLicenseNames.
 * Removes apexTestAccess and packageMetadataAccess from the returned descriptor.
 *
 * @param descriptor Package descriptor to normalize
 * @param codecoverage Whether to enable apexTestAccess-based permission processing
 * @returns A normalized copy of the descriptor with flattened permission fields
 */
export declare function resolveBuildUserPermissions(descriptor: PackageDescriptorJson, codecoverage: boolean): PackageDescriptorJson;
/**
 * This function finds the package directory in the project that matches the given packageId
 *
 * @param project The SfProject instance to search
 * @param packageId The package ID to match against
 * @returns A NamedPackageDir or empty object if not found
 */
export declare function findPackageDirectory(project: SfProject | undefined, packageId: string): Optional<NamedPackageDir>;
/**
 * Brand new SFDX projects contain a force-app directory tree containing empty folders
 * and a few .eslintrc.json files. We still want to consider such a directory tree
 * as 'empty' for the sake of operations like downloading package version metadata.
 *
 * @param directory The absolute path to a directory
 * @returns true if the directory contains nothing except empty directories or
 * directories containing only an .eslintrc.json file.
 */
export declare function isPackageDirectoryEffectivelyEmpty(directory: string): boolean;
/**
 * Cleans client-side-only attribute(s) from the packageDescriptorJSON so it can go to API
 */
export declare function cleanPackageDescriptorJson(packageDescriptorJson: PackageDescriptorJson): PackageDescriptorJson;