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

package/src/packlets/resource-json/json.ts

@@ -1,295 +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 { JsonObject } from '@fgv/ts-json-base';
-import { ConditionOperator, ResourceValueMergeMethod } from '../common';
-
-/**
- * Non-validated loose declaration of a {@link Conditions.Condition | condition}.
- * @public
- */
-export interface ILooseConditionDecl {
-  /**
-   * The name of the {@link Qualifiers.Qualifier | qualifier} to be compared.
-   */
-  qualifierName: string;
-  /**
-   * The value to be compared.
-   */
-  value: string;
-  /**
-   * The operator to be used in the comparison.
-   * Default is 'matches'.
-   */
-  operator?: ConditionOperator;
-
-  /**
-   * The priority of the condition. Default is the default priority for the qualifier.
-   */
-  priority?: number;
-
-  /**
-   * The score to be used if the condition is used as a default.
-   */
-  scoreAsDefault?: number;
-}
-
-/**
- * Non-validated child declaration of a {@link Conditions.Condition | condition}.
- * @public
- */
-export interface IChildConditionDecl {
-  /**
-   * The value to be compared.
-   */
-  value: string;
-  /**
-   * The operator to be used in the comparison.
-   * Default is 'matches'.
-   */
-  operator?: ConditionOperator;
-
-  /**
-   * The priority of the condition. Default is the default priority for the qualifier.
-   */
-  priority?: number;
-
-  /**
-   * The score to be used if the condition is used as a default.
-   */
-  scoreAsDefault?: number;
-}
-
-/**
- * Non-validated declaration of a {@link Conditions.Condition | condition}.
- * @public
- */
-export type ConditionSetDeclAsArray = ReadonlyArray<ILooseConditionDecl>;
-
-/**
- * Non-validated declaration of a {@link Conditions.Condition | condition}.
- * @public
- */
-export type ConditionSetDeclAsRecord = Record<string, string | IChildConditionDecl>;
-
-/**
- * Non-validated declaration of a {@link Conditions.Condition | condition}.
- * @public
- */
-export type ConditionSetDecl = ConditionSetDeclAsArray | ConditionSetDeclAsRecord;
-
-/**
- * Non-validated child declaration of a {@link Resources.ResourceCandidate | resource candidate}.
- * @public
- */
-export interface IChildResourceCandidateDecl {
-  /**
-   * The JSON value of the resource.
-   */
-  readonly json: JsonObject;
-
-  /**
-   * The conditions that must be met for the resource to be selected.
-   */
-  readonly conditions?: ConditionSetDecl;
-
-  /**
-   * If true, the resource is only a partial representation of the full resource.
-   */
-  readonly isPartial?: boolean;
-
-  /**
-   * The merge method to be used when merging the resource into the existing resource.
-   * default is 'augment'.
-   */
-  readonly mergeMethod?: ResourceValueMergeMethod;
-}
-
-/**
- * Non-validated declaration of a resource candidate for import,
- * which can be either a loose or child resource candidate.
- * @public
- */
-export interface IImporterResourceCandidateDecl extends IChildResourceCandidateDecl {
-  /**
-   * The {@link ResourceId | id} of the resource.
-   */
-  readonly id?: string;
-
-  /**
-   * The name of the type of this resource.
-   */
-  readonly resourceTypeName?: string;
-}
-
-/**
- * Non-validated loose declaration of a {@link Resources.ResourceCandidate | resource candidate}.
- * @public
- */
-export interface ILooseResourceCandidateDecl extends IChildResourceCandidateDecl {
-  /**
-   * The {@link ResourceId | id} of the resource.
-   */
-  readonly id: string;
-
-  /**
-   * The JSON value of the resource.
-   */
-  readonly json: JsonObject;
-
-  /**
-   * The conditions that must be met for the resource to be selected.
-   */
-  readonly conditions?: ConditionSetDecl;
-
-  /**
-   * If true, the resource is only a partial representation of the full resource.
-   */
-  readonly isPartial?: boolean;
-
-  /**
-   * The merge method to be used when merging the resource into the existing resource.
-   * default is 'augment'.
-   */
-  readonly mergeMethod?: ResourceValueMergeMethod;
-
-  /**
-   * The type of the resource.
-   */
-  readonly resourceTypeName?: string;
-}
-
-/**
- * Non-validated child declaration of a {@link Resources.Resource | resource}.
- * @public
- */
-export interface IChildResourceDecl {
-  /**
-   * The name of the type of this resource.
-   */
-  readonly resourceTypeName: string;
-
-  /**
-   * Possible candidates for this value.
-   */
-  readonly candidates?: ReadonlyArray<IChildResourceCandidateDecl>;
-}
-
-/**
- * Non-validated loose declaration of a {@link Resources.Resource | resource}.
- * @public
- */
-export interface ILooseResourceDecl extends IChildResourceDecl {
-  /**
-   * The id of the resource.
-   */
-  readonly id: string;
-
-  /**
-   * The name of the type of this resource.
-   */
-  readonly resourceTypeName: string;
-
-  /**
-   * Possible candidates for this value.
-   */
-  readonly candidates?: ReadonlyArray<IChildResourceCandidateDecl>;
-}
-
-/**
- * Normalized non-validated declaration of a {@link Resources.Resource | resource} tree node.
- * @public
- */
-export interface IResourceTreeChildNodeDecl {
-  readonly resources?: Record<string, IChildResourceDecl>;
-  readonly children?: Record<string, IResourceTreeChildNodeDecl>;
-}
-
-/**
- * Declared context for a resource container.
- * @public
- */
-export interface IContainerContextDecl {
-  readonly baseId?: string;
-  readonly conditions?: ConditionSetDecl;
-  readonly mergeMethod?: ResourceValueMergeMethod;
-}
-
-/**
- * Normalized non-validated declaration of a {@link Resources.Resource | resource} tree root.
- * @public
- */
-export interface IResourceTreeRootDecl extends IResourceTreeChildNodeDecl {
-  readonly context?: IContainerContextDecl;
-  readonly resources?: Record<string, IChildResourceDecl>;
-  readonly children?: Record<string, IResourceTreeChildNodeDecl>;
-  readonly metadata?: JsonObject;
-}
-
-/**
- * Non-validated declaration of a collection of resources.
- * @public
- */
-export interface IResourceCollectionDecl {
-  readonly context?: IContainerContextDecl;
-  readonly candidates?: ReadonlyArray<ILooseResourceCandidateDecl>;
-  readonly resources?: ReadonlyArray<ILooseResourceDecl>;
-  readonly collections?: ReadonlyArray<IResourceCollectionDecl>;
-  readonly metadata?: JsonObject;
-}
-
-/**
- * Non-validated declaration of a resource for import,
- * which can be either a loose or child resource.
- * @public
- */
-export type IImporterResourceDecl = ILooseResourceDecl | IChildResourceDecl;
-
-/**
- * Non-validated declaration of a collection of resources for an importer.
- * @public
- */
-export interface IImporterResourceCollectionDecl {
-  readonly context?: IContainerContextDecl;
-  readonly candidates?: ReadonlyArray<IImporterResourceCandidateDecl>;
-  readonly resources?: ReadonlyArray<IImporterResourceDecl>;
-  readonly collections?: ReadonlyArray<IImporterResourceCollectionDecl>;
-  readonly metadata?: JsonObject;
-}
-
-/**
- * Type guard function to check if a resource candidate declaration is a loose resource candidate declaration.
- * @public
- */
-export function isLooseResourceCandidateDecl(
-  decl: IImporterResourceCandidateDecl
-): decl is ILooseResourceCandidateDecl {
-  return 'id' in decl;
-}
-
-/**
- * Type guard function to check if a resource declaration is a loose resource declaration.
- * @public
- */
-export function isLooseResourceDecl(decl: IImporterResourceDecl): decl is ILooseResourceDecl {
-  return 'id' in decl;
-}

package/src/packlets/resource-json/normalized.ts

@@ -1,211 +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 { JsonObject } from '@fgv/ts-json-base';
-import { ResourceValueMergeMethod } from '../common';
-import { ILooseConditionDecl } from './json';
-
-/**
- * Normalized non-validated declaration of a {@link Conditions.Condition | condition}.
- * @public
- */
-export type ConditionSetDecl = ReadonlyArray<ILooseConditionDecl>;
-
-/**
- * Normalized non-validated child declaration of a {@link Resources.ResourceCandidate | resource candidate}.
- * @public
- */
-export interface IChildResourceCandidateDecl {
-  /**
-   * The JSON value of the resource.
-   */
-  readonly json: JsonObject;
-
-  /**
-   * The conditions that must be met for the resource to be selected.
-   */
-  readonly conditions?: ConditionSetDecl;
-
-  /**
-   * If true, the resource is only a partial representation of the full resource.
-   */
-  readonly isPartial?: boolean;
-
-  /**
-   * The merge method to be used when merging the resource into the existing resource.
-   * default is 'augment'.
-   */
-  readonly mergeMethod?: ResourceValueMergeMethod;
-}
-
-/**
- * Normalized non-validated declaration of a resource candidate for import,
- * which can be either a loose or child resource candidate.
- * @public
- */
-export interface IImporterResourceCandidateDecl extends IChildResourceCandidateDecl {
-  /**
-   * The {@link ResourceId | id} of the resource.
-   */
-  readonly id?: string;
-
-  /**
-   * The name of the type of this resource.
-   */
-  readonly resourceTypeName?: string;
-}
-
-/**
- * Normalized non-validated loose declaration of a {@link Resources.ResourceCandidate | resource candidate}.
- * @public
- */
-export interface ILooseResourceCandidateDecl extends IChildResourceCandidateDecl {
-  /**
-   * The {@link ResourceId | id} of the resource.
-   */
-  readonly id: string;
-
-  /**
-   * The JSON value of the resource.
-   */
-  readonly json: JsonObject;
-
-  /**
-   * The conditions that must be met for the resource to be selected.
-   */
-  readonly conditions?: ConditionSetDecl;
-
-  /**
-   * If true, the resource is only a partial representation of the full resource.
-   */
-  readonly isPartial?: boolean;
-
-  /**
-   * The merge method to be used when merging the resource into the existing resource.
-   * default is 'augment'.
-   */
-  readonly mergeMethod?: ResourceValueMergeMethod;
-
-  /**
-   * The type of the resource.
-   */
-  readonly resourceTypeName?: string;
-}
-
-/**
- * Normalized non-validated child declaration of a {@link Resources.Resource | resource}.
- * @public
- */
-export interface IChildResourceDecl {
-  /**
-   * The name of the type of this resource.
-   */
-  readonly resourceTypeName: string;
-
-  /**
-   * Possible candidates for this value.
-   */
-  readonly candidates?: ReadonlyArray<IChildResourceCandidateDecl>;
-}
-
-/**
- * Normalized non-validated loose declaration of a {@link Resources.Resource | resource}.
- * @public
- */
-export interface ILooseResourceDecl extends IChildResourceDecl {
-  /**
-   * The id of the resource.
-   */
-  readonly id: string;
-
-  /**
-   * The name of the type of this resource.
-   */
-  readonly resourceTypeName: string;
-
-  /**
-   * Possible candidates for this value.
-   */
-  readonly candidates?: ReadonlyArray<IChildResourceCandidateDecl>;
-}
-
-/**
- * Normalized non-validated declaration of a {@link Resources.Resource | resource} tree node.
- * @public
- */
-export interface IResourceTreeChildNodeDecl {
-  readonly resources?: Record<string, IChildResourceDecl>;
-  readonly children?: Record<string, IResourceTreeChildNodeDecl>;
-}
-
-/**
- * Declared context for a resource container.
- * @public
- */
-export interface IContainerContextDecl {
-  readonly baseId?: string;
-  readonly conditions?: ConditionSetDecl;
-  readonly mergeMethod?: ResourceValueMergeMethod;
-}
-
-/**
- * Normalized non-validated declaration of a {@link Resources.Resource | resource} tree root.
- * @public
- */
-export interface IResourceTreeRootDecl extends IResourceTreeChildNodeDecl {
-  readonly context?: IContainerContextDecl;
-  readonly resources?: Record<string, IChildResourceDecl>;
-  readonly children?: Record<string, IResourceTreeChildNodeDecl>;
-  readonly metadata?: JsonObject;
-}
-
-/**
- * Normalized non-validated declaration of a collection of resources.
- * @public
- */
-export interface IResourceCollectionDecl {
-  readonly context?: IContainerContextDecl;
-  readonly candidates?: ReadonlyArray<ILooseResourceCandidateDecl>;
-  readonly resources?: ReadonlyArray<ILooseResourceDecl>;
-  readonly collections?: ReadonlyArray<IResourceCollectionDecl>;
-  readonly metadata?: JsonObject;
-}
-
-/**
- * Normalized non-validated declaration of a resource for import,
- * which can be either a loose or child resource.
- * @public
- */
-export type IImporterResourceDecl = ILooseResourceDecl | IChildResourceDecl;
-
-/**
- * Normalized non-validated declaration of a collection of resources for importers.
- * This allows for a mix of loose and child resource declarations.
- * @public
- */
-export interface IImporterResourceCollectionDecl {
-  readonly context?: IContainerContextDecl;
-  readonly candidates?: ReadonlyArray<IImporterResourceCandidateDecl>;
-  readonly resources?: ReadonlyArray<IImporterResourceDecl>;
-  readonly collections?: ReadonlyArray<IImporterResourceCollectionDecl>;
-  readonly metadata?: JsonObject;
-}

package/src/packlets/resource-json/resourceDeclCollection.ts

@@ -1,117 +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 { captureResult, mapResults, MessageAggregator, Result, succeed } from '@fgv/ts-utils';
-import { IResourceDeclContainer } from './resourceDeclContainer';
-import * as Convert from './convert';
-import * as Normalized from './normalized';
-import * as Json from './json';
-import { mergeContextDecl, mergeImporterCandidate, mergeImporterResource } from './helpers';
-
-/**
- * Class that extracts resources and candidates from a
- * {@link ResourceJson.Json.IResourceCollectionDecl | resource collection declaration}.
- * @public
- */
-export class ResourceDeclCollection implements IResourceDeclContainer {
-  /**
-   * The {@link ResourceJson.Normalized.IResourceCollectionDecl | resource collection declaration}
-   * being processed.
-   */
-  public readonly collection: Normalized.IImporterResourceCollectionDecl;
-
-  /**
-   * {@inheritdoc ResourceJson.IResourceDeclContainer.context}
-   */
-  public get context(): Normalized.IContainerContextDecl | undefined {
-    return this.collection.context;
-  }
-
-  protected _resources: Normalized.IImporterResourceDecl[] = [];
-  protected _candidates: Normalized.IImporterResourceCandidateDecl[] = [];
-
-  protected constructor(collection: Normalized.IImporterResourceCollectionDecl) {
-    this.collection = collection;
-    this._extract(collection).orThrow();
-  }
-
-  /**
-   * Creates a new {@link ResourceJson.ResourceDeclCollection | ResourceDeclCollection} from an
-   * untyped {@link ResourceJson.Json.IResourceCollectionDecl | resource collection declaration}.
-   * @param from - The JSON object to convert.
-   * @returns `Success` with the new collection if the JSON object is valid, otherwise `Failure`.
-   */
-  public static create(from: unknown): Result<ResourceDeclCollection> {
-    return Convert.importerResourceCollectionDecl
-      .convert(from)
-      .withErrorFormat((err) => `Invalid resource collection: ${err}`)
-      .onSuccess((decl) => {
-        return captureResult(() => new ResourceDeclCollection(decl));
-      });
-  }
-
-  /**
-   * Gets the importer resources extracted from the collection.
-   * @returns The {@link ResourceJson.Normalized.IImporterResourceDecl | importer resource declarations}
-   * extracted from the collection.
-   */
-  public getImporterResources(): ReadonlyArray<Normalized.IImporterResourceDecl> {
-    return this._resources;
-  }
-
-  /**
-   * Gets the importer candidates extracted from the collection.
-   * @returns The {@link ResourceJson.Normalized.IImporterResourceCandidateDecl | importer resource candidate declarations}
-   * extracted from the collection.
-   */
-  public getImporterCandidates(): ReadonlyArray<Normalized.IImporterResourceCandidateDecl> {
-    return this._candidates;
-  }
-
-  private _extract(
-    collection: Normalized.IImporterResourceCollectionDecl,
-    parentName?: string,
-    parentConditions?: ReadonlyArray<Json.ILooseConditionDecl>
-  ): Result<this> {
-    const errors: MessageAggregator = new MessageAggregator();
-    return mergeContextDecl(collection.context, parentName, parentConditions).onSuccess(
-      ({ baseId: baseName, conditions: baseConditions }) => {
-        const mergedCandidates =
-          collection.candidates?.map((candidate) =>
-            mergeImporterCandidate(candidate, baseName, baseConditions)
-          ) ?? [];
-        this._candidates.push(...mapResults(mergedCandidates).aggregateError(errors).orDefault([]));
-
-        const mergedResources =
-          collection.resources?.map((resource) =>
-            mergeImporterResource(resource, baseName, baseConditions)
-          ) ?? [];
-        this._resources.push(...mapResults(mergedResources).aggregateError(errors).orDefault([]));
-
-        collection.collections?.forEach((subCollection) => {
-          this._extract(subCollection, baseName, baseConditions).aggregateError(errors);
-        });
-        return errors.returnOrReport(succeed(this));
-      }
-    );
-  }
-}

package/src/packlets/resource-json/resourceDeclContainer.ts

@@ -1,48 +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 Normalized from './normalized';
-
-/**
- * Generic container for resource and resource candidate
- * declarations.
- * @public
- */
-export interface IResourceDeclContainer {
-  /**
-   * Optional initial {@link ResourceJson.Normalized.IContainerContextDecl | resource context}
-   * declaration for the container.
-   */
-  readonly context?: Normalized.IContainerContextDecl;
-
-  /**
-   * Gets a normalized array of {@link ResourceJson.Normalized.IImporterResourceDecl | importer resource}
-   * declarations for all resources in the container, including children.
-   */
-  getImporterResources(): ReadonlyArray<Normalized.IImporterResourceDecl>;
-
-  /**
-   * Gets a normalized array of {@link ResourceJson.Normalized.IImporterResourceCandidateDecl | importer resource candidate}
-   * declarations for all resources in the container, including children.
-   */
-  getImporterCandidates(): ReadonlyArray<Normalized.IImporterResourceCandidateDecl>;
-}