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

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

@@ -1,79 +0,0 @@
-/*
- * Copyright (c) 2025 Erik Fortune
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- */
-
-import { Collections, Result, fail, succeed, ValidatingCollector, captureResult } from '@fgv/ts-utils';
-import { ResourceType } from './resourceType';
-import { Convert as CommonConvert, ResourceTypeName } from '../common';
-
-/**
- * Parameters for creating a {@link ResourceTypes.ResourceTypeCollector | ResourceTypeCollector}.
- * @public
- */
-export interface IResourceCollectorCreateParams {
-  resourceTypes?: ResourceType[];
-}
-
-/**
- * Map {@link ResourceTypeName | resource type names} to {@link ResourceTypes.ResourceType | resource types}.
- * @public
- */
-export class ResourceTypeCollector extends ValidatingCollector<ResourceType> {
-  protected constructor({ resourceTypes }: IResourceCollectorCreateParams) {
-    /* c8 ignore next 1 - coverage having a rough day */
-    resourceTypes = resourceTypes ?? [];
-
-    super({
-      converters: new Collections.KeyValueConverters<ResourceTypeName, ResourceType>({
-        key: CommonConvert.resourceTypeName,
-        value: (from: unknown) => this._toResourceType(from)
-      })
-    });
-    resourceTypes.forEach((resourceType) => {
-      this.add(resourceType).orThrow();
-    });
-  }
-
-  /**
-   * Creates a new {@link ResourceTypes.ResourceTypeCollector | ResourceTypeCollector}.
-   * @param params - Optional for creating the new collector.
-   * @returns `Success` with the new instance, or `Failure` with an error
-   * message if the collector could not be created.
-   */
-  public static create(params?: IResourceCollectorCreateParams): Result<ResourceTypeCollector> {
-    /* c8 ignore next 1 - coverage having a rough day */
-    params = params ?? {};
-    return captureResult(() => new ResourceTypeCollector(params));
-  }
-
-  protected _toResourceType(from: unknown): Result<ResourceType> {
-    if (from instanceof ResourceType) {
-      return succeed(from);
-    }
-    return fail('Not a resource type.');
-  }
-}
-
-/**
- * A read-only version of {@link ResourceTypes.ResourceTypeCollector | ResourceTypeCollector}.
- * @public
- */
-export type ReadOnlyResourceTypeCollector = Collections.IReadOnlyValidatingCollector<ResourceType>;

package/src/packlets/resources/candidateReducer.ts

@@ -1,331 +0,0 @@
-/*
- * 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 { QualifierName, ResourceId, ResourceValueMergeMethod } from '../common';
-import * as Context from '../context';
-import * as ResourceJson from '../resource-json';
-import { ResourceCandidate } from './resourceCandidate';
-import { JsonObject } from '@fgv/ts-json-base';
-import { JsonEditor } from '@fgv/ts-json';
-import { Result, succeed, fail, mapResults } from '@fgv/ts-utils';
-
-/**
- * Action taken on a candidate during reduction processing.
- * @public
- */
-export type CandidateAction = 'unchanged' | 'reduced' | 'suppressed';
-
-/**
- * Information about a candidate being processed by the reducer.
- * @public
- */
-export interface ICandidateInfo {
-  readonly originalCandidate: ResourceCandidate;
-  action: CandidateAction;
-  conditions: ResourceJson.Json.ILooseConditionDecl[];
-  conditionSetKey: string;
-  readonly json?: JsonObject;
-}
-
-/**
- * Represents a reduced candidate after applying reduction logic.
- * @public
- */
-export interface IReducedCandidate {
-  readonly candidate: ResourceCandidate;
-  readonly conditions: ResourceJson.Json.ConditionSetDecl;
-  readonly json?: JsonObject;
-  readonly isPartial?: boolean;
-  readonly mergeMethod?: ResourceValueMergeMethod;
-}
-
-/**
- * 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 {
-  private readonly _candidateInfos: ICandidateInfo[];
-  private readonly _filterForContext: Context.IValidatedContextDecl;
-  private readonly _qualifiersToReduce: ReadonlySet<QualifierName>;
-
-  /**
-   * Constructor for CandidateReducer.
-   * @param candidates - The set of candidates to potentially reduce
-   * @param filterForContext - Context to filter candidates against
-   */
-  public constructor(
-    candidates: ReadonlyArray<ResourceCandidate>,
-    filterForContext: Context.IValidatedContextDecl
-  ) {
-    this._filterForContext = filterForContext;
-
-    // Use existing logic to determine reducible qualifiers
-    this._qualifiersToReduce =
-      ResourceCandidate.findReducibleQualifiers(candidates, filterForContext) ?? new Set();
-
-    // Initialize candidate info array with initial reduction attempts
-    this._candidateInfos = candidates.map((candidate): ICandidateInfo => {
-      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: CandidateAction =
-        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
-   */
-  private static _computeConditionSetKey(conditions: ResourceJson.Json.ILooseConditionDecl[]): string {
-    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
-   */
-  private static _mergeJsonValues(baseJson: JsonObject, partialJson: JsonObject): JsonObject {
-    // 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
-   */
-  private _resolveCollisions(): void {
-    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<string, ICandidateInfo[]>();
-
-      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 {
-              // 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 as { json?: JsonObject }).json = mergedJson;
-
-              // Suppress the reduced candidate
-              reducedCandidate.action = 'suppressed';
-              hasCollisions = true;
-            }
-          } else {
-            // 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
-   */
-  public static reduceToChildResourceCandidateDecls(
-    candidates: ReadonlyArray<ResourceCandidate>,
-    filterForContext?: Context.IValidatedContextDecl
-  ): Result<ResourceJson.Json.IChildResourceCandidateDecl[]> {
-    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 is IReducedCandidate => reduction !== undefined
-      );
-
-      return succeed(
-        validReductions.map((reduction) => ({
-          /* c8 ignore next 3 -- defense in depth */
-          json: reduction.json ?? reduction.candidate.json,
-          isPartial: reduction.isPartial ?? reduction.candidate.isPartial,
-          mergeMethod: reduction.mergeMethod ?? 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
-   */
-  public static reduceToLooseResourceCandidateDecls(
-    id: ResourceId,
-    candidates: ReadonlyArray<ResourceCandidate>,
-    filterForContext?: Context.IValidatedContextDecl
-  ): Result<ResourceJson.Json.ILooseResourceCandidateDecl[]> {
-    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 is IReducedCandidate => reduction !== undefined
-      );
-
-      return succeed(
-        validReductions.map((reduction) => ({
-          id,
-          /* c8 ignore next 3 -- defense in depth */
-          json: reduction.json ?? reduction.candidate.json,
-          isPartial: reduction.isPartial ?? reduction.candidate.isPartial,
-          mergeMethod: reduction.mergeMethod ?? 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
-   */
-  public reduceCandidate(candidate: ResourceCandidate): Result<IReducedCandidate | undefined> {
-    const candidateInfo = this._candidateInfos.find((info) => info.originalCandidate === candidate);
-    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 { ...acc, [condition.qualifierName]: condition.value };
-    }, {} as ResourceJson.Json.ConditionSetDecl);
-
-    return succeed({
-      candidate,
-      conditions: conditionsAsRecord,
-      json: candidateInfo.json ?? candidate.json,
-      isPartial: candidate.isPartial,
-      mergeMethod: candidate.mergeMethod
-    });
-  }
-}

package/src/packlets/resources/common.ts

@@ -1,114 +0,0 @@
-/*
- * Copyright (c) 2025 Erik Fortune
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- */
-
-import * as ResourceJson from '../resource-json';
-import { IValidatedContextDecl } from '../context';
-import { IReadOnlyQualifierCollector } from '../qualifiers';
-import { ReadOnlyResourceTypeCollector } from '../resource-types';
-
-/**
- * Options for resource declaration operations with strongly-typed context filtering.
- * Extends the base IDeclarationOptions with proper type safety for context filtering.
- *
- * @example
- * ```typescript
- * // Preferred Result pattern with onSuccess chaining
- * resourceManager.validateContext({ language: 'en' })
- *   .onSuccess((validatedContext) => {
- *     return resourceManager.clone({ filterForContext: validatedContext });
- *   })
- *   .onSuccess((clonedManager) => {
- *     return clonedManager.getResourceCollectionDecl();
- *   })
- *   .onFailure((error) => {
- *     console.error('Failed to create filtered clone:', error);
- *   });
- * ```
- * @public
- */
-export interface IResourceDeclarationOptions extends ResourceJson.Helpers.IDeclarationOptions {
-  /**
-   * If provided, filters resource candidates to only include those that can match the
-   * specified validated context. This provides strongly-typed context filtering.
-   *
-   * Use resourceManager.validateContext() to create a validated context from an IContextDecl.
-   */
-  filterForContext?: IValidatedContextDecl;
-
-  /**
-   * If true, reduces the qualifiers of the resource candidates by removing qualifiers that are made
-   * irrelevant by the filterForContext.
-   * @defaultValue false
-   */
-  reduceQualifiers?: boolean;
-
-  /**
-   * Whether to include metadata in compiled outputs.
-   * Metadata includes human-readable information like semantic keys
-   * that can be useful for debugging or tooling.
-   * @defaultValue false
-   */
-  includeMetadata?: boolean;
-}
-
-/**
- * Extended compiled resource options that includes context filtering capabilities.
- * This interface combines the standard compilation options with strongly-typed
- * context filtering for resource candidates.
- * @public
- */
-export interface ICompiledResourceOptionsWithFilter extends ResourceJson.Compiled.ICompiledResourceOptions {
-  /**
-   * If provided, filters resource candidates to only include those that can match the
-   * specified validated context. This provides strongly-typed context filtering.
-   *
-   * Use resourceManager.validateContext() to create a validated context from an IContextDecl.
-   */
-  filterForContext?: IValidatedContextDecl;
-}
-
-/**
- * Options for ResourceManagerBuilder clone operations.
- * Extends IDeclarationOptions to include support for applying edits when cloning.
- * @public
- */
-export interface IResourceManagerCloneOptions extends IResourceDeclarationOptions {
-  /**
-   * Optional array of loose condition declarations to be applied as edits during the clone operation.
-   * These conditions can modify or extend the resource candidates in the cloned manager.
-   */
-  readonly candidates?: ReadonlyArray<ResourceJson.Json.ILooseResourceCandidateDecl>;
-
-  /**
-   * Optional qualifier collector to use for the cloned manager.
-   * If not provided, uses the same qualifiers as the original manager.
-   * This allows creating clones with different qualifier configurations.
-   */
-  readonly qualifiers?: IReadOnlyQualifierCollector;
-
-  /**
-   * Optional resource type collector to use for the cloned manager.
-   * If not provided, uses the same resource types as the original manager.
-   * This allows creating clones with different resource type configurations.
-   */
-  readonly resourceTypes?: ReadOnlyResourceTypeCollector;
-}

package/src/packlets/resources/index.ts

@@ -1,28 +0,0 @@
-/*
- * 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 * from './candidateReducer';
-export * from './resourceCandidate';
-export * from './resource';
-export * from './resourceBuilder';
-export * from './resourceManagerBuilder';
-export * from './common';