@fgv/ts-res 5.0.0-22 → 5.0.0-23

package/lib/packlets/qualifier-types/literalQualifierType.js

@@ -20,12 +20,46 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LiteralQualifierType = void 0;
 const ts_utils_1 = require("@fgv/ts-utils");
 const common_1 = require("../common");
 const qualifierType_1 = require("./qualifierType");
 const literalValueHierarchy_1 = require("./literalValueHierarchy");
+const Config = __importStar(require("./config"));
 const ts_json_base_1 = require("@fgv/ts-json-base");
 /**
  * A {@link QualifierTypes.QualifierType | qualifier} that matches a literal value,
@@ -49,6 +83,10 @@ class LiteralQualifierType extends qualifierType_1.QualifierType {
             allowContextList,
             index: index !== undefined ? common_1.Convert.qualifierTypeIndex.convert(index).orThrow() : undefined
         });
+        /**
+         * {@inheritdoc QualifierTypes.IQualifierType.systemTypeName}
+         */
+        this.systemTypeName = common_1.Convert.qualifierTypeName.convert('literal').orThrow();
         this.caseSensitive = caseSensitive === true;
         this.enumeratedValues = enumeratedValues
             ? (0, ts_utils_1.mapResults)(Array.from(enumeratedValues).map(LiteralQualifierType.toLiteralConditionValue)).orThrow()
@@ -91,6 +129,45 @@ class LiteralQualifierType extends qualifierType_1.QualifierType {
         }
         return false;
     }
+    /**
+     * Gets a {@link QualifierTypes.Config.ISystemLiteralQualifierTypeConfig | strongly typed configuration object}
+     * for this qualifier type.
+     * @returns `Success` with the configuration if successful, `Failure` with an error message otherwise.
+     */
+    getConfiguration() {
+        return this.getConfigurationJson().onSuccess((json) => Config.Convert.systemLiteralQualifierTypeConfig.convert(json));
+    }
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.getConfigurationJson}
+     */
+    getConfigurationJson() {
+        const hierarchy = this.hierarchy ? { hierarchy: this.hierarchy.asRecord() } : {};
+        const enumeratedValues = this.enumeratedValues
+            ? { enumeratedValues: [...this.enumeratedValues] }
+            : {};
+        return (0, ts_utils_1.succeed)({
+            name: this.name,
+            systemType: 'literal',
+            configuration: Object.assign(Object.assign({ allowContextList: this.allowContextList, caseSensitive: this.caseSensitive }, enumeratedValues), hierarchy)
+        });
+    }
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.validateConfigurationJson}
+     */
+    validateConfigurationJson(from) {
+        return Config.Convert.systemLiteralQualifierTypeConfig
+            .convert(from)
+            .onSuccess((config) => (0, ts_utils_1.succeed)(config));
+    }
+    /**
+     * Validates a {@link QualifierTypes.Config.ISystemLiteralQualifierTypeConfig | strongly typed configuration object}
+     * for this qualifier type.
+     * @param from - The unknown data to validate as a configuration object.
+     * @returns `Success` with the validated configuration if successful, `Failure` with an error message otherwise.
+     */
+    validateConfiguration(from) {
+        return this.validateConfigurationJson(from).onSuccess((json) => Config.Convert.systemLiteralQualifierTypeConfig.convert(json));
+    }
     /**
      * {@inheritdoc QualifierTypes.QualifierType._matchOne}
      */

package/lib/packlets/qualifier-types/literalValueHierarchy.d.ts

@@ -1,15 +1,6 @@
 import { Result } from '@fgv/ts-utils';
 import { ConditionOperator, QualifierConditionValue, QualifierContextValue, QualifierMatchScore } from '../common';
-/**
- * Declares a hierarchy of literal values. The keys are the names of the values, and the
- * values are the names of their parents.
- * @remarks
- * The hierarchy is defined as a tree, where each value can have multiple children but
- * only one parent. The root of the tree has no parent. The hierarchy is used to
- * determine the relationship between values when matching conditions and contexts.
- * @public
- */
-export type LiteralValueHierarchyDecl<T extends string> = Partial<Record<T, T>>;
+import { LiteralValueHierarchyDecl } from './config';
 /**
  * Describes a single valid literal value including optional parent and child values.
  * @public
@@ -110,5 +101,10 @@ export declare class LiteralValueHierarchy<T extends string = string> {
      */
     match(condition: QualifierConditionValue, context: QualifierContextValue, __operator?: ConditionOperator): QualifierMatchScore;
     protected static _buildValuesFromHierarchy<T extends string>(params: ILiteralValueHierarchyCreateParams<T>): Result<ReadonlyMap<T, ILiteralValue<T>>>;
+    /**
+     * Converts the hierarchy to a record of parent-child relationships.
+     * @returns A record of parent-child relationships.
+     */
+    asRecord(): Record<string, string>;
 }
 //# sourceMappingURL=literalValueHierarchy.d.ts.map

package/lib/packlets/qualifier-types/literalValueHierarchy.js

@@ -223,6 +223,16 @@ class LiteralValueHierarchy {
         }
         return errors.returnOrReport((0, ts_utils_1.succeed)(valueMap));
     }
+    /**
+     * Converts the hierarchy to a record of parent-child relationships.
+     * @returns A record of parent-child relationships.
+     */
+    asRecord() {
+        const entries = Array.from(this.values.values())
+            .filter((v) => v.parent !== undefined)
+            .map((v) => [v.name, v.parent.name]);
+        return Object.fromEntries(entries);
+    }
 }
 exports.LiteralValueHierarchy = LiteralValueHierarchy;
 //# sourceMappingURL=literalValueHierarchy.js.map

package/lib/packlets/qualifier-types/qualifierType.d.ts

@@ -1,5 +1,6 @@
 import { Collections, ICollectible, Result } from '@fgv/ts-utils';
 import { ConditionOperator, QualifierConditionValue, QualifierContextValue, QualifierMatchScore, QualifierTypeIndex, QualifierTypeName } from '../common';
+import { JsonObject } from '@fgv/ts-json-base';
 /**
  * Interface for a qualifier type. A qualifier type implements the build and
  * runtime semantics for some class of related qualifiers (e.g. language,
@@ -11,6 +12,10 @@ export interface IQualifierType extends ICollectible<QualifierTypeName, Qualifie
      * The name of the qualifier type.
      */
     readonly name: QualifierTypeName;
+    /**
+     * Name of the underlying system type.
+     */
+    readonly systemTypeName: QualifierTypeName;
     /**
      * Unique key for this qualifier.
      */
@@ -73,6 +78,17 @@ export interface IQualifierType extends ICollectible<QualifierTypeName, Qualifie
      * Sets the index for this qualifier type. Once set, index is immutable.
      */
     setIndex(index: number): Result<QualifierTypeIndex>;
+    /**
+     * Gets the configuration for this qualifier type.
+     * @returns `Success` with the configuration if successful, `Failure` with an error message otherwise.
+     */
+    getConfigurationJson(): Result<JsonObject>;
+    /**
+     * Validates configuration JSON data for this qualifier type.
+     * @param from - The unknown data to validate as configuration JSON.
+     * @returns `Success` with validated JSON configuration if valid, `Failure` with an error message otherwise.
+     */
+    validateConfigurationJson(from: unknown): Result<JsonObject>;
 }
 /**
  * Parameters used to create a base {@link QualifierTypes.QualifierType | qualifier type}.
@@ -103,6 +119,10 @@ export declare abstract class QualifierType implements IQualifierType {
      * {@inheritdoc QualifierTypes.IQualifierType.name}
      */
     readonly name: QualifierTypeName;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.systemTypeName}
+     */
+    abstract readonly systemTypeName: QualifierTypeName;
     /**
      * {@inheritdoc QualifierTypes.IQualifierType.key}
      */
@@ -148,6 +168,14 @@ export declare abstract class QualifierType implements IQualifierType {
      * {@inheritdoc QualifierTypes.IQualifierType.matches}
      */
     matches(condition: QualifierConditionValue, context: QualifierContextValue, operator: ConditionOperator): QualifierMatchScore;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.getConfigurationJson}
+     */
+    abstract getConfigurationJson(): Result<JsonObject>;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.validateConfigurationJson}
+     */
+    abstract validateConfigurationJson(from: unknown): Result<JsonObject>;
     /**
      * {@inheritdoc QualifierTypes.IQualifierType.setIndex}
      */

package/lib/packlets/qualifier-types/territoryQualifierType.d.ts

@@ -1,8 +1,9 @@
 import { Result } from '@fgv/ts-utils';
-import { QualifierConditionValue, QualifierContextValue, QualifierMatchScore, ConditionOperator } from '../common';
+import { QualifierConditionValue, QualifierContextValue, QualifierMatchScore, ConditionOperator, QualifierTypeName } from '../common';
 import { QualifierType } from './qualifierType';
-import { LiteralValueHierarchy, LiteralValueHierarchyDecl } from './literalValueHierarchy';
+import { LiteralValueHierarchy } from './literalValueHierarchy';
 import * as Config from './config';
+import { JsonObject } from '@fgv/ts-json-base';
 /**
  * Parameters used to create a new {@link QualifierTypes.TerritoryQualifierType | TerritoryQualifierType} instance.
  * @public
@@ -30,10 +31,10 @@ export interface ITerritoryQualifierTypeCreateParams {
      */
     acceptLowercase?: boolean;
     /**
-     * Optional {@link QualifierTypes.LiteralValueHierarchyDecl | hierarchy declaration}
+     * Optional {@link QualifierTypes.Config.LiteralValueHierarchyDecl | hierarchy declaration}
      * of territory values to use for matching. If not provided, no hierarchy will be used.
      */
-    hierarchy?: LiteralValueHierarchyDecl<string>;
+    hierarchy?: Config.LiteralValueHierarchyDecl<string>;
 }
 /**
  * Qualifier type for territory values. Territories are two-letter ISO-3166-2
@@ -42,6 +43,10 @@ export interface ITerritoryQualifierTypeCreateParams {
  * @public
  */
 export declare class TerritoryQualifierType extends QualifierType {
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.systemTypeName}
+     */
+    readonly systemTypeName: QualifierTypeName;
     /**
      * Optional array enumerating allowed territories to further constrain the type.
      */
@@ -83,6 +88,25 @@ export declare class TerritoryQualifierType extends QualifierType {
      * @public
      */
     static createFromConfig(config: Config.IQualifierTypeConfig<Config.ITerritoryQualifierTypeConfig>): Result<TerritoryQualifierType>;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.getConfigurationJson}
+     */
+    getConfiguration(): Result<Config.ISystemTerritoryQualifierTypeConfig>;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.getConfigurationJson}
+     */
+    getConfigurationJson(): Result<JsonObject>;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.validateConfigurationJson}
+     */
+    validateConfigurationJson(from: unknown): Result<JsonObject>;
+    /**
+     * Validates a {@link QualifierTypes.Config.ISystemTerritoryQualifierTypeConfig | strongly typed configuration object}
+     * for this qualifier type.
+     * @param from - The unknown data to validate as a configuration object.
+     * @returns `Success` with the validated configuration if successful, `Failure` with an error message otherwise.
+     */
+    validateConfiguration(from: unknown): Result<Config.ISystemTerritoryQualifierTypeConfig>;
     /**
      * {@inheritdoc QualifierTypes.QualifierType._matchOne}
      */

package/lib/packlets/qualifier-types/territoryQualifierType.js

@@ -20,12 +20,46 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TerritoryQualifierType = void 0;
 const ts_utils_1 = require("@fgv/ts-utils");
 const common_1 = require("../common");
 const qualifierType_1 = require("./qualifierType");
 const literalValueHierarchy_1 = require("./literalValueHierarchy");
+const Config = __importStar(require("./config"));
 const ts_json_base_1 = require("@fgv/ts-json-base");
 /**
  * Qualifier type for territory values. Territories are two-letter ISO-3166-2
@@ -51,6 +85,12 @@ class TerritoryQualifierType extends qualifierType_1.QualifierType {
             allowContextList,
             index: validIndex
         });
+        /**
+         * {@inheritdoc QualifierTypes.IQualifierType.systemTypeName}
+         */
+        this.systemTypeName = common_1.Convert.qualifierTypeName
+            .convert('territory')
+            .orThrow();
         this.allowedTerritories = validTerritories;
         this.acceptLowercase = acceptLowercase === true;
         if (hierarchy) {
@@ -106,6 +146,43 @@ class TerritoryQualifierType extends qualifierType_1.QualifierType {
             hierarchy: territoryConfig.hierarchy
         }).onSuccess(TerritoryQualifierType.create);
     }
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.getConfigurationJson}
+     */
+    getConfiguration() {
+        return this.getConfigurationJson().onSuccess((json) => Config.Convert.systemTerritoryQualifierTypeConfig.convert(json));
+    }
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.getConfigurationJson}
+     */
+    getConfigurationJson() {
+        const hierarchy = this.hierarchy ? { hierarchy: this.hierarchy.asRecord() } : {};
+        const allowedTerritories = this.allowedTerritories
+            ? { allowedTerritories: [...this.allowedTerritories] }
+            : {};
+        return (0, ts_utils_1.succeed)({
+            name: this.name,
+            systemType: 'territory',
+            configuration: Object.assign(Object.assign({ allowContextList: this.allowContextList, acceptLowercase: this.acceptLowercase }, allowedTerritories), hierarchy)
+        });
+    }
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.validateConfigurationJson}
+     */
+    validateConfigurationJson(from) {
+        return Config.Convert.systemTerritoryQualifierTypeConfig
+            .convert(from)
+            .onSuccess((config) => (0, ts_utils_1.succeed)(config));
+    }
+    /**
+     * Validates a {@link QualifierTypes.Config.ISystemTerritoryQualifierTypeConfig | strongly typed configuration object}
+     * for this qualifier type.
+     * @param from - The unknown data to validate as a configuration object.
+     * @returns `Success` with the validated configuration if successful, `Failure` with an error message otherwise.
+     */
+    validateConfiguration(from) {
+        return this.validateConfigurationJson(from).onSuccess((json) => Config.Convert.systemTerritoryQualifierTypeConfig.convert(json));
+    }
     /**
      * {@inheritdoc QualifierTypes.QualifierType._matchOne}
      */

package/lib/packlets/resource-json/compiled/convert.js

@@ -136,7 +136,7 @@ exports.compiledAbstractDecision = ts_utils_1.Converters.strictObject({
  * @public
  */
 exports.compiledCandidate = ts_utils_1.Converters.strictObject({
-    json: ts_json_base_1.Converters.jsonValue,
+    valueIndex: Common.Convert.candidateValueIndex,
     isPartial: ts_utils_1.Converters.boolean,
     mergeMethod: Common.Convert.resourceValueMergeMethod
 });
@@ -162,6 +162,7 @@ exports.compiledResourceCollection = ts_utils_1.Converters.strictObject({
     conditions: ts_utils_1.Converters.arrayOf(exports.compiledCondition),
     conditionSets: ts_utils_1.Converters.arrayOf(exports.compiledConditionSet),
     decisions: ts_utils_1.Converters.arrayOf(exports.compiledAbstractDecision),
+    candidateValues: ts_utils_1.Converters.arrayOf(ts_json_base_1.Converters.jsonValue),
     resources: ts_utils_1.Converters.arrayOf(exports.compiledResource)
 });
 //# sourceMappingURL=convert.js.map

package/lib/packlets/resource-json/compiled/json.d.ts

@@ -132,9 +132,9 @@ export interface ICompiledAbstractDecision {
  */
 export interface ICompiledCandidate {
     /**
-     * The JSON value of the candidate.
+     * The global index of the JSON value of the candidate.
      */
-    json: JsonValue;
+    valueIndex: Common.CandidateValueIndex;
     /**
      * Indicates if this is a partial resource that needs to be merged.
      */
@@ -196,6 +196,10 @@ export interface ICompiledResourceCollection {
      * Array of all decisions in the collection.
      */
     decisions: ReadonlyArray<ICompiledAbstractDecision>;
+    /**
+     * Array of all candidate values in the collection.
+     */
+    candidateValues: ReadonlyArray<JsonValue>;
     /**
      * Array of all resources in the collection.
      */

package/lib/packlets/resource-types/jsonResourceType.d.ts

@@ -28,6 +28,10 @@ export interface IJsonResourceTypeCreateParams {
  * @public
  */
 export declare class JsonResourceType extends ResourceType<JsonObject> {
+    /**
+     * {@inheritdoc ResourceTypes.ResourceType.systemTypeName}
+     */
+    readonly systemTypeName: ResourceTypeName;
     /**
      * Protected {@link ResourceTypes.JsonResourceType | JsonResourceType} constructor for use by subclasses.
      * Use {@link ResourceTypes.JsonResourceType.create | JsonResourceType.create} to create a new instance.

package/lib/packlets/resource-types/jsonResourceType.js

@@ -39,6 +39,10 @@ class JsonResourceType extends resourceType_1.ResourceType {
      */
     constructor(key, index, template) {
         super(key, index, template);
+        /**
+         * {@inheritdoc ResourceTypes.ResourceType.systemTypeName}
+         */
+        this.systemTypeName = common_1.Convert.resourceTypeName.convert('json').orThrow();
     }
     /**
      * Factory method to create a new {@link ResourceTypes.JsonResourceType | JsonResourceType} instance.

package/lib/packlets/resource-types/resourceType.d.ts

@@ -108,6 +108,10 @@ export declare abstract class ResourceType<T = unknown> implements IResourceType
      * {@inheritdoc ResourceTypes.IResourceType.key}
      */
     get key(): ResourceTypeName;
+    /**
+     * Name of the underlying system type.
+     */
+    abstract readonly systemTypeName: ResourceTypeName;
     /**
      * {@inheritdoc ResourceTypes.IResourceType.index}
      */

package/lib/packlets/resources/candidateValue.d.ts

@@ -0,0 +1,92 @@
+import { JsonValue } from '@fgv/ts-json-base';
+import { Collections, Hash, Result } from '@fgv/ts-utils';
+import { CandidateValueIndex, CandidateValueKey } from '../common';
+/**
+ * Interface for a candidate value that can be collected and indexed.
+ * Candidate values are normalized JSON values that can be shared across
+ * multiple resource candidates to reduce duplication.
+ * @public
+ */
+export interface ICandidateValue extends Collections.ICollectible<CandidateValueKey, CandidateValueIndex> {
+    /**
+     * The unique key for this candidate value, derived from the hash of the normalized JSON.
+     */
+    readonly key: CandidateValueKey;
+    /**
+     * The index of this candidate value in the collection.
+     */
+    readonly index: CandidateValueIndex | undefined;
+    /**
+     * The normalized JSON value.
+     */
+    readonly json: JsonValue;
+    /**
+     * Sets the index of this candidate value.
+     * @param index - The index to set.
+     * @returns `Success` with the index if successful, or `Failure` with an error message if not.
+     */
+    setIndex(index: number): Result<CandidateValueIndex>;
+}
+/**
+ * Parameters for creating a {@link Resources.CandidateValue | CandidateValue}.
+ * @public
+ */
+export interface ICandidateValueCreateParams {
+    /**
+     * The JSON value to store. Will be normalized during creation.
+     */
+    json: JsonValue;
+    /**
+     * Optional normalizer to use for normalizing the JSON value.
+     * If not provided, a default Crc32Normalizer will be used.
+     */
+    normalizer?: Hash.Crc32Normalizer;
+    /**
+     * Optional index if the value is already indexed.
+     */
+    index?: number;
+}
+/**
+ * Implementation of a candidate value that stores normalized JSON data.
+ * The value is normalized on creation and a hash-based key is generated
+ * for efficient deduplication.
+ * @public
+ */
+export declare class CandidateValue implements ICandidateValue {
+    private readonly _collectible;
+    private readonly _json;
+    /**
+     * The unique key for this candidate value.
+     */
+    get key(): CandidateValueKey;
+    /**
+     * The index of this candidate value in the collection.
+     */
+    get index(): CandidateValueIndex | undefined;
+    /**
+     * The normalized JSON value.
+     */
+    get json(): JsonValue;
+    /**
+     * Constructor for a {@link Resources.CandidateValue} object.
+     * @param params - Parameters to create the candidate value.
+     * @internal
+     */
+    protected constructor(params: ICandidateValueCreateParams);
+    /**
+     * Creates a new {@link Resources.CandidateValue} object.
+     * @param params - Parameters to create the candidate value.
+     * @returns `Success` with the new candidate value if successful,
+     * or `Failure` with an error message if not.
+     * @public
+     */
+    static create(params: ICandidateValueCreateParams): Result<CandidateValue>;
+    /**
+     * Sets the index of this candidate value.
+     * @param index - The index to set.
+     * @returns `Success` with the index if successful, or `Failure` with an error message if not.
+     * @public
+     */
+    setIndex(index: number): Result<CandidateValueIndex>;
+}
+//# sourceMappingURL=candidateValue.d.ts.map

package/lib/packlets/resources/candidateValue.js

@@ -0,0 +1,128 @@
+"use strict";
+/*
+ * 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.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CandidateValue = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const common_1 = require("../common");
+const Common = __importStar(require("../common"));
+/**
+ * Implementation of a candidate value that stores normalized JSON data.
+ * The value is normalized on creation and a hash-based key is generated
+ * for efficient deduplication.
+ * @public
+ */
+class CandidateValue {
+    /**
+     * The unique key for this candidate value.
+     */
+    get key() {
+        return this._collectible.key;
+    }
+    /**
+     * The index of this candidate value in the collection.
+     */
+    get index() {
+        return this._collectible.index;
+    }
+    /**
+     * The normalized JSON value.
+     */
+    get json() {
+        return this._json;
+    }
+    /**
+     * Constructor for a {@link Resources.CandidateValue} object.
+     * @param params - Parameters to create the candidate value.
+     * @internal
+     */
+    constructor(params) {
+        var _a;
+        const normalizer = (_a = params.normalizer) !== null && _a !== void 0 ? _a : new ts_utils_1.Hash.Crc32Normalizer();
+        // Normalize the JSON value
+        const normalizedResult = normalizer.normalize(params.json);
+        this._json = normalizedResult.orThrow();
+        // Generate key from the normalized value using computeHash
+        const keyResult = normalizer.computeHash(this._json);
+        const key = common_1.Convert.candidateValueKey.convert(keyResult.orThrow()).orThrow();
+        // Create the collectible with the key and optional index
+        this._collectible = new ts_utils_1.Collections.Collectible({
+            key,
+            index: params.index,
+            indexConverter: Common.Convert.candidateValueIndex
+        });
+    }
+    /**
+     * Creates a new {@link Resources.CandidateValue} object.
+     * @param params - Parameters to create the candidate value.
+     * @returns `Success` with the new candidate value if successful,
+     * or `Failure` with an error message if not.
+     * @public
+     */
+    static create(params) {
+        return (0, ts_utils_1.captureResult)(() => new CandidateValue(params));
+    }
+    /**
+     * Sets the index of this candidate value.
+     * @param index - The index to set.
+     * @returns `Success` with the index if successful, or `Failure` with an error message if not.
+     * @public
+     */
+    setIndex(index) {
+        return this._collectible.setIndex(index);
+    }
+}
+exports.CandidateValue = CandidateValue;
+//# sourceMappingURL=candidateValue.js.map