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

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

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

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

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

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