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

package/src/packlets/bundle/bundleNormalizer.ts

@@ -1,173 +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 { Result, succeed, MessageAggregator } from '@fgv/ts-utils';
-import { ResourceManagerBuilder } from '../resources';
-import { ResourceCandidate } from '../resources';
-import { SystemConfiguration, PredefinedSystemConfiguration } from '../config';
-import { Condition, ConditionSet } from '../conditions';
-
-/**
- * Normalizes ResourceManagerBuilder instances to ensure consistent ordering
- * of internal entities, enabling order-independent bundle checksums.
- *
- * The normalization process rebuilds the ResourceManagerBuilder from the ground up
- * in a canonical order to ensure identical index assignments regardless of
- * original construction order.
- * @public
- */
-export class BundleNormalizer {
-  /**
-   * Creates a normalized ResourceManagerBuilder from an existing builder.
-   * The normalized builder will have identical entities but arranged in
-   * canonical order to ensure consistent index assignments.
-   *
-   * @param originalBuilder - The ResourceManagerBuilder to normalize
-   * @param systemConfig - The SystemConfiguration used to create the original builder
-   * @returns Success with the normalized ResourceManagerBuilder if successful, Failure otherwise
-   */
-  public static normalize(
-    originalBuilder: ResourceManagerBuilder,
-    systemConfig: SystemConfiguration
-  ): Result<ResourceManagerBuilder> {
-    // Create a fresh builder using the same system configuration
-    return ResourceManagerBuilder.create({
-      qualifiers: systemConfig.qualifiers,
-      resourceTypes: systemConfig.resourceTypes
-    }).onSuccess((normalizedBuilder) => {
-      return BundleNormalizer._addNormalizedResources(originalBuilder, normalizedBuilder).onSuccess(() =>
-        succeed(normalizedBuilder)
-      );
-    });
-  }
-
-  /**
-   * Creates a normalized ResourceManagerBuilder using a predefined system configuration.
-   * This is a convenience method for the common case of using predefined configurations.
-   *
-   * @param originalBuilder - The ResourceManagerBuilder to normalize
-   * @param configName - The name of the predefined system configuration used
-   * @returns Success with the normalized ResourceManagerBuilder if successful, Failure otherwise
-   */
-  public static normalizeFromPredefined(
-    originalBuilder: ResourceManagerBuilder,
-    configName: PredefinedSystemConfiguration
-  ): Result<ResourceManagerBuilder> {
-    return ResourceManagerBuilder.createPredefined(configName).onSuccess((normalizedBuilder) => {
-      return BundleNormalizer._addNormalizedResources(originalBuilder, normalizedBuilder).onSuccess(() =>
-        succeed(normalizedBuilder)
-      );
-    });
-  }
-
-  /**
-   * Normalizes all conditions from the original builder by adding them to the
-   * normalized builder in sorted order using loose condition declarations.
-   *
-   * @param originalBuilder - The source ResourceManagerBuilder
-   * @param normalizedBuilder - The target normalized ResourceManagerBuilder
-   * @returns Success if all conditions were normalized successfully, Failure otherwise
-   * @internal
-   */
-  private static _normalizeConditions(
-    originalBuilder: ResourceManagerBuilder,
-    normalizedBuilder: ResourceManagerBuilder
-  ): Result<boolean> {
-    const conditions = Array.from(originalBuilder.conditions.values()).sort(Condition.compare);
-
-    const errors = new MessageAggregator();
-    for (const condition of conditions) {
-      const looseDecl = condition.toLooseConditionDecl();
-      normalizedBuilder.addCondition(looseDecl).aggregateError(errors);
-    }
-
-    return errors.returnOrReport(succeed(true));
-  }
-
-  /**
-   * Normalizes all condition sets from the original builder by adding them to the
-   * normalized builder in sorted order using loose condition set declarations.
-   *
-   * @param originalBuilder - The source ResourceManagerBuilder
-   * @param normalizedBuilder - The target normalized ResourceManagerBuilder
-   * @returns Success if all condition sets were normalized successfully, Failure otherwise
-   * @internal
-   */
-  private static _normalizeConditionSets(
-    originalBuilder: ResourceManagerBuilder,
-    normalizedBuilder: ResourceManagerBuilder
-  ): Result<boolean> {
-    const conditionSets = Array.from(originalBuilder.conditionSets.values()).sort(ConditionSet.compare);
-
-    const errors = new MessageAggregator();
-    for (const conditionSet of conditionSets) {
-      const conditions = conditionSet.toConditionSetArrayDecl();
-      normalizedBuilder.addConditionSet(conditions).aggregateError(errors);
-    }
-
-    return errors.returnOrReport(succeed(true));
-  }
-
-  /**
-   * Normalizes all candidates by sorting them first by resource ID, then by condition set.
-   *
-   * @param originalBuilder - The source ResourceManagerBuilder
-   * @param normalizedBuilder - The target normalized ResourceManagerBuilder
-   * @returns Success if all candidates were normalized successfully, Failure otherwise
-   * @internal
-   */
-  private static _normalizeCandidates(
-    originalBuilder: ResourceManagerBuilder,
-    normalizedBuilder: ResourceManagerBuilder
-  ): Result<boolean> {
-    const candidates = Array.from(originalBuilder.getAllCandidates()).sort((c1, c2) => {
-      const idCompare = c1.id.localeCompare(c2.id);
-      return idCompare !== 0 ? idCompare : ResourceCandidate.compare(c1, c2);
-    });
-
-    const errors = new MessageAggregator();
-    for (const candidate of candidates) {
-      const decl = candidate.toLooseResourceCandidateDecl();
-      normalizedBuilder.addLooseCandidate(decl).aggregateError(errors);
-    }
-
-    return errors.returnOrReport(succeed(true));
-  }
-
-  /**
-   * Adds normalized resources to the target builder by first normalizing conditions,
-   * then condition sets, then candidates.
-   *
-   * @param originalBuilder - The source ResourceManagerBuilder
-   * @param normalizedBuilder - The target normalized ResourceManagerBuilder
-   * @returns Success if all resources were added successfully, Failure otherwise
-   * @internal
-   */
-  private static _addNormalizedResources(
-    originalBuilder: ResourceManagerBuilder,
-    normalizedBuilder: ResourceManagerBuilder
-  ): Result<boolean> {
-    return BundleNormalizer._normalizeConditions(originalBuilder, normalizedBuilder)
-      .onSuccess(() => BundleNormalizer._normalizeConditionSets(originalBuilder, normalizedBuilder))
-      .onSuccess(() => BundleNormalizer._normalizeCandidates(originalBuilder, normalizedBuilder));
-  }
-}

package/src/packlets/bundle/bundleUtils.ts

@@ -1,142 +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 { Result, succeed, fail } from '@fgv/ts-utils';
-import { SystemConfiguration } from '../config';
-import { Compiled as ResourceJsonCompiled } from '../resource-json';
-import { IBundleMetadata } from './model';
-import { bundle as bundleConverter } from './convert';
-
-/**
- * Components extracted from a bundle for reuse in different contexts.
- * @public
- */
-export interface IBundleComponents {
-  /**
-   * The system configuration from the bundle.
-   */
-  systemConfiguration: SystemConfiguration;
-
-  /**
-   * The compiled resource collection from the bundle.
-   */
-  compiledCollection: ResourceJsonCompiled.ICompiledResourceCollection;
-
-  /**
-   * The bundle metadata including build information.
-   */
-  metadata: IBundleMetadata;
-}
-
-/**
- * Utility functions for working with resource bundles.
- * Provides reusable logic for bundle detection, parsing, and component extraction.
- * @public
- */
-export class BundleUtils {
-  /**
-   * Checks if the given object appears to be a bundle file by examining its structure.
-   * This is a lightweight check that doesn't perform full validation.
-   * @param data - The data to check
-   * @returns True if the data appears to be a bundle structure
-   * @public
-   */
-  public static isBundleFile(data: unknown): boolean {
-    return bundleConverter.convert(data).isSuccess();
-  }
-
-  /**
-   * Extracts and validates components from a bundle for reuse.
-   * Performs full validation of the bundle structure and creates typed components.
-   * @param bundleData - The raw bundle data to extract components from
-   * @returns Success with bundle components if valid, Failure with error message otherwise
-   * @public
-   */
-  public static extractBundleComponents(bundleData: unknown): Result<IBundleComponents> {
-    return bundleConverter
-      .convert(bundleData)
-      .withErrorFormat((err) => `Invalid bundle structure: ${err}`)
-      .onSuccess((bundle) => {
-        return SystemConfiguration.create(bundle.config)
-          .withErrorFormat((err) => `Invalid system configuration in bundle: ${err}`)
-          .onSuccess((systemConfiguration) => {
-            return succeed({
-              systemConfiguration,
-              compiledCollection: bundle.compiledCollection,
-              metadata: bundle.metadata
-            });
-          });
-      });
-  }
-
-  /**
-   * Extracts just the metadata from potential bundle data without full validation.
-   * Useful for displaying bundle information without processing the entire bundle.
-   * @param data - The data to extract metadata from
-   * @returns Success with metadata if found and valid, Failure otherwise
-   * @public
-   */
-  public static extractBundleMetadata(data: unknown): Result<IBundleMetadata> {
-    return bundleConverter
-      .convert(data)
-      .onSuccess((bundle) => {
-        return succeed(bundle.metadata);
-      })
-      .withErrorFormat((err) => {
-        return `Not a bundle file: ${err}`;
-      });
-  }
-
-  /**
-   * Parses bundle data from a JSON string.
-   * Convenience method that combines JSON parsing with bundle component extraction.
-   * @param jsonString - The JSON string containing bundle data
-   * @returns Success with bundle components if valid, Failure with error message otherwise
-   * @public
-   */
-  public static parseBundleFromJson(jsonString: string): Result<IBundleComponents> {
-    try {
-      const data = JSON.parse(jsonString);
-      return BundleUtils.extractBundleComponents(data);
-    } catch (error) {
-      /* c8 ignore next 1 - defense in depth */
-      return fail(`Failed to parse JSON: ${error instanceof Error ? error.message : String(error)}`);
-    }
-  }
-
-  /**
-   * Checks if a file name suggests it might be a bundle file.
-   * This is a heuristic check based on file naming conventions.
-   * @param fileName - The file name to check
-   * @returns True if the file name suggests a bundle file
-   * @public
-   */
-  public static isBundleFileName(fileName: string): boolean {
-    const lowerName = fileName.toLowerCase();
-    return (
-      lowerName.endsWith('.bundle.json') ||
-      lowerName.endsWith('-bundle.json') ||
-      lowerName.endsWith('_bundle.json') ||
-      (lowerName.includes('bundle') && lowerName.endsWith('.json'))
-    );
-  }
-}

package/src/packlets/bundle/convert.ts

@@ -1,87 +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 { Converter, Converters } from '@fgv/ts-utils';
-import { Converters as JsonConverters } from '@fgv/ts-json-base';
-import { Convert as ConfigConvert } from '../config';
-import { Compiled as ResourceJsonCompiled } from '../resource-json';
-import { IBundleMetadata, IBundleExportMetadata, IBundle, IBundleCreateParams } from './model';
-
-/**
- * `Converter` for a {@link Bundle.IBundleMetadata | bundle metadata} object.
- * @public
- */
-export const bundleMetadata: Converter<IBundleMetadata> = Converters.strictObject<IBundleMetadata>({
-  dateBuilt: Converters.string,
-  checksum: Converters.string,
-  version: Converters.string.optional(),
-  description: Converters.string.optional()
-});
-
-/**
- * `Converter` for {@link Bundle.IBundleExportMetadata | bundle export metadata}.
- * @public
- */
-export const bundleExportMetadata: Converter<IBundleExportMetadata> =
-  Converters.strictObject<IBundleExportMetadata>({
-    exportedAt: Converters.string,
-    exportedFrom: Converters.string,
-    type: Converters.string,
-    filterContext: JsonConverters.jsonObject.optional()
-  });
-
-/**
- * `Converter` for a {@link Bundle.IBundle | bundle} object.
- * @public
- */
-export const bundle: Converter<IBundle> = Converters.strictObject<IBundle>({
-  metadata: bundleMetadata,
-  config: ConfigConvert.systemConfiguration,
-  compiledCollection: ResourceJsonCompiled.Convert.compiledResourceCollection,
-  exportMetadata: bundleExportMetadata.optional()
-});
-
-/**
- * `Converter` for {@link Bundle.IBundleCreateParams | bundle creation parameters}.
- * @public
- */
-export const bundleCreateParams: Converter<IBundleCreateParams> =
-  Converters.strictObject<IBundleCreateParams>({
-    version: Converters.string.optional(),
-    description: Converters.string.optional(),
-    dateBuilt: Converters.string.optional()
-  });
-
-/**
- * Lightweight converter for bundle structure validation without full processing.
- * Useful for detecting bundle files without the overhead of full validation.
- * @public
- */
-export const bundleStructure: Converter<{
-  metadata: IBundleMetadata;
-  config: unknown;
-  compiledCollection: unknown;
-}> = Converters.strictObject({
-  metadata: bundleMetadata,
-  config: JsonConverters.jsonValue,
-  compiledCollection: JsonConverters.jsonValue
-});

package/src/packlets/bundle/index.ts

@@ -1,52 +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.
- */
-
-/**
- * Bundle packlet providing functionality for creating and loading resource bundles.
- *
- * Resource bundles encapsulate compiled resources, configuration, and metadata with
- * integrity verification. They provide a portable way to distribute pre-compiled
- * resource collections.
- *
- * @packageDocumentation
- */
-
-import * as Model from './model';
-import * as Convert from './convert';
-
-// Model interfaces
-export type { IBundleMetadata, IBundleExportMetadata, IBundle, IBundleCreateParams } from './model';
-
-// Builder and loader classes
-export { BundleBuilder } from './bundleBuilder';
-export { BundleLoader } from './bundleLoader';
-export type { IBundleLoaderCreateParams } from './bundleLoader';
-
-// Utilities
-export { BundleUtils } from './bundleUtils';
-export type { IBundleComponents } from './bundleUtils';
-
-export { Model, Convert };
-
-// Internal utilities (not part of public API)
-/** @internal */
-export { BundleNormalizer } from './bundleNormalizer';

package/src/packlets/bundle/model.ts

@@ -1,138 +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 { Hash } from '@fgv/ts-utils';
-import { Model as ConfigModel } from '../config';
-import { Compiled as ResourceJsonCompiled } from '../resource-json';
-
-/**
- * Metadata for a resource bundle, including build information and integrity verification.
- * @public
- */
-export interface IBundleMetadata {
-  /**
-   * ISO timestamp indicating when the bundle was built.
-   */
-  dateBuilt: string;
-
-  /**
-   * SHA-256 checksum of the serialized compiled resource collection for integrity verification.
-   */
-  checksum: string;
-
-  /**
-   * Optional version identifier for the bundle.
-   */
-  version?: string;
-
-  /**
-   * Optional human-readable description of the bundle.
-   */
-  description?: string;
-}
-
-/**
- * Optional export metadata for tracking bundle export information.
- * @public
- */
-export interface IBundleExportMetadata {
-  /**
-   * ISO timestamp indicating when the bundle was exported.
-   */
-  exportedAt: string;
-
-  /**
-   * Tool or application that exported the bundle.
-   */
-  exportedFrom: string;
-
-  /**
-   * Type of bundle export (e.g., 'ts-res-bundle', 'ts-res-bundle-filtered').
-   */
-  type: string;
-
-  /**
-   * Optional filter context if the bundle represents filtered data.
-   */
-  filterContext?: Record<string, unknown>;
-}
-
-/**
- * A complete resource bundle that encapsulates built resources, configuration, and metadata.
- * Bundles provide a portable, integrity-verified way to distribute pre-compiled resource collections.
- * @public
- */
-export interface IBundle {
-  /**
-   * Metadata about the bundle including build date and integrity checksum.
-   */
-  metadata: IBundleMetadata;
-
-  /**
-   * The system configuration that was used to build the resources in this bundle.
-   */
-  config: ConfigModel.ISystemConfiguration;
-
-  /**
-   * The compiled resource collection containing all resources, conditions, and decisions.
-   */
-  compiledCollection: ResourceJsonCompiled.ICompiledResourceCollection;
-
-  /**
-   * Optional export metadata for tracking when and how the bundle was exported.
-   */
-  exportMetadata?: IBundleExportMetadata;
-}
-
-/**
- * Optional parameters for bundle creation.
- * @public
- */
-export interface IBundleCreateParams {
-  /**
-   * Optional version identifier to include in the bundle metadata.
-   */
-  version?: string;
-
-  /**
-   * Optional description to include in the bundle metadata.
-   */
-  description?: string;
-
-  /**
-   * Optional custom build date. If not provided, the current date will be used.
-   */
-  dateBuilt?: string;
-
-  /**
-   * Optional hash normalizer for generating checksums. If not provided,
-   * a CRC32 normalizer will be used for browser compatibility.
-   */
-  hashNormalizer?: Hash.HashingNormalizer;
-
-  /**
-   * Whether to normalize the ResourceManagerBuilder before bundle creation.
-   * When true, the builder is reconstructed in canonical order to ensure
-   * order-independent checksums. Defaults to false for Phase 1 compatibility.
-   */
-  normalize?: boolean;
-}