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

package/lib/test/unit/resource-types/testDerivedResourceType.js

@@ -0,0 +1,113 @@
+"use strict";
+/*
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestDerivedResourceType = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const common_1 = require("../../../packlets/common");
+// eslint-disable-next-line @rushstack/packlets/mechanics
+const resourceType_1 = require("../../../packlets/resource-types/resourceType");
+/**
+ * A derived resource type for testing that demonstrates:
+ * 1. Custom validation logic
+ * 2. Using a resource resolver to look up template values
+ * 3. Type-specific defaults and error handling
+ */
+class TestDerivedResourceType extends resourceType_1.ResourceType {
+    constructor(key, index, template, templateResourceId) {
+        super(key, index, template);
+        this.systemTypeName = common_1.Convert.resourceTypeName
+            .convert('test-derived')
+            .orThrow();
+        this._templateResourceId = templateResourceId;
+    }
+    /**
+     * Factory method to create a new TestDerivedResourceType instance.
+     */
+    static create(params) {
+        var _a;
+        return common_1.Convert.resourceTypeName.convert((_a = params === null || params === void 0 ? void 0 : params.key) !== null && _a !== void 0 ? _a : 'test-derived').onSuccess((key) => {
+            return (0, ts_utils_1.captureResult)(() => new TestDerivedResourceType(key, params === null || params === void 0 ? void 0 : params.index, params === null || params === void 0 ? void 0 : params.template, params === null || params === void 0 ? void 0 : params.templateResourceId));
+        });
+    }
+    /**
+     * Validates a resource candidate declaration with custom logic.
+     */
+    validateDeclaration(props) {
+        // Custom validation: merge method must be 'replace' for full candidates
+        if (props.completeness === 'full' && props.mergeMethod !== 'replace') {
+            return (0, ts_utils_1.fail)(`${this.key}: Full candidates must use 'replace' merge method, got '${props.mergeMethod}'`);
+        }
+        return this.validate(props.json, props.completeness);
+    }
+    validate(json, completeness) {
+        if (typeof json !== 'object' || json === null || Array.isArray(json)) {
+            return (0, ts_utils_1.fail)(`${this.key}: Expected JSON object, got ${typeof json}`);
+        }
+        const obj = json;
+        // Validate required title field for full resources
+        if (completeness === 'full' && (typeof obj.title !== 'string' || !obj.title.trim())) {
+            return (0, ts_utils_1.fail)(`${this.key}: 'title' field is required and must be a non-empty string`);
+        }
+        // Validate optional description
+        if (obj.description !== undefined && typeof obj.description !== 'string') {
+            return (0, ts_utils_1.fail)(`${this.key}: 'description' field must be a string if provided`);
+        }
+        // Validate optional metadata
+        if (obj.metadata !== undefined) {
+            if (typeof obj.metadata !== 'object' || obj.metadata === null || Array.isArray(obj.metadata)) {
+                return (0, ts_utils_1.fail)(`${this.key}: 'metadata' field must be an object if provided`);
+            }
+        }
+        const result = Object.assign(Object.assign(Object.assign({}, (obj.title && { title: obj.title })), (obj.description && { description: obj.description })), (obj.metadata && { metadata: obj.metadata }));
+        return (0, ts_utils_1.succeed)(result);
+    }
+    /**
+     * Override to demonstrate looking up template values from another resource.
+     */
+    getDefaultTemplateCandidate(json, conditions, resolver) {
+        // If a template resource ID is configured and resolver is available, try to resolve it
+        if (this._templateResourceId && resolver && !json) {
+            return resolver
+                .resolveComposedResourceValue(this._templateResourceId)
+                .onFailure((error) => (0, ts_utils_1.fail)(`${this.key}: Failed to resolve template resource '${this._templateResourceId}': ${error}`))
+                .onSuccess((resolvedValue) => {
+                // Use the resolved value as our JSON template
+                return super.getDefaultTemplateCandidate(resolvedValue, conditions, resolver);
+            });
+        }
+        // Use provided JSON or fall back to base implementation
+        return super.getDefaultTemplateCandidate(json, conditions, resolver);
+    }
+    /**
+     * Override createTemplate to add additional validation for the derived type.
+     */
+    createTemplate(resourceId, init, conditions, resolver) {
+        // Additional validation: warn if trying to use resolver functionality without a resolver
+        if (this._templateResourceId && !resolver) {
+            return (0, ts_utils_1.fail)(`${this.key}: Template resource ID '${this._templateResourceId}' is configured but no resolver provided`);
+        }
+        return super.createTemplate(resourceId, init, conditions, resolver);
+    }
+}
+exports.TestDerivedResourceType = TestDerivedResourceType;
+//# sourceMappingURL=testDerivedResourceType.js.map

package/lib/test/unit/resources/candidateValue.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=candidateValue.test.d.ts.map

package/lib/test/unit/resources/candidateValueCollector.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=candidateValueCollector.test.d.ts.map

package/lib/test/unit/runtime/resourceResolver.coverage.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=resourceResolver.coverage.test.d.ts.map

package/lib/test/unit/runtime/resourceResolver.newFeatures.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=resourceResolver.newFeatures.test.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-res",
-  "version": "5.0.0-21",
+  "version": "5.0.0-23",
   "description": "Multi-dimensional Resource Runtime",
   "main": "lib/index.js",
   "types": "dist/ts-res.d.ts",
@@ -44,16 +44,16 @@
     "@rushstack/heft-node-rig": "~2.9.3",
     "@types/heft-jest": "1.0.6",
     "eslint-plugin-tsdoc": "~0.4.0",
-    "@fgv/ts-utils-jest": "5.0.0-21",
-    "@fgv/ts-extras": "5.0.0-21"
+    "@fgv/ts-utils-jest": "5.0.0-23",
+    "@fgv/ts-extras": "5.0.0-23"
   },
   "dependencies": {
     "luxon": "^3.7.1",
     "fflate": "~0.8.2",
-    "@fgv/ts-utils": "5.0.0-21",
-    "@fgv/ts-json-base": "5.0.0-21",
-    "@fgv/ts-bcp47": "5.0.0-21",
-    "@fgv/ts-json": "5.0.0-21"
+    "@fgv/ts-utils": "5.0.0-23",
+    "@fgv/ts-json-base": "5.0.0-23",
+    "@fgv/ts-json": "5.0.0-23",
+    "@fgv/ts-bcp47": "5.0.0-23"
   },
   "scripts": {
     "build": "heft build --clean",

package/src/index.ts

@@ -1,75 +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 Bundle from './packlets/bundle';
-import * as QualifierTypes from './packlets/qualifier-types';
-import * as Qualifiers from './packlets/qualifiers';
-import * as Conditions from './packlets/conditions';
-import * as Config from './packlets/config';
-import * as Context from './packlets/context';
-import * as Decisions from './packlets/decisions';
-import * as ResourceJson from './packlets/resource-json';
-import * as Resources from './packlets/resources';
-import * as ResourceTypes from './packlets/resource-types';
-import * as Import from './packlets/import';
-import * as Runtime from './packlets/runtime';
-import * as ZipArchive from './packlets/zip-archive';
-
-export * from './packlets/common';
-
-import { Condition, ConditionSet } from './packlets/conditions';
-import { Decision } from './packlets/decisions';
-import { QualifierType } from './packlets/qualifier-types';
-import { Qualifier } from './packlets/qualifiers';
-import { ResourceType } from './packlets/resource-types';
-import { Resource, ResourceCandidate, ResourceManagerBuilder } from './packlets/resources';
-import { IResourceManager, ResourceResolver } from './packlets/runtime';
-import { BundleBuilder, BundleLoader } from './packlets/bundle';
-
-export {
-  Bundle,
-  BundleBuilder,
-  BundleLoader,
-  Condition,
-  Conditions,
-  ConditionSet,
-  Config,
-  Context,
-  Decision,
-  Decisions,
-  Import,
-  IResourceManager,
-  Qualifier,
-  QualifierType,
-  QualifierTypes,
-  Qualifiers,
-  Resource,
-  ResourceCandidate,
-  ResourceJson,
-  ResourceResolver,
-  ResourceManagerBuilder,
-  ResourceType,
-  ResourceTypes,
-  Resources,
-  Runtime,
-  ZipArchive
-};

package/src/packlets/bundle/bundleBuilder.ts

@@ -1,159 +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, Hash } from '@fgv/ts-utils';
-import { ResourceManagerBuilder } from '../resources';
-import {
-  SystemConfiguration,
-  PredefinedSystemConfiguration,
-  getPredefinedSystemConfiguration
-} from '../config';
-import { IBundle, IBundleCreateParams, IBundleMetadata } from './model';
-import { BundleNormalizer } from './bundleNormalizer';
-
-/**
- * Builder for creating resource bundles from a ResourceManagerBuilder.
- * Handles the compilation, configuration extraction, and integrity verification
- * needed to create a complete, portable bundle.
- * @public
- */
-export class BundleBuilder {
-  /**
-   * Creates a resource bundle from a ResourceManagerBuilder.
-   * @param builder - The ResourceManagerBuilder containing the resources to bundle
-   * @param systemConfig - The SystemConfiguration used to create the builder
-   * @param params - Optional parameters for bundle creation
-   * @returns Success with the created bundle if successful, Failure with error message otherwise
-   * @public
-   */
-  public static create(
-    builder: ResourceManagerBuilder,
-    systemConfig: SystemConfiguration,
-    params?: IBundleCreateParams
-  ): Result<IBundle> {
-    /* c8 ignore next 2 - defense in depth */
-    params = params ?? {};
-    const hashNormalizer = params.hashNormalizer ?? new Hash.Crc32Normalizer();
-
-    const builderToUse =
-      params.normalize === true
-        ? BundleNormalizer.normalize(builder, systemConfig)
-        : /* c8 ignore next 1 - is tested but coverage gets confused */
-          succeed(builder);
-
-    return builderToUse.onSuccess((targetBuilder) => {
-      return systemConfig.getConfig().onSuccess((config) => {
-        return targetBuilder.getCompiledResourceCollection().onSuccess((compiledCollection) => {
-          return BundleBuilder._generateChecksum(compiledCollection, hashNormalizer).onSuccess((checksum) => {
-            /* c8 ignore next 1 - defense in depth */
-            const dateBuilt = params.dateBuilt ?? new Date().toISOString();
-
-            const metadata: IBundleMetadata = {
-              dateBuilt,
-              checksum,
-              version: params.version,
-              description: params.description
-            };
-
-            const bundle: IBundle = {
-              metadata,
-              config,
-              compiledCollection
-            };
-
-            return succeed(bundle);
-          });
-        });
-      });
-    });
-  }
-
-  /**
-   * Creates a resource bundle from a ResourceManagerBuilder using a predefined system configuration.
-   * This is a convenience method for the common case of using predefined configurations.
-   * @param builder - The ResourceManagerBuilder containing the resources to bundle
-   * @param configName - The name of the predefined system configuration used
-   * @param params - Optional parameters for bundle creation
-   * @returns Success with the created bundle if successful, Failure with error message otherwise
-   * @public
-   */
-  public static createFromPredefined(
-    builder: ResourceManagerBuilder,
-    configName: PredefinedSystemConfiguration,
-    params?: IBundleCreateParams
-  ): Result<IBundle> {
-    /* c8 ignore next 1 */
-    params = params ?? {};
-    const hashNormalizer = params.hashNormalizer ?? new Hash.Crc32Normalizer();
-
-    // Determine which builder to use based on normalization setting
-    const builderToUse = params.normalize
-      ? BundleNormalizer.normalizeFromPredefined(builder, configName)
-      : succeed(builder);
-
-    return builderToUse.onSuccess((targetBuilder) => {
-      return getPredefinedSystemConfiguration(configName).onSuccess((systemConfig) => {
-        return systemConfig.getConfig().onSuccess((config) => {
-          return targetBuilder.getCompiledResourceCollection().onSuccess((compiledCollection) => {
-            return BundleBuilder._generateChecksum(compiledCollection, hashNormalizer).onSuccess(
-              (checksum) => {
-                /* c8 ignore next 1 - defense in depth */
-                const dateBuilt = params.dateBuilt ?? new Date().toISOString();
-
-                const metadata: IBundleMetadata = {
-                  dateBuilt,
-                  checksum,
-                  version: params.version,
-                  /* c8 ignore next 1 - defense in depth */
-                  description: params?.description
-                };
-
-                const bundle: IBundle = {
-                  metadata,
-                  config,
-                  compiledCollection
-                };
-
-                return succeed(bundle);
-              }
-            );
-          });
-        });
-      });
-    });
-  }
-
-  /**
-   * Generates a hash checksum for the compiled resource collection.
-   * The checksum is calculated using the provided hash normalizer.
-   * @param compiledCollection - The compiled resource collection to generate checksum for
-   * @param hashNormalizer - The hash normalizer to use for checksum generation
-   * @returns Success with the checksum string if successful, Failure otherwise
-   * @internal
-   */
-  private static _generateChecksum(
-    compiledCollection: unknown,
-    hashNormalizer: Hash.HashingNormalizer
-  ): Result<string> {
-    return hashNormalizer.computeHash(compiledCollection);
-  }
-}

package/src/packlets/bundle/bundleLoader.ts

@@ -1,157 +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, Collections, Hash } from '@fgv/ts-utils';
-import { CompiledResourceCollection, IResourceManager } from '../runtime';
-import { SystemConfiguration } from '../config';
-import { ResourceType } from '../resource-types';
-import { QualifierType } from '../qualifier-types';
-import { IBundle } from './model';
-
-/**
- * Parameters for creating a BundleLoader.
- * @public
- */
-export interface IBundleLoaderCreateParams {
-  /**
-   * The bundle to load.
-   */
-  bundle: IBundle;
-
-  /**
-   * Whether to skip checksum verification during loading.
-   * Default is false - checksum verification is performed.
-   */
-  skipChecksumVerification?: boolean;
-
-  /**
-   * Optional hash normalizer for verifying checksums. If not provided,
-   * a CRC32 normalizer will be used for browser compatibility.
-   * Must match the normalizer used during bundle creation.
-   */
-  hashNormalizer?: Hash.HashingNormalizer;
-}
-
-/**
- * Loader for creating an IResourceManager from a resource bundle.
- * Handles integrity verification and reconstruction of the runtime resource manager.
- * @public
- */
-export class BundleLoader {
-  /**
-   * Creates an IResourceManager from a resource bundle.
-   * @param params - Parameters for bundle loading including the bundle and options
-   * @returns Success with the IResourceManager if successful, Failure with error message otherwise
-   * @public
-   */
-  public static createManagerFromBundle(params: IBundleLoaderCreateParams): Result<IResourceManager> {
-    /* c8 ignore next 1 - defense in depth */
-    const hashNormalizer = params.hashNormalizer ?? new Hash.Crc32Normalizer();
-
-    return BundleLoader._verifyBundleIntegrity(
-      params.bundle,
-      params.skipChecksumVerification ?? false,
-      hashNormalizer
-    ).onSuccess(() => {
-      return BundleLoader._createSystemConfiguration(params.bundle).onSuccess((systemConfig) => {
-        return BundleLoader._createCompiledResourceCollection(
-          params.bundle,
-          systemConfig.qualifierTypes,
-          systemConfig.resourceTypes
-        );
-      });
-    });
-  }
-
-  /**
-   * Verifies the integrity of a bundle by checking its checksum.
-   * @param bundle - The bundle to verify
-   * @param skipVerification - Whether to skip verification
-   * @param hashNormalizer - The hash normalizer to use for verification
-   * @returns Success if verification passes or is skipped, Failure otherwise
-   * @internal
-   */
-  private static _verifyBundleIntegrity(
-    bundle: IBundle,
-    skipVerification: boolean,
-    hashNormalizer: Hash.HashingNormalizer
-  ): Result<boolean> {
-    if (skipVerification) {
-      return succeed(true);
-    }
-
-    return BundleLoader._generateChecksum(bundle.compiledCollection, hashNormalizer).onSuccess(
-      (calculatedChecksum) => {
-        if (calculatedChecksum !== bundle.metadata.checksum) {
-          return fail(
-            `Bundle integrity verification failed: expected checksum ${bundle.metadata.checksum}, got ${calculatedChecksum}`
-          );
-        }
-        return succeed(true);
-      }
-    );
-  }
-
-  /**
-   * Generates a hash checksum for the compiled resource collection.
-   * @param compiledCollection - The compiled resource collection to generate checksum for
-   * @param hashNormalizer - The hash normalizer to use for checksum generation
-   * @returns Success with the checksum string if successful, Failure otherwise
-   * @internal
-   */
-  private static _generateChecksum(
-    compiledCollection: unknown,
-    hashNormalizer: Hash.HashingNormalizer
-  ): Result<string> {
-    return hashNormalizer.computeHash(compiledCollection);
-  }
-
-  /**
-   * Creates a SystemConfiguration from the bundle's configuration.
-   * @param bundle - The bundle containing the configuration
-   * @returns Success with the SystemConfiguration if successful, Failure otherwise
-   * @internal
-   */
-  private static _createSystemConfiguration(bundle: IBundle): Result<SystemConfiguration> {
-    return SystemConfiguration.create(bundle.config);
-  }
-
-  /**
-   * Creates a CompiledResourceCollection from the bundle.
-   * @param bundle - The bundle to load
-   * @param qualifierTypes - The qualifier type collector from the system configuration
-   * @param resourceTypes - The resource type collector from the system configuration
-   * @returns Success with the CompiledResourceCollection if successful, Failure otherwise
-   * @internal
-   */
-  private static _createCompiledResourceCollection(
-    bundle: IBundle,
-    qualifierTypes: Collections.IReadOnlyResultMap<string, QualifierType>,
-    resourceTypes: Collections.IReadOnlyResultMap<string, ResourceType>
-  ): Result<CompiledResourceCollection> {
-    return CompiledResourceCollection.create({
-      compiledCollection: bundle.compiledCollection,
-      qualifierTypes,
-      resourceTypes
-    });
-  }
-}