@salesforce/packaging 2.1.10 → 2.2.0

package/lib/package/packageVersion.d.ts

@@ -2,7 +2,29 @@ import { Connection, SfProject } from '@salesforce/core';
 import { Duration } from '@salesforce/kit';
 import { PackageSaveResult, PackageType, PackageVersionCreateOptions, PackageVersionCreateRequestQueryOptions, PackageVersionCreateRequestResult, PackageVersionOptions, PackageVersionReportResult, PackageVersionUpdateOptions, PackagingSObjects } from '../interfaces';
 type Package2Version = PackagingSObjects.Package2Version;
-export declare const Package2VersionFields: string[];
+export declare const Package2VersionFields: Array<keyof Package2Version>;
+export type Package2VersionFieldTypes = Array<(typeof Package2VersionFields)[number]>;
+export type Package2VersionQueryOptions = {
+    /**
+     * The fields to include in the returned data. Defaults to all fields.
+     */
+    fields?: Package2VersionFieldTypes;
+    /**
+     * The where clause to filter the query. E.g., "WHERE Id IN ('%IDS%')";
+     */
+    whereClause?: string;
+    /**
+     * An array of where clause items to match. The query is chunked,meaning broken into
+     * multiple queries when the query length would exceed the maximum char limit.
+     * When defining items here, the `whereClause` argument must use this token for the
+     * item replacement: `'%IDS%'`.
+     */
+    whereClauseItems?: string[];
+    /**
+     * The order-by clause for the query. Defaults to LastModifiedDate descending.
+     */
+    orderBy?: string;
+};
 /**
  * Provides the ability to create, update, delete, and promote 2nd
  * generation package versions.
@@ -94,6 +116,18 @@ export declare class PackageVersion {
         frequency: Duration;
         timeout: Duration;
     }): Promise<PackageVersionCreateRequestResult>;
+    /**
+     * Query the Package2Version SObject and return data with the provided type.
+     *
+     * NOTE: There is a limit of 2000 records that can be returned, otherwise
+     * a GACK might be thrown. If more than 2000 records are desired you should
+     * filter the query by date and aggregate all results.
+     *
+     * @param connection jsForce Connection to the org.
+     * @param options Package2Version query options
+     * @returns Results from querying the Package2Version SObject.
+     */
+    static queryPackage2Version(connection: Connection, options?: Package2VersionQueryOptions): Promise<Partial<Package2Version[]>>;
     /**
      * Get the package version ID for this PackageVersion.
      *

package/lib/package/packageVersion.js

@@ -283,6 +283,37 @@ class PackageVersion {
             throw (0, packageUtils_1.applyErrorAction)(err);
         }
     }
+    /**
+     * Query the Package2Version SObject and return data with the provided type.
+     *
+     * NOTE: There is a limit of 2000 records that can be returned, otherwise
+     * a GACK might be thrown. If more than 2000 records are desired you should
+     * filter the query by date and aggregate all results.
+     *
+     * @param connection jsForce Connection to the org.
+     * @param options Package2Version query options
+     * @returns Results from querying the Package2Version SObject.
+     */
+    static async queryPackage2Version(connection, options = {}) {
+        const fields = options.fields ?? exports.Package2VersionFields;
+        const { whereClause, whereClauseItems } = options;
+        const orderBy = options.orderBy ?? 'ORDER BY LastModifiedDate DESC';
+        let query = `SELECT ${fields.toString()} FROM Package2Version`;
+        if (whereClause) {
+            query += ` ${whereClause} ${orderBy}`;
+            if (whereClauseItems) {
+                query += ' LIMIT 2000';
+                return (0, packageUtils_1.queryWithInConditionChunking)(query, whereClauseItems, '%IDS%', connection);
+            }
+        }
+        query += ' LIMIT 2000';
+        const result = await connection.tooling.query(query);
+        if (result?.totalSize === 2000) {
+            const warningMsg = messages.getMessage('maxPackage2VersionRecords');
+            await core_1.Lifecycle.getInstance().emitWarning(warningMsg);
+        }
+        return result.records ?? [];
+    }
     /**
      * Get the package version ID for this PackageVersion.
      *

package/lib/utils/index.d.ts

@@ -1 +1 @@
-export { INSTALL_URL_BASE, getContainerOptions, getPackageVersionStrings } from './packageUtils';
+export { INSTALL_URL_BASE, getContainerOptions, getPackageVersionStrings, getPackageVersionNumber, } from './packageUtils';

package/lib/utils/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getPackageVersionStrings = exports.getContainerOptions = exports.INSTALL_URL_BASE = void 0;
+exports.getPackageVersionNumber = exports.getPackageVersionStrings = exports.getContainerOptions = exports.INSTALL_URL_BASE = void 0;
 /*
  * Copyright (c) 2022, salesforce.com, inc.
  * All rights reserved.
@@ -11,4 +11,5 @@ var packageUtils_1 = require("./packageUtils");
 Object.defineProperty(exports, "INSTALL_URL_BASE", { enumerable: true, get: function () { return packageUtils_1.INSTALL_URL_BASE; } });
 Object.defineProperty(exports, "getContainerOptions", { enumerable: true, get: function () { return packageUtils_1.getContainerOptions; } });
 Object.defineProperty(exports, "getPackageVersionStrings", { enumerable: true, get: function () { return packageUtils_1.getPackageVersionStrings; } });
+Object.defineProperty(exports, "getPackageVersionNumber", { enumerable: true, get: function () { return packageUtils_1.getPackageVersionNumber; } });
 //# sourceMappingURL=index.js.map

package/lib/utils/packageUtils.d.ts

@@ -65,7 +65,18 @@ export declare function getContainerOptions(packageIds: string | undefined | Arr
  * @param connection For tooling query
  */
 export declare function getPackageVersionStrings(subscriberPackageVersionIds: string[], connection: Connection): Promise<Map<string, string>>;
-export declare function getPackageVersionNumber(package2VersionObj: PackagingSObjects.Package2Version): 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
  *

package/lib/utils/packageUtils.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isPackageDirectoryEffectivelyEmpty = exports.replaceIfEmpty = exports.copyDescriptorProperties = exports.copyDir = exports.zipDir = exports.numberToDuration = exports.combineSaveErrors = exports.generatePackageAliasEntry = exports.getPackageVersionNumber = exports.getPackageVersionStrings = exports.getContainerOptions = exports.escapeInstallationKey = exports.getPackageVersionId = exports.massageErrorMessage = exports.applyErrorAction = exports.validateIdNoThrow = exports.validateId = exports.uniqid = exports.BY_LABEL = exports.DEFAULT_PACKAGE_DIR = exports.POLL_INTERVAL_SECONDS = exports.INSTALL_URL_BASE = exports.VERSION_NUMBER_SEP = void 0;
+exports.isPackageDirectoryEffectivelyEmpty = exports.replaceIfEmpty = exports.copyDescriptorProperties = exports.copyDir = exports.zipDir = exports.numberToDuration = exports.combineSaveErrors = exports.generatePackageAliasEntry = exports.getPackageVersionNumber = exports.queryWithInConditionChunking = exports.getPackageVersionStrings = exports.getContainerOptions = exports.escapeInstallationKey = exports.getPackageVersionId = exports.massageErrorMessage = exports.applyErrorAction = exports.validateIdNoThrow = exports.validateId = exports.uniqid = exports.BY_LABEL = exports.DEFAULT_PACKAGE_DIR = exports.POLL_INTERVAL_SECONDS = exports.INSTALL_URL_BASE = exports.VERSION_NUMBER_SEP = void 0;
 /*
  * Copyright (c) 2022, salesforce.com, inc.
  * All rights reserved.
@@ -268,6 +268,7 @@ async function queryWithInConditionChunking(query, items, replaceToken, connecti
     }
     return records;
 }
+exports.queryWithInConditionChunking = queryWithInConditionChunking;
 /**
  * Returns the number of items that can be included in a quoted comma-separated string (e.g., "'item1','item2'") not exceeding maxLength
  */
@@ -295,9 +296,9 @@ function getInClauseItemsCount(items, startIndex, maxLength) {
 function concatVersion(major, minor, patch, build) {
     return [major, minor, patch, build].map((part) => (part ? `${part}` : '0')).join('.');
 }
-function getPackageVersionNumber(package2VersionObj) {
-    const version = concatVersion(package2VersionObj.MajorVersion, package2VersionObj.MinorVersion, package2VersionObj.PatchVersion, undefined);
-    return version.slice(0, version.lastIndexOf('.'));
+function getPackageVersionNumber(package2VersionObj, includeBuild = false) {
+    const version = concatVersion(package2VersionObj.MajorVersion, package2VersionObj.MinorVersion, package2VersionObj.PatchVersion, includeBuild ? package2VersionObj.BuildNumber : undefined);
+    return includeBuild ? version : version.slice(0, version.lastIndexOf('.'));
 }
 exports.getPackageVersionNumber = getPackageVersionNumber;
 /**

package/messages/package_version.md

@@ -17,3 +17,7 @@ The package version create result ID must be defined when checking for completio
 # errorNoSubscriberPackageVersionId
 
 Could not fetch the subscriber package version ID (04t).
+
+# maxPackage2VersionRecords
+
+The maximum result size (2000) was reached when querying the Package2Version SObject. This means there could be more records that were not returned by the query. If all records are required you may have to break the query into multiple requests filtered by date, then aggregate the results.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/packaging",
-  "version": "2.1.10",
+  "version": "2.2.0",
   "description": "Packaging library for the Salesforce packaging platform",
   "main": "lib/exported",
   "types": "lib/exported.d.ts",
@@ -44,7 +44,7 @@
     "@oclif/core": "^2.8.7",
     "@salesforce/core": "^4.3.2",
     "@salesforce/kit": "^3.0.3",
-    "@salesforce/schemas": "^1.5.1",
+    "@salesforce/schemas": "^1.6.0",
     "@salesforce/source-deploy-retrieve": "^8.6.0",
     "@salesforce/ts-types": "^2.0.3",
     "@xmldom/xmldom": "^0.8.8",
@@ -70,17 +70,17 @@
     "@types/jszip": "^3.4.1",
     "@types/xml2js": "^0.4.11",
     "@typescript-eslint/eslint-plugin": "^5.60.0",
-    "@typescript-eslint/parser": "^5.60.0",
+    "@typescript-eslint/parser": "^5.60.1",
     "chai": "^4.3.7",
     "commitizen": "^4.2.6",
-    "eslint": "^8.43.0",
+    "eslint": "^8.44.0",
     "eslint-config-prettier": "^8.8.0",
     "eslint-config-salesforce": "^2.0.1",
     "eslint-config-salesforce-license": "^0.2.0",
     "eslint-config-salesforce-typescript": "^1.1.1",
     "eslint-plugin-header": "3.1.1",
     "eslint-plugin-import": "^2.27.5",
-    "eslint-plugin-jsdoc": "^44.2.4",
+    "eslint-plugin-jsdoc": "^44.2.7",
     "eslint-plugin-sf-plugin": "^1.15.9",
     "husky": "^8.0.3",
     "mocha": "^10.2.0",