@salesforce/source-tracking-bundle/lib/sourceTracking.d.ts

API for tracking local and remote Salesforce metadata changes

import { Org, SfProject } from '@salesforce/core-bundle';
import { AsyncCreatable } from '@salesforce/kit';
import { ComponentSet, SourceComponent, FileResponse, DeployResult, RetrieveResult, RegistryAccess } from '@salesforce/source-deploy-retrieve-bundle';
import { RemoteSyncInput, StatusOutputRow, ChangeOptions, ChangeResult, LocalUpdateOptions } from './shared/types';
export type SourceTrackingOptions = {
    org: Org;
    project: SfProject;
    /** listen for the SDR scoped<Pre|Post><Deploy|Retrieve> events
     * `pre` events will check for conflicts and throw if there are any (use ignoreConflicts: true to disable)
     * `post` events will update tracking files with the results of the deploy/retrieve
     */
    subscribeSDREvents?: boolean;
    /** don't check for conflicts when responding to SDR events.
     * This property has no effect unless you also set subscribeSDREvents to true.
     */
    ignoreConflicts?: boolean;
    /** SourceTracking is caching local file statuses.
     * If you're using STL as part of a long running process (ex: vscode extensions), set this to false
     */
    ignoreLocalCache?: boolean;
};
type RemoteChangesResults = {
    componentSetFromNonDeletes: ComponentSet;
    fileResponsesFromDelete: FileResponse[];
};
/**
 * Manages source tracking files (remote and local)
 *
 * const tracking = await SourceTracking.create({org: this.org, project: this.project});
 *
 */
export declare class SourceTracking extends AsyncCreatable {
    readonly registry: RegistryAccess;
    readonly projectPath: string;
    private org;
    private project;
    private packagesDirs;
    private logger;
    private localRepo;
    private remoteSourceTrackingService;
    private forceIgnore;
    private ignoreConflicts;
    private subscribeSDREvents;
    private ignoreLocalCache;
    private orgId;
    constructor(options: SourceTrackingOptions);
    init(): Promise<void>;
    /**
     *
     * @param byPackageDir if true, returns a ComponentSet for each packageDir that has any changes
     * * if false, returns an array containing one ComponentSet with all changes
     * * if not specified, this method will follow what sfdx-project.json says
     * @returns ComponentSet[]
     */
    localChangesAsComponentSet(byPackageDir?: boolean): Promise<ComponentSet[]>;
    /** reads tracking files for remote changes.  It DOES NOT consider the effects of .forceignore unless told to */
    remoteNonDeletesAsComponentSet({ applyIgnore, }?: {
        applyIgnore?: boolean;
    }): Promise<ComponentSet>;
    /**
     * Does most of the work for the force:source:status command.
     * Outputs need a bit of massage since this aims to provide nice json.
     *
     * @param local you want local status
     * @param remote you want remote status
     * @returns StatusOutputRow[]
     */
    getStatus({ local, remote }: {
        local: boolean;
        remote: boolean;
    }): Promise<StatusOutputRow[]>;
    /**
     * Get metadata changes made locally and in the org.
     *
     * @returns local and remote changed metadata
     *
     */
    getChanges(options: ChangeOptions & {
        format: 'string';
    }): Promise<string[]>;
    getChanges(options: ChangeOptions & {
        format: 'SourceComponent';
    }): Promise<SourceComponent[]>;
    getChanges(options: ChangeOptions & {
        format: 'ChangeResult';
    }): Promise<ChangeResult[]>;
    /**
     * @deprecated omit the type parameter <string>.
     */
    getChanges<T extends string>(options: ChangeOptions & {
        format: 'string';
    }): Promise<T[]>;
    /**
     * @deprecated omit the type parameter <SourceComponent>.
     */
    getChanges<T extends SourceComponent>(options: ChangeOptions & {
        format: 'SourceComponent';
    }): Promise<T[]>;
    /**
     * @deprecated omit the type parameter <ChangeResult>.
     */
    getChanges<T extends ChangeResult>(options: ChangeOptions & {
        format: 'ChangeResult';
    }): Promise<T[]>;
    getChanges(options: ChangeOptions & {
        format: 'ChangeResultWithPaths';
    }): Promise<Array<ChangeResult & {
        filename: string[];
    }>>;
    /**
     *
     * Convenience method to reduce duplicated steps required to do a fka pull
     * It's full of side effects: retrieving remote deletes, deleting those files locall, and then updating tracking files
     * Most bizarrely, it then returns a ComponentSet of the remote nonDeletes and the FileResponses from the delete
     *
     * @returns the ComponentSet for what you would retrieve now that the deletes are done, and optionally, a FileResponses array for the deleted files
     */
    maybeApplyRemoteDeletesToLocal(returnDeleteFileResponses: true): Promise<RemoteChangesResults>;
    maybeApplyRemoteDeletesToLocal(returnDeleteFileResponses?: false): Promise<ComponentSet>;
    /**
     *
     * returns immediately if there are no changesToDelete
     *
     * @param changesToDelete array of SourceComponent
     */
    deleteFilesAndUpdateTracking(changesToDelete: SourceComponent[]): Promise<FileResponse[]>;
    /**
     * Update tracking for the options passed.
     *
     * @param options the files to update
     */
    updateLocalTracking(options: LocalUpdateOptions): Promise<void>;
    /**
     * Mark remote source tracking files so say that we have received the latest version from the server
     * Optional skip polling for the SourceMembers to exist on the server and be updated in local files
     */
    updateRemoteTracking(fileResponses: RemoteSyncInput[], skipPolling?: boolean): Promise<void>;
    reReadLocalTrackingCache(): Promise<void>;
    /**
     * If the local tracking shadowRepo doesn't exist, it will be created.
     * Does nothing if it already exists, unless you've instantiate SourceTracking to not cache local status, in which case it'll re-read your files
     * Useful before parallel operations
     */
    ensureLocalTracking(): Promise<void>;
    /**
     * If the remote tracking shadowRepo doesn't exist, it will be created.
     * Does nothing if it already exists.
     * Useful before parallel operations
     */
    ensureRemoteTracking(initializeWithQuery?: boolean): Promise<void>;
    /**
     * Deletes the local tracking shadowRepo
     * return the list of files that were in it
     */
    clearLocalTracking(): Promise<string>;
    /**
     * Commits all the local changes so that no changes are present in status
     */
    resetLocalTracking(): Promise<string[]>;
    /**
     * Deletes the remote tracking files
     */
    clearRemoteTracking(): Promise<string>;
    /**
     * Sets the files to max revision so that no changes appear
     */
    resetRemoteTracking(serverRevision?: number): Promise<number>;
    /**
     * Compares local and remote changes to detect conflicts
     */
    getConflicts(): Promise<ChangeResult[]>;
    /**
     * handles both remote and local tracking
     *
     * @param result FileResponse[]
     */
    updateTrackingFromDeploy(deployResult: DeployResult): Promise<void>;
    /**
     * handles both remote and local tracking
     *
     * @param result FileResponse[]
     */
    updateTrackingFromRetrieve(retrieveResult: RetrieveResult): Promise<void>;
    /**
     * If you've already got an instance of STL, but need to change the conflicts setting
     * normally you set this on instantiation
     *
     * @param value true/false
     */
    setIgnoreConflicts(value: boolean): void;
    private maybeSubscribeLifecycleEvents;
    private getLocalStatusRows;
    private remoteChangesToOutputRows;
}
export {};