@fgv/ts-res 5.0.0-9 → 5.0.1-1

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))

package/lib/packlets/config/configInitFactory.d.ts

@@ -0,0 +1,217 @@
+import { Result } from '@fgv/ts-utils';
+import { QualifierType, SystemQualifierType } from '../qualifier-types';
+import * as QualifierTypes from '../qualifier-types';
+import * as ResourceTypes from '../resource-types';
+import { ResourceType } from '../resource-types';
+/**
+ * Function signature for creating a qualifier type from configuration.
+ * @public
+ */
+export type QualifierTypeFactoryFunction<T extends QualifierType = QualifierType> = (config: QualifierTypes.Config.IAnyQualifierTypeConfig) => Result<T>;
+/**
+ * Function signature for creating a resource type from configuration.
+ * @public
+ */
+export type ResourceTypeFactoryFunction = (config: ResourceTypes.Config.IResourceTypeConfig) => Result<ResourceType>;
+/**
+ * Interface for a factory that creates a new instance of a configuration object.
+ * @public
+ */
+export interface IConfigInitFactory<TConfig, T> {
+    /**
+     * Creates a new instance of a configuration object.
+     * @param config - The configuration object to create.
+     * @returns A result containing the new instance of the configuration object.
+     */
+    create(config: TConfig): Result<T>;
+}
+/**
+ * Creates a {@link Config.IConfigInitFactory | IConfigInitFactory} from a factory function.
+ * @param fn - The factory function to wrap.
+ * @returns An `IConfigInitFactory` instance that delegates to the function.
+ * @public
+ */
+export declare function createQualifierTypeFactory<T extends QualifierType = QualifierType>(fn: QualifierTypeFactoryFunction<T>): IConfigInitFactory<QualifierTypes.Config.IAnyQualifierTypeConfig, T>;
+/**
+ * Creates a {@link Config.IConfigInitFactory | IConfigInitFactory} from a resource type factory function.
+ * @param fn - The factory function to wrap.
+ * @returns An `IConfigInitFactory` instance that delegates to the function.
+ * @public
+ */
+export declare function createResourceTypeFactory(fn: ResourceTypeFactoryFunction): IConfigInitFactory<ResourceTypes.Config.IResourceTypeConfig, ResourceType>;
+/**
+ * A factory that chains multiple factories together.
+ * @public
+ */
+export declare class ChainedConfigInitFactory<TConfig, T> implements IConfigInitFactory<TConfig, T> {
+    readonly factories: IConfigInitFactory<TConfig, T>[];
+    /**
+     * Constructor for a chained config init factory.
+     * @param factories - The factories to chain.
+     */
+    constructor(factories: IConfigInitFactory<TConfig, T>[]);
+    /**
+     * Creates a new instance of a configuration object.
+     * @param config - The configuration object to create.
+     * @returns A result containing the new instance of the configuration object.
+     */
+    create(config: TConfig): Result<T>;
+}
+/**
+ * A factory that creates a {@link QualifierTypes.SystemQualifierType | SystemQualifierType} from
+ * {@link QualifierTypes.Config.IAnyQualifierTypeConfig | any qualifier type configuration}.
+ * @returns `Success` with the new {@link QualifierTypes.SystemQualifierType | SystemQualifierType}
+ * if successful, `Failure` with an error message otherwise.
+ * @public
+ */
+export declare class BuiltInQualifierTypeFactory implements IConfigInitFactory<QualifierTypes.Config.ISystemQualifierTypeConfig, SystemQualifierType> {
+    /** {@inheritDoc Config.IConfigInitFactory.create} */
+    create(config: QualifierTypes.Config.IAnyQualifierTypeConfig): Result<SystemQualifierType>;
+}
+/**
+ * A factory that creates {@link QualifierTypes.QualifierType | QualifierType} instances from configuration,
+ * supporting both built-in system types and custom external types.
+ *
+ * This factory allows external consumers to extend the qualifier type system with their own custom types
+ * while maintaining support for all built-in types (Language, Territory, Literal).
+ *
+ * @typeParam T - The custom qualifier type(s) to support. Defaults to {@link QualifierTypes.SystemQualifierType | SystemQualifierType}.
+ *
+ * @example Creating a factory with custom qualifier types
+ * ```typescript
+ * // Define a custom qualifier type
+ * class CustomQualifierType extends QualifierType {
+ *   // ... implementation
+ * }
+ *
+ * // Define a discriminated union of all types
+ * type AppQualifierType = SystemQualifierType | CustomQualifierType;
+ *
+ * // Create a factory that handles custom types
+ * const customFactory: IConfigInitFactory<IAnyQualifierTypeConfig, CustomQualifierType> = {
+ *   create(config) {
+ *     // ... handle custom type creation
+ *   }
+ * };
+ *
+ * // Create the combined factory
+ * const qualifierTypeFactory = new QualifierTypeFactory<AppQualifierType>([customFactory]);
+ *
+ * // The factory returns T | SystemQualifierType, supporting all types
+ * const result = qualifierTypeFactory.create(config); // Result<AppQualifierType | SystemQualifierType>
+ * ```
+ *
+ * @remarks
+ * - The factory chains custom factories with the built-in factory
+ * - Custom factories are tried first, falling back to built-in types
+ * - The return type is a union of custom types (T) and system types
+ *
+ * @public
+ */
+export declare class QualifierTypeFactory<T extends QualifierType = SystemQualifierType> extends ChainedConfigInitFactory<QualifierTypes.Config.IAnyQualifierTypeConfig, T | SystemQualifierType> {
+    /**
+     * Constructor for a {@link Config.QualifierTypeFactory | qualifier type factory}.
+     * @param factories - Array of factories for custom qualifier types. Can be:
+     *                    - {@link Config.IConfigInitFactory | IConfigInitFactory} instances
+     *                    - {@link Config.QualifierTypeFactoryFunction | Factory functions}
+     *                    - A mix of both
+     *                    These are tried in order before falling back to built-in types.
+     * @remarks The {@link Config.BuiltInQualifierTypeFactory | built-in factory} is always appended to handle
+     *          system qualifier types (Language, Territory, Literal).
+     */
+    constructor(factories: Array<IConfigInitFactory<QualifierTypes.Config.IAnyQualifierTypeConfig, T> | QualifierTypeFactoryFunction<T>>);
+}
+/**
+ * A factory that validates and creates {@link QualifierTypes.QualifierType | QualifierType} instances
+ * from weakly-typed configuration objects. This factory accepts configurations with unvalidated
+ * string properties and validates them before delegating to the underlying factory chain.
+ *
+ * This pattern is useful at package boundaries where type identity issues may occur with
+ * branded types across different package instances.
+ *
+ * @example
+ * ```typescript
+ * // Accept weakly-typed config from external source
+ * const validatingFactory = new ValidatingQualifierTypeFactory([customFactory]);
+ *
+ * // Config can have plain string types instead of branded types
+ * const config = {
+ *   name: 'my-qualifier',  // plain string, not QualifierTypeName
+ *   systemType: 'custom',   // plain string
+ *   configuration: { ... }
+ * };
+ *
+ * const result = validatingFactory.create(config); // Validates and converts internally
+ * ```
+ *
+ * @public
+ */
+export declare class ValidatingQualifierTypeFactory<T extends QualifierType = SystemQualifierType> implements IConfigInitFactory<unknown, T | SystemQualifierType> {
+    private readonly _innerFactory;
+    /**
+     * Constructor for a validating qualifier type factory.
+     * @param factories - Array of factories for custom qualifier types. Can be:
+     *                    - {@link Config.IConfigInitFactory | IConfigInitFactory} instances
+     *                    - {@link Config.QualifierTypeFactoryFunction | Factory functions}
+     *                    - A mix of both
+     */
+    constructor(factories: Array<IConfigInitFactory<QualifierTypes.Config.IAnyQualifierTypeConfig, T> | QualifierTypeFactoryFunction<T>>);
+    /**
+     * Creates a qualifier type from a weakly-typed configuration object.
+     * @param config - The configuration object to validate and use for creation.
+     * @returns A result containing the new qualifier type if successful.
+     */
+    create(config: unknown): Result<T | SystemQualifierType>;
+}
+/**
+ * A factory that creates a {@link ResourceTypes.ResourceType | ResourceType} from a {@link ResourceTypes.Config.IResourceTypeConfig | resource type configuration}.
+ * @public
+ */
+export declare class BuiltInResourceTypeFactory implements IConfigInitFactory<ResourceTypes.Config.IResourceTypeConfig, ResourceType> {
+    /** {@inheritDoc Config.IConfigInitFactory.create} */
+    create(config: ResourceTypes.Config.IResourceTypeConfig): Result<ResourceType>;
+}
+/**
+ * A factory that creates a {@link ResourceTypes.ResourceType | ResourceType} from a {@link ResourceTypes.Config.IResourceTypeConfig | resource type configuration}
+ * by chaining a supplied factory with a {@link Config.BuiltInResourceTypeFactory | built-in factory} that handles built-in resource types.
+ * @public
+ */
+export declare class ResourceTypeFactory extends ChainedConfigInitFactory<ResourceTypes.Config.IResourceTypeConfig, ResourceType> {
+    /**
+     * Constructor for a resource type factory.
+     * @param factories - Array of factories for resource types. Can be:
+     *                    - {@link Config.IConfigInitFactory | IConfigInitFactory} instances
+     *                    - {@link Config.ResourceTypeFactoryFunction | Factory functions}
+     *                    - A mix of both
+     * @remarks The {@link Config.BuiltInResourceTypeFactory | built-in factory} is always added to the end of the chain.
+     */
+    constructor(factories: Array<IConfigInitFactory<ResourceTypes.Config.IResourceTypeConfig, ResourceType> | ResourceTypeFactoryFunction>);
+}
+/**
+ * A factory that validates and creates {@link ResourceTypes.ResourceType | ResourceType} instances
+ * from weakly-typed configuration objects. This factory accepts configurations with unvalidated
+ * string properties and validates them before delegating to the underlying factory chain.
+ *
+ * This pattern is useful at package boundaries where type identity issues may occur with
+ * branded types across different package instances.
+ *
+ * @public
+ */
+export declare class ValidatingResourceTypeFactory implements IConfigInitFactory<unknown, ResourceType> {
+    private readonly _innerFactory;
+    /**
+     * Constructor for a validating resource type factory.
+     * @param factories - Array of factories for resource types. Can be:
+     *                    - {@link Config.IConfigInitFactory | IConfigInitFactory} instances
+     *                    - {@link Config.ResourceTypeFactoryFunction | Factory functions}
+     *                    - A mix of both
+     */
+    constructor(factories: Array<IConfigInitFactory<ResourceTypes.Config.IResourceTypeConfig, ResourceType> | ResourceTypeFactoryFunction>);
+    /**
+     * Creates a resource type from a weakly-typed configuration object.
+     * @param config - The configuration object to validate and use for creation.
+     * @returns A result containing the new resource type if successful.
+     */
+    create(config: unknown): Result<ResourceType>;
+}
+//# sourceMappingURL=configInitFactory.d.ts.map