@fgv/ts-res 5.1.0-0 → 5.1.0-10

package/dist/packlets/import/importManager.js

@@ -45,7 +45,7 @@ export class ImportManager {
         this._importers = [];
         this.resources = params.resources;
         this.initialContext = (_a = params.initialContext) !== null && _a !== void 0 ? _a : ImportContext.create().orThrow();
-        this._importers = Array.from((_b = params.importers) !== null && _b !== void 0 ? _b : ImportManager.getDefaultImporters(this.resources.qualifiers, params.fileTree));
+        this._importers = Array.from((_b = params.importers) !== null && _b !== void 0 ? _b : ImportManager.getDefaultImporters(this.resources.qualifiers, params.fileTree, params.fileContentConverter, params.fileContentExtensions));
     }
     /**
      * Factory method to create a new {@link Import.ImportManager | ImportManager}.
@@ -81,12 +81,16 @@ export class ImportManager {
      * and optional `FileTree`.
      * @param qualifiers - The {@link Qualifiers.IReadOnlyQualifierCollector | qualifiers} to use for the import.
      * @param tree - An optional `FileTree` for importing path items.
+     * @param fileContentConverter - An optional converter used to pre-process raw file contents before JSON import
+     * validation.
+     * @param fileContentExtensions - Optional file extensions which should be parsed using the supplied file
+     * content converter.
      * @returns A read-only array of {@link Import.Importers.IImporter | importers}.
      */
-    static getDefaultImporters(qualifiers, tree) {
+    static getDefaultImporters(qualifiers, tree, fileContentConverter, fileContentExtensions) {
         return [
             PathImporter.create({ qualifiers, tree }).orThrow(),
-            FsItemImporter.create({ qualifiers }).orThrow(),
+            FsItemImporter.create({ qualifiers, fileContentConverter, fileContentExtensions }).orThrow(),
             JsonImporter.create().orThrow(),
             CollectionImporter.create().orThrow()
         ];

package/dist/packlets/import/importers/fsItemImporter.js

@@ -19,7 +19,7 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-import { captureResult, failWithDetail, succeed, succeedWithDetail, MessageAggregator } from '@fgv/ts-utils';
+import { captureResult, failWithDetail, MessageAggregator, succeed, succeedWithDetail } from '@fgv/ts-utils';
 import { Converters as JsonConverters } from '@fgv/ts-json-base';
 import { FsItem } from '../fsItem';
 /**
@@ -37,6 +37,8 @@ export class FsItemImporter {
          */
         this.types = ['fsItem'];
         this.qualifiers = params.qualifiers;
+        this.fileContentConverter = params.fileContentConverter;
+        this.fileContentExtensions = params.fileContentExtensions;
     }
     /**
      * Creates a new {@link Import.Importers.FsItemImporter | FsItemImporter}.
@@ -81,23 +83,37 @@ export class FsItemImporter {
                 .withDetail('failed', 'processed');
         }
         else if (fsItem.item.type === 'file') {
-            if (fsItem.item.extension === '.json') {
-                return fsItem.item
-                    .getContents(JsonConverters.jsonValue)
-                    .onSuccess((json) => {
-                    const jsonItem = {
-                        type: 'json',
-                        json,
-                        context
-                    };
-                    return succeed([jsonItem]);
-                })
-                    .withDetail('failed', 'processed');
+            if (!this._isSupportedFileExtension(fsItem.item.extension)) {
+                return succeedWithDetail([], 'skipped');
             }
+            return this._getJsonContents(fsItem.item)
+                .onSuccess((json) => {
+                const jsonItem = {
+                    type: 'json',
+                    json,
+                    context
+                };
+                return succeed([jsonItem]);
+            })
+                .withDetail('failed', 'processed');
         }
         /* c8 ignore next 2 - defensive coding: fallback case for unsupported file types */
         return succeedWithDetail([], 'skipped');
     }
+    _isSupportedFileExtension(extension) {
+        return extension === '.json' || this._canConvertFileExtension(extension);
+    }
+    _getJsonContents(file) {
+        const converter = this.fileContentConverter;
+        if (converter !== undefined) {
+            return file.getRawContents().onSuccess((contents) => converter.convert(contents));
+        }
+        return file.getContents(JsonConverters.jsonValue);
+    }
+    _canConvertFileExtension(extension) {
+        var _a;
+        return (this.fileContentConverter !== undefined && ((_a = this.fileContentExtensions) === null || _a === void 0 ? void 0 : _a.includes(extension)) === true);
+    }
     /**
      * Gets an {@link Import.FsItem | FsItem} from an {@link Import.IImportable | importable}.
      * @param item - The importable to convert.

package/dist/ts-res.d.ts

@@ -2824,6 +2824,14 @@ declare class FsItemImporter implements IImporter {
      * The {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector} to use for this importer.
      */
     readonly qualifiers: IReadOnlyQualifierCollector;
+    /**
+     * Optional converter used to parse raw file contents before they are exposed as JSON importables.
+     */
+    readonly fileContentConverter?: Converter<JsonValue>;
+    /**
+     * Optional list of file extensions which should be parsed using the file content converter.
+     */
+    readonly fileContentExtensions?: ReadonlyArray<string>;
     /**
      * The types of {@link Import.IImportable | importables} that this importer can handle.
      */
@@ -2843,6 +2851,9 @@ declare class FsItemImporter implements IImporter {
      * {@inheritdoc Import.Importers.IImporter.import}
      */
     import(item: IImportable, __manager: ResourceManagerBuilder): DetailedResult<IImportable[], ImporterResultDetail>;
+    private _isSupportedFileExtension;
+    private _getJsonContents;
+    private _canConvertFileExtension;
     /**
      * Gets an {@link Import.FsItem | FsItem} from an {@link Import.IImportable | importable}.
      * @param item - The importable to convert.
@@ -4021,6 +4032,8 @@ declare const identifierList: RegExp;
  */
 declare interface IFsItemImporterCreateParams {
     qualifiers: IReadOnlyQualifierCollector;
+    fileContentConverter?: Converter<JsonValue>;
+    fileContentExtensions?: ReadonlyArray<string>;
 }
 
 /**
@@ -4204,6 +4217,14 @@ declare interface IImporterCreateParams {
      * An optional list of {@link Import.Importers.IImporter | importers} to use for the import.
      */
     importers?: IImporter[];
+    /**
+     * An optional converter used to pre-process file contents before JSON import validation.
+     */
+    fileContentConverter?: Converter<JsonValue>;
+    /**
+     * Optional file extensions which should be parsed using the supplied file content converter.
+     */
+    fileContentExtensions?: ReadonlyArray<string>;
 }
 
 /**
@@ -4717,9 +4738,13 @@ declare class ImportManager {
      * and optional `FileTree`.
      * @param qualifiers - The {@link Qualifiers.IReadOnlyQualifierCollector | qualifiers} to use for the import.
      * @param tree - An optional `FileTree` for importing path items.
+     * @param fileContentConverter - An optional converter used to pre-process raw file contents before JSON import
+     * validation.
+     * @param fileContentExtensions - Optional file extensions which should be parsed using the supplied file
+     * content converter.
      * @returns A read-only array of {@link Import.Importers.IImporter | importers}.
      */
-    static getDefaultImporters(qualifiers: IReadOnlyQualifierCollector, tree?: FileTree.FileTree): ReadonlyArray<IImporter>;
+    static getDefaultImporters(qualifiers: IReadOnlyQualifierCollector, tree?: FileTree.FileTree, fileContentConverter?: Converter<JsonValue>, fileContentExtensions?: ReadonlyArray<string>): ReadonlyArray<IImporter>;
     /**
      * Imports any items on the import stack.
      * @returns `Success` with the {@link Import.ImportManager | ImportManager} if successful,

package/dist/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.57.6"
+      "packageVersion": "7.57.7"
     }
   ]
 }

package/lib/packlets/import/importManager.d.ts

@@ -1,5 +1,7 @@
 import { Result } from '@fgv/ts-utils';
 import { FileTree } from '@fgv/ts-json-base';
+import { Converter } from '@fgv/ts-utils';
+import { JsonValue } from '@fgv/ts-json-base';
 import { ResourceManagerBuilder } from '../resources';
 import { ImportContext } from './importContext';
 import { IImportable } from './importable';
@@ -27,6 +29,14 @@ export interface IImporterCreateParams {
      * An optional list of {@link Import.Importers.IImporter | importers} to use for the import.
      */
     importers?: IImporter[];
+    /**
+     * An optional converter used to pre-process file contents before JSON import validation.
+     */
+    fileContentConverter?: Converter<JsonValue>;
+    /**
+     * Optional file extensions which should be parsed using the supplied file content converter.
+     */
+    fileContentExtensions?: ReadonlyArray<string>;
 }
 /**
  * Class to manage the import of resources from various sources.
@@ -80,9 +90,13 @@ export declare class ImportManager {
      * and optional `FileTree`.
      * @param qualifiers - The {@link Qualifiers.IReadOnlyQualifierCollector | qualifiers} to use for the import.
      * @param tree - An optional `FileTree` for importing path items.
+     * @param fileContentConverter - An optional converter used to pre-process raw file contents before JSON import
+     * validation.
+     * @param fileContentExtensions - Optional file extensions which should be parsed using the supplied file
+     * content converter.
      * @returns A read-only array of {@link Import.Importers.IImporter | importers}.
      */
-    static getDefaultImporters(qualifiers: IReadOnlyQualifierCollector, tree?: FileTree.FileTree): ReadonlyArray<IImporter>;
+    static getDefaultImporters(qualifiers: IReadOnlyQualifierCollector, tree?: FileTree.FileTree, fileContentConverter?: Converter<JsonValue>, fileContentExtensions?: ReadonlyArray<string>): ReadonlyArray<IImporter>;
     /**
      * Imports any items on the import stack.
      * @returns `Success` with the {@link Import.ImportManager | ImportManager} if successful,

package/lib/packlets/import/importManager.js

@@ -48,7 +48,7 @@ class ImportManager {
         this._importers = [];
         this.resources = params.resources;
         this.initialContext = (_a = params.initialContext) !== null && _a !== void 0 ? _a : importContext_1.ImportContext.create().orThrow();
-        this._importers = Array.from((_b = params.importers) !== null && _b !== void 0 ? _b : ImportManager.getDefaultImporters(this.resources.qualifiers, params.fileTree));
+        this._importers = Array.from((_b = params.importers) !== null && _b !== void 0 ? _b : ImportManager.getDefaultImporters(this.resources.qualifiers, params.fileTree, params.fileContentConverter, params.fileContentExtensions));
     }
     /**
      * Factory method to create a new {@link Import.ImportManager | ImportManager}.
@@ -84,12 +84,16 @@ class ImportManager {
      * and optional `FileTree`.
      * @param qualifiers - The {@link Qualifiers.IReadOnlyQualifierCollector | qualifiers} to use for the import.
      * @param tree - An optional `FileTree` for importing path items.
+     * @param fileContentConverter - An optional converter used to pre-process raw file contents before JSON import
+     * validation.
+     * @param fileContentExtensions - Optional file extensions which should be parsed using the supplied file
+     * content converter.
      * @returns A read-only array of {@link Import.Importers.IImporter | importers}.
      */
-    static getDefaultImporters(qualifiers, tree) {
+    static getDefaultImporters(qualifiers, tree, fileContentConverter, fileContentExtensions) {
         return [
             importers_1.PathImporter.create({ qualifiers, tree }).orThrow(),
-            fsItemImporter_1.FsItemImporter.create({ qualifiers }).orThrow(),
+            fsItemImporter_1.FsItemImporter.create({ qualifiers, fileContentConverter, fileContentExtensions }).orThrow(),
             importers_1.JsonImporter.create().orThrow(),
             importers_1.CollectionImporter.create().orThrow()
         ];

package/lib/packlets/import/importers/fsItemImporter.d.ts

@@ -1,4 +1,5 @@
-import { DetailedResult, Result } from '@fgv/ts-utils';
+import { DetailedResult, Result, Converter } from '@fgv/ts-utils';
+import { JsonValue } from '@fgv/ts-json-base';
 import { ResourceManagerBuilder } from '../../resources';
 import { IImportable } from '../importable';
 import { IImporter, ImporterResultDetail } from './importer';
@@ -10,6 +11,8 @@ import { FsItem, FsItemResultDetail } from '../fsItem';
  */
 export interface IFsItemImporterCreateParams {
     qualifiers: IReadOnlyQualifierCollector;
+    fileContentConverter?: Converter<JsonValue>;
+    fileContentExtensions?: ReadonlyArray<string>;
 }
 /**
  * {@link Import.Importers.IImporter | Importer} implementation which imports resources from a `FileTree`.
@@ -20,6 +23,14 @@ export declare class FsItemImporter implements IImporter {
      * The {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector} to use for this importer.
      */
     readonly qualifiers: IReadOnlyQualifierCollector;
+    /**
+     * Optional converter used to parse raw file contents before they are exposed as JSON importables.
+     */
+    readonly fileContentConverter?: Converter<JsonValue>;
+    /**
+     * Optional list of file extensions which should be parsed using the file content converter.
+     */
+    readonly fileContentExtensions?: ReadonlyArray<string>;
     /**
      * The types of {@link Import.IImportable | importables} that this importer can handle.
      */
@@ -39,6 +50,9 @@ export declare class FsItemImporter implements IImporter {
      * {@inheritdoc Import.Importers.IImporter.import}
      */
     import(item: IImportable, __manager: ResourceManagerBuilder): DetailedResult<IImportable[], ImporterResultDetail>;
+    private _isSupportedFileExtension;
+    private _getJsonContents;
+    private _canConvertFileExtension;
     /**
      * Gets an {@link Import.FsItem | FsItem} from an {@link Import.IImportable | importable}.
      * @param item - The importable to convert.

package/lib/packlets/import/importers/fsItemImporter.js

@@ -40,6 +40,8 @@ class FsItemImporter {
          */
         this.types = ['fsItem'];
         this.qualifiers = params.qualifiers;
+        this.fileContentConverter = params.fileContentConverter;
+        this.fileContentExtensions = params.fileContentExtensions;
     }
     /**
      * Creates a new {@link Import.Importers.FsItemImporter | FsItemImporter}.
@@ -84,23 +86,37 @@ class FsItemImporter {
                 .withDetail('failed', 'processed');
         }
         else if (fsItem.item.type === 'file') {
-            if (fsItem.item.extension === '.json') {
-                return fsItem.item
-                    .getContents(ts_json_base_1.Converters.jsonValue)
-                    .onSuccess((json) => {
-                    const jsonItem = {
-                        type: 'json',
-                        json,
-                        context
-                    };
-                    return (0, ts_utils_1.succeed)([jsonItem]);
-                })
-                    .withDetail('failed', 'processed');
+            if (!this._isSupportedFileExtension(fsItem.item.extension)) {
+                return (0, ts_utils_1.succeedWithDetail)([], 'skipped');
             }
+            return this._getJsonContents(fsItem.item)
+                .onSuccess((json) => {
+                const jsonItem = {
+                    type: 'json',
+                    json,
+                    context
+                };
+                return (0, ts_utils_1.succeed)([jsonItem]);
+            })
+                .withDetail('failed', 'processed');
         }
         /* c8 ignore next 2 - defensive coding: fallback case for unsupported file types */
         return (0, ts_utils_1.succeedWithDetail)([], 'skipped');
     }
+    _isSupportedFileExtension(extension) {
+        return extension === '.json' || this._canConvertFileExtension(extension);
+    }
+    _getJsonContents(file) {
+        const converter = this.fileContentConverter;
+        if (converter !== undefined) {
+            return file.getRawContents().onSuccess((contents) => converter.convert(contents));
+        }
+        return file.getContents(ts_json_base_1.Converters.jsonValue);
+    }
+    _canConvertFileExtension(extension) {
+        var _a;
+        return (this.fileContentConverter !== undefined && ((_a = this.fileContentExtensions) === null || _a === void 0 ? void 0 : _a.includes(extension)) === true);
+    }
     /**
      * Gets an {@link Import.FsItem | FsItem} from an {@link Import.IImportable | importable}.
      * @param item - The importable to convert.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-res",
-  "version": "5.1.0-0",
+  "version": "5.1.0-10",
   "description": "Multi-dimensional Resource Runtime",
   "main": "lib/index.js",
   "types": "dist/ts-res.d.ts",
@@ -39,22 +39,24 @@
     "typescript": "5.9.3",
     "eslint-plugin-n": "^17.23.1",
     "@rushstack/eslint-config": "4.6.4",
-    "@rushstack/heft": "1.2.6",
+    "@rushstack/heft": "1.2.7",
     "@rushstack/heft-jest-plugin": "1.2.6",
-    "@rushstack/heft-node-rig": "2.11.26",
+    "@rushstack/heft-node-rig": "2.11.27",
     "@types/heft-jest": "1.0.6",
     "eslint-plugin-tsdoc": "~0.5.2",
-    "@fgv/heft-dual-rig": "0.1.0",
-    "@fgv/ts-extras": "5.1.0-0",
-    "@fgv/ts-utils-jest": "5.1.0-0"
+    "typedoc": "~0.28.16",
+    "@fgv/heft-dual-rig": "5.1.0-10",
+    "@fgv/typedoc-compact-theme": "5.1.0-10",
+    "@fgv/ts-utils-jest": "5.1.0-10",
+    "@fgv/ts-extras": "5.1.0-10"
   },
   "dependencies": {
     "luxon": "^3.7.2",
     "fflate": "~0.8.2",
-    "@fgv/ts-utils": "5.1.0-0",
-    "@fgv/ts-json-base": "5.1.0-0",
-    "@fgv/ts-bcp47": "5.1.0-0",
-    "@fgv/ts-json": "5.1.0-0"
+    "@fgv/ts-utils": "5.1.0-10",
+    "@fgv/ts-bcp47": "5.1.0-10",
+    "@fgv/ts-json-base": "5.1.0-10",
+    "@fgv/ts-json": "5.1.0-10"
   },
   "exports": {
     ".": {