@fgv/ts-res 5.0.1-9 → 5.0.1

package/dist/packlets/import/fsItem.js

@@ -0,0 +1,134 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { captureResult, mapResults, fail, succeed, useOrInitialize } from '@fgv/ts-utils';
+import { FileTree } from '@fgv/ts-json-base';
+import { Helpers as CommonHelpers, Validate } from '../common';
+import * as Conditions from '../conditions';
+import { ImportContext } from './importContext';
+/**
+ * Class describing some file system item to be imported.
+ * @public
+ */
+export class FsItem {
+    /**
+     * Protected constructor creates a new {@link Import.FsItem | FsItem}.
+     * @param props - The {@link Import.IFsItemProps | file system item properties} to use for this item.
+     * @param qualifiers - The {@link Qualifiers.IReadOnlyQualifierCollector | qualifiers} used to parse
+     * embedded condition set tokens.
+     * @param tree - file tree implementation to use for this item.
+     * @returns `Success` containing the new {@link Import.FsItem | FsItem} if successful, or a `Failure`
+     * containing an error message if not.
+     */
+    constructor(props, qualifiers) {
+        const { baseName, conditions, item } = props;
+        this.baseName = baseName;
+        this.conditions = conditions;
+        this.item = item;
+        this.qualifiers = qualifiers;
+    }
+    /**
+     * Creates a new {@link Import.FsItem | FsItem} from a `FileTreeItem`.
+     * @param item - The `FileTreeItem` to import.
+     * @param qualifiers - The {@link Qualifiers.IReadOnlyQualifierCollector | qualifiers} used to parse
+     * embedded condition set tokens.
+     * @returns `Success` containing the new {@link Import.FsItem | FsItem} if successful, or a `Failure`
+     * containing an error message if not.  Note that the result detail `skipped` indicates that the item
+     * was not created because it is not relevant - this is a soft error that should be silently ignored.
+     */
+    static createForItem(item, qualifiers) {
+        const baseName = item.type === 'file' ? item.baseName : item.name;
+        return FsItem.tryParseBaseName(baseName, qualifiers)
+            .withErrorFormat((msg) => `${baseName}: error extracting conditions - ${msg}`)
+            .onSuccess(({ baseName: newBaseName, conditions }) => {
+            return captureResult(() => new FsItem({ baseName: newBaseName, conditions, item }, qualifiers));
+        })
+            .withDetail('failed', 'succeeded');
+    }
+    /**
+     * Creates a new {@link Import.FsItem | FsItem} from a file system path.
+     * @param importPath - The path to the file system item to import.
+     * @param qualifiers - The {@link Qualifiers.IReadOnlyQualifierCollector | qualifiers} used to parse
+     * embedded condition set tokens.
+     * @param fs - An optional {@link Import.IImporterFilesystem | file system implementation} to use for this item.
+     * @returns `Success` containing the new {@link Import.FsItem | FsItem} if an item is created
+     * successfully, or a `Failure` containing an error message if it is not.  Note that the result detail
+     * `skipped` indicates that the item was not created because it is not relevant - this is a soft error
+     * that should be silently ignored.
+     */
+    static createForPath(importPath, qualifiers, tree) {
+        return useOrInitialize(tree, () => FileTree.forFilesystem())
+            .withDetail('failed', 'succeeded')
+            .onSuccess((tree) => {
+            return tree
+                .getItem(importPath)
+                .withDetail('failed')
+                .onSuccess((item) => FsItem.createForItem(item, qualifiers));
+        });
+    }
+    /**
+     * Tries to parse a base name into a base name and a set of conditions.
+     * @param baseName - The base name to parse.
+     * @param qualifiers - The {@link Qualifiers.IReadOnlyQualifierCollector | qualifiers} used to parse
+     * embedded condition set tokens.
+     * @returns `Success` containing the parsed base name and conditions on success, or `Failure` containing
+     * an error message if it is not.
+     */
+    static tryParseBaseName(baseName, qualifiers) {
+        const nameParts = baseName.split('.');
+        const segmentToTest = nameParts.length > 1 ? nameParts[nameParts.length - 1] : nameParts[0];
+        const validatedConditions = CommonHelpers.parseConditionSetTokenParts(segmentToTest).onSuccess((parts) => {
+            return mapResults(parts.map((part) => Conditions.ConditionTokens.validateConditionTokenParts(part, qualifiers))).onFailure((msg) => {
+                if (parts.length === 1 && parts[0].qualifier === undefined) {
+                    return succeed([]);
+                }
+                return fail(msg);
+            });
+        });
+        if (validatedConditions.isFailure()) {
+            return fail(validatedConditions.message);
+        }
+        const conditions = validatedConditions.value;
+        if (conditions.length > 0) {
+            baseName = nameParts.filter((s) => s !== segmentToTest).join('.');
+        }
+        return succeed({ baseName, conditions });
+    }
+    /**
+     * Gets the context for this file system item.
+     * @returns `Success` containing the {@link Import.ImportContext | import context} for this item
+     * if successful, or a `Failure` containing an error message if an error occurs.
+     */
+    getContext() {
+        return Validate.toOptionalResourceId(this.baseName).onSuccess((baseId) => {
+            const conditions = this.conditions.map((c) => {
+                return {
+                    qualifierName: c.qualifier.name,
+                    value: c.value,
+                    operator: c.operator,
+                    priority: c.priority
+                };
+            });
+            return ImportContext.create({ baseId, conditions });
+        });
+    }
+}
+//# sourceMappingURL=fsItem.js.map

package/dist/packlets/import/importContext.js

@@ -0,0 +1,129 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { Helpers } from '../common';
+import { captureResult, succeed } from '@fgv/ts-utils';
+/**
+ * Class to accumulate context for a resource import operation.
+ * @public
+ */
+export class ImportContext {
+    /**
+     * Protected {@link Import.ImportContext | import context} for derived classes.
+     * Public consumers use {@link Import.ImportContext.create | create} to create new instances.
+     * @param baseId - The base ID for the import context.
+     * @param conditions - Conditions to be applied to resources imported in this context.
+     */
+    constructor({ baseId, conditions }) {
+        this.baseId = Helpers.joinOptionalResourceIds(baseId).orThrow();
+        this.conditions = Array.from(conditions !== null && conditions !== void 0 ? conditions : []);
+    }
+    /**
+     * Factory method to create a new {@link Import.ImportContext | import context}.
+     * @param context - The {@link Import.IImportContext | import context} to create
+     * the new context from.
+     * @returns `Success` with the new {@link Import.ImportContext | import context}
+     * if successful, or `Failure` with an error message if creation fails.
+     */
+    static create(context) {
+        /* c8 ignore next */
+        context = context !== null && context !== void 0 ? context : { conditions: [] };
+        return captureResult(() => new ImportContext(context));
+    }
+    /**
+     * Adds conditions to the import context.
+     * @param conditions - Conditions to be added to the import context.
+     * @returns `Success` with a new {@link Import.ImportContext | import context} containing the added conditions
+     * if successful, or `Failure` with an error message if the operation fails.
+     */
+    withConditions(conditions) {
+        return ImportContext.create({
+            baseId: this.baseId,
+            conditions: [...this.conditions, ...conditions]
+        });
+    }
+    /**
+     * Appends names to the base ID of the import context.
+     * @param name - The base name to set.
+     * @returns `Success` with a new {@link Import.ImportContext | import context} containing the new base ID
+     * if successful, or `Failure` with an error message if the operation fails.
+     */
+    withName(...names) {
+        return Helpers.joinResourceIds(this.baseId, ...names).onSuccess((baseId) => {
+            return ImportContext.create({ baseId, conditions: this.conditions });
+        });
+    }
+    /**
+     * Extends the import context with additional name segments and conditions.
+     * @param context - The {@link Import.IImportContext | import context} to extend this context with.
+     * @returns `Success` with a new {@link Import.ImportContext | import context}
+     * containing the extended context if successful, or `Failure` with an error
+     * message if the operation fails.
+     */
+    extend(context) {
+        /* c8 ignore next 1 */
+        context = context !== null && context !== void 0 ? context : { conditions: [] };
+        const conditions = [...this.conditions, ...context.conditions];
+        return Helpers.joinOptionalResourceIds(this.baseId, context.baseId).onSuccess((baseId) => {
+            return ImportContext.create({ baseId, conditions });
+        });
+    }
+    /**
+     * Creates a new {@link Import.ImportContext | import context} to import resources from a
+     * container with the specified {@link ResourceJson.Normalized.IContainerContextDecl | container context declaration}e
+     * @param container - The {@link ResourceJson.Normalized.IContainerContextDecl | container context declaration}
+     * to consider when creating the new context.
+     * @param importer - The base {@link Import.ImportContext | import context} to adjust for the container
+     * context.
+     * @returns `Success` with the new {@link Import.ImportContext | import context} if successful,
+     * or `Failure` with an error message if the operation fails.
+     * @remarks
+     * A container context declaration may specify a merge method, which determines how the
+     * container context is merged with the base context. The merge method can be one of the following:
+     * - `augment`: The base context is augmented with the container context. This is the default behavior.
+     * - `replace`: The base context is selectively replaced with the container context. If the container context
+     *   specifies a base ID or conditions, the corresponding values in the base context are ignored.
+     * - `delete`: The base context is deleted. This means that the container context is not used at all.
+     */
+    static forContainerImport(container, importer) {
+        var _a;
+        if (!importer) {
+            return succeed(undefined);
+        }
+        /* c8 ignore next 1 */
+        container = container !== null && container !== void 0 ? container : {};
+        const mergeMethod = (_a = container.mergeMethod) !== null && _a !== void 0 ? _a : 'augment';
+        switch (mergeMethod) {
+            case 'augment':
+                return succeed(importer);
+            case 'replace': {
+                // if the container defines baseId or conditions, then we ignore
+                // the corresponding values in the importer
+                const baseId = container.baseId ? undefined : importer.baseId;
+                const conditions = container.conditions ? undefined : importer.conditions;
+                return ImportContext.create({ baseId, conditions });
+            }
+            case 'delete':
+                return succeed(undefined);
+        }
+    }
+}
+//# sourceMappingURL=importContext.js.map

package/dist/packlets/import/importManager.js

@@ -0,0 +1,129 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { captureResult, MessageAggregator, succeed } from '@fgv/ts-utils';
+import { ImportContext } from './importContext';
+import { FsItemImporter } from './importers/fsItemImporter';
+import { CollectionImporter, JsonImporter, PathImporter } from './importers';
+/**
+ * Class to manage the import of resources from various sources.
+ * @public
+ */
+export class ImportManager {
+    /**
+     * The list of {@link Import.Importers.IImporter | importers} to use for the
+     * import operations.
+     */
+    get importers() {
+        return this._importers;
+    }
+    /**
+     * Protected constructor for the {@link Import.ImportManager | ImportManager}.
+     * @param params - Parameters for creating the {@link Import.ImportManager | ImportManager}.
+     */
+    constructor(params) {
+        var _a, _b;
+        this._stack = [];
+        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));
+    }
+    /**
+     * Factory method to create a new {@link Import.ImportManager | ImportManager}.
+     * @param params - Parameters for creating the {@link Import.ImportManager | ImportManager}.
+     * @returns `Success` with the new {@link Import.ImportManager | ImportManager}
+     * if successful, or `Failure` with an error message if creation fails.
+     */
+    static create(params) {
+        return captureResult(() => new ImportManager(params));
+    }
+    /**
+     * Imports resources from an {@link Import.IImportable | importable} object.
+     * @param importable - The {@link Import.IImportable | importable} object to import.
+     * @returns `Success` with the {@link Import.ImportManager | ImportManager} if successful,
+     * or `Failure` with an error message if the import fails.
+     */
+    import(importable) {
+        this._stack.push(importable);
+        return this._import();
+    }
+    /**
+     * Imports resources from a file system path.
+     * @param filePath - The path to import resources from.
+     * @returns `Success` with the {@link Import.ImportManager | ImportManager} if successful,
+     * or `Failure` with an error message if the import fails.
+     */
+    importFromFileSystem(filePath) {
+        const importable = { type: 'path', path: filePath };
+        return this.import(importable);
+    }
+    /**
+     * Gets the default importers using supplied {@link Qualifiers.IReadOnlyQualifierCollector | qualifiers}
+     * and optional `FileTree`.
+     * @param qualifiers - The {@link Qualifiers.IReadOnlyQualifierCollector | qualifiers} to use for the import.
+     * @param tree - An optional `FileTree` for importing path items.
+     * @returns A read-only array of {@link Import.Importers.IImporter | importers}.
+     */
+    static getDefaultImporters(qualifiers, tree) {
+        return [
+            PathImporter.create({ qualifiers, tree }).orThrow(),
+            FsItemImporter.create({ qualifiers }).orThrow(),
+            JsonImporter.create().orThrow(),
+            CollectionImporter.create().orThrow()
+        ];
+    }
+    /**
+     * Imports any items on the import stack.
+     * @returns `Success` with the {@link Import.ImportManager | ImportManager} if successful,
+     * or `Failure` with an error message if the import fails.
+     * @public
+     */
+    _import() {
+        const errors = new MessageAggregator();
+        while (this._stack.length > 0) {
+            const item = this._stack.pop();
+            if (item !== undefined) {
+                let processed = false;
+                let consumed = false;
+                for (const importer of this._importers) {
+                    if (consumed || !importer.types.includes(item.type)) {
+                        continue;
+                    }
+                    const result = importer.import(item, this.resources).aggregateError(errors);
+                    processed = processed || result.detail !== 'skipped';
+                    consumed = consumed || result.detail === 'consumed';
+                    if (result.isSuccess()) {
+                        this._stack.push(...result.value);
+                    }
+                    else if (result.detail !== 'skipped') {
+                        errors.addMessage(`${item.type}: ${result.message}`);
+                    }
+                }
+                if (!processed) {
+                    errors.addMessage(`${item.type}: No matching importer found`);
+                }
+            }
+        }
+        return errors.returnOrReport(succeed(this));
+    }
+}
+//# sourceMappingURL=importManager.js.map

package/dist/packlets/import/importable.js

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+/**
+ * Type guard for {@link Import.Importable | importables}.
+ * @param i - The entity to check.
+ * @returns `true` if the supplied {@link Import.IImportable | IImportable} is a
+ * {@link Import.Importable | known importable}, `false` otherwise.
+ * @public
+ */
+export function isImportable(i) {
+    return ['path', 'fsItem', 'json', 'resourceCollection', 'resourceTree'].includes(i.type);
+}
+//# sourceMappingURL=importable.js.map

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

@@ -0,0 +1,118 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { captureResult, failWithDetail, MessageAggregator, succeed } from '@fgv/ts-utils';
+import { isImportable } from '../importable';
+import * as ResourceJson from '../../resource-json';
+import { ImportContext } from '../importContext';
+/**
+ * {@link Import.Importers.IImporter | Importer} implementation which imports
+ * a {@link ResourceJson.ResourceDeclCollection | resource collection} or
+ * {@link ResourceJson.ResourceDeclTree | resource tree} from an importable item.
+ * @public
+ */
+export class CollectionImporter {
+    /**
+     * Protected {@link Import.Importers.CollectionImporter | CollectionImporter} constructor for derived classes
+     */
+    constructor() {
+        /**
+         * {@inheritdoc Import.Importers.IImporter.types}
+         */
+        this.types = ['resourceCollection', 'resourceTree'];
+    }
+    /**
+     * Creates a new {@link Import.Importers.CollectionImporter | CollectionImporter} instance.
+     * @returns `Success` with the new {@link Import.Importers.CollectionImporter | CollectionImporter} if successful,
+     * `Failure` otherwise.
+     */
+    static create() {
+        return captureResult(() => new CollectionImporter());
+    }
+    /**
+     * {@inheritdoc Import.Importers.IImporter.import}
+     */
+    import(item, manager) {
+        var _a, _b;
+        if (!isImportable(item) || (item.type !== 'resourceCollection' && item.type !== 'resourceTree')) {
+            /* c8 ignore next 1 - defense in depth */
+            const name = (_b = (_a = item.context) === null || _a === void 0 ? void 0 : _a.baseId) !== null && _b !== void 0 ? _b : 'unknown';
+            return failWithDetail(`${name}: invalid resource collection importable (${item.type})`, 'skipped');
+        }
+        const container = item.type === 'resourceCollection' ? item.collection : item.tree;
+        return ImportContext.forContainerImport(container.context, item.context)
+            .onSuccess((context) => {
+            const errors = new MessageAggregator();
+            for (const resource of container.getImporterResources()) {
+                this._addResource(manager, resource, context).aggregateError(errors);
+            }
+            for (const candidate of container.getImporterCandidates()) {
+                this._addCandidate(manager, candidate, context).aggregateError(errors);
+            }
+            return errors.returnOrReport(succeed([]));
+        })
+            .withDetail('failed', 'consumed');
+    }
+    /**
+     * Adds a {@link ResourceJson.Normalized.IImporterResourceDecl | declared resource} to
+     * the supplied {@link Resources.ResourceManagerBuilder | resource manager builder}, merging an
+     * optional {@link Import.ImportContext | import context} if provided.
+     * @param manager - The {@link Resources.ResourceManagerBuilder | resource manager builder} to which
+     * the resource will be added.
+     * @param resource - The {@link ResourceJson.Normalized.IImporterResourceDecl | resource}
+     * to add.
+     * @param context - Optional {@link Import.ImportContext | import context} to merge
+     * with the resource.
+     * @returns `Success` with the {@link Resources.ResourceBuilder | resource builder}
+     * for the resource if successful, `Failure` with an error message if not.
+     */
+    _addResource(manager, resource, context) {
+        if (context) {
+            return ResourceJson.Helpers.mergeLooseResource(resource, context.baseId, context.conditions).onSuccess((merged) => manager.addResource(merged));
+        } /* c8 ignore next 4 - defense in depth, should be guarded elsewhere */
+        else if (!ResourceJson.Json.isLooseResourceDecl(resource)) {
+            return fail('cannot add child resource to manager');
+        }
+        return manager.addResource(resource);
+    }
+    /**
+     * Adds a {@link ResourceJson.Normalized.IImporterResourceCandidateDecl | declared resource candidate}
+     * to the supplied {@link Resources.ResourceManagerBuilder | resource manager builder}, merging an optional
+     * {@link Import.ImportContext | import context} if provided.
+     * @param manager - The {@link Resources.ResourceManagerBuilder | resource manager builder} to which the
+     * candidate will be added.
+     * @param candidate - The {@link ResourceJson.Normalized.IImporterResourceCandidateDecl | candidate}
+     * to add.
+     * @param context - Optional {@link Import.ImportContext | import context} to merge with the candidate.
+     * @returns `Success` with the {@link Resources.ResourceCandidate | resource candidate} if successful,
+     * `Failure` with an error message if not.
+     */
+    _addCandidate(manager, candidate, context) {
+        if (context) {
+            return ResourceJson.Helpers.mergeLooseCandidate(candidate, context.baseId, context.conditions).onSuccess((merged) => manager.addLooseCandidate(merged));
+        } /* c8 ignore next 4 - defense in depth, should be guarded elsewhere */
+        else if (!ResourceJson.Json.isLooseResourceCandidateDecl(candidate)) {
+            return fail('cannot add child resource candidate to manager');
+        }
+        return manager.addLooseCandidate(candidate);
+    }
+}
+//# sourceMappingURL=collectionImporter.js.map

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

@@ -0,0 +1,116 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * 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 { Converters as JsonConverters } from '@fgv/ts-json-base';
+import { FsItem } from '../fsItem';
+/**
+ * {@link Import.Importers.IImporter | Importer} implementation which imports resources from a `FileTree`.
+ * @public
+ */
+export class FsItemImporter {
+    /**
+     * Protected constructor for the {@link Import.Importers.FsItemImporter | FsItemImporter}.
+     * @param params - Parameters for creating the {@link Import.Importers.FsItemImporter | FsItemImporter}.
+     */
+    constructor(params) {
+        /**
+         * The types of {@link Import.IImportable | importables} that this importer can handle.
+         */
+        this.types = ['fsItem'];
+        this.qualifiers = params.qualifiers;
+    }
+    /**
+     * Creates a new {@link Import.Importers.FsItemImporter | FsItemImporter}.
+     * @param params - Parameters for creating the {@link Import.Importers.FsItemImporter | FsItemImporter}.
+     * @returns `Success` with the new `FsItemImporter` if successful, `Failure` with an error message if not.
+     */
+    static create(params) {
+        return captureResult(() => new FsItemImporter(params));
+    }
+    /**
+     * {@inheritdoc Import.Importers.IImporter.import}
+     */
+    import(item, __manager) {
+        const { value: fsItem, message: getTreeMessage, detail: getTreeDetail } = this._getFileTreeItemFromImportable(item);
+        if (getTreeMessage !== undefined) {
+            return failWithDetail(getTreeMessage, getTreeDetail === 'skipped' ? 'skipped' : 'failed');
+        }
+        const { value: context, message: getContextMessage } = fsItem.getContext().onSuccess((fsItemContext) => {
+            return item.context ? item.context.extend(fsItemContext) : succeed(fsItemContext);
+        });
+        /* c8 ignore next 3 - defensive coding: getContext failure is extremely rare in practice */
+        if (getContextMessage) {
+            return failWithDetail(getContextMessage, 'failed');
+        }
+        if (fsItem.item.type === 'directory') {
+            return fsItem.item
+                .getChildren()
+                .onSuccess((children) => {
+                const errors = new MessageAggregator();
+                const items = [];
+                for (const child of children) {
+                    const { value: item, message, detail } = FsItem.createForItem(child, this.qualifiers);
+                    if (item) {
+                        items.push({ type: 'fsItem', item, context });
+                    }
+                    else if (detail !== 'skipped') {
+                        errors.addMessage(message);
+                    }
+                }
+                return errors.returnOrReport(succeed(items));
+            })
+                .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');
+            }
+        }
+        /* c8 ignore next 2 - defensive coding: fallback case for unsupported file types */
+        return succeedWithDetail([], 'skipped');
+    }
+    /**
+     * Gets an {@link Import.FsItem | FsItem} from an {@link Import.IImportable | importable}.
+     * @param item - The importable to convert.
+     * @returns `Success` containing the `FsItem` if successful, `Failure` with an error message if not.
+     */
+    _getFileTreeItemFromImportable(item) {
+        if (item.type === 'fsItem') {
+            if ('item' in item && item.item instanceof FsItem) {
+                return succeedWithDetail(item.item, 'succeeded');
+            }
+            return failWithDetail(`malformed fsItem importable does not contain a valid item`, 'failed');
+        }
+        return failWithDetail(`${item.type}: invalid importable type for an FsItemImporter`, 'skipped');
+    }
+}
+//# sourceMappingURL=fsItemImporter.js.map