@fgv/ts-res 5.0.0-3 → 5.0.0-31

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

@@ -1,4 +1,5 @@
-import { Brand } from '@fgv/ts-utils';
+import { JsonValue } from '@fgv/ts-json-base';
+import { Brand, Result } from '@fgv/ts-utils';
 /**
  * Branded string representing a validated resource id.  A resource ID
  * is a dot-separated sequence of resource names.
@@ -38,4 +39,50 @@ export type ResourceValueMergeMethod = 'augment' | 'delete' | 'replace';
  * @public
  */
 export declare const allResourceValueMergeMethods: ResourceValueMergeMethod[];
+/**
+ * The completeness of a resource candidate value.  A full value is one that
+ * contains all of the required properties for the resource type.  A partial
+ * value is one that contains some of the required properties for the resource
+ * type.
+ * @public
+ */
+export type CandidateCompleteness = 'full' | 'partial';
+/**
+ * Branded number representing a validated candidate value index.
+ * Candidate value indices are used to identify candidate values
+ * within a resource set and to enable sharing of like values.
+ * @public
+ */
+export type CandidateValueIndex = Brand<number, 'CandidateValueIndex'>;
+/**
+ * Branded string representing a validated candidate value key.
+ * Candidate value keys are used to identify candidate values
+ * within a resource set and to enable sharing of like values.
+ * @public
+ */
+export type CandidateValueKey = Brand<string, 'CandidateValueKey'>;
+/**
+ * Minimal resource resolver
+ * @public
+ */
+export interface IResourceResolver {
+    /**
+     * Resolves a resource to a composed value by merging matching candidates according to their merge methods.
+     * Starting from the highest priority candidates, finds the first "full" candidate and merges all higher
+     * priority "partial" candidates into it in ascending order of priority.
+     * @param resource - The string id of the resource to resolve.
+     * @returns `Success` with the composed JsonValue if successful,
+     * or `Failure` with an error message if no candidates match or resolution fails.
+     * @public
+     */
+    resolveComposedResourceValue(resource: string): Result<JsonValue>;
+    /**
+     * Creates a new {@link IResourceResolver | resource resolver} with the given context.
+     * @param context - The context to use for the new resource resolver.
+     * @returns `Success` with the new resource resolver if successful,
+     * or `Failure` with an error message if the context is invalid.
+     * @public
+     */
+    withContext(context: Record<string, string>): Result<IResourceResolver>;
+}
 //# sourceMappingURL=resources.d.ts.map

package/lib/packlets/common/validate/conditions.d.ts

@@ -1,5 +1,5 @@
 import { Result } from '@fgv/ts-utils';
-import { ConditionPriority, QualifierName, QualifierTypeName, QualifierIndex, QualifierTypeIndex, ConditionIndex, ConditionSetIndex, QualifierMatchScore, ConditionKey, ConditionSetKey, DecisionKey, DecisionIndex, ConditionSetHash, ConditionOperator, ConditionToken, ConditionSetToken, ContextQualifierToken, ContextToken, QualifierDefaultValueToken, QualifierDefaultValuesToken } from '../conditions';
+import { ConditionPriority, QualifierName, QualifierTypeName, QualifierIndex, QualifierTypeIndex, ConditionIndex, ConditionSetIndex, QualifierMatchScore, QualifierContextValue, ConditionKey, ConditionSetKey, DecisionKey, DecisionIndex, ConditionSetHash, ConditionOperator, ConditionToken, ConditionSetToken, ContextQualifierToken, ContextToken, QualifierDefaultValueToken, QualifierDefaultValuesToken } from '../conditions';
 /**
  * Determines whether a string is a valid qualifier name.
  * @param name - the string to validate
@@ -117,6 +117,14 @@ export declare function isValidDecisionKey(key: string): key is DecisionKey;
  * @public
  */
 export declare function isValidDecisionIndex(index: number): index is DecisionIndex;
+/**
+ * Determines whether a string is a valid qualifier context value.
+ * For now, any non-empty string is considered a valid context value.
+ * @param value - the string to validate
+ * @returns true if the string is a valid qualifier context value, false otherwise.
+ * @public
+ */
+export declare function isValidQualifierContextValue(value: string): value is QualifierContextValue;
 /**
  * Converts a string to a {@link QualifierName} if it is a valid qualifier name.
  * @param name - the string to convert
@@ -125,6 +133,14 @@ export declare function isValidDecisionIndex(index: number): index is DecisionIn
  * @public
  */
 export declare function toQualifierName(name: string): Result<QualifierName>;
+/**
+ * Converts a string to a {@link QualifierContextValue} if it is a valid qualifier context value.
+ * @param value - the string to convert
+ * @returns `Success` with the converted {@link QualifierContextValue} if successful, or `Failure` with an
+ * error message if not.
+ * @public
+ */
+export declare function toQualifierContextValue(value: string): Result<QualifierContextValue>;
 /**
  * Converts a number to a {@link QualifierIndex} if it is a valid qualifier index.
  * @param index - the number to convert

package/lib/packlets/common/validate/conditions.js

@@ -37,7 +37,9 @@ exports.isValidConditionSetToken = isValidConditionSetToken;
 exports.isValidConditionSetHash = isValidConditionSetHash;
 exports.isValidDecisionKey = isValidDecisionKey;
 exports.isValidDecisionIndex = isValidDecisionIndex;
+exports.isValidQualifierContextValue = isValidQualifierContextValue;
 exports.toQualifierName = toQualifierName;
+exports.toQualifierContextValue = toQualifierContextValue;
 exports.toQualifierIndex = toQualifierIndex;
 exports.toQualifierTypeName = toQualifierTypeName;
 exports.toQualifierTypeIndex = toQualifierTypeIndex;
@@ -182,6 +184,7 @@ function isValidConditionSetKey(key) {
     if (key === '') {
         return true;
     }
+    /* c8 ignore next 2 - edge case: condition set key validation rarely fails */
     // a condition set key is a `+` separated list of condition keys
     return key.split('+').every(isValidConditionKey);
 }
@@ -224,6 +227,16 @@ function isValidDecisionKey(key) {
 function isValidDecisionIndex(index) {
     return index >= 0;
 }
+/**
+ * Determines whether a string is a valid qualifier context value.
+ * For now, any non-empty string is considered a valid context value.
+ * @param value - the string to validate
+ * @returns true if the string is a valid qualifier context value, false otherwise.
+ * @public
+ */
+function isValidQualifierContextValue(value) {
+    return typeof value === 'string' && value.length > 0;
+}
 /**
  * Converts a string to a {@link QualifierName} if it is a valid qualifier name.
  * @param name - the string to convert
@@ -234,10 +247,23 @@ function isValidDecisionIndex(index) {
 function toQualifierName(name) {
     /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
     if (!isValidQualifierName(name)) {
-        return (0, ts_utils_1.fail)(`${name}: not a valid qualifier name`);
+        return (0, ts_utils_1.fail)(`${name}: invalid qualifier name`);
     }
     return (0, ts_utils_1.succeed)(name);
 }
+/**
+ * Converts a string to a {@link QualifierContextValue} if it is a valid qualifier context value.
+ * @param value - the string to convert
+ * @returns `Success` with the converted {@link QualifierContextValue} if successful, or `Failure` with an
+ * error message if not.
+ * @public
+ */
+function toQualifierContextValue(value) {
+    if (!isValidQualifierContextValue(value)) {
+        return (0, ts_utils_1.fail)(`${value}: invalid qualifier context value`);
+    }
+    return (0, ts_utils_1.succeed)(value);
+}
 /**
  * Converts a number to a {@link QualifierIndex} if it is a valid qualifier index.
  * @param index - the number to convert
@@ -248,7 +274,7 @@ function toQualifierName(name) {
 function toQualifierIndex(index) {
     /* c8 ignore next 3 - coverage is having a bad day */
     if (!isValidQualifierIndex(index)) {
-        return (0, ts_utils_1.fail)(`${index}: not a valid qualifier index`);
+        return (0, ts_utils_1.fail)(`${index}: invalid qualifier index`);
     }
     return (0, ts_utils_1.succeed)(index);
 }
@@ -262,7 +288,7 @@ function toQualifierIndex(index) {
 function toQualifierTypeName(name) {
     /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
     if (!isValidQualifierTypeName(name)) {
-        return (0, ts_utils_1.fail)(`${name}: not a valid qualifier type name`);
+        return (0, ts_utils_1.fail)(`${name}: invalid qualifier type name`);
     }
     return (0, ts_utils_1.succeed)(name);
 }
@@ -276,7 +302,7 @@ function toQualifierTypeName(name) {
 function toQualifierTypeIndex(index) {
     /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
     if (!isValidQualifierTypeIndex(index)) {
-        return (0, ts_utils_1.fail)(`${index}: not a valid qualifier type index`);
+        return (0, ts_utils_1.fail)(`${index}: invalid qualifier type index`);
     }
     return (0, ts_utils_1.succeed)(index);
 }
@@ -541,7 +567,7 @@ function isValidQualifierDefaultValuesToken(token) {
 function toQualifierDefaultValueToken(token) {
     /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
     if (!isValidQualifierDefaultValueToken(token)) {
-        return (0, ts_utils_1.fail)(`${token}: not a valid qualifier default value token`);
+        return (0, ts_utils_1.fail)(`${token}: invalid qualifier default value token`);
     }
     return (0, ts_utils_1.succeed)(token);
 }
@@ -555,7 +581,7 @@ function toQualifierDefaultValueToken(token) {
 function toQualifierDefaultValuesToken(token) {
     /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
     if (!isValidQualifierDefaultValuesToken(token)) {
-        return (0, ts_utils_1.fail)(`${token}: not a valid qualifier default values token`);
+        return (0, ts_utils_1.fail)(`${token}: invalid qualifier default values token`);
     }
     return (0, ts_utils_1.succeed)(token);
 }

package/lib/packlets/common/validate/regularExpressions.d.ts

@@ -38,6 +38,10 @@ export declare const conditionSetHash: RegExp;
  * @internal
  */
 export declare const decisionKey: RegExp;
+/**
+ * @internal
+ */
+export declare const candidateValueKey: RegExp;
 /**
  * A {@link QualifierDefaultValueToken | qualifier default value token} has the form
  * `<qualifierName>=<value>` or `<qualifierName>=` (to remove default).

package/lib/packlets/common/validate/regularExpressions.js

@@ -21,7 +21,7 @@
  * SOFTWARE.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.territoryCode = exports.qualifierDefaultValuesToken = exports.qualifierDefaultValueToken = exports.decisionKey = exports.conditionSetHash = exports.contextToken = exports.conditionToken = exports.conditionKey = exports.identifierList = exports.segmentedIdentifier = exports.identifier = void 0;
+exports.territoryCode = exports.qualifierDefaultValuesToken = exports.qualifierDefaultValueToken = exports.candidateValueKey = exports.decisionKey = exports.conditionSetHash = exports.contextToken = exports.conditionToken = exports.conditionKey = exports.identifierList = exports.segmentedIdentifier = exports.identifier = void 0;
 /**
  * @internal
  */
@@ -62,6 +62,10 @@ exports.conditionSetHash = /^[a-zA-Z0-9]{8}$/;
  * @internal
  */
 exports.decisionKey = /^[a-zA-Z0-9]{8}(?:\+[a-zA-Z0-9]{8})*(?:\|[a-zA-Z0-9]{8})?$/;
+/**
+ * @internal
+ */
+exports.candidateValueKey = /^[a-zA-Z0-9]+$/;
 /**
  * A {@link QualifierDefaultValueToken | qualifier default value token} has the form
  * `<qualifierName>=<value>` or `<qualifierName>=` (to remove default).

package/lib/packlets/common/validate/resources.d.ts

@@ -1,5 +1,5 @@
 import { Result } from '@fgv/ts-utils';
-import { ResourceId, ResourceIndex, ResourceName, ResourceTypeIndex, ResourceTypeName } from '../resources';
+import { CandidateValueIndex, CandidateValueKey, ResourceId, ResourceIndex, ResourceName, ResourceTypeIndex, ResourceTypeName } from '../resources';
 /**
  * Checks if the given name is a valid resource name.
  *
@@ -40,6 +40,22 @@ export declare function isValidResourceTypeName(name: string): name is ResourceT
  * @public
  */
 export declare function isValidResourceTypeIndex(index: number): index is ResourceTypeIndex;
+/**
+ * Checks if the given index is a valid candidate value index.
+ *
+ * @param index - The index to validate.
+ * @returns `true` if the index is a valid candidate value index, otherwise `false`.
+ * @public
+ */
+export declare function isValidCandidateValueIndex(index: number): index is CandidateValueIndex;
+/**
+ * Checks if the given key is a valid candidate value key.
+ *
+ * @param key - The key to validate.
+ * @returns `true` if the key is a valid candidate value key, otherwise `false`.
+ * @public
+ */
+export declare function isValidCandidateValueKey(key: string): key is CandidateValueKey;
 /**
  * Converts a string to a {@link ResourceName | resource name}.
  *
@@ -94,4 +110,22 @@ export declare function toResourceTypeName(name: string): Result<ResourceTypeNam
  * @public
  */
 export declare function toResourceTypeIndex(index: number): Result<ResourceTypeIndex>;
+/**
+ * Converts a string to a {@link CandidateValueKey | candidate value key}.
+ *
+ * @param key - The key to convert.
+ * @returns `Success` with the converted key if valid, or `Failure` with an error message
+ * if not.
+ * @public
+ */
+export declare function toCandidateValueKey(key: string): Result<CandidateValueKey>;
+/**
+ * Converts a number to a {@link CandidateValueIndex | candidate value index}.
+ *
+ * @param index - The number to convert.
+ * @returns `Success` with the converted index if valid, or `Failure` with an error message
+ * if not.
+ * @public
+ */
+export declare function toCandidateValueIndex(index: number): Result<CandidateValueIndex>;
 //# sourceMappingURL=resources.d.ts.map

package/lib/packlets/common/validate/resources.js

@@ -26,12 +26,16 @@ exports.isValidResourceId = isValidResourceId;
 exports.isValidResourceIndex = isValidResourceIndex;
 exports.isValidResourceTypeName = isValidResourceTypeName;
 exports.isValidResourceTypeIndex = isValidResourceTypeIndex;
+exports.isValidCandidateValueIndex = isValidCandidateValueIndex;
+exports.isValidCandidateValueKey = isValidCandidateValueKey;
 exports.toResourceName = toResourceName;
 exports.toResourceId = toResourceId;
 exports.toOptionalResourceId = toOptionalResourceId;
 exports.toResourceIndex = toResourceIndex;
 exports.toResourceTypeName = toResourceTypeName;
 exports.toResourceTypeIndex = toResourceTypeIndex;
+exports.toCandidateValueKey = toCandidateValueKey;
+exports.toCandidateValueIndex = toCandidateValueIndex;
 const ts_utils_1 = require("@fgv/ts-utils");
 const regularExpressions_1 = require("./regularExpressions");
 /**
@@ -84,6 +88,26 @@ function isValidResourceTypeName(name) {
 function isValidResourceTypeIndex(index) {
     return index >= 0;
 }
+/**
+ * Checks if the given index is a valid candidate value index.
+ *
+ * @param index - The index to validate.
+ * @returns `true` if the index is a valid candidate value index, otherwise `false`.
+ * @public
+ */
+function isValidCandidateValueIndex(index) {
+    return index >= 0;
+}
+/**
+ * Checks if the given key is a valid candidate value key.
+ *
+ * @param key - The key to validate.
+ * @returns `true` if the key is a valid candidate value key, otherwise `false`.
+ * @public
+ */
+function isValidCandidateValueKey(key) {
+    return regularExpressions_1.candidateValueKey.test(key);
+}
 /**
  * Converts a string to a {@link ResourceName | resource name}.
  *
@@ -108,6 +132,7 @@ function toResourceName(name) {
  * @public
  */
 function toResourceId(id) {
+    /* c8 ignore next 3 - defensive coding: resource ID validation should prevent invalid IDs */
     if (!isValidResourceId(id)) {
         return (0, ts_utils_1.fail)(`${id}: not a valid resource ID.`);
     }
@@ -168,4 +193,34 @@ function toResourceTypeIndex(index) {
     }
     return (0, ts_utils_1.succeed)(index);
 }
+/**
+ * Converts a string to a {@link CandidateValueKey | candidate value key}.
+ *
+ * @param key - The key to convert.
+ * @returns `Success` with the converted key if valid, or `Failure` with an error message
+ * if not.
+ * @public
+ */
+function toCandidateValueKey(key) {
+    /* c8 ignore next 3 - coverage having issues */
+    if (!isValidCandidateValueKey(key)) {
+        return (0, ts_utils_1.fail)(`${key}: not a valid candidate value key.`);
+    }
+    return (0, ts_utils_1.succeed)(key);
+}
+/**
+ * Converts a number to a {@link CandidateValueIndex | candidate value index}.
+ *
+ * @param index - The number to convert.
+ * @returns `Success` with the converted index if valid, or `Failure` with an error message
+ * if not.
+ * @public
+ */
+function toCandidateValueIndex(index) {
+    /* c8 ignore next 3 - coverage having issues */
+    if (!isValidCandidateValueIndex(index)) {
+        return (0, ts_utils_1.fail)(`${index}: not a valid candidate value index.`);
+    }
+    return (0, ts_utils_1.succeed)(index);
+}
 //# sourceMappingURL=resources.js.map

package/lib/packlets/conditions/condition.js

@@ -43,6 +43,7 @@ class Condition {
      */
     constructor({ qualifier, value, operator, priority, scoreAsDefault, index }) {
         if (scoreAsDefault === undefined && qualifier.defaultValue !== undefined) {
+            /* c8 ignore next 4 - edge case: default value matching logic rarely triggered */
             const defaultMatch = qualifier.type.matches(value, qualifier.defaultValue, 'matches');
             if (defaultMatch !== common_1.NoMatch) {
                 scoreAsDefault = defaultMatch;

package/lib/packlets/conditions/conditionSet.d.ts

@@ -2,6 +2,7 @@ import { Collections, Result } from '@fgv/ts-utils';
 import { Condition } from './condition';
 import { ConditionSetIndex, ConditionSetKey, QualifierName } from '../common';
 import { IValidatedConditionSetDecl } from './conditionSetDecls';
+import { ConditionCollector } from './conditionCollector';
 import * as ResourceJson from '../resource-json';
 import * as Context from '../context';
 /**
@@ -93,6 +94,14 @@ export declare class ConditionSet implements IValidatedConditionSetDecl {
      * @public
      */
     static getKeyForDecl(decl: IValidatedConditionSetDecl): Result<ConditionSetKey>;
+    /**
+     * Gets a condition set key from a loose condition set declaration.
+     * @param conditionSet - The loose condition set declaration to convert.
+     * @param conditionCollector - The condition collector used for validation.
+     * @returns `Success` with the condition set key if successful, `Failure` otherwise.
+     * @public
+     */
+    static getKeyFromLooseDecl(conditionSet: ResourceJson.Json.ConditionSetDecl | undefined, conditionCollector: ConditionCollector): Result<ConditionSetKey>;
     /**
      * Gets a {@link ConditionSetToken | condition set token} for this condition set,
      * if possible.

package/lib/packlets/conditions/conditionSet.js

@@ -20,11 +20,45 @@
  * 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.ConditionSet = void 0;
 const ts_utils_1 = require("@fgv/ts-utils");
 const condition_1 = require("./condition");
 const common_1 = require("../common");
+const ConditionsConvert = __importStar(require("./convert"));
 /**
  * Represents a set of {@link Conditions.Condition | conditions} that must all be met in some runtime
  * context for a resource instance to be valid.
@@ -129,6 +163,44 @@ class ConditionSet {
     static getKeyForDecl(decl) {
         return common_1.Validate.toConditionSetKey(decl.conditions.map((c) => c.toKey()).join('+'));
     }
+    /**
+     * Gets a condition set key from a loose condition set declaration.
+     * @param conditionSet - The loose condition set declaration to convert.
+     * @param conditionCollector - The condition collector used for validation.
+     * @returns `Success` with the condition set key if successful, `Failure` otherwise.
+     * @public
+     */
+    static getKeyFromLooseDecl(conditionSet, conditionCollector) {
+        if (!conditionSet) {
+            return (0, ts_utils_1.succeed)(ConditionSet.UnconditionalKey);
+        }
+        // Convert ConditionSetDecl to IConditionSetDecl format
+        let conditionSetDecl;
+        if (Array.isArray(conditionSet)) {
+            // ConditionSetDeclAsArray: array of ILooseConditionDecl
+            conditionSetDecl = { conditions: conditionSet };
+        }
+        else {
+            // ConditionSetDeclAsRecord: Record<string, string | IChildConditionDecl>
+            const conditions = Object.entries(conditionSet).map(([qualifierName, value]) => {
+                if (typeof value === 'string') {
+                    return { qualifierName, value };
+                }
+                else {
+                    /* c8 ignore next 1 - edge case: object spread pattern rarely used */
+                    return Object.assign({ qualifierName }, value);
+                }
+            });
+            conditionSetDecl = { conditions };
+        }
+        // Validate and convert to IValidatedConditionSetDecl
+        return ConditionsConvert.validatedConditionSetDecl
+            .convert(conditionSetDecl, { conditions: conditionCollector })
+            .onSuccess((validatedDecl) => {
+            // Use proper ConditionSet.getKeyForDecl method to generate the key
+            return ConditionSet.getKeyForDecl(validatedDecl);
+        });
+    }
     /**
      * Gets a {@link ConditionSetToken | condition set token} for this condition set,
      * if possible.
@@ -174,7 +246,8 @@ class ConditionSet {
     toConditionSetRecordDecl(options) {
         const qualifiersToReduce = options === null || options === void 0 ? void 0 : options.qualifiersToReduce;
         const conditions = qualifiersToReduce
-            ? this.conditions.filter((c) => !qualifiersToReduce.has(c.qualifier.name))
+            ? /* c8 ignore next 1 - coverage intermittently misses the next line */
+                this.conditions.filter((c) => !qualifiersToReduce.has(c.qualifier.name))
             : this.conditions;
         return Object.fromEntries(conditions.map((c) => {
             return [c.qualifier.name, c.toValueOrChildConditionDecl(options)];
@@ -186,6 +259,7 @@ class ConditionSet {
      * @returns The {@link ResourceJson.Json.ConditionSetDeclAsArray | condition set declaration as an array} for this condition set.
      */
     toConditionSetArrayDecl(options) {
+        /* c8 ignore next 1 - defense in depth */
         const qualifiersToReduce = options === null || options === void 0 ? void 0 : options.qualifiersToReduce;
         const conditions = qualifiersToReduce
             ? this.conditions.filter((c) => !qualifiersToReduce.has(c.qualifier.name))