@rushstack/heft-config-file - npm Package Compare versions

Comparing version 0.15.9 to 0.16.0

CHANGELOG.json

@@ -5,2 +5,17 @@ {
     {
+      "version": "0.16.0",
+      "tag": "@rushstack/heft-config-file_v0.16.0",
+      "date": "Tue, 03 Dec 2024 16:11:07 GMT",
+      "comments": {
+        "minor": [
+          {
+            "comment": "Add a new `NonProjectConfigurationFile` class that is designed to load absolute-pathed configuration files without rig support."
+          },
+          {
+            "comment": "Rename `ConfigurationFile` to `ProjectConfigurationFile` and mark `ConfigurationFile` as `@deprecated`."
+          }
+        ]
+      }
+    },
+    {
       "version": "0.15.9",
@@ -7,0 +22,0 @@ "tag": "@rushstack/heft-config-file_v0.15.9",

CHANGELOG.md

 # Change Log - @rushstack/heft-config-file
 
-This log was last generated on Fri, 22 Nov 2024 01:10:43 GMT and should not be manually modified.
+This log was last generated on Tue, 03 Dec 2024 16:11:07 GMT and should not be manually modified.
 
+## 0.16.0
+Tue, 03 Dec 2024 16:11:07 GMT
+
+### Minor changes
+
+- Add a new `NonProjectConfigurationFile` class that is designed to load absolute-pathed configuration files without rig support.
+- Rename `ConfigurationFile` to `ProjectConfigurationFile` and mark `ConfigurationFile` as `@deprecated`.
+
 ## 0.15.9
@@ -6,0 +14,0 @@ Fri, 22 Nov 2024 01:10:43 GMT

dist/heft-config-file.d.ts

@@ -12,8 +12,18 @@ /**
 /**
+ * @deprecated Use {@link ProjectConfigurationFile} instead.
  * @beta
  */
-export declare class ConfigurationFile<TConfigurationFile> {
+export declare const ConfigurationFile: typeof ProjectConfigurationFile;
+
+/**
+ * @deprecated Use {@link ProjectConfigurationFile} instead.
+ * @beta
+ */
+export declare type ConfigurationFile<TConfigurationFile> = ProjectConfigurationFile<TConfigurationFile>;
+
+/**
+ * @beta
+ */
+export declare abstract class ConfigurationFileBase<TConfigurationFile, TExtraOptions extends {}> {
     private readonly _getSchema;
-    /** {@inheritDoc IConfigurationFileOptionsBase.projectRelativeFilePath} */
-    readonly projectRelativeFilePath: string;
     private readonly _jsonPathMetadata;
@@ -27,26 +37,4 @@ private readonly _propertyInheritanceTypes;
     private readonly _packageJsonLookup;
-    constructor(options: IConfigurationFileOptions<TConfigurationFile>);
+    constructor(options: IConfigurationFileOptions<TConfigurationFile, TExtraOptions>);
     /**
-     * Find and return a configuration file for the specified project, automatically resolving
-     * `extends` properties and handling rigged configuration files. Will throw an error if a configuration
-     * file cannot be found in the rig or project config folder.
-     */
-    loadConfigurationFileForProject(terminal: ITerminal, projectPath: string, rigConfig?: IRigConfig): TConfigurationFile;
-    /**
-     * Find and return a configuration file for the specified project, automatically resolving
-     * `extends` properties and handling rigged configuration files. Will throw an error if a configuration
-     * file cannot be found in the rig or project config folder.
-     */
-    loadConfigurationFileForProjectAsync(terminal: ITerminal, projectPath: string, rigConfig?: IRigConfig): Promise<TConfigurationFile>;
-    /**
-     * This function is identical to {@link ConfigurationFile.loadConfigurationFileForProject}, except
-     * that it returns `undefined` instead of throwing an error if the configuration file cannot be found.
-     */
-    tryLoadConfigurationFileForProject(terminal: ITerminal, projectPath: string, rigConfig?: IRigConfig): TConfigurationFile | undefined;
-    /**
-     * This function is identical to {@link ConfigurationFile.loadConfigurationFileForProjectAsync}, except
-     * that it returns `undefined` instead of throwing an error if the configuration file cannot be found.
-     */
-    tryLoadConfigurationFileForProjectAsync(terminal: ITerminal, projectPath: string, rigConfig?: IRigConfig): Promise<TConfigurationFile | undefined>;
-    /**
      * @internal
@@ -65,9 +53,9 @@ */
     getPropertyOriginalValue<TParentProperty extends object, TValue>(options: IOriginalValueOptions<TParentProperty>): TValue | undefined;
-    private _loadConfigurationFileInnerWithCache;
-    private _loadConfigurationFileInnerWithCacheAsync;
+    protected _loadConfigurationFileInnerWithCache(terminal: ITerminal, resolvedConfigurationFilePath: string, visitedConfigurationFilePaths: Set<string>, rigConfig: IRigConfig | undefined): TConfigurationFile;
+    protected _loadConfigurationFileInnerWithCacheAsync(terminal: ITerminal, resolvedConfigurationFilePath: string, visitedConfigurationFilePaths: Set<string>, rigConfig: IRigConfig | undefined): Promise<TConfigurationFile>;
+    protected abstract _tryLoadConfigurationFileInRig(terminal: ITerminal, rigConfig: IRigConfig, visitedConfigurationFilePaths: Set<string>): TConfigurationFile | undefined;
+    protected abstract _tryLoadConfigurationFileInRigAsync(terminal: ITerminal, rigConfig: IRigConfig, visitedConfigurationFilePaths: Set<string>): Promise<TConfigurationFile | undefined>;
     private _parseAndResolveConfigurationFile;
     private _loadConfigurationFileInner;
     private _loadConfigurationFileInnerAsync;
-    private _tryLoadConfigurationFileInRig;
-    private _tryLoadConfigurationFileInRigAsync;
     private _annotateProperties;
@@ -78,3 +66,2 @@ private _annotateProperty;
     private _mergeObjects;
-    private _getConfigurationFilePathForProject;
 }
@@ -85,3 +72,3 @@
  */
-export declare type IConfigurationFileOptions<TConfigurationFile> = IConfigurationFileOptionsWithJsonSchemaFilePath<TConfigurationFile> | IConfigurationFileOptionsWithJsonSchemaObject<TConfigurationFile>;
+export declare type IConfigurationFileOptions<TConfigurationFile, TExtraOptions extends object> = IConfigurationFileOptionsWithJsonSchemaFilePath<TConfigurationFile, TExtraOptions> | IConfigurationFileOptionsWithJsonSchemaObject<TConfigurationFile, TExtraOptions>;
 
@@ -93,6 +80,2 @@ /**
     /**
-     * A project root-relative path to the configuration file that should be loaded.
-     */
-    projectRelativeFilePath: string;
-    /**
      * Use this property to specify how JSON nodes are postprocessed.
@@ -116,3 +99,3 @@ */
  */
-export declare interface IConfigurationFileOptionsWithJsonSchemaFilePath<TConfigurationFile> extends IConfigurationFileOptionsBase<TConfigurationFile> {
+export declare type IConfigurationFileOptionsWithJsonSchemaFilePath<TConfigurationFile, TExtraOptions extends {}> = IConfigurationFileOptionsBase<TConfigurationFile> & TExtraOptions & {
     /**
@@ -123,3 +106,3 @@ * The path to the schema for the configuration file.
     jsonSchemaObject?: never;
-}
+};
 
@@ -129,3 +112,3 @@ /**
  */
-export declare interface IConfigurationFileOptionsWithJsonSchemaObject<TConfigurationFile> extends IConfigurationFileOptionsBase<TConfigurationFile> {
+export declare type IConfigurationFileOptionsWithJsonSchemaObject<TConfigurationFile, TExtraOptions extends {}> = IConfigurationFileOptionsBase<TConfigurationFile> & TExtraOptions & {
     /**
@@ -136,3 +119,3 @@ * The schema for the configuration file.
     jsonSchemaPath?: never;
-}
+};
 
@@ -256,2 +239,12 @@ /**
  */
+export declare interface IProjectConfigurationFileOptions {
+    /**
+     * A project root-relative path to the configuration file that should be loaded.
+     */
+    projectRelativeFilePath: string;
+}
+
+/**
+ * @beta
+ */
 export declare type IPropertiesInheritance<TConfigurationFile> = {
@@ -279,2 +272,30 @@ [propertyName in keyof TConfigurationFile]?: IPropertyInheritance<InheritanceType.append | InheritanceType.merge | InheritanceType.replace> | ICustomPropertyInheritance<TConfigurationFile[propertyName]>;
  */
+export declare class NonProjectConfigurationFile<TConfigurationFile> extends ConfigurationFileBase<TConfigurationFile, {}> {
+    /**
+     * Load the configuration file at the specified absolute path, automatically resolving
+     * `extends` properties. Will throw an error if the file cannot be found.
+     */
+    loadConfigurationFile(terminal: ITerminal, filePath: string): TConfigurationFile;
+    /**
+     * Load the configuration file at the specified absolute path, automatically resolving
+     * `extends` properties. Will throw an error if the file cannot be found.
+     */
+    loadConfigurationFileAsync(terminal: ITerminal, filePath: string): Promise<TConfigurationFile>;
+    /**
+     * This function is identical to {@link NonProjectConfigurationFile.loadConfigurationFile}, except
+     * that it returns `undefined` instead of throwing an error if the configuration file cannot be found.
+     */
+    tryLoadConfigurationFile(terminal: ITerminal, filePath: string): TConfigurationFile | undefined;
+    /**
+     * This function is identical to {@link NonProjectConfigurationFile.loadConfigurationFileAsync}, except
+     * that it returns `undefined` instead of throwing an error if the configuration file cannot be found.
+     */
+    tryLoadConfigurationFileAsync(terminal: ITerminal, filePath: string): Promise<TConfigurationFile | undefined>;
+    protected _tryLoadConfigurationFileInRig(terminal: ITerminal, rigConfig: IRigConfig, visitedConfigurationFilePaths: Set<string>): TConfigurationFile | undefined;
+    protected _tryLoadConfigurationFileInRigAsync(terminal: ITerminal, rigConfig: IRigConfig, visitedConfigurationFilePaths: Set<string>): Promise<TConfigurationFile | undefined>;
+}
+
+/**
+ * @beta
+ */
 export declare enum PathResolutionMethod {
@@ -311,4 +332,51 @@ /**
  */
+export declare class ProjectConfigurationFile<TConfigurationFile> extends ConfigurationFileBase<TConfigurationFile, IProjectConfigurationFileOptions> {
+    /** {@inheritDoc IProjectConfigurationFileOptions.projectRelativeFilePath} */
+    readonly projectRelativeFilePath: string;
+    constructor(options: IConfigurationFileOptions<TConfigurationFile, IProjectConfigurationFileOptions>);
+    /**
+     * Find and return a configuration file for the specified project, automatically resolving
+     * `extends` properties and handling rigged configuration files. Will throw an error if a configuration
+     * file cannot be found in the rig or project config folder.
+     */
+    loadConfigurationFileForProject(terminal: ITerminal, projectPath: string, rigConfig?: IRigConfig): TConfigurationFile;
+    /**
+     * Find and return a configuration file for the specified project, automatically resolving
+     * `extends` properties and handling rigged configuration files. Will throw an error if a configuration
+     * file cannot be found in the rig or project config folder.
+     */
+    loadConfigurationFileForProjectAsync(terminal: ITerminal, projectPath: string, rigConfig?: IRigConfig): Promise<TConfigurationFile>;
+    /**
+     * This function is identical to {@link ProjectConfigurationFile.loadConfigurationFileForProject}, except
+     * that it returns `undefined` instead of throwing an error if the configuration file cannot be found.
+     */
+    tryLoadConfigurationFileForProject(terminal: ITerminal, projectPath: string, rigConfig?: IRigConfig): TConfigurationFile | undefined;
+    /**
+     * This function is identical to {@link ProjectConfigurationFile.loadConfigurationFileForProjectAsync}, except
+     * that it returns `undefined` instead of throwing an error if the configuration file cannot be found.
+     */
+    tryLoadConfigurationFileForProjectAsync(terminal: ITerminal, projectPath: string, rigConfig?: IRigConfig): Promise<TConfigurationFile | undefined>;
+    protected _tryLoadConfigurationFileInRig(terminal: ITerminal, rigConfig: IRigConfig, visitedConfigurationFilePaths: Set<string>): TConfigurationFile | undefined;
+    protected _tryLoadConfigurationFileInRigAsync(terminal: ITerminal, rigConfig: IRigConfig, visitedConfigurationFilePaths: Set<string>): Promise<TConfigurationFile | undefined>;
+    private _getConfigurationFilePathForProject;
+}
+
+/**
+ * @beta
+ */
 export declare type PropertyInheritanceCustomFunction<TObject> = (currentObject: TObject, parentObject: TObject) => TObject;
 
+/**
+ * Returns an object with investigative annotations stripped, useful for snapshot testing.
+ *
+ * @beta
+ */
+declare function stripAnnotations<TObject>(obj: TObject): TObject;
+
+export declare namespace TestUtilities {
+    export {
+        stripAnnotations
+    }
+}
+
 export { }

dist/tsdoc-metadata.json

@@ -8,5 +8,5 @@ // This file is read by tools that parse documentation comments conforming to the TSDoc standard.
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.47.9"
+      "packageVersion": "7.47.12"
     }
   ]
 }

lib/index.d.ts

@@ -7,3 +7,17 @@ /**
  */
-export { ConfigurationFile, type IConfigurationFileOptionsBase, type IConfigurationFileOptionsWithJsonSchemaFilePath, type IConfigurationFileOptionsWithJsonSchemaObject, type IConfigurationFileOptions, type ICustomJsonPathMetadata, type ICustomPropertyInheritance, type IJsonPathMetadataResolverOptions, type IJsonPathMetadata, type IJsonPathsMetadata, InheritanceType, type INonCustomJsonPathMetadata, type IOriginalValueOptions, type IPropertiesInheritance, type IPropertyInheritance, type IPropertyInheritanceDefaults, PathResolutionMethod, type PropertyInheritanceCustomFunction } from './ConfigurationFile';
+export { ConfigurationFileBase, type IConfigurationFileOptionsBase, type IConfigurationFileOptionsWithJsonSchemaFilePath, type IConfigurationFileOptionsWithJsonSchemaObject, type IConfigurationFileOptions, type ICustomJsonPathMetadata, type ICustomPropertyInheritance, type IJsonPathMetadataResolverOptions, type IJsonPathMetadata, type IJsonPathsMetadata, InheritanceType, type INonCustomJsonPathMetadata, type IOriginalValueOptions, type IPropertiesInheritance, type IPropertyInheritance, type IPropertyInheritanceDefaults, PathResolutionMethod, type PropertyInheritanceCustomFunction } from './ConfigurationFileBase';
+import { ProjectConfigurationFile } from './ProjectConfigurationFile';
+/**
+ * @deprecated Use {@link ProjectConfigurationFile} instead.
+ * @beta
+ */
+export declare const ConfigurationFile: typeof ProjectConfigurationFile;
+/**
+ * @deprecated Use {@link ProjectConfigurationFile} instead.
+ * @beta
+ */
+export type ConfigurationFile<TConfigurationFile> = ProjectConfigurationFile<TConfigurationFile>;
+export { ProjectConfigurationFile, type IProjectConfigurationFileOptions } from './ProjectConfigurationFile';
+export { NonProjectConfigurationFile } from './NonProjectConfigurationFile';
+export * as TestUtilities from './TestUtilities';
 //# sourceMappingURL=index.d.ts.map

lib/index.js

 "use strict";
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PathResolutionMethod = exports.InheritanceType = exports.ConfigurationFile = void 0;
+exports.TestUtilities = exports.NonProjectConfigurationFile = exports.ProjectConfigurationFile = exports.ConfigurationFile = exports.PathResolutionMethod = exports.InheritanceType = exports.ConfigurationFileBase = void 0;
 /**
@@ -12,6 +35,17 @@ * A library for loading config files for use with the
  */
-var ConfigurationFile_1 = require("./ConfigurationFile");
-Object.defineProperty(exports, "ConfigurationFile", { enumerable: true, get: function () { return ConfigurationFile_1.ConfigurationFile; } });
-Object.defineProperty(exports, "InheritanceType", { enumerable: true, get: function () { return ConfigurationFile_1.InheritanceType; } });
-Object.defineProperty(exports, "PathResolutionMethod", { enumerable: true, get: function () { return ConfigurationFile_1.PathResolutionMethod; } });
+var ConfigurationFileBase_1 = require("./ConfigurationFileBase");
+Object.defineProperty(exports, "ConfigurationFileBase", { enumerable: true, get: function () { return ConfigurationFileBase_1.ConfigurationFileBase; } });
+Object.defineProperty(exports, "InheritanceType", { enumerable: true, get: function () { return ConfigurationFileBase_1.InheritanceType; } });
+Object.defineProperty(exports, "PathResolutionMethod", { enumerable: true, get: function () { return ConfigurationFileBase_1.PathResolutionMethod; } });
+const ProjectConfigurationFile_1 = require("./ProjectConfigurationFile");
+/**
+ * @deprecated Use {@link ProjectConfigurationFile} instead.
+ * @beta
+ */
+exports.ConfigurationFile = ProjectConfigurationFile_1.ProjectConfigurationFile;
+var ProjectConfigurationFile_2 = require("./ProjectConfigurationFile");
+Object.defineProperty(exports, "ProjectConfigurationFile", { enumerable: true, get: function () { return ProjectConfigurationFile_2.ProjectConfigurationFile; } });
+var NonProjectConfigurationFile_1 = require("./NonProjectConfigurationFile");
+Object.defineProperty(exports, "NonProjectConfigurationFile", { enumerable: true, get: function () { return NonProjectConfigurationFile_1.NonProjectConfigurationFile; } });
+exports.TestUtilities = __importStar(require("./TestUtilities"));
 //# sourceMappingURL=index.js.map

package.json

 {
   "name": "@rushstack/heft-config-file",
-  "version": "0.15.9",
+  "version": "0.16.0",
   "description": "Configuration file loader for @rushstack/heft",
@@ -24,4 +24,4 @@ "repository": {
   "devDependencies": {
-    "@rushstack/heft": "0.67.2",
-    "@rushstack/heft-node-rig": "2.6.31",
+    "@rushstack/heft": "0.68.7",
+    "@rushstack/heft-node-rig": "2.6.41",
     "@types/heft-jest": "1.0.1",
@@ -28,0 +28,0 @@ "@types/node": "18.17.15",

No alert changes

Improved metrics

Total package byte prevSize

230309

increased by15.16%

Number of package files

27

increased by80%

Lines of code

3687

increased by9.63%

No dependency changes