@fgv/ts-res 5.0.0-2 → 5.0.0-21

package/src/packlets/import/importManager.ts

@@ -0,0 +1,187 @@
+/*
+ * 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, FileTree, MessageAggregator, Result, succeed } from '@fgv/ts-utils';
+import { ResourceManagerBuilder } from '../resources';
+import { ImportContext } from './importContext';
+import { IImportable, IImportablePath } from './importable';
+import { FsItemImporter } from './importers/fsItemImporter';
+import { CollectionImporter, IImporter, JsonImporter, PathImporter } from './importers';
+import { IReadOnlyQualifierCollector } from '../qualifiers';
+
+/**
+ * Parameters for creating an {@link  Import.ImportManager | ImportManager}.
+ * @public
+ */
+export interface IImporterCreateParams {
+  /**
+   * The {@link Resources.ResourceManagerBuilder | resource manager builder} into which resources
+   * will be imported.
+   */
+  resources: ResourceManagerBuilder;
+
+  /**
+   * An optional initial {@link Import.ImportContext | import context} for the import operation.
+   */
+  initialContext?: ImportContext;
+
+  /**
+   * An optional `FileTree` for importing path items.
+   */
+  fileTree?: FileTree.FileTree;
+
+  /**
+   * An optional list of {@link Import.Importers.IImporter | importers} to use for the import.
+   */
+  importers?: IImporter[];
+}
+
+/**
+ * Class to manage the import of resources from various sources.
+ * @public
+ */
+export class ImportManager {
+  /**
+   * The {@link Resources.ResourceManagerBuilder | resource manager builder} into which resources
+   * will be imported.
+   */
+  public readonly resources: ResourceManagerBuilder;
+
+  /**
+   * The list of {@link Import.Importers.IImporter | importers} to use for the
+   * import operations.
+   */
+  public get importers(): ReadonlyArray<IImporter> {
+    return this._importers;
+  }
+
+  /**
+   * The initial {@link Import.ImportContext | import context} for the import operation.
+   */
+  public initialContext: ImportContext;
+
+  protected _stack: IImportable[] = [];
+  protected _importers: IImporter[] = [];
+
+  /**
+   * Protected constructor for the {@link Import.ImportManager | ImportManager}.
+   * @param params - Parameters for creating the {@link Import.ImportManager | ImportManager}.
+   */
+  protected constructor(params: IImporterCreateParams) {
+    this.resources = params.resources;
+    this.initialContext = params.initialContext ?? ImportContext.create().orThrow();
+    this._importers = Array.from(
+      params.importers ?? 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.
+   */
+  public static create(params: IImporterCreateParams): Result<ImportManager> {
+    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.
+   */
+  public import(importable: IImportable): Result<ImportManager> {
+    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.
+   */
+  public importFromFileSystem(filePath: string): Result<ImportManager> {
+    const importable: IImportablePath = { 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}.
+   */
+  public static getDefaultImporters(
+    qualifiers: IReadOnlyQualifierCollector,
+    tree?: FileTree.FileTree
+  ): ReadonlyArray<IImporter> {
+    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
+   */
+  protected _import(): Result<ImportManager> {
+    const errors: MessageAggregator = new MessageAggregator();
+
+    while (this._stack.length > 0) {
+      const item = this._stack.pop();
+      if (item !== undefined) {
+        let processed: boolean = false;
+        let consumed: boolean = 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));
+  }
+}

package/src/packlets/import/importable.ts

@@ -0,0 +1,107 @@
+/*
+ * 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 { JsonValue } from '@fgv/ts-json-base';
+import * as ResourceJson from '../resource-json';
+import { ImportContext } from './importContext';
+import { FsItem } from './fsItem';
+
+/**
+ * Base interface for importable entities.
+ * @public
+ */
+export interface IImportable {
+  type: string;
+  context?: ImportContext;
+}
+
+/**
+ * Represents a filesystem path to be imported.
+ * @public
+ */
+export interface IImportablePath extends IImportable {
+  type: 'path';
+  path: string;
+  context?: ImportContext;
+}
+
+/**
+ * Represents a filesystem item to be imported.
+ * @public
+ */
+export interface IImportableFsItem extends IImportable {
+  type: 'fsItem';
+  item: FsItem;
+  context?: ImportContext;
+}
+
+/**
+ * Represents some JSON to be imported.
+ * @public
+ */
+export interface IImportableJson extends IImportable {
+  type: 'json';
+  json: JsonValue;
+  context?: ImportContext;
+}
+
+/**
+ * Represents a resource collection to be imported.
+ * @public
+ */
+export interface IImportableResourceCollection extends IImportable {
+  type: 'resourceCollection';
+  collection: ResourceJson.ResourceDeclCollection;
+  context?: ImportContext;
+}
+
+/**
+ * Represents a resource tree to be imported.
+ * @public
+ */
+export interface IImportableResourceTree extends IImportable {
+  type: 'resourceTree';
+  tree: ResourceJson.ResourceDeclTree;
+  context?: ImportContext;
+}
+
+/**
+ * Type of importable entities.
+ * @public
+ */
+export type Importable =
+  | IImportablePath
+  | IImportableFsItem
+  | IImportableJson
+  | IImportableResourceCollection
+  | IImportableResourceTree;
+
+/**
+ * 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: IImportable): i is Importable {
+  return ['path', 'fsItem', 'json', 'resourceCollection', 'resourceTree'].includes(i.type);
+}

package/src/packlets/import/importers/collectionImporter.ts

@@ -0,0 +1,153 @@
+/*
+ * 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,
+  DetailedResult,
+  failWithDetail,
+  MessageAggregator,
+  Result,
+  succeed
+} from '@fgv/ts-utils';
+import { ResourceBuilder, ResourceCandidate, ResourceManagerBuilder } from '../../resources';
+import { IImportable, isImportable } from '../importable';
+import { IImporter, ImporterResultDetail } from './importer';
+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 implements IImporter {
+  /**
+   * {@inheritdoc Import.Importers.IImporter.types}
+   */
+  public readonly types: string[] = ['resourceCollection', 'resourceTree'];
+
+  /**
+   * Protected {@link Import.Importers.CollectionImporter | CollectionImporter} constructor for derived classes
+   */
+  protected constructor() {}
+
+  /**
+   * Creates a new {@link Import.Importers.CollectionImporter | CollectionImporter} instance.
+   * @returns `Success` with the new {@link Import.Importers.CollectionImporter | CollectionImporter} if successful,
+   * `Failure` otherwise.
+   */
+  public static create(): Result<CollectionImporter> {
+    return captureResult(() => new CollectionImporter());
+  }
+
+  /**
+   * {@inheritdoc Import.Importers.IImporter.import}
+   */
+  public import(
+    item: IImportable,
+    manager: ResourceManagerBuilder
+  ): DetailedResult<IImportable[], ImporterResultDetail> {
+    if (!isImportable(item) || (item.type !== 'resourceCollection' && item.type !== 'resourceTree')) {
+      /* c8 ignore next 1 - defense in depth */
+      const name = item.context?.baseId ?? 'unknown';
+      return failWithDetail(`${name}: not a valid 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: MessageAggregator = 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.
+   */
+  private _addResource(
+    manager: ResourceManagerBuilder,
+    resource: ResourceJson.Normalized.IImporterResourceDecl,
+    context?: ImportContext
+  ): Result<ResourceBuilder> {
+    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.
+   */
+  private _addCandidate(
+    manager: ResourceManagerBuilder,
+    candidate: ResourceJson.Normalized.IImporterResourceCandidateDecl,
+    context?: ImportContext
+  ): Result<ResourceCandidate> {
+    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);
+  }
+}

package/src/packlets/import/importers/fsItemImporter.ts

@@ -0,0 +1,154 @@
+/*
+ * 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,
+  DetailedResult,
+  failWithDetail,
+  Result,
+  succeed,
+  succeedWithDetail,
+  MessageAggregator
+} from '@fgv/ts-utils';
+import { Converters as JsonConverters } from '@fgv/ts-json-base';
+import { ResourceManagerBuilder } from '../../resources';
+import { IImportable, IImportableJson, Importable } from '../importable';
+import { IImporter, ImporterResultDetail } from './importer';
+import { IReadOnlyQualifierCollector } from '../../qualifiers';
+import { FsItem, FsItemResultDetail } from '../fsItem';
+
+/**
+ * Parameters for creating a {@link Import.Importers.FsItemImporter | FsItemImporter}.
+ * @public
+ */
+export interface IFsItemImporterCreateParams {
+  qualifiers: IReadOnlyQualifierCollector;
+}
+
+/**
+ * {@link Import.Importers.IImporter | Importer} implementation which imports resources from a `FileTree`.
+ * @public
+ */
+export class FsItemImporter implements IImporter {
+  /**
+   * The {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector} to use for this importer.
+   */
+  public readonly qualifiers: IReadOnlyQualifierCollector;
+
+  /**
+   * The types of {@link Import.IImportable | importables} that this importer can handle.
+   */
+  public readonly types: ReadonlyArray<string> = ['fsItem'];
+
+  /**
+   * Protected constructor for the {@link Import.Importers.FsItemImporter | FsItemImporter}.
+   * @param params - Parameters for creating the {@link Import.Importers.FsItemImporter | FsItemImporter}.
+   */
+  protected constructor(params: IFsItemImporterCreateParams) {
+    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.
+   */
+  public static create(params: IFsItemImporterCreateParams): Result<FsItemImporter> {
+    return captureResult(() => new FsItemImporter(params));
+  }
+
+  /**
+   * {@inheritdoc Import.Importers.IImporter.import}
+   */
+  public import(
+    item: IImportable,
+    __manager: ResourceManagerBuilder
+  ): DetailedResult<IImportable[], ImporterResultDetail> {
+    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: Importable[] = [];
+          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: IImportableJson = {
+              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.
+   */
+  protected _getFileTreeItemFromImportable(item: IImportable): DetailedResult<FsItem, FsItemResultDetail> {
+    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');
+  }
+}

package/src/packlets/import/importers/importer.ts

@@ -0,0 +1,58 @@
+/*
+ * 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 { DetailedResult } from '@fgv/ts-utils';
+import { IImportable } from '../importable';
+import { ResourceManagerBuilder } from '../../resources';
+
+/**
+ * Possible results of an import operation.
+ * @public
+ */
+export type ImporterResultDetail = 'consumed' | 'processed' | 'skipped' | 'failed';
+
+/**
+ * Generic interface for an importer than accepts a typed
+ * {@link Import.IImportable | importable} item, extracts any resources
+ * or candidates from it, and returns an optional list of
+ * additional importable items derived from the original.
+ * @public
+ */
+export interface IImporter {
+  /**
+   * The types of {@link Import.Importable | importable} items that this importer can process.
+   */
+  readonly types: ReadonlyArray<string>;
+
+  /**
+   * Imports an item, extracting any resources or candidates from it and returns an optional
+   * list of additional importable items derived from it.
+   * @param item - The {@link Import.IImportable | importable} item to import.
+   * @param manager - The {@link Resources.ResourceManagerBuilder | resource manager builder} to use for the import.
+   * @returns `Success` with a list of additional importable items derived from the original, or
+   * `Failure` with an error message and a {@link Import.Importers.ImporterResultDetail | result detail}.
+   */
+  import(
+    item: IImportable,
+    manager: ResourceManagerBuilder
+  ): DetailedResult<IImportable[], ImporterResultDetail>;
+}

package/src/packlets/import/importers/index.ts

@@ -0,0 +1,27 @@
+/*
+ * 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.
+ */
+
+export * from './importer';
+export * from './collectionImporter';
+export * from './fsItemImporter';
+export * from './jsonImporter';
+export * from './pathImporter';