@fgv/ts-res 5.0.0-12 → 5.0.0-14

package/src/packlets/bundle/bundleUtils.ts

@@ -0,0 +1,142 @@
+/*
+ * 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

@@ -0,0 +1,87 @@
+/*
+ * 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

@@ -0,0 +1,52 @@
+/*
+ * 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

@@ -0,0 +1,138 @@
+/*
+ * 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

@@ -0,0 +1,226 @@
+/*
+ * 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'>;