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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (197) hide show
  1. package/README.md +794 -137
  2. package/dist/ts-res.d.ts +506 -33
  3. package/lib/packlets/common/convert.d.ts +10 -0
  4. package/lib/packlets/common/convert.js +11 -1
  5. package/lib/packlets/common/resources.d.ts +40 -1
  6. package/lib/packlets/common/validate/regularExpressions.d.ts +4 -0
  7. package/lib/packlets/common/validate/regularExpressions.js +5 -1
  8. package/lib/packlets/common/validate/resources.d.ts +35 -1
  9. package/lib/packlets/common/validate/resources.js +54 -0
  10. package/lib/packlets/config/convert.js +1 -1
  11. package/lib/packlets/config/json.d.ts +1 -1
  12. package/lib/packlets/qualifier-types/config/convert.d.ts +22 -1
  13. package/lib/packlets/qualifier-types/config/convert.js +67 -2
  14. package/lib/packlets/qualifier-types/config/json.d.ts +11 -2
  15. package/lib/packlets/qualifier-types/helpers.d.ts +1 -2
  16. package/lib/packlets/qualifier-types/languageQualifierType.d.ts +27 -1
  17. package/lib/packlets/qualifier-types/languageQualifierType.js +75 -0
  18. package/lib/packlets/qualifier-types/literalQualifierType.d.ts +30 -4
  19. package/lib/packlets/qualifier-types/literalQualifierType.js +77 -0
  20. package/lib/packlets/qualifier-types/literalValueHierarchy.d.ts +6 -10
  21. package/lib/packlets/qualifier-types/literalValueHierarchy.js +10 -0
  22. package/lib/packlets/qualifier-types/qualifierType.d.ts +28 -0
  23. package/lib/packlets/qualifier-types/territoryQualifierType.d.ts +28 -4
  24. package/lib/packlets/qualifier-types/territoryQualifierType.js +77 -0
  25. package/lib/packlets/resource-json/compiled/convert.js +2 -1
  26. package/lib/packlets/resource-json/compiled/json.d.ts +6 -2
  27. package/lib/packlets/resource-types/config/convert.js +3 -1
  28. package/lib/packlets/resource-types/config/json.d.ts +2 -0
  29. package/lib/packlets/resource-types/jsonResourceType.d.ts +10 -6
  30. package/lib/packlets/resource-types/jsonResourceType.js +7 -10
  31. package/lib/packlets/resource-types/resourceType.d.ts +20 -8
  32. package/lib/packlets/resource-types/resourceType.js +20 -16
  33. package/lib/packlets/resources/candidateValue.d.ts +92 -0
  34. package/lib/packlets/resources/candidateValue.js +128 -0
  35. package/lib/packlets/resources/candidateValueCollector.d.ts +55 -0
  36. package/lib/packlets/resources/candidateValueCollector.js +96 -0
  37. package/lib/packlets/resources/index.d.ts +2 -0
  38. package/lib/packlets/resources/index.js +2 -0
  39. package/lib/packlets/resources/resource.js +2 -2
  40. package/lib/packlets/resources/resourceBuilder.d.ts +6 -0
  41. package/lib/packlets/resources/resourceBuilder.js +3 -1
  42. package/lib/packlets/resources/resourceCandidate.d.ts +10 -1
  43. package/lib/packlets/resources/resourceCandidate.js +11 -5
  44. package/lib/packlets/resources/resourceManagerBuilder.d.ts +7 -0
  45. package/lib/packlets/resources/resourceManagerBuilder.js +13 -6
  46. package/lib/packlets/runtime/compiledResourceCollection.d.ts +20 -8
  47. package/lib/packlets/runtime/compiledResourceCollection.js +25 -4
  48. package/lib/packlets/runtime/resource-tree/common.d.ts +1 -1
  49. package/lib/packlets/runtime/resourceResolver.d.ts +39 -1
  50. package/lib/packlets/runtime/resourceResolver.js +45 -28
  51. package/lib/test/unit/qualifier-types/testQualifierType.d.ts +4 -0
  52. package/lib/test/unit/qualifier-types/testQualifierType.js +24 -0
  53. package/lib/test/unit/resource-types/derivedResourceType.test.d.ts +2 -0
  54. package/lib/test/unit/resource-types/testDerivedResourceType.d.ts +79 -0
  55. package/lib/test/unit/resource-types/testDerivedResourceType.js +113 -0
  56. package/lib/test/unit/resources/candidateValue.test.d.ts +2 -0
  57. package/lib/test/unit/resources/candidateValueCollector.test.d.ts +2 -0
  58. package/lib/test/unit/runtime/resourceResolver.coverage.test.d.ts +2 -0
  59. package/lib/test/unit/runtime/resourceResolver.newFeatures.test.d.ts +2 -0
  60. package/package.json +7 -7
  61. package/src/index.ts +0 -75
  62. package/src/packlets/bundle/bundleBuilder.ts +0 -159
  63. package/src/packlets/bundle/bundleLoader.ts +0 -157
  64. package/src/packlets/bundle/bundleNormalizer.ts +0 -173
  65. package/src/packlets/bundle/bundleUtils.ts +0 -142
  66. package/src/packlets/bundle/convert.ts +0 -87
  67. package/src/packlets/bundle/index.ts +0 -52
  68. package/src/packlets/bundle/model.ts +0 -138
  69. package/src/packlets/common/conditions.ts +0 -226
  70. package/src/packlets/common/convert.ts +0 -184
  71. package/src/packlets/common/helpers/conditions.ts +0 -84
  72. package/src/packlets/common/helpers/context.ts +0 -88
  73. package/src/packlets/common/helpers/index.ts +0 -26
  74. package/src/packlets/common/helpers/qualifierDefaultValues.ts +0 -91
  75. package/src/packlets/common/helpers/resources.ts +0 -96
  76. package/src/packlets/common/index.ts +0 -30
  77. package/src/packlets/common/resources.ts +0 -78
  78. package/src/packlets/common/validate/conditions.ts +0 -595
  79. package/src/packlets/common/validate/index.ts +0 -27
  80. package/src/packlets/common/validate/regularExpressions.ts +0 -92
  81. package/src/packlets/common/validate/resources.ts +0 -170
  82. package/src/packlets/conditions/condition.ts +0 -351
  83. package/src/packlets/conditions/conditionCollector.ts +0 -103
  84. package/src/packlets/conditions/conditionDecls.ts +0 -50
  85. package/src/packlets/conditions/conditionSet.ts +0 -318
  86. package/src/packlets/conditions/conditionSetCollector.ts +0 -127
  87. package/src/packlets/conditions/conditionSetDecls.ts +0 -41
  88. package/src/packlets/conditions/conditionToken.ts +0 -180
  89. package/src/packlets/conditions/convert/conditionSetDecls.ts +0 -72
  90. package/src/packlets/conditions/convert/decls.ts +0 -95
  91. package/src/packlets/conditions/convert/index.ts +0 -24
  92. package/src/packlets/conditions/index.ts +0 -33
  93. package/src/packlets/config/common.ts +0 -107
  94. package/src/packlets/config/configInitFactory.ts +0 -142
  95. package/src/packlets/config/convert.ts +0 -61
  96. package/src/packlets/config/index.ts +0 -30
  97. package/src/packlets/config/json.ts +0 -43
  98. package/src/packlets/config/predefined/default.ts +0 -150
  99. package/src/packlets/config/predefined/extended.ts +0 -198
  100. package/src/packlets/config/predefined/index.ts +0 -26
  101. package/src/packlets/config/systemConfiguration.ts +0 -217
  102. package/src/packlets/context/contextDecls.ts +0 -76
  103. package/src/packlets/context/contextToken.ts +0 -252
  104. package/src/packlets/context/convert/decls.ts +0 -126
  105. package/src/packlets/context/convert/index.ts +0 -23
  106. package/src/packlets/context/index.ts +0 -27
  107. package/src/packlets/decisions/abstractDecision.ts +0 -87
  108. package/src/packlets/decisions/abstractDecisionCollector.ts +0 -122
  109. package/src/packlets/decisions/candidate.ts +0 -101
  110. package/src/packlets/decisions/common.ts +0 -37
  111. package/src/packlets/decisions/concreteDecision.ts +0 -157
  112. package/src/packlets/decisions/decision.ts +0 -172
  113. package/src/packlets/decisions/index.ts +0 -28
  114. package/src/packlets/import/fsItem.ts +0 -212
  115. package/src/packlets/import/importContext.ts +0 -183
  116. package/src/packlets/import/importManager.ts +0 -187
  117. package/src/packlets/import/importable.ts +0 -107
  118. package/src/packlets/import/importers/collectionImporter.ts +0 -153
  119. package/src/packlets/import/importers/fsItemImporter.ts +0 -154
  120. package/src/packlets/import/importers/importer.ts +0 -58
  121. package/src/packlets/import/importers/index.ts +0 -27
  122. package/src/packlets/import/importers/jsonImporter.ts +0 -133
  123. package/src/packlets/import/importers/pathImporter.ts +0 -134
  124. package/src/packlets/import/index.ts +0 -29
  125. package/src/packlets/qualifier-types/config/convert.ts +0 -108
  126. package/src/packlets/qualifier-types/config/index.ts +0 -27
  127. package/src/packlets/qualifier-types/config/json.ts +0 -126
  128. package/src/packlets/qualifier-types/convert.ts +0 -77
  129. package/src/packlets/qualifier-types/helpers.ts +0 -94
  130. package/src/packlets/qualifier-types/index.ts +0 -34
  131. package/src/packlets/qualifier-types/languageQualifierType.ts +0 -143
  132. package/src/packlets/qualifier-types/literalQualifierType.ts +0 -244
  133. package/src/packlets/qualifier-types/literalValueHierarchy.ts +0 -332
  134. package/src/packlets/qualifier-types/qualifierType.ts +0 -360
  135. package/src/packlets/qualifier-types/qualifierTypeCollector.ts +0 -102
  136. package/src/packlets/qualifier-types/territoryQualifierType.ts +0 -255
  137. package/src/packlets/qualifiers/convert/decls.ts +0 -90
  138. package/src/packlets/qualifiers/convert/index.ts +0 -24
  139. package/src/packlets/qualifiers/convert/qualifier.ts +0 -55
  140. package/src/packlets/qualifiers/index.ts +0 -31
  141. package/src/packlets/qualifiers/qualifier.ts +0 -169
  142. package/src/packlets/qualifiers/qualifierCollector.ts +0 -194
  143. package/src/packlets/qualifiers/qualifierDecl.ts +0 -80
  144. package/src/packlets/qualifiers/qualifierDefaultValueDecls.ts +0 -57
  145. package/src/packlets/qualifiers/qualifierDefaultValueToken.ts +0 -230
  146. package/src/packlets/resource-json/compiled/common.ts +0 -35
  147. package/src/packlets/resource-json/compiled/convert.ts +0 -143
  148. package/src/packlets/resource-json/compiled/index.ts +0 -27
  149. package/src/packlets/resource-json/compiled/json.ts +0 -239
  150. package/src/packlets/resource-json/convert.ts +0 -236
  151. package/src/packlets/resource-json/helpers.ts +0 -284
  152. package/src/packlets/resource-json/index.ts +0 -33
  153. package/src/packlets/resource-json/json.ts +0 -295
  154. package/src/packlets/resource-json/normalized.ts +0 -211
  155. package/src/packlets/resource-json/resourceDeclCollection.ts +0 -117
  156. package/src/packlets/resource-json/resourceDeclContainer.ts +0 -48
  157. package/src/packlets/resource-json/resourceDeclTree.ts +0 -116
  158. package/src/packlets/resource-types/config/convert.ts +0 -36
  159. package/src/packlets/resource-types/config/index.ts +0 -27
  160. package/src/packlets/resource-types/config/json.ts +0 -30
  161. package/src/packlets/resource-types/helpers.ts +0 -44
  162. package/src/packlets/resource-types/index.ts +0 -30
  163. package/src/packlets/resource-types/jsonResourceType.ts +0 -104
  164. package/src/packlets/resource-types/resourceType.ts +0 -259
  165. package/src/packlets/resource-types/resourceTypeCollector.ts +0 -79
  166. package/src/packlets/resources/candidateReducer.ts +0 -331
  167. package/src/packlets/resources/common.ts +0 -114
  168. package/src/packlets/resources/index.ts +0 -28
  169. package/src/packlets/resources/resource.ts +0 -307
  170. package/src/packlets/resources/resourceBuilder.ts +0 -269
  171. package/src/packlets/resources/resourceCandidate.ts +0 -333
  172. package/src/packlets/resources/resourceManagerBuilder.ts +0 -1169
  173. package/src/packlets/runtime/cacheListener.ts +0 -113
  174. package/src/packlets/runtime/cacheMetrics.ts +0 -206
  175. package/src/packlets/runtime/compiledResourceCollection.ts +0 -607
  176. package/src/packlets/runtime/conditionSetResolutionResult.ts +0 -160
  177. package/src/packlets/runtime/context/contextQualifierProvider.ts +0 -117
  178. package/src/packlets/runtime/context/contextQualifierProviderValidator.ts +0 -281
  179. package/src/packlets/runtime/context/index.ts +0 -26
  180. package/src/packlets/runtime/context/simpleContextQualifierProvider.ts +0 -225
  181. package/src/packlets/runtime/context/validatingSimpleContextQualifierProvider.ts +0 -96
  182. package/src/packlets/runtime/iResourceManager.ts +0 -130
  183. package/src/packlets/runtime/index.ts +0 -35
  184. package/src/packlets/runtime/resource-tree/common.ts +0 -126
  185. package/src/packlets/runtime/resource-tree/index.ts +0 -26
  186. package/src/packlets/runtime/resource-tree/readOnlyResourceTree.ts +0 -342
  187. package/src/packlets/runtime/resource-tree/resourceTreeChildren.ts +0 -125
  188. package/src/packlets/runtime/resource-tree/resourceTreeChildrenValidator.ts +0 -187
  189. package/src/packlets/runtime/resourceResolver.ts +0 -626
  190. package/src/packlets/runtime/validate.ts +0 -63
  191. package/src/packlets/zip-archive/convert.ts +0 -121
  192. package/src/packlets/zip-archive/index.ts +0 -76
  193. package/src/packlets/zip-archive/json.ts +0 -91
  194. package/src/packlets/zip-archive/types.ts +0 -140
  195. package/src/packlets/zip-archive/zipArchiveCreator.ts +0 -229
  196. package/src/packlets/zip-archive/zipArchiveFormat.ts +0 -158
  197. package/src/packlets/zip-archive/zipArchiveLoader.ts +0 -370
@@ -1,160 +0,0 @@
1
- /*
2
- * Copyright (c) 2025 Erik Fortune
3
- *
4
- * Permission is hereby granted, free of charge, to any person obtaining a copy
5
- * of this software and associated documentation files (the "Software"), to deal
6
- * in the Software without restriction, including without limitation the rights
7
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8
- * copies of the Software, and to permit persons to whom the Software is
9
- * furnished to do so, subject to the following conditions:
10
- *
11
- * The above copyright notice and this permission notice shall be included in all
12
- * copies or substantial portions of the Software.
13
- *
14
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20
- * SOFTWARE.
21
- */
22
-
23
- import { captureResult, Result } from '@fgv/ts-utils';
24
- import { QualifierMatchScore, ConditionPriority } from '../common';
25
-
26
- /**
27
- * The outcome of a condition match.
28
- * @public
29
- */
30
- export type ConditionMatchType = 'match' | 'matchAsDefault' | 'noMatch';
31
-
32
- /**
33
- * Represents a single condition match result with priority and outcome.
34
- * @public
35
- */
36
- export interface IConditionMatchResult {
37
- readonly priority: ConditionPriority;
38
- readonly matchType: ConditionMatchType;
39
- readonly score: QualifierMatchScore;
40
- }
41
-
42
- /**
43
- * Represents the result of resolving a condition set.
44
- * Contains either a failure indicator or a list of condition priority/score tuples sorted by priority then score.
45
- * @public
46
- */
47
- export class ConditionSetResolutionResult {
48
- public readonly matchType: ConditionMatchType;
49
- public readonly matches: ReadonlyArray<IConditionMatchResult>;
50
-
51
- /**
52
- * Constructor for a {@link Runtime.ConditionSetResolutionResult | ConditionSetResolutionResult}.
53
- * @param success - Whether the condition set resolution was successful.
54
- * @param matches - Array of condition match results, if successful.
55
- */
56
- private constructor(matchType: ConditionMatchType, matches: ReadonlyArray<IConditionMatchResult>) {
57
- this.matchType = matchType;
58
- this.matches = [...matches];
59
- }
60
-
61
- /**
62
- * Creates a new condition set resolution result.
63
- * @param matchType - The type of match.
64
- * @param matches - Array of condition match results.
65
- * @returns A new {@link Runtime.ConditionSetResolutionResult | ConditionSetResolutionResult}.
66
- * @public
67
- */
68
- public static create(
69
- matchType: ConditionMatchType,
70
- matches: ReadonlyArray<IConditionMatchResult>
71
- ): Result<ConditionSetResolutionResult> {
72
- return captureResult(() => new ConditionSetResolutionResult(matchType, matches));
73
- }
74
-
75
- /**
76
- * Compares two condition set resolution results for sorting purposes.
77
- * The priority of a condition set result cannot be boiled down to a single number -
78
- * we have to examine each condition result in turn.
79
- *
80
- * Comparison logic:
81
- * - If priority differs, return the higher priority
82
- * - If priority matches but score is different, return the higher score
83
- * - If priority and score both match, proceed to the next condition
84
- * - Failed results are considered lower priority than successful results
85
- *
86
- * @param a - The first condition set resolution result to compare.
87
- * @param b - The second condition set resolution result to compare.
88
- * @returns A negative number if a should come before b, a positive number if a should
89
- * come after b, or zero if they are equivalent.
90
- * @public
91
- */
92
- public static compare(a: ConditionSetResolutionResult, b: ConditionSetResolutionResult): number {
93
- // Failed results are always lower priority than default match which are lower than match
94
- if (a.matchType === 'match') {
95
- if (b.matchType !== 'match') return -1;
96
- } else if (a.matchType === 'matchAsDefault') {
97
- if (b.matchType === 'match') {
98
- return 1;
99
- } else if (b.matchType === 'noMatch') {
100
- return -1;
101
- }
102
- } else {
103
- // a.matchType === 'noMatch'
104
- if (b.matchType === 'noMatch') {
105
- return 0;
106
- } else {
107
- return 1; // noMatch comes after any other match type
108
- }
109
- }
110
-
111
- // Both are successful with the same match type - compare condition by condition
112
- const minLength = Math.min(a.matches.length, b.matches.length);
113
-
114
- for (let i = 0; i < minLength; i++) {
115
- const matchA = a.matches[i];
116
- const matchB = b.matches[i];
117
-
118
- // Compare priority first
119
- const priorityDiff = matchB.priority - matchA.priority;
120
- if (priorityDiff !== 0) {
121
- return priorityDiff;
122
- }
123
-
124
- // If priority matches, compare score
125
- const scoreDiff = matchB.score - matchA.score;
126
- if (scoreDiff !== 0) {
127
- return scoreDiff;
128
- }
129
-
130
- // If both priority and score match, continue to next condition
131
- }
132
-
133
- // If all compared conditions are equal, the one with more conditions wins
134
- return b.matches.length - a.matches.length;
135
- }
136
-
137
- /**
138
- * Gets the highest priority among all condition matches.
139
- * @returns The highest priority, or 0 if no matches.
140
- * @public
141
- */
142
- public get maxPriority(): ConditionPriority {
143
- if (this.matchType === 'noMatch' || this.matches.length === 0) {
144
- return 0 as ConditionPriority;
145
- }
146
- return Math.max(...this.matches.map((m) => m.priority)) as ConditionPriority;
147
- }
148
-
149
- /**
150
- * Gets the total score by summing all condition match scores.
151
- * @returns The total score, or 0 if no matches.
152
- * @public
153
- */
154
- public get totalScore(): QualifierMatchScore {
155
- if (this.matchType === 'noMatch' || this.matches.length === 0) {
156
- return 0 as QualifierMatchScore;
157
- }
158
- return this.matches.reduce((sum, match) => sum + match.score, 0) as QualifierMatchScore;
159
- }
160
- }
@@ -1,117 +0,0 @@
1
- /*
2
- * Copyright (c) 2025 Erik Fortune
3
- *
4
- * Permission is hereby granted, free of charge, to any person obtaining a copy
5
- * of this software and associated documentation files (the "Software"), to deal
6
- * in the Software without restriction, including without limitation the rights
7
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8
- * copies of the Software, and to permit persons to whom the Software is
9
- * furnished to do so, subject to the following conditions:
10
- *
11
- * The above copyright notice and this permission notice shall be included in all
12
- * copies or substantial portions of the Software.
13
- *
14
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20
- * SOFTWARE.
21
- */
22
-
23
- import { Result } from '@fgv/ts-utils';
24
- import { QualifierName, QualifierContextValue, QualifierIndex } from '../../common';
25
- import { IReadOnlyQualifierCollector, Qualifier } from '../../qualifiers';
26
-
27
- /**
28
- * Abstract interface for providing qualifier values in an optimized runtime context.
29
- * Acts as a property bag using the Result pattern for qualifier value lookups.
30
- * @public
31
- */
32
- export interface IContextQualifierProvider {
33
- /**
34
- * Gets a qualifier value by its name, index, or qualifier object.
35
- * @param nameOrIndexOrQualifier - The {@link QualifierName | qualifier name}, {@link QualifierIndex | index}, or {@link Qualifiers.Qualifier | qualifier object} to look up.
36
- * @returns `Success` with the {@link QualifierContextValue | qualifier context value} if found,
37
- * or `Failure` with an error message if not found or an error occurs.
38
- */
39
- get(nameOrIndexOrQualifier: QualifierName | QualifierIndex | Qualifier): Result<QualifierContextValue>;
40
-
41
- /**
42
- * Gets a validated qualifier context value by its name, index, or qualifier object.
43
- * @param nameOrIndexOrQualifier - The {@link QualifierName | qualifier name}, {@link QualifierIndex | index}, or {@link Qualifiers.Qualifier | qualifier object} to look up.
44
- * @returns `Success` with the validated {@link QualifierContextValue | qualifier context value} if found,
45
- * or `Failure` with an error message if not found, invalid, or an error occurs.
46
- */
47
- getValidated(
48
- nameOrIndexOrQualifier: QualifierName | QualifierIndex | Qualifier
49
- ): Result<QualifierContextValue>;
50
-
51
- /**
52
- * Checks if a qualifier value exists with the given name.
53
- * @param name - The {@link QualifierName | qualifier name} to check.
54
- * @returns `Success` with `true` if the qualifier value exists, `false` if it doesn't,
55
- * or `Failure` with an error message if an error occurs during the check.
56
- */
57
- has(name: QualifierName): Result<boolean>;
58
-
59
- /**
60
- * Gets all available qualifier names in this context.
61
- * @returns `Success` with an array of all {@link QualifierName | qualifier names},
62
- * or `Failure` with an error message if an error occurs.
63
- */
64
- getNames(): Result<ReadonlyArray<QualifierName>>;
65
-
66
- /**
67
- * The readonly qualifier collector that defines and validates the qualifiers for this context.
68
- */
69
- readonly qualifiers: IReadOnlyQualifierCollector;
70
- }
71
-
72
- /**
73
- * Abstract base class for implementing context qualifier providers.
74
- * Provides common functionality and enforces the contract for derived classes.
75
- * @public
76
- */
77
- export abstract class ContextQualifierProvider implements IContextQualifierProvider {
78
- /**
79
- * The readonly qualifier collector that defines and validates the qualifiers for this context.
80
- */
81
- public abstract readonly qualifiers: IReadOnlyQualifierCollector;
82
-
83
- /**
84
- * Gets a qualifier value by its name, index, or qualifier object.
85
- * @param nameOrIndexOrQualifier - The {@link QualifierName | qualifier name}, {@link QualifierIndex | index}, or {@link Qualifiers.Qualifier | qualifier object} to look up.
86
- * @returns `Success` with the {@link QualifierContextValue | qualifier context value} if found,
87
- * or `Failure` with an error message if not found or an error occurs.
88
- */
89
- public abstract get(
90
- nameOrIndexOrQualifier: QualifierName | QualifierIndex | Qualifier
91
- ): Result<QualifierContextValue>;
92
-
93
- /**
94
- * Gets a validated qualifier context value by its name, index, or qualifier object.
95
- * @param nameOrIndexOrQualifier - The {@link QualifierName | qualifier name}, {@link QualifierIndex | index}, or {@link Qualifiers.Qualifier | qualifier object} to look up.
96
- * @returns `Success` with the validated {@link QualifierContextValue | qualifier context value} if found,
97
- * or `Failure` with an error message if not found, invalid, or an error occurs.
98
- */
99
- public abstract getValidated(
100
- nameOrIndexOrQualifier: QualifierName | QualifierIndex | Qualifier
101
- ): Result<QualifierContextValue>;
102
-
103
- /**
104
- * Checks if a qualifier value exists with the given name.
105
- * @param name - The {@link QualifierName | qualifier name} to check.
106
- * @returns `Success` with `true` if the qualifier value exists, `false` if it doesn't,
107
- * or `Failure` with an error message if an error occurs during the check.
108
- */
109
- public abstract has(name: QualifierName): Result<boolean>;
110
-
111
- /**
112
- * Gets all available qualifier names in this context.
113
- * @returns `Success` with an array of all {@link QualifierName | qualifier names},
114
- * or `Failure` with an error message if an error occurs.
115
- */
116
- public abstract getNames(): Result<ReadonlyArray<QualifierName>>;
117
- }
@@ -1,281 +0,0 @@
1
- /*
2
- * Copyright (c) 2025 Erik Fortune
3
- *
4
- * Permission is hereby granted, free of charge, to any person obtaining a copy
5
- * of this software and associated documentation files (the "Software"), to deal
6
- * in the Software without restriction, including without limitation the rights
7
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8
- * copies of the Software, and to permit persons to whom the Software is
9
- * furnished to do so, subject to the following conditions:
10
- *
11
- * The above copyright notice and this permission notice shall be included in all
12
- * copies or substantial portions of the Software.
13
- *
14
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20
- * SOFTWARE.
21
- */
22
-
23
- import { Result, fail, succeed } from '@fgv/ts-utils';
24
- import { QualifierName, QualifierContextValue, QualifierIndex } from '../../common';
25
- import { IReadOnlyQualifierCollector } from '../../qualifiers';
26
- import { IContextQualifierProvider } from './contextQualifierProvider';
27
-
28
- /**
29
- * A read-only interface exposing non-mutating methods of a {@link Runtime.Context.ContextQualifierProviderValidator | ContextQualifierProviderValidator}.
30
- * @public
31
- */
32
- export interface IReadOnlyContextQualifierProviderValidator {
33
- /**
34
- * {@inheritdoc Runtime.Context.ContextQualifierProviderValidator.provider}
35
- */
36
- readonly provider: IContextQualifierProvider;
37
-
38
- /**
39
- * {@inheritdoc Runtime.Context.ContextQualifierProviderValidator.qualifiers}
40
- */
41
- readonly qualifiers: IReadOnlyQualifierCollector;
42
-
43
- /**
44
- * Gets a qualifier value by its string name, converting to strongly-typed QualifierName.
45
- * @param name - The string name to convert and look up.
46
- * @returns `Success` with the {@link QualifierContextValue | qualifier context value} if found,
47
- * or `Failure` with an error message if not found or an error occurs.
48
- */
49
- get(name: string): Result<QualifierContextValue>;
50
-
51
- /**
52
- * Gets a qualifier value by its number index, converting to strongly-typed QualifierIndex.
53
- * @param index - The number index to convert and look up.
54
- * @returns `Success` with the {@link QualifierContextValue | qualifier context value} if found,
55
- * or `Failure` with an error message if not found or an error occurs.
56
- */
57
- getByIndex(index: number): Result<QualifierContextValue>;
58
-
59
- /**
60
- * Gets a validated qualifier context value by its string name.
61
- * @param name - The string name to convert and look up.
62
- * @returns `Success` with the validated {@link QualifierContextValue | qualifier context value} if found,
63
- * or `Failure` with an error message if not found, invalid, or an error occurs.
64
- */
65
- getValidated(name: string): Result<QualifierContextValue>;
66
-
67
- /**
68
- * Gets a validated qualifier context value by its number index.
69
- * @param index - The number index to convert and look up.
70
- * @returns `Success` with the validated {@link QualifierContextValue | qualifier context value} if found,
71
- * or `Failure` with an error message if not found, invalid, or an error occurs.
72
- */
73
- getValidatedByIndex(index: number): Result<QualifierContextValue>;
74
-
75
- /**
76
- * Checks if a qualifier value exists with the given string name.
77
- * @param name - The string name to convert and check.
78
- * @returns `Success` with `true` if the qualifier value exists, `false` if it doesn't,
79
- * or `Failure` with an error message if an error occurs during the check.
80
- */
81
- has(name: string): Result<boolean>;
82
-
83
- /**
84
- * Sets a qualifier value using string inputs, converting to strongly-typed values.
85
- * @param name - The string name to convert.
86
- * @param value - The string value to convert.
87
- * @returns `Success` with the set {@link QualifierContextValue | qualifier context value} if successful,
88
- * or `Failure` with an error message if an error occurs.
89
- */
90
- set(name: string, value: string): Result<QualifierContextValue>;
91
-
92
- /**
93
- * Removes a qualifier value using string input, converting to strongly-typed QualifierName.
94
- * @param name - The string name to convert.
95
- * @returns `Success` with the removed {@link QualifierContextValue | qualifier context value} if successful,
96
- * or `Failure` with an error message if an error occurs.
97
- */
98
- remove(name: string): Result<QualifierContextValue>;
99
- }
100
-
101
- /**
102
- * Parameters for constructing a {@link Runtime.Context.ContextQualifierProviderValidator | ContextQualifierProviderValidator}.
103
- * @public
104
- */
105
- export interface IContextQualifierProviderValidatorCreateParams {
106
- provider: IContextQualifierProvider;
107
- }
108
-
109
- /**
110
- * A wrapper for {@link Runtime.Context.IContextQualifierProvider | IContextQualifierProvider} that accepts
111
- * string inputs and converts them to strongly-typed values before calling the wrapped provider.
112
- * This eliminates the need for type casting in consumer code while maintaining type safety.
113
- * @public
114
- */
115
- export class ContextQualifierProviderValidator implements IReadOnlyContextQualifierProviderValidator {
116
- /**
117
- * The wrapped context qualifier provider.
118
- */
119
- public readonly provider: IContextQualifierProvider;
120
-
121
- /**
122
- * The readonly qualifier collector that defines and validates the qualifiers for this context.
123
- */
124
- public get qualifiers(): IReadOnlyQualifierCollector {
125
- return this.provider.qualifiers;
126
- }
127
-
128
- /**
129
- * Constructs a new {@link Runtime.Context.ContextQualifierProviderValidator | ContextQualifierProviderValidator}.
130
- * @param params - Required parameters for constructing the validator.
131
- */
132
- public constructor(params: IContextQualifierProviderValidatorCreateParams) {
133
- this.provider = params.provider;
134
- }
135
-
136
- /**
137
- * Gets a qualifier value by its string name, converting to strongly-typed QualifierName.
138
- * @param name - The string name to convert and look up.
139
- * @returns `Success` with the {@link QualifierContextValue | qualifier context value} if found,
140
- * or `Failure` with an error message if not found or an error occurs.
141
- */
142
- public get(name: string): Result<QualifierContextValue> {
143
- return this._validateQualifierName(name).onSuccess((qualifierName) => {
144
- return this.provider.get(qualifierName);
145
- });
146
- }
147
-
148
- /**
149
- * Gets a qualifier value by its number index, converting to strongly-typed QualifierIndex.
150
- * @param index - The number index to convert and look up.
151
- * @returns `Success` with the {@link QualifierContextValue | qualifier context value} if found,
152
- * or `Failure` with an error message if not found or an error occurs.
153
- */
154
- public getByIndex(index: number): Result<QualifierContextValue> {
155
- return this._validateQualifierIndex(index).onSuccess((qualifierIndex) => {
156
- return this.provider.get(qualifierIndex);
157
- });
158
- }
159
-
160
- /**
161
- * Gets a validated qualifier context value by its string name.
162
- * @param name - The string name to convert and look up.
163
- * @returns `Success` with the validated {@link QualifierContextValue | qualifier context value} if found,
164
- * or `Failure` with an error message if not found, invalid, or an error occurs.
165
- */
166
- public getValidated(name: string): Result<QualifierContextValue> {
167
- return this._validateQualifierName(name).onSuccess((qualifierName) => {
168
- return this.provider.getValidated(qualifierName);
169
- });
170
- }
171
-
172
- /**
173
- * Gets a validated qualifier context value by its number index.
174
- * @param index - The number index to convert and look up.
175
- * @returns `Success` with the validated {@link QualifierContextValue | qualifier context value} if found,
176
- * or `Failure` with an error message if not found, invalid, or an error occurs.
177
- */
178
- public getValidatedByIndex(index: number): Result<QualifierContextValue> {
179
- return this._validateQualifierIndex(index).onSuccess((qualifierIndex) => {
180
- return this.provider.getValidated(qualifierIndex);
181
- });
182
- }
183
-
184
- /**
185
- * Checks if a qualifier value exists with the given string name.
186
- * @param name - The string name to convert and check.
187
- * @returns `Success` with `true` if the qualifier value exists, `false` if it doesn't,
188
- * or `Failure` with an error message if an error occurs during the check.
189
- */
190
- public has(name: string): Result<boolean> {
191
- return this._validateQualifierName(name).onSuccess((qualifierName) => {
192
- return this.provider.has(qualifierName);
193
- });
194
- }
195
-
196
- /**
197
- * Sets a qualifier value using string inputs, converting to strongly-typed values.
198
- * @param name - The string name to convert.
199
- * @param value - The string value to convert.
200
- * @returns `Success` with the set {@link QualifierContextValue | qualifier context value} if successful,
201
- * or `Failure` with an error message if an error occurs.
202
- */
203
- public set(name: string, value: string): Result<QualifierContextValue> {
204
- return this._validateQualifierName(name)
205
- .onSuccess((qualifierName) => this._validateQualifierContextValue(value))
206
- .onSuccess((qualifierValue) => {
207
- // Check if the provider has a set method (only available on mutable providers)
208
- if ('set' in this.provider && typeof this.provider.set === 'function') {
209
- try {
210
- return (
211
- this.provider.set as (
212
- name: QualifierName,
213
- value: QualifierContextValue
214
- ) => Result<QualifierContextValue>
215
- )(name as QualifierName, qualifierValue);
216
- } catch {
217
- return fail(`Provider does not support setting values`);
218
- }
219
- }
220
- return fail(`Provider does not support setting values`);
221
- });
222
- }
223
-
224
- /**
225
- * Removes a qualifier value using string input, converting to strongly-typed QualifierName.
226
- * @param name - The string name to convert.
227
- * @returns `Success` with the removed {@link QualifierContextValue | qualifier context value} if successful,
228
- * or `Failure` with an error message if an error occurs.
229
- */
230
- public remove(name: string): Result<QualifierContextValue> {
231
- return this._validateQualifierName(name).onSuccess((qualifierName) => {
232
- // Check if the provider has a remove method (only available on mutable providers)
233
- if ('remove' in this.provider && typeof this.provider.remove === 'function') {
234
- try {
235
- return (this.provider.remove as (name: QualifierName) => Result<QualifierContextValue>)(
236
- qualifierName
237
- );
238
- } catch {
239
- return fail(`Provider does not support removing values`);
240
- }
241
- }
242
- return fail(`Provider does not support removing values`);
243
- });
244
- }
245
-
246
- /**
247
- * Validates a string as a QualifierName.
248
- * @param name - The string to validate.
249
- * @returns `Success` with the strongly-typed QualifierName, or `Failure` if invalid.
250
- */
251
- private _validateQualifierName(name: string): Result<QualifierName> {
252
- if (typeof name !== 'string' || name.length === 0) {
253
- return fail(`Invalid qualifier name: "${name}"`);
254
- }
255
- return succeed(name as QualifierName);
256
- }
257
-
258
- /**
259
- * Validates a number as a QualifierIndex.
260
- * @param index - The number to validate.
261
- * @returns `Success` with the strongly-typed QualifierIndex, or `Failure` if invalid.
262
- */
263
- private _validateQualifierIndex(index: number): Result<QualifierIndex> {
264
- if (typeof index !== 'number' || !Number.isInteger(index) || index < 0) {
265
- return fail(`Invalid qualifier index: ${index}`);
266
- }
267
- return succeed(index as QualifierIndex);
268
- }
269
-
270
- /**
271
- * Validates a string as a QualifierContextValue.
272
- * @param value - The string to validate.
273
- * @returns `Success` with the strongly-typed QualifierContextValue, or `Failure` if invalid.
274
- */
275
- private _validateQualifierContextValue(value: string): Result<QualifierContextValue> {
276
- if (typeof value !== 'string') {
277
- return fail(`Invalid qualifier context value: "${value}"`);
278
- }
279
- return succeed(value as QualifierContextValue);
280
- }
281
- }
@@ -1,26 +0,0 @@
1
- /*
2
- * Copyright (c) 2025 Erik Fortune
3
- *
4
- * Permission is hereby granted, free of charge, to any person obtaining a copy
5
- * of this software and associated documentation files (the "Software"), to deal
6
- * in the Software without restriction, including without limitation the rights
7
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8
- * copies of the Software, and to permit persons to whom the Software is
9
- * furnished to do so, subject to the following conditions:
10
- *
11
- * The above copyright notice and this permission notice shall be included in all
12
- * copies or substantial portions of the Software.
13
- *
14
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20
- * SOFTWARE.
21
- */
22
-
23
- export * from './contextQualifierProvider';
24
- export * from './contextQualifierProviderValidator';
25
- export * from './simpleContextQualifierProvider';
26
- export * from './validatingSimpleContextQualifierProvider';