@fgv/ts-res 5.0.0-22 → 5.0.0-24

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;
-}

package/src/packlets/common/conditions.ts

@@ -1,226 +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 { Brand } from '@fgv/ts-utils';
-
-/**
- * Branded string representing a validated qualifier name.
- * @public
- */
-export type QualifierName = Brand<string, 'QualifierName'>;
-
-/**
- * Branded number representing a validated qualifier index.
- * @public
- */
-export type QualifierIndex = Brand<number, 'QualifierIndex'>;
-
-/**
- * Branded string representing a validated qualifier type name.
- * @public
- */
-export type QualifierTypeName = Brand<string, 'QualifierTypeName'>;
-
-/**
- * Branded number representing a validated qualifier type index.
- * @public
- */
-export type QualifierTypeIndex = Brand<number, 'QualifierTypeIndex'>;
-
-/**
- * Branded type for a validated qualifier condition value - i.e. a value
- * that has been determined to be valid for use in a condition attached
- * to some resource.
- *
- * @example
- * For a language qualifier type, it is likely that a single language
- * tag can be used for either a condition or a context value. However,
- * a list of languages would likely only be valid as a context value.
- * @public
- */
-export type QualifierConditionValue = Brand<string, 'QualifierConditionValue'>;
-
-/**
- * Branded type for a validated qualifier context value - i.e. a value
- * that has been determined to be valid for use in some runtime context.
- * @example
- * For a language qualifier type, it is likely that a single language
- * tag can be used for either a condition or a context value. However,
- * a list of languages would likely only be valid as a context value.
- * @public
- */
-export type QualifierContextValue = Brand<string, 'QualifierContextValue'>;
-
-/**
- * Branded number representing a score in the range 0.0 (no match) .. 1.0 (perfect match)
- * which results from evaluating some condition.
- * @public
- */
-export type QualifierMatchScore = Brand<number, 'QualifierMatchScore'>;
-
-/**
- * {@link QualifierMatchScore | Match score} indicating no match.
- * @public
- */
-export const NoMatch: QualifierMatchScore = 0.0 as QualifierMatchScore;
-
-/**
- * {@link QualifierMatchScore | Match score} indicating a perfect match.
- * @public
- */
-export const PerfectMatch: QualifierMatchScore = 1.0 as QualifierMatchScore;
-
-/**
- * Branded number representing a validated condition priority.
- * @public
- */
-export type ConditionPriority = Brand<number, 'ConditionPriority'>;
-
-/**
- * Minimum valid priority for a condition.
- * @public
- */
-export const MinConditionPriority: ConditionPriority = 0 as ConditionPriority;
-
-/**
- * Maximum valid priority for a condition.
- * @public
- */
-export const MaxConditionPriority: ConditionPriority = 1000 as ConditionPriority;
-
-/**
- * Condition operators for use in conditions.
- * @public
- */
-export type ConditionOperator = 'always' | 'never' | 'matches';
-
-/**
- * Array of all valid condition operators.
- * @public
- */
-export const allConditionOperators: ConditionOperator[] = ['always', 'never', 'matches'];
-
-/**
- * Branded number representing a validated condition index.
- * @public
- */
-export type ConditionIndex = Brand<number, 'ConditionIndex'>;
-
-/**
- * A branded string representing a validated condition key.  A condition key is a
- * string value which fully describes the condition apart from index.  The condition
- * key can be used to quickly determine if two conditions are identical apart from
- * index, or for inspection.
- * @public
- */
-export type ConditionKey = Brand<string, 'ConditionKey'>;
-
-/**
- * A string representing a validated condition token.  Condition tokens are
- * typically extracted from the name of some resource (e.g. file or folder)
- * being imported.   A condition token has the form `<qualifierName>=<value>`
- * or `<value>`.
- * @public
- */
-export type ConditionToken = Brand<string, 'ConditionToken'>;
-
-/**
- * Branded number representing a validated condition set index.
- * @public
- */
-export type ConditionSetIndex = Brand<number, 'ConditionSetIndex'>;
-
-/**
- * Branded string representing a validated condition set key. A condition set key
- * is a string value which fully describes the condition set apart from index. The
- * condition set key can be used to quickly determine if two condition sets are
- * identical apart from index, or for inspection.
- * @public
- */
-export type ConditionSetKey = Brand<string, 'ConditionSetKey'>;
-
-/**
- * A string representing a validated condition set token.  Condition set tokens are
- * typically extracted from the name of some resource (e.g. file or folder) being
- * imported.  A condition set token is a comma-separated list of one or more
- * {@link ConditionToken | condition tokens}, where a condition token has either
- * the form `<qualifierName>=<value>` or `<value>`.
- * @public
- */
-export type ConditionSetToken = Brand<string, 'ConditionSetToken'>;
-
-/**
- * Branded string representing a hash value for a condition set. The hash value
- * is an 8-character string derived from the crc32 hash of the condition set key
- * and is used to quickly and compactly identify a condition set or compare for
- * equality.
- * @public
- */
-export type ConditionSetHash = Brand<string, 'ConditionSetHash'>;
-
-/**
- * Branded string representing a validated decision key. A decision key is a string
- * value which fully describes the decision apart from index. The decision key can
- * be used to quickly determine if two decisions are identical apart from index.
- * @public
- */
-export type DecisionKey = Brand<string, 'DecisionKey'>;
-
-/**
- * Branded number representing a validated decision index.
- * @public
- */
-export type DecisionIndex = Brand<number, 'DecisionIndex'>;
-
-/**
- * A string representing a validated context qualifier token. Context qualifier tokens are used
- * for filtering resources by context criteria. A context qualifier token has the form
- * `<qualifierName>=<value>` or `<value>`.
- * @public
- */
-export type ContextQualifierToken = Brand<string, 'ContextQualifierToken'>;
-
-/**
- * A string representing a validated context token. Context tokens are
- * pipe-separated lists of one or more context qualifier tokens. Uses "|" as separator
- * to avoid conflicts with comma-separated values within context values.
- * Example: "language=en-US,de-DE|territory=US|role=admin"
- * @public
- */
-export type ContextToken = Brand<string, 'ContextToken'>;
-
-/**
- * A string representing a single qualifier default value assignment.
- * Format: "qualifierName=defaultValue" or "qualifierName=" (to remove default)
- * Example: "language=en-US,en-CA" or "territory=US"
- * @public
- */
-export type QualifierDefaultValueToken = Brand<string, 'QualifierDefaultValueToken'>;
-
-/**
- * A string representing a validated qualifier default values token. Default value tokens are
- * pipe-separated lists of one or more qualifier default value tokens. Uses "|" as separator
- * to avoid conflicts with comma-separated values within default values.
- * Example: "language=en-US,en-CA|territory=US|device=desktop,tablet"
- * @public
- */
-export type QualifierDefaultValuesToken = Brand<string, 'QualifierDefaultValuesToken'>;