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

package/src/packlets/config/convert.ts

@@ -0,0 +1,61 @@
+/*
+ * 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.
+ */
+
+/* eslint-disable @rushstack/typedef-var */
+
+import { Converters, Result } from '@fgv/ts-utils';
+import { ISystemConfiguration } from './json';
+import * as QualifierTypes from '../qualifier-types';
+import * as Qualifiers from '../qualifiers';
+import * as ResourceTypes from '../resource-types';
+import { allPredefinedSystemConfigurations } from './common';
+
+/**
+ * A `Converter` for {@link Config.Model.ISystemConfiguration | ISystemConfiguration} objects.
+ * @returns A `Converter` for {@link Config.Model.ISystemConfiguration | ISystemConfiguration} objects.
+ * @public
+ */
+export const systemConfiguration = Converters.strictObject<ISystemConfiguration>({
+  name: Converters.optionalString,
+  description: Converters.optionalString,
+  qualifierTypes: Converters.arrayOf(QualifierTypes.Config.Convert.systemQualifierTypeConfig),
+  qualifiers: Converters.arrayOf(Qualifiers.Convert.qualifierDecl),
+  resourceTypes: Converters.arrayOf(ResourceTypes.Config.Convert.resourceTypeConfig)
+});
+
+/**
+ * A `Converter` for {@link Config.PredefinedSystemConfiguration | PredefinedSystemConfiguration} values.
+ * @returns A `Converter` for {@link Config.PredefinedSystemConfiguration | PredefinedSystemConfiguration} values.
+ * @public
+ */
+export const predefinedSystemConfiguration = Converters.enumeratedValue(allPredefinedSystemConfigurations);
+
+/**
+ * Validate a {@link Config.Model.ISystemConfiguration | ISystemConfiguration} object.
+ * @param config - The system configuration to validate
+ * @returns `Success` with the validated system configuration if successful,
+ * or `Failure` with an error message if validation fails.
+ * @public
+ */
+export function validateSystemConfiguration(config: unknown): Result<ISystemConfiguration> {
+  return systemConfiguration.convert(config);
+}

package/src/packlets/config/index.ts

@@ -0,0 +1,30 @@
+/*
+ * 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 Model from './json';
+import * as Convert from './convert';
+
+export * from './configInitFactory';
+export * from './systemConfiguration';
+export * from './common';
+
+export { Model, Convert };

package/src/packlets/config/json.ts

@@ -0,0 +1,43 @@
+/*
+ * 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 QualifierTypes from '../qualifier-types';
+import * as Qualifiers from '../qualifiers';
+import * as ResourceTypes from '../resource-types';
+
+/**
+ * System configuration for both runtime or build.
+ * @public
+ */
+export interface ISystemConfiguration {
+  /** Optional human-readable name for the configuration. */
+
+  name?: string;
+  /** Optional description explaining the purpose and use case of the configuration. */
+  description?: string;
+  /** Qualifier type configurations that define the available qualifier types in the system. */
+  qualifierTypes: QualifierTypes.Config.ISystemQualifierTypeConfig[];
+  /** Qualifier declarations that define the available qualifiers in the system. */
+  qualifiers: Qualifiers.IQualifierDecl[];
+  /** Resource type configurations that define the available resource types in the system. */
+  resourceTypes: ResourceTypes.Config.IResourceTypeConfig[];
+}

package/src/packlets/config/predefined/default.ts

@@ -0,0 +1,150 @@
+/*
+ * 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 { ISystemConfiguration } from '../json';
+
+import * as QualifierTypes from '../../qualifier-types';
+import * as Qualifiers from '../../qualifiers';
+import * as ResourceTypes from '../../resource-types';
+
+/**
+ * Default qualifier types.
+ * @remarks
+ * The default qualifier types are:
+ * - language: recognizes BCP 47 language tags, accepts a comma-separated list of language tags in the context
+ * - territory: recognizes ISO 3166-1 alpha-2 territory codes, accepts a single code in the context
+ * @public
+ */
+export const DefaultQualifierTypes: ReadonlyArray<QualifierTypes.Config.ISystemQualifierTypeConfig> = [
+  {
+    name: 'language',
+    systemType: 'language',
+    configuration: {
+      allowContextList: true
+    }
+  },
+  {
+    name: 'territory',
+    systemType: 'territory',
+    configuration: {
+      allowContextList: false
+    }
+  }
+];
+
+/**
+ * Qualifier definitions in which territory is the primary qualifier, with
+ * language as a secondary qualifier.
+ * @remarks
+ * The default qualifiers are:
+ * - currentTerritory(token: geo): territory qualifier, priority 850
+ * - language(token: lang): language qualifier, priority 800
+ * @public
+ */
+export const TerritoryPriorityQualifiers: ReadonlyArray<Qualifiers.IQualifierDecl> = [
+  {
+    name: 'currentTerritory',
+    token: 'geo',
+    typeName: 'territory',
+    defaultPriority: 850
+  },
+  {
+    name: 'language',
+    token: 'lang',
+    typeName: 'language',
+    defaultPriority: 800
+  }
+];
+
+/**
+ * Qualifier definitions in which language is the primary qualifier, with
+ * territory as a secondary qualifier.
+ * @remarks
+ * The default qualifiers are:
+ * - language(token: lang): language qualifier, priority 850
+ * - currentTerritory(token: geo): territory qualifier, priority 800
+ * @public
+ */
+export const LanguagePriorityQualifiers: ReadonlyArray<Qualifiers.IQualifierDecl> = [
+  {
+    name: 'language',
+    token: 'lang',
+    typeName: 'language',
+    defaultPriority: 850
+  },
+  {
+    name: 'currentTerritory',
+    token: 'geo',
+    typeName: 'territory',
+    defaultPriority: 800
+  }
+];
+
+/**
+ * Default resource types.
+ * @public
+ */
+export const DefaultResourceTypes: ReadonlyArray<ResourceTypes.Config.IResourceTypeConfig> = [
+  {
+    name: 'json',
+    typeName: 'json'
+  }
+];
+
+/**
+ * System configuration with territory as the primary qualifier, and
+ * language as a secondary qualifier.
+ * @public
+ */
+export const TerritoryPrioritySystemConfiguration: ISystemConfiguration = {
+  name: 'territory-priority',
+  description: 'Territory priority system configuration',
+  qualifierTypes: [...DefaultQualifierTypes],
+  qualifiers: [...TerritoryPriorityQualifiers],
+  resourceTypes: [...DefaultResourceTypes]
+};
+
+/**
+ * System configuration with language as the primary qualifier, and
+ * territory as a secondary qualifier.
+ * @public
+ */
+export const LanguagePrioritySystemConfiguration: ISystemConfiguration = {
+  name: 'language-priority',
+  description: 'Language priority system configuration',
+  qualifierTypes: [...DefaultQualifierTypes],
+  qualifiers: [...LanguagePriorityQualifiers],
+  resourceTypes: [...DefaultResourceTypes]
+};
+
+/**
+ * The default system configuration gives priority to territory as the primary qualifier,
+ * with language as a secondary qualifier.
+ * @public
+ */
+export const DefaultSystemConfiguration: ISystemConfiguration = {
+  name: 'default',
+  description: 'Default system configuration',
+  qualifierTypes: [...DefaultQualifierTypes],
+  qualifiers: [...TerritoryPriorityQualifiers],
+  resourceTypes: [...DefaultResourceTypes]
+};

package/src/packlets/config/predefined/extended.ts

@@ -0,0 +1,198 @@
+/*
+ * 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 ResourceTypes from '../../resource-types';
+import * as QualifierTypes from '../../qualifier-types';
+import * as Qualifiers from '../../qualifiers';
+import { ISystemConfiguration } from '../json';
+
+/**
+ * Example extended qualifier types.
+ * @public
+ */
+export const ExtendedQualifierTypes: ReadonlyArray<QualifierTypes.Config.ISystemQualifierTypeConfig> = [
+  {
+    name: 'language',
+    systemType: 'language',
+    configuration: {
+      allowContextList: true
+    }
+  },
+  {
+    name: 'territory',
+    systemType: 'territory',
+    configuration: {
+      allowContextList: false,
+      acceptLowercase: false
+    }
+  },
+  {
+    name: 'role',
+    systemType: 'literal',
+    configuration: {
+      enumeratedValues: ['admin', 'agent', 'user', 'guest']
+    }
+  },
+  {
+    name: 'environment',
+    systemType: 'literal',
+    configuration: {
+      enumeratedValues: ['production', 'integration', 'development', 'test', 'ephemeral']
+    }
+  },
+  {
+    name: 'currency',
+    systemType: 'literal',
+    configuration: {
+      caseSensitive: true,
+      enumeratedValues: ['USD', 'EUR', 'GBP', 'JPY', 'CNY']
+    }
+  },
+  {
+    name: 'market',
+    systemType: 'literal',
+    configuration: {
+      enumeratedValues: [
+        'world',
+        'americas',
+        'europe',
+        'asia',
+        'oceania',
+        'africa',
+        'middle-east',
+        'latin-america',
+        'caribbean',
+        'central-america',
+        'south-america',
+        'north-america',
+        'nordics',
+        'baltic',
+        'balkans',
+        'eastern-europe',
+        'western-europe',
+        'central-europe',
+        'eastern-africa',
+        'western-africa',
+        'central-africa',
+        'north-africa',
+        'south-africa',
+        'middle-africa',
+        'southeast-asia'
+      ],
+      hierarchy: {
+        americas: 'world',
+        europe: 'world',
+        asia: 'world',
+        oceania: 'world',
+        africa: 'world',
+        'middle-east': 'world',
+        'latin-america': 'americas',
+        caribbean: 'americas',
+        'central-america': 'americas',
+        'south-america': 'americas',
+        'north-america': 'americas',
+        nordics: 'europe',
+        baltic: 'europe',
+        balkans: 'europe',
+        'eastern-europe': 'europe',
+        'western-europe': 'europe',
+        'central-europe': 'europe',
+        'eastern-africa': 'africa',
+        'western-africa': 'africa',
+        'central-africa': 'africa',
+        'north-africa': 'africa',
+        'south-africa': 'africa',
+        'middle-africa': 'africa',
+        'southeast-asia': 'asia'
+      }
+    }
+  }
+];
+
+/**
+ * Example extended qualifiers.
+ * @public
+ */
+export const ExtendedQualifiers: ReadonlyArray<Qualifiers.IQualifierDecl> = [
+  {
+    name: 'homeTerritory',
+    token: 'home',
+    typeName: 'territory',
+    defaultPriority: 900
+  },
+  {
+    name: 'currentTerritory',
+    token: 'geo',
+    typeName: 'territory',
+    defaultPriority: 850
+  },
+  {
+    name: 'language',
+    token: 'lang',
+    typeName: 'language',
+    defaultPriority: 800
+  },
+  {
+    name: 'market',
+    typeName: 'market',
+    defaultPriority: 750
+  },
+  {
+    name: 'role',
+    typeName: 'role',
+    defaultPriority: 700
+  },
+  {
+    name: 'environment',
+    token: 'env',
+    typeName: 'environment',
+    defaultPriority: 650
+  },
+  {
+    name: 'currency',
+    typeName: 'currency',
+    defaultPriority: 600
+  }
+];
+
+/**
+ * Example resource types.
+ * @public
+ */
+export const ExtendedResourceTypes: ReadonlyArray<ResourceTypes.Config.IResourceTypeConfig> = [
+  {
+    name: 'json',
+    typeName: 'json'
+  }
+];
+
+/**
+ * An example system configuration demonstrating various configuration options.
+ * @public
+ */
+export const ExtendedSystemConfiguration: ISystemConfiguration = {
+  name: 'extended-example',
+  description: 'An example system configuration demonstrating various configuration options',
+  qualifierTypes: [...ExtendedQualifierTypes],
+  qualifiers: [...ExtendedQualifiers],
+  resourceTypes: [...ExtendedResourceTypes]
+};

package/src/packlets/config/predefined/index.ts

@@ -0,0 +1,26 @@
+/*
+ * 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 Default from './default';
+import * as Example from './extended';
+
+export { Default, Example };