@fgv/ts-res 5.0.0-12 → 5.0.0-14

package/src/packlets/resource-json/resourceDeclTree.ts

@@ -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, mapResults, MessageAggregator, Result, succeed } from '@fgv/ts-utils';
+import { IResourceDeclContainer } from './resourceDeclContainer';
+import * as Convert from './convert';
+import * as Normalized from './normalized';
+import * as Json from './json';
+import { Helpers as CommonHelpers } from '../common';
+import { mergeChildResource } from './helpers';
+
+/**
+ * Class that extracts resources and candidates from a
+ * {@link ResourceJson.Json.IResourceTreeRootDecl | resource tree root}.
+ * @public
+ */
+export class ResourceDeclTree implements IResourceDeclContainer {
+  /**
+   * The {@link ResourceJson.Normalized.IResourceTreeRootDecl | resource tree root declaration}
+   * being processed.
+   */
+  public readonly tree: Normalized.IResourceTreeRootDecl;
+
+  /**
+   * {@inheritdoc ResourceJson.IResourceDeclContainer.context}
+   */
+  public get context(): Normalized.IContainerContextDecl | undefined {
+    return this.tree.context;
+  }
+
+  protected _resources: Normalized.ILooseResourceDecl[] = [];
+  protected _candidates: Normalized.ILooseResourceCandidateDecl[] = [];
+
+  protected constructor(tree: Normalized.IResourceTreeRootDecl) {
+    this.tree = tree;
+    const id = tree.context?.baseId;
+    const conditions = tree.context?.conditions;
+    this._extract(tree, id, conditions).orThrow();
+  }
+
+  /**
+   * Creates a new {@link ResourceJson.ResourceDeclTree | ResourceDeclTree} from an
+   * untyped {@link ResourceJson.Json.IResourceTreeRootDecl | resource tree root declaration}.
+   * @param from - The JSON object to convert.
+   * @returns `Success` with the new tree if the JSON object is valid, otherwise `Failure`.
+   */
+  public static create(from: unknown): Result<ResourceDeclTree> {
+    return Convert.resourceTreeRootDecl
+      .convert(from)
+      .withErrorFormat((err) => `Invalid resource tree: ${err}`)
+      .onSuccess((decl) => {
+        return captureResult(() => new ResourceDeclTree(decl));
+      });
+  }
+
+  /**
+   * Gets the loose resources extracted from the collection.
+   * @returns The {@link ResourceJson.Normalized.ILooseResourceDecl | loose resource declarations}
+   * extracted from the collection.
+   */
+  public getImporterResources(): ReadonlyArray<Normalized.ILooseResourceDecl> {
+    return this._resources;
+  }
+
+  /**
+   * Gets the loose candidates extracted from the collection.
+   * @returns The {@link ResourceJson.Normalized.ILooseResourceCandidateDecl | loose resource candidate declarations}
+   * extracted from the collection.
+   */
+  public getImporterCandidates(): ReadonlyArray<Normalized.ILooseResourceCandidateDecl> {
+    return this._candidates;
+  }
+
+  private _extract(
+    node: Normalized.IResourceTreeChildNodeDecl,
+    parentName?: string,
+    parentConditions?: ReadonlyArray<Json.ILooseConditionDecl>
+  ): Result<this> {
+    const errors: MessageAggregator = new MessageAggregator();
+
+    const resourceEntries = Array.from(Object.entries(node.resources ?? {}));
+    const mergedResources = resourceEntries.map(([name, resource]) =>
+      mergeChildResource(resource, name, parentName, parentConditions)
+    );
+    this._resources.push(...mapResults(mergedResources).aggregateError(errors).orDefault([]));
+
+    const children = Array.from(Object.entries(node.children ?? {}));
+    children.forEach(([name, childNode]) => {
+      CommonHelpers.joinResourceIds(parentName, name)
+        .onSuccess((childName) => {
+          return this._extract(childNode, childName, parentConditions).aggregateError(errors);
+        })
+        .aggregateError(errors);
+    });
+    return errors.returnOrReport(succeed(this));
+  }
+}

package/src/packlets/resource-types/config/convert.ts

@@ -0,0 +1,36 @@
+/*
+ * 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.
+ */
+
+/* eslint-disable @rushstack/typedef-var */
+
+import { Converters } from '@fgv/ts-utils';
+import { IResourceTypeConfig } from './json';
+
+/**
+ * A `Converter` for {@link ResourceTypes.Config.IResourceTypeConfig | ResourceTypeConfig} objects.
+ * @returns A `Converter` for {@link ResourceTypes.Config.IResourceTypeConfig | ResourceTypeConfig} objects.
+ * @public
+ */
+export const resourceTypeConfig = Converters.strictObject<IResourceTypeConfig>({
+  name: Converters.string,
+  typeName: Converters.string
+});

package/src/packlets/resource-types/config/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.
+ */
+
+import * as Convert from './convert';
+
+export * from './json';
+
+export { Convert };

package/src/packlets/resource-types/config/json.ts

@@ -0,0 +1,30 @@
+/*
+ * 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.
+ */
+
+/**
+ * Configuration for a {@link ResourceTypes.ResourceType | resource type}.
+ * @public
+ */
+export interface IResourceTypeConfig {
+  name: string;
+  typeName: string;
+}

package/src/packlets/resource-types/helpers.ts

@@ -0,0 +1,44 @@
+/*
+ * 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 { fail, Result } from '@fgv/ts-utils';
+import { IResourceTypeConfig } from './config';
+import { ResourceType } from './resourceType';
+import { JsonResourceType } from './jsonResourceType';
+import { Convert as CommonConverters } from '../common';
+
+/**
+ * Creates a {@link ResourceTypes.ResourceType | ResourceType} from a configuration object.
+ * @param config - The {@link ResourceTypes.Config.IResourceTypeConfig | configuration object}
+ * containing the name and type name of the resource type.
+ * @returns `Success` with the new {@link ResourceTypes.ResourceType | ResourceType}
+ * if successful, `Failure` with an error message otherwise.
+ * @public
+ */
+export function createResourceTypeFromConfig(config: IResourceTypeConfig): Result<ResourceType> {
+  if (config.typeName === 'json') {
+    return CommonConverters.resourceTypeName
+      .convert(config.name)
+      .onSuccess((key) => JsonResourceType.create({ key }));
+  }
+  return fail(`${config.typeName}: Unknown resource type.`);
+}

package/src/packlets/resource-types/index.ts

@@ -0,0 +1,30 @@
+/*
+ * 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 * as Config from './config';
+
+export * from './resourceType';
+export * from './resourceTypeCollector';
+export * from './jsonResourceType';
+export * from './helpers';
+
+export { Config };

package/src/packlets/resource-types/jsonResourceType.ts

@@ -0,0 +1,96 @@
+/*
+ * 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 { Converters as JsonConverters, JsonObject } from '@fgv/ts-json-base';
+import { IResourceCandidateValidationProperties, ResourceType } from './resourceType';
+import { CandidateCompleteness, Convert, ResourceTypeName } from '../common';
+import { captureResult, Result } from '@fgv/ts-utils';
+
+/**
+ * Parameters to create a {@link ResourceTypes.JsonResourceType | JsonResourceType} instance.
+ * @public
+ */
+export interface IJsonResourceTypeCreateParams {
+  /**
+   * Optional key for the new {@link ResourceTypes.JsonResourceType | JsonResourceType} instance.
+   * Defaults to 'json'.
+   */
+  key?: string;
+
+  /**
+   * Optional index for the new {@link ResourceTypes.JsonResourceType | JsonResourceType}
+   * instance.
+   */
+  index?: number;
+}
+
+/**
+ * Implementation of a {@link ResourceTypes.ResourceType | ResourceType} for JSON values.
+ * @public
+ */
+export class JsonResourceType extends ResourceType<JsonObject> {
+  /**
+   * Protected {@link ResourceTypes.JsonResourceType | JsonResourceType} constructor for use by subclasses.
+   * Use {@link ResourceTypes.JsonResourceType.create | JsonResourceType.create} to create a new instance.
+   * @param key - The key for the new {@link ResourceTypes.JsonResourceType | JsonResourceType} instance.
+   * @param index - Optional index for the new {@link ResourceTypes.JsonResourceType | JsonResourceType} instance.
+   */
+  protected constructor(key: ResourceTypeName, index?: number) {
+    super(key, index);
+  }
+
+  /**
+   * Factory method to create a new {@link ResourceTypes.JsonResourceType | JsonResourceType} instance.
+   * @param params - {@link ResourceTypes.IJsonResourceTypeCreateParams | Parameters} to create the new instance.
+   * @returns `Success` with the new {@link ResourceTypes.JsonResourceType | JsonResourceType} instance if successful
+   * or `Failure` with an error message if not.
+   */
+  public static create(params?: IJsonResourceTypeCreateParams): Result<JsonResourceType> {
+    return Convert.resourceTypeName.convert(params?.key ?? 'json').onSuccess((key) => {
+      return captureResult(() => new JsonResourceType(key, params?.index));
+    });
+  }
+
+  /**
+   * {@inheritdoc ResourceTypes.ResourceType.validateDeclaration}
+   */
+
+  public validateDeclaration(props: IResourceCandidateValidationProperties): Result<JsonObject> {
+    return JsonConverters.jsonObject.convert(props.json);
+  }
+
+  /**
+   * {@inheritdoc ResourceTypes.ResourceType.(validate:1)}
+   */
+  public validate(json: JsonObject, completeness: CandidateCompleteness): Result<JsonObject>;
+  /**
+   * {@inheritdoc ResourceTypes.ResourceType.(validate:2)}
+   */
+  public validate(json: JsonObject, completeness: 'full'): Result<JsonObject>;
+  /**
+   * {@inheritdoc ResourceTypes.ResourceType.(validate:3)}
+   */
+  public validate(json: JsonObject, completeness: 'partial'): Result<JsonObject>;
+  public validate(json: JsonObject, __completeness?: CandidateCompleteness): Result<JsonObject> {
+    return JsonConverters.jsonObject.convert(json);
+  }
+}

package/src/packlets/resource-types/resourceType.ts

@@ -0,0 +1,215 @@
+/*
+ * 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 { Collections, ICollectible, Result } from '@fgv/ts-utils';
+import {
+  CandidateCompleteness,
+  Convert as CommonConvert,
+  Validate,
+  ResourceTypeIndex,
+  ResourceTypeName,
+  ResourceValueMergeMethod,
+  ResourceId
+} from '../common';
+
+/**
+ * Parameters used to validate a {@link ResourceJson.Json.ILooseResourceCandidateDecl | resource candidate declaration}.
+ * @public
+ */
+export interface IResourceCandidateValidationProperties {
+  /**
+   * {@inheritdoc ResourceJson.Json.ILooseResourceCandidateDecl.id}
+   * @public
+   */
+  id: ResourceId;
+
+  /**
+   * Describes how complete the candidate value is.
+   * @public
+   */
+  completeness: CandidateCompleteness;
+
+  /**
+   * {@inheritdoc ResourceJson.Json.ILooseResourceCandidateDecl.json}
+   * @public
+   */
+  json: JsonValue;
+
+  /**
+   * {@inheritdoc ResourceJson.Json.ILooseResourceCandidateDecl.mergeMethod}
+   * @public
+   */
+  mergeMethod: ResourceValueMergeMethod;
+}
+
+/**
+ * Interface for a resource type.  Resource types are responsible for
+ * validating and converting JSON values into the appropriate strongly-typed
+ * resource value.
+ * @public
+ */
+export interface IResourceType<T = unknown> extends ICollectible<ResourceTypeName, ResourceTypeIndex> {
+  /**
+   * The key for this resource type.
+   */
+  readonly key: ResourceTypeName;
+
+  /**
+   * The index for this resource type.
+   */
+  readonly index: ResourceTypeIndex | undefined;
+
+  /**
+   * Validates properties of a {@link ResourceJson.Json.ILooseResourceCandidateDecl | resource candidate declaration} for
+   * a resource instance value.
+   * @param props - The {@link ResourceTypes.IResourceCandidateValidationProperties | properties } to validate.
+   * @returns `Success` with the strongly-typed resource value if the JSON and merge method
+   * are valid, `Failure` with an error message otherwise.
+   * @public
+   */
+  validateDeclaration(props: IResourceCandidateValidationProperties): Result<T | Partial<T>>;
+
+  /**
+   * Validates a JSON value for use as a partial resource instance value.
+   * @param json - The JSON value to validate.
+   * @param completeness - Describes {@link CandidateCompleteness | how complete} the candidate value is.
+   * @returns `Success` with the strongly-typed partial resource value if the JSON is valid,
+   * `Failure` with an error message otherwise.
+   * @public
+   */
+  validate(json: JsonValue, completeness: CandidateCompleteness): Result<Partial<T>>;
+
+  /**
+   * Validates a JSON value for use as a complete resource instance value.
+   * @param json - The JSON value to validate.
+   * @param completeness - Describes {@link CandidateCompleteness | how complete} the candidate value is.
+   * @returns `Success` with the strongly-typed resource value if the JSON is valid,
+   * `Failure` with an error message otherwise.
+   * @public
+   */
+  validate(json: JsonValue, completeness: 'full'): Result<T>;
+
+  /**
+   * Validates a JSON value for use as a partial resource instance value.
+   * @param json - The JSON value to validate.
+   * @param completeness - Describes {@link CandidateCompleteness | how complete} the candidate value is.
+   * @returns `Success` with the strongly-typed partial resource value if the JSON is valid,
+   * `Failure` with an error message otherwise.
+   * @public
+   */
+  validate(json: JsonValue, completeness: 'partial'): Result<Partial<T>>;
+
+  /**
+   * Sets the index for this resource type.  Once set, the index cannot be changed.
+   */
+  setIndex(index: number): Result<ResourceTypeIndex>;
+}
+
+/**
+ * Abstract base class for resource types which are responsible for
+ * validating and converting JSON values into the appropriate strongly-typed
+ * resource value.
+ * @public
+ */
+export abstract class ResourceType<T = unknown> implements IResourceType<T> {
+  private _collectible: Collections.Collectible<ResourceTypeName, ResourceTypeIndex>;
+  /**
+   * {@inheritdoc ResourceTypes.IResourceType.key}
+   */
+  public get key(): ResourceTypeName {
+    return this._collectible.key;
+  }
+
+  /**
+   * {@inheritdoc ResourceTypes.IResourceType.index}
+   */
+  public get index(): ResourceTypeIndex | undefined {
+    return this._collectible.index;
+  }
+
+  protected constructor(key: ResourceTypeName, index?: number) {
+    this._collectible = new Collections.Collectible<ResourceTypeName, ResourceTypeIndex>({
+      key,
+      /* c8 ignore next 1 - coverage having a rough time */
+      index: index !== undefined ? Validate.toResourceTypeIndex(index).orThrow() : undefined,
+      indexConverter: CommonConvert.resourceTypeIndex
+    });
+  }
+
+  /**
+   * Validates properties of a {@link ResourceJson.Json.ILooseResourceCandidateDecl | resource candidate declaration} for
+   * a resource instance value.
+   * @param props - The {@link ResourceTypes.IResourceCandidateValidationProperties | properties } to validate.
+   * @returns `Success` with the strongly-typed resource value if the JSON and merge method
+   * are valid, `Failure` with an error message otherwise.
+   * @public
+   */
+  public abstract validateDeclaration(props: IResourceCandidateValidationProperties): Result<T | Partial<T>>;
+
+  /**
+   * Validates a JSON value for use as a partial resource instance value.
+   * @param json - The JSON value to validate.
+   * @param completeness - Describes {@link CandidateCompleteness | how complete} the candidate value is.
+   * @returns `Success` with the strongly-typed partial resource value if the JSON is valid,
+   * `Failure` with an error message otherwise.
+   * @public
+   */
+  public abstract validate(json: JsonValue, completeness: CandidateCompleteness): Result<Partial<T>>;
+
+  /**
+   * Validates a JSON value for use as a complete resource instance value.
+   * @param json - The JSON value to validate.
+   * @param completeness - Describes {@link CandidateCompleteness | how complete} the candidate value is.
+   * @returns `Success` with the strongly-typed resource value if the JSON is valid,
+   * `Failure` with an error message otherwise.
+   * @public
+   */
+  public abstract validate(json: JsonValue, completeness: 'full'): Result<T>;
+
+  /**
+   * Validates a JSON value for use as a partial resource instance value.
+   * @param json - The JSON value to validate.
+   * @param completeness - Describes {@link CandidateCompleteness | how complete} the candidate value is.
+   * @returns `Success` with the strongly-typed partial resource value if the JSON is valid,
+   * `Failure` with an error message otherwise.
+   * @public
+   */
+  public abstract validate(json: JsonValue, completeness: 'partial'): Result<Partial<T>>;
+
+  /**
+   * Validates a JSON value for use as a full or partial resource instance value.
+   * @param json - The JSON value to validate.
+   * @param completeness - Describes {@link CandidateCompleteness | how complete} the candidate value is.
+   * @returns `Success` with the strongly-typed full or partial resource value if
+   * the JSON is valid, `Failure` with an error message otherwise.
+   * @public
+   */
+  public abstract validate(json: JsonValue, completeness?: CandidateCompleteness): Result<T | Partial<T>>;
+
+  /**
+   * Sets the index for this resource type.  Once set, the index cannot be changed.
+   */
+  public setIndex(index: number): Result<ResourceTypeIndex> {
+    return this._collectible.setIndex(index);
+  }
+}

package/src/packlets/resource-types/resourceTypeCollector.ts

@@ -0,0 +1,79 @@
+/*
+ * 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 { Collections, Result, fail, succeed, ValidatingCollector, captureResult } from '@fgv/ts-utils';
+import { ResourceType } from './resourceType';
+import { Convert as CommonConvert, ResourceTypeName } from '../common';
+
+/**
+ * Parameters for creating a {@link ResourceTypes.ResourceTypeCollector | ResourceTypeCollector}.
+ * @public
+ */
+export interface IResourceCollectorCreateParams {
+  resourceTypes?: ResourceType[];
+}
+
+/**
+ * Map {@link ResourceTypeName | resource type names} to {@link ResourceTypes.ResourceType | resource types}.
+ * @public
+ */
+export class ResourceTypeCollector extends ValidatingCollector<ResourceType> {
+  protected constructor({ resourceTypes }: IResourceCollectorCreateParams) {
+    /* c8 ignore next 1 - coverage having a rough day */
+    resourceTypes = resourceTypes ?? [];
+
+    super({
+      converters: new Collections.KeyValueConverters<ResourceTypeName, ResourceType>({
+        key: CommonConvert.resourceTypeName,
+        value: (from: unknown) => this._toResourceType(from)
+      })
+    });
+    resourceTypes.forEach((resourceType) => {
+      this.add(resourceType).orThrow();
+    });
+  }
+
+  /**
+   * Creates a new {@link ResourceTypes.ResourceTypeCollector | ResourceTypeCollector}.
+   * @param params - Optional for creating the new collector.
+   * @returns `Success` with the new instance, or `Failure` with an error
+   * message if the collector could not be created.
+   */
+  public static create(params?: IResourceCollectorCreateParams): Result<ResourceTypeCollector> {
+    /* c8 ignore next 1 - coverage having a rough day */
+    params = params ?? {};
+    return captureResult(() => new ResourceTypeCollector(params));
+  }
+
+  protected _toResourceType(from: unknown): Result<ResourceType> {
+    if (from instanceof ResourceType) {
+      return succeed(from);
+    }
+    return fail('Not a resource type.');
+  }
+}
+
+/**
+ * A read-only version of {@link ResourceTypes.ResourceTypeCollector | ResourceTypeCollector}.
+ * @public
+ */
+export type ReadOnlyResourceTypeCollector = Collections.IReadOnlyValidatingCollector<ResourceType>;