@fgv/ts-res 5.0.1-1 → 5.0.1-10

package/dist/packlets/resources/candidateReducer.js

@@ -0,0 +1,246 @@
+/*
+ * 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 { ResourceCandidate } from './resourceCandidate';
+import { JsonEditor } from '@fgv/ts-json';
+import { succeed, fail, mapResults } from '@fgv/ts-utils';
+/**
+ * Manages candidate reduction logic for filtering and qualifier reduction operations.
+ * Encapsulates the state and logic needed to consistently process candidates for reduction.
+ * @public
+ */
+export class CandidateReducer {
+    /**
+     * Constructor for CandidateReducer.
+     * @param candidates - The set of candidates to potentially reduce
+     * @param filterForContext - Context to filter candidates against
+     */
+    constructor(candidates, filterForContext) {
+        var _a;
+        this._filterForContext = filterForContext;
+        // Use existing logic to determine reducible qualifiers
+        this._qualifiersToReduce =
+            (_a = ResourceCandidate.findReducibleQualifiers(candidates, filterForContext)) !== null && _a !== void 0 ? _a : new Set();
+        // Initialize candidate info array with initial reduction attempts
+        this._candidateInfos = candidates.map((candidate) => {
+            const filteredConditions = candidate.conditions.conditions.filter((c) => !this._qualifiersToReduce.has(c.qualifier.name));
+            const reducedConditions = filteredConditions.map((c) => c.toLooseConditionDecl());
+            const conditionSetKey = CandidateReducer._computeConditionSetKey(reducedConditions);
+            const action = filteredConditions.length < candidate.conditions.conditions.length ? 'reduced' : 'unchanged';
+            return {
+                originalCandidate: candidate,
+                action,
+                conditions: reducedConditions,
+                conditionSetKey,
+                json: undefined // Will be set later when needed
+            };
+        });
+        // Resolve collisions by reverting reduced candidates to unchanged when they collide
+        this._resolveCollisions();
+    }
+    /**
+     * Computes a string key for a set of condition declarations for collision detection.
+     * @param conditions - The conditions to compute a key for
+     * @returns A string key representing the condition set
+     */
+    static _computeConditionSetKey(conditions) {
+        if (conditions.length === 0) {
+            return '{}';
+        }
+        // Sort conditions by qualifier name for consistent keys
+        const sortedConditions = [...conditions].sort((a, b) => a.qualifierName.localeCompare(b.qualifierName));
+        const pairs = sortedConditions.map((c) => `${c.qualifierName}:${c.value}`);
+        return `{${pairs.join(',')}}`;
+    }
+    /**
+     * Merges a partial candidate's JSON value into a base candidate's JSON value.
+     * @param baseJson - The base JSON value to merge into
+     * @param partialJson - The partial JSON value to merge from
+     * @returns The merged JSON value
+     * @internal
+     */
+    static _mergeJsonValues(baseJson, partialJson) {
+        // Create JsonEditor with array replacement behavior for candidate merging
+        const editor = JsonEditor.create({
+            merge: {
+                arrayMergeBehavior: 'replace'
+            }
+        }).orThrow(); // Should never fail with valid options
+        return editor.mergeObjectsInPlace({}, [baseJson, partialJson]).orThrow(); // Internal method should throw on error - this indicates a serious bug
+    }
+    /**
+     * Resolves collisions using smart collision resolution rules.
+     * - If a reduced candidate collides with an unchanged candidate and only one reduced candidate collides:
+     *   - If reduced candidate is complete: suppress unchanged, keep reduced
+     *   - If reduced candidate is partial: merge into unchanged, suppress reduced
+     * - Otherwise: revert reduced candidates to unchanged to avoid collisions
+     * @internal
+     */
+    _resolveCollisions() {
+        let hasCollisions = true;
+        let iterationCount = 0;
+        const maxIterations = this._candidateInfos.length; // Safety limit
+        while (hasCollisions && iterationCount < maxIterations) {
+            hasCollisions = false;
+            iterationCount++;
+            // Group candidates by their condition set keys (excluding suppressed)
+            const conditionKeyGroups = new Map();
+            for (const candidateInfo of this._candidateInfos) {
+                if (candidateInfo.action !== 'suppressed') {
+                    // Don't include suppressed candidates
+                    const key = candidateInfo.conditionSetKey;
+                    if (!conditionKeyGroups.has(key)) {
+                        conditionKeyGroups.set(key, []);
+                    }
+                    conditionKeyGroups.get(key).push(candidateInfo);
+                }
+            }
+            // Apply smart collision resolution
+            for (const [, candidatesWithSameKey] of conditionKeyGroups) {
+                if (candidatesWithSameKey.length > 1) {
+                    // Categorize candidates
+                    const unchangedCandidates = candidatesWithSameKey.filter((c) => c.action === 'unchanged');
+                    const reducedCandidates = candidatesWithSameKey.filter((c) => c.action === 'reduced');
+                    if (unchangedCandidates.length === 1 && reducedCandidates.length === 1) {
+                        // Simple case: one unchanged vs one reduced - apply smart resolution
+                        const unchangedCandidate = unchangedCandidates[0];
+                        const reducedCandidate = reducedCandidates[0];
+                        if (!reducedCandidate.originalCandidate.isPartial) {
+                            // Complete reduced candidate wins - suppress unchanged
+                            unchangedCandidate.action = 'suppressed';
+                            hasCollisions = true;
+                        }
+                        else {
+                            /* c8 ignore next 12 - complex collision handling for partial candidates rarely triggered */
+                            // Partial reduced candidate - merge into unchanged and suppress reduced
+                            const mergedJson = CandidateReducer._mergeJsonValues(unchangedCandidate.originalCandidate.json, reducedCandidate.originalCandidate.json);
+                            // Update unchanged candidate with merged JSON, keeping its isPartial status
+                            unchangedCandidate.json = mergedJson;
+                            // Suppress the reduced candidate
+                            reducedCandidate.action = 'suppressed';
+                            hasCollisions = true;
+                        }
+                    }
+                    else {
+                        /* c8 ignore next 15 - complex collision reversion logic rarely triggered in practice */
+                        // Complex collision case - revert all reduced candidates to unchanged
+                        for (const candidateInfo of reducedCandidates) {
+                            // Revert to original conditions and mark as unchanged
+                            const originalConditions = candidateInfo.originalCandidate.conditions.conditions.map((c) => c.toLooseConditionDecl());
+                            const originalKey = CandidateReducer._computeConditionSetKey(originalConditions);
+                            // Update the candidate info to revert to original state
+                            candidateInfo.action = 'unchanged';
+                            candidateInfo.conditions = originalConditions;
+                            candidateInfo.conditionSetKey = originalKey;
+                            hasCollisions = true;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Static convenience method to construct an array of properly reduced
+     * {@link ResourceJson.Json.IChildResourceCandidateDecl | child resource candidate declarations}
+     * from a set of {@link Resources.ResourceCandidate | resource candidates}.
+     * @param candidates - The candidates to reduce
+     * @param filterForContext - Optional context to filter against
+     * @returns Result with array of reduced candidate declarations, or Failure if reduction fails
+     */
+    static reduceToChildResourceCandidateDecls(candidates, filterForContext) {
+        if (!filterForContext || Object.keys(filterForContext).length === 0) {
+            return succeed(candidates.map((candidate) => candidate.toChildResourceCandidateDecl()));
+        }
+        const reducer = new CandidateReducer(candidates, filterForContext);
+        const reductionResults = mapResults(candidates.map((candidate) => reducer.reduceCandidate(candidate)));
+        return reductionResults.onSuccess((reductions) => {
+            const validReductions = reductions.filter((reduction) => reduction !== undefined);
+            return succeed(validReductions.map((reduction) => {
+                var _a, _b, _c;
+                return ({
+                    /* c8 ignore next 3 -- defense in depth */
+                    json: (_a = reduction.json) !== null && _a !== void 0 ? _a : reduction.candidate.json,
+                    isPartial: (_b = reduction.isPartial) !== null && _b !== void 0 ? _b : reduction.candidate.isPartial,
+                    mergeMethod: (_c = reduction.mergeMethod) !== null && _c !== void 0 ? _c : reduction.candidate.mergeMethod,
+                    conditions: reduction.conditions
+                });
+            }));
+        });
+    }
+    /**
+     * Static convenience method to construct an array of properly reduced
+     * {@link ResourceJson.Json.ILooseResourceCandidateDecl | loose resource candidate declarations}
+     * from a set of {@link Resources.ResourceCandidate | resource candidates}.
+     * @param id - The id of the resource
+     * @param candidates - The candidates to reduce
+     * @param filterForContext - Optional context to filter against
+     * @returns Result with array of reduced candidate declarations, or Failure if reduction fails
+     */
+    static reduceToLooseResourceCandidateDecls(id, candidates, filterForContext) {
+        if (!filterForContext || Object.keys(filterForContext).length === 0) {
+            return succeed(candidates.map((candidate) => candidate.toLooseResourceCandidateDecl()));
+        }
+        const reducer = new CandidateReducer(candidates, filterForContext);
+        const reductionResults = mapResults(candidates.map((candidate) => reducer.reduceCandidate(candidate)));
+        return reductionResults.onSuccess((reductions) => {
+            const validReductions = reductions.filter((reduction) => reduction !== undefined);
+            return succeed(validReductions.map((reduction) => {
+                var _a, _b, _c;
+                return ({
+                    id,
+                    /* c8 ignore next 3 -- defense in depth */
+                    json: (_a = reduction.json) !== null && _a !== void 0 ? _a : reduction.candidate.json,
+                    isPartial: (_b = reduction.isPartial) !== null && _b !== void 0 ? _b : reduction.candidate.isPartial,
+                    mergeMethod: (_c = reduction.mergeMethod) !== null && _c !== void 0 ? _c : reduction.candidate.mergeMethod,
+                    conditions: reduction.conditions
+                });
+            }));
+        });
+    }
+    /**
+     * Reduces a single candidate according to the configured reduction rules.
+     * @param candidate - The candidate to reduce
+     * @returns Either a reduced candidate declaration or an error if the candidate is not found
+     */
+    reduceCandidate(candidate) {
+        var _a;
+        const candidateInfo = this._candidateInfos.find((info) => info.originalCandidate === candidate);
+        /* c8 ignore next 3 - defensive coding: candidate should always be found if properly managed */
+        if (!candidateInfo) {
+            return fail(`Candidate not found in reducer state`);
+        }
+        if (candidateInfo.action === 'suppressed') {
+            return succeed(undefined);
+        }
+        // Convert array of conditions back to ConditionSetDecl for compatibility
+        const conditionsAsRecord = candidateInfo.conditions.reduce((acc, condition) => {
+            return Object.assign(Object.assign({}, acc), { [condition.qualifierName]: condition.value });
+        }, {});
+        return succeed({
+            candidate,
+            conditions: conditionsAsRecord,
+            json: (_a = candidateInfo.json) !== null && _a !== void 0 ? _a : candidate.json,
+            isPartial: candidate.isPartial,
+            mergeMethod: candidate.mergeMethod
+        });
+    }
+}
+//# sourceMappingURL=candidateReducer.js.map

package/dist/packlets/resources/candidateValue.js

@@ -0,0 +1,92 @@
+/*
+ * 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, Hash, captureResult } from '@fgv/ts-utils';
+import { Convert as CommonConverters } from '../common';
+import * as Common from '../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
+ */
+export 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;
+        /* c8 ignore next 1 - defense in depth */
+        const normalizer = (_a = params.normalizer) !== null && _a !== void 0 ? _a : new 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 = CommonConverters.candidateValueKey.convert(keyResult.orThrow()).orThrow();
+        // Create the collectible with the key and optional index
+        this._collectible = new 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 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);
+    }
+}
+//# sourceMappingURL=candidateValue.js.map

package/dist/packlets/resources/candidateValueCollector.js

@@ -0,0 +1,94 @@
+/*
+ * 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 { Validators as JsonValidators } from '@fgv/ts-json-base';
+import { Collections, Hash, captureResult, succeed, ValidatingCollector } from '@fgv/ts-utils';
+import { Convert as CommonConvert } from '../common';
+import { CandidateValue } from './candidateValue';
+/**
+ * A `ValidatingCollector` for {@link Resources.CandidateValue | CandidateValues},
+ * which collects candidate values supplied as either {@link Resources.CandidateValue | CandidateValue} or
+ * `JsonValue`.
+ * @public
+ */
+export class CandidateValueCollector extends ValidatingCollector {
+    /**
+     * Constructor for a {@link Resources.CandidateValueCollector} object.
+     * @param params - Parameters to create the collector.
+     * @internal
+     */
+    constructor(params) {
+        var _a, _b;
+        super({
+            converters: new Collections.KeyValueConverters({
+                key: CommonConvert.candidateValueKey,
+                value: (from) => this._toCandidateValue(from)
+            })
+        });
+        /* c8 ignore next 3 - defense in depth */
+        params = params !== null && params !== void 0 ? params : {};
+        this.normalizer = (_a = params.normalizer) !== null && _a !== void 0 ? _a : new Hash.Crc32Normalizer();
+        (_b = params.candidateValues) === null || _b === void 0 ? void 0 : _b.forEach((candidateValue) => this.validating.add(candidateValue));
+    }
+    /**
+     * Creates a new {@link Resources.CandidateValueCollector} object.
+     * @param params - Parameters to create the collector.
+     * @returns `Success` with the new collector if successful,
+     * or `Failure` with an error message if not.
+     * @public
+     */
+    static create(params) {
+        return captureResult(() => new CandidateValueCollector(params));
+    }
+    /**
+     * Returns an array of JSON values ordered by their indices.
+     * @returns Array of JsonValue objects in index order.
+     * @public
+     */
+    getValuesByIndex() {
+        // Use the base class valuesByIndex() method to get CandidateValues in index order,
+        // then extract their JSON values
+        return this.valuesByIndex().map((candidateValue) => candidateValue.json);
+    }
+    /**
+     * Converter method to handle CandidateValue | JsonValue.
+     * @param from - The value to convert.
+     * @returns `Success` with the CandidateValue if successful, or `Failure` with an error message if not.
+     * @internal
+     */
+    _toCandidateValue(from) {
+        /* c8 ignore next 3 - functional code tested but coverage intermittently missed */
+        if (from instanceof CandidateValue) {
+            return succeed(from);
+        }
+        // Validate as JsonValue and create new CandidateValue
+        return JsonValidators.jsonValue
+            .validate(from)
+            .withErrorFormat((msg) => `Invalid JSON value: ${msg}`)
+            .onSuccess((jsonValue) => {
+            return CandidateValue.create({
+                json: jsonValue,
+                normalizer: this.normalizer
+            });
+        });
+    }
+}
+//# sourceMappingURL=candidateValueCollector.js.map

package/dist/packlets/resources/common.js

@@ -0,0 +1,23 @@
+/*
+ * 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 {};
+//# sourceMappingURL=common.js.map