@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,236 +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 { Converter, Converters, mapResults, Result, fail } from '@fgv/ts-utils';
24
- import { Convert as CommonConvert } from '../common';
25
- import { isJsonObject, Converters as JsonConverters } from '@fgv/ts-json-base';
26
- import * as Json from './json';
27
- import * as Normalized from './normalized';
28
-
29
- /**
30
- * `Converter` for a normalized {@link ResourceJson.Json.ILooseConditionDecl | loose condition declaration}.
31
- * @public
32
- */
33
- export const looseConditionDecl: Converter<Json.ILooseConditionDecl> =
34
- Converters.strictObject<Json.ILooseConditionDecl>({
35
- qualifierName: CommonConvert.qualifierName,
36
- value: Converters.string,
37
- operator: CommonConvert.conditionOperator.optional(),
38
- priority: CommonConvert.conditionPriority.optional(),
39
- scoreAsDefault: Converters.number.optional()
40
- });
41
-
42
- /**
43
- * `Converter` for a normalized {@link ResourceJson.Json.IChildConditionDecl | child condition declaration}.
44
- * @public
45
- */
46
- export const childConditionDecl: Converter<Json.IChildConditionDecl> =
47
- Converters.strictObject<Json.IChildConditionDecl>({
48
- value: Converters.string,
49
- operator: CommonConvert.conditionOperator.optional(),
50
- priority: CommonConvert.conditionPriority.optional(),
51
- scoreAsDefault: Converters.number.optional()
52
- });
53
-
54
- function _isConditionSetRecord(from: unknown): from is Record<string, string | Json.IChildConditionDecl> {
55
- return isJsonObject(from);
56
- }
57
-
58
- const conditionSetDeclFromArray: Converter<Normalized.ConditionSetDecl> =
59
- Converters.arrayOf(looseConditionDecl);
60
- const conditionSetDeclFromRecord: Converter<Normalized.ConditionSetDecl> = Converters.generic<
61
- Normalized.ConditionSetDecl,
62
- unknown
63
- >(
64
- (
65
- from: unknown,
66
- __self: Converter<Normalized.ConditionSetDecl, unknown>,
67
- context?: unknown
68
- ): Result<Normalized.ConditionSetDecl> => {
69
- /* c8 ignore next 3 - this is tested but coverage is confused */
70
- if (!_isConditionSetRecord(from)) {
71
- return fail('Expected an object');
72
- }
73
- return mapResults(
74
- Array.from(Object.entries(from)).map(([qualifierName, value]) => {
75
- const toConvert: Json.ILooseConditionDecl =
76
- typeof value === 'string' ? { qualifierName, value } : { qualifierName, ...value };
77
- return looseConditionDecl.convert(toConvert, context);
78
- })
79
- );
80
- }
81
- );
82
-
83
- /**
84
- * `Converter` for a normalized {@link ResourceJson.Normalized.ConditionSetDecl | condition set declaration}.
85
- * @public
86
- */
87
- export const conditionSetDecl: Converter<Normalized.ConditionSetDecl> =
88
- Converters.oneOf<Normalized.ConditionSetDecl>([conditionSetDeclFromArray, conditionSetDeclFromRecord]);
89
-
90
- /**
91
- * `Converter` for a normalized {@link ResourceJson.Json.ILooseResourceCandidateDecl | loose resource candidate declaration}.
92
- * @public
93
- */
94
- export const looseResourceCandidateDecl: Converter<Normalized.ILooseResourceCandidateDecl> =
95
- Converters.strictObject<Normalized.ILooseResourceCandidateDecl>({
96
- id: CommonConvert.resourceId,
97
- json: JsonConverters.jsonObject,
98
- conditions: conditionSetDecl.optional(),
99
- mergeMethod: CommonConvert.resourceValueMergeMethod.optional(),
100
- isPartial: Converters.boolean.optional(),
101
- resourceTypeName: CommonConvert.resourceTypeName.optional()
102
- });
103
-
104
- /**
105
- * `Converter` for a normalized {@link ResourceJson.Normalized.IImporterResourceCandidateDecl | importer resource candidate declaration}.
106
- * @public
107
- */
108
- export const importerResourceCandidateDecl: Converter<Normalized.IImporterResourceCandidateDecl> =
109
- Converters.strictObject<Normalized.IImporterResourceCandidateDecl>({
110
- id: CommonConvert.resourceId.optional(),
111
- json: JsonConverters.jsonObject,
112
- conditions: conditionSetDecl.optional(),
113
- mergeMethod: CommonConvert.resourceValueMergeMethod.optional(),
114
- isPartial: Converters.boolean.optional(),
115
- resourceTypeName: CommonConvert.resourceTypeName.optional()
116
- });
117
-
118
- /**
119
- * `Converter` for a normalized {@link ResourceJson.Json.IChildResourceCandidateDecl | child resource candidate declaration}.
120
- * @public
121
- */
122
- export const childResourceCandidateDecl: Converter<Normalized.IChildResourceCandidateDecl> =
123
- Converters.strictObject<Normalized.IChildResourceCandidateDecl>({
124
- json: JsonConverters.jsonObject,
125
- conditions: conditionSetDecl.optional(),
126
- isPartial: Converters.boolean.optional(),
127
- mergeMethod: CommonConvert.resourceValueMergeMethod.optional()
128
- });
129
-
130
- /**
131
- * `Converter` for a normalized {@link ResourceJson.Normalized.ILooseResourceDecl | loose resource declaration}.
132
- * @public
133
- */
134
- export const looseResourceDecl: Converter<Normalized.ILooseResourceDecl> =
135
- Converters.strictObject<Normalized.ILooseResourceDecl>({
136
- id: CommonConvert.resourceId,
137
- resourceTypeName: CommonConvert.resourceTypeName,
138
- candidates: Converters.arrayOf(childResourceCandidateDecl).optional()
139
- });
140
-
141
- /**
142
- * `Converter` for a normalized {@link ResourceJson.Normalized.IChildResourceDecl | child resource declaration}.
143
- * @public
144
- */
145
- export const childResourceDecl: Converter<Normalized.IChildResourceDecl> =
146
- Converters.strictObject<Normalized.IChildResourceDecl>({
147
- resourceTypeName: CommonConvert.resourceTypeName,
148
- candidates: Converters.arrayOf(childResourceCandidateDecl).optional()
149
- });
150
-
151
- /**
152
- * `Converter` for a normalized {@link ResourceJson.Normalized.IContainerContextDecl | resource context declaration}.
153
- * @public
154
- */
155
- export const containerContextDecl: Converter<Normalized.IContainerContextDecl> =
156
- Converters.strictObject<Normalized.IContainerContextDecl>({
157
- baseId: Converters.oneOf([CommonConvert.resourceId, Converters.literal('')]).optional(),
158
- conditions: conditionSetDecl.optional(),
159
- mergeMethod: CommonConvert.resourceValueMergeMethod.optional()
160
- });
161
-
162
- /**
163
- * `Converter` for a normalized {@link ResourceJson.Normalized.IResourceTreeChildNodeDecl | resource tree child node declaration}.
164
- * @public
165
- */
166
- export const resourceTreeChildNodeDecl: Converter<Normalized.IResourceTreeChildNodeDecl> = Converters.generic<
167
- Normalized.IResourceTreeChildNodeDecl,
168
- unknown
169
- >(
170
- (
171
- from: unknown,
172
- self: Converter<Normalized.IResourceTreeChildNodeDecl, unknown>,
173
- context?: unknown
174
- ): Result<Normalized.IResourceTreeChildNodeDecl> => {
175
- return Converters.strictObject<Normalized.IResourceTreeChildNodeDecl>({
176
- resources: Converters.recordOf(childResourceDecl).optional(),
177
- children: Converters.recordOf(self).optional()
178
- }).convert(from, context);
179
- }
180
- );
181
-
182
- /**
183
- * `Converter` for a normalized {@link ResourceJson.Normalized.IResourceTreeRootDecl | resource tree root declaration}.
184
- * @public
185
- */
186
- export const resourceTreeRootDecl: Converter<Normalized.IResourceTreeRootDecl> =
187
- Converters.strictObject<Normalized.IResourceTreeRootDecl>({
188
- context: containerContextDecl.optional(),
189
- resources: Converters.recordOf(childResourceDecl).optional(),
190
- children: Converters.recordOf(resourceTreeChildNodeDecl).optional()
191
- });
192
-
193
- /**
194
- * `Converter` for a normalized {@link ResourceJson.Normalized.IResourceCollectionDecl | resource collection declaration}.
195
- * @public
196
- */
197
- export const resourceCollectionDecl: Converter<Normalized.IResourceCollectionDecl> = Converters.generic<
198
- Normalized.IResourceCollectionDecl,
199
- unknown
200
- >(
201
- (
202
- from: unknown,
203
- self: Converter<Normalized.IResourceCollectionDecl, unknown>,
204
- context?: unknown
205
- ): Result<Normalized.IResourceCollectionDecl> => {
206
- return Converters.strictObject<Normalized.IResourceCollectionDecl>({
207
- context: containerContextDecl.optional(),
208
- candidates: Converters.arrayOf(looseResourceCandidateDecl).optional(),
209
- resources: Converters.arrayOf(looseResourceDecl).optional(),
210
- collections: Converters.arrayOf(self).optional(),
211
- metadata: JsonConverters.jsonObject.optional()
212
- }).convert(from, context);
213
- }
214
- );
215
-
216
- /**
217
- * `Converter` for a normalized {@link ResourceJson.Normalized.IImporterResourceCollectionDecl | importer resource collection declaration}.
218
- * This allows for a mix of loose and child resource declarations.
219
- * @public
220
- */
221
- export const importerResourceCollectionDecl: Converter<Normalized.IImporterResourceCollectionDecl> =
222
- Converters.generic<Normalized.IImporterResourceCollectionDecl, unknown>(
223
- (
224
- from: unknown,
225
- self: Converter<Normalized.IImporterResourceCollectionDecl, unknown>,
226
- context?: unknown
227
- ): Result<Normalized.IImporterResourceCollectionDecl> => {
228
- return Converters.strictObject<Normalized.IImporterResourceCollectionDecl>({
229
- context: containerContextDecl.optional(),
230
- candidates: Converters.arrayOf(importerResourceCandidateDecl).optional(),
231
- resources: Converters.arrayOf(Converters.oneOf([looseResourceDecl, childResourceDecl])).optional(),
232
- collections: Converters.arrayOf(self).optional(),
233
- metadata: JsonConverters.jsonObject.optional()
234
- }).convert(from, context);
235
- }
236
- );
@@ -1,284 +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 { mapResults, Result, fail, succeed } from '@fgv/ts-utils';
24
- import * as Normalized from './normalized';
25
- import * as Json from './json';
26
- import { Helpers as CommonHelpers } from '../common';
27
- import { sanitizeJsonObject } from '@fgv/ts-json-base';
28
-
29
- /**
30
- * Common options when creating or displaying declarations.
31
- * @public
32
- */
33
- export interface IDeclarationOptions {
34
- /**
35
- * If `true`, properties with default values will be included in the
36
- * output. If omitted or `false`, properties with default values will be omitted.
37
- */
38
- showDefaults?: boolean;
39
-
40
- /**
41
- * If `true`, the output will be normalized using hash-based ordering for consistent structure.
42
- * If omitted or `false`, no normalization will be applied. Defaults to `false`.
43
- */
44
- normalized?: boolean;
45
- }
46
-
47
- /**
48
- * Helper method to merge a resource context declaration with a parent name and conditions.
49
- * @param decl - The resource context declaration to merge.
50
- * @param parentName - The name of the parent resource.
51
- * @param parentConditions - The conditions of the parent resource.
52
- * @returns `Success` with the merged resource context declaration if successful, otherwise `Failure`.
53
- * @public
54
- */
55
- export function mergeContextDecl(
56
- decl?: Normalized.IContainerContextDecl,
57
- parentName?: string,
58
- parentConditions?: ReadonlyArray<Json.ILooseConditionDecl>
59
- ): Result<Normalized.IContainerContextDecl> {
60
- if (!decl) {
61
- return sanitizeJsonObject({ baseId: parentName, conditions: parentConditions });
62
- } else if (!parentName && !parentConditions) {
63
- return succeed(decl);
64
- }
65
- switch (decl.mergeMethod ?? 'augment') {
66
- case 'augment':
67
- return CommonHelpers.joinResourceIds(parentName, decl.baseId).onSuccess((baseId) => {
68
- /* c8 ignore next 1 - defense in depth */
69
- const conditions = [...(parentConditions ?? []), ...(decl.conditions ?? [])];
70
- return sanitizeJsonObject({ baseId, conditions });
71
- });
72
- case 'replace': {
73
- const baseId = decl.baseId ?? parentName;
74
- const conditions = decl.conditions ?? parentConditions;
75
- return sanitizeJsonObject({ baseId, conditions });
76
- }
77
- case 'delete': {
78
- return sanitizeJsonObject({});
79
- }
80
- }
81
- }
82
-
83
- /**
84
- * Helper method to merge a loose candidate with a base name and conditions.
85
- * @param candidate - The candidate to merge.
86
- * @param baseName - The base name to merge with the candidate.
87
- * @param baseConditions - The base conditions to merge with the candidate.
88
- * @returns `Success` with the merged candidate if successful, otherwise `Failure`.
89
- * @public
90
- */
91
- export function mergeLooseCandidate(
92
- candidate: Normalized.IImporterResourceCandidateDecl,
93
- baseName?: string,
94
- baseConditions?: ReadonlyArray<Json.ILooseConditionDecl>
95
- ): Result<Normalized.ILooseResourceCandidateDecl> {
96
- const candidateId = Json.isLooseResourceCandidateDecl(candidate) ? candidate.id : '';
97
- if (!Json.isLooseResourceCandidateDecl(candidate) && !baseName) {
98
- return fail('id is required in mergeLooseCandidate');
99
- }
100
-
101
- return CommonHelpers.joinResourceIds(baseName, candidateId).onSuccess((id) => {
102
- /* c8 ignore next 1 - defense in depth */
103
- const conditions = [...(baseConditions ?? []), ...(candidate.conditions ?? [])];
104
- return succeed({ ...candidate, id, conditions });
105
- });
106
- }
107
-
108
- /**
109
- * Helper method to merge a resource candidate with a base name and conditions from import context.
110
- * This function enables name inheritance for resource candidates, similar to resources.
111
- *
112
- * @param candidate - The candidate to merge. Can have an optional ID that will be joined with baseName.
113
- * @param baseName - The base name from import context to merge with the candidate.
114
- * When provided, this will be used as the parent component of the candidate ID.
115
- * @param baseConditions - The base conditions from import context to merge with the candidate's conditions.
116
- * @returns `Success` with the merged candidate if successful, otherwise `Failure`.
117
- *
118
- * @remarks
119
- * This function supports name inheritance for candidates:
120
- * - Joins baseName with candidate's existing ID using dot notation
121
- * - If candidate has no ID, uses baseName as the full ID
122
- * - Always merges base conditions with candidate's existing conditions
123
- *
124
- * @example
125
- * ```typescript
126
- * // Candidate inherits full name from import context
127
- * const candidate = { value: "Hello", conditions: [...] }; // No id field
128
- * const result = mergeImporterCandidate(candidate, "pages.home.greeting", []);
129
- * // Result: { id: "pages.home.greeting", value: "Hello", conditions: [...] }
130
- * ```
131
- *
132
- * @public
133
- */
134
- export function mergeImporterCandidate(
135
- candidate: Normalized.IImporterResourceCandidateDecl,
136
- baseName?: string,
137
- baseConditions?: ReadonlyArray<Json.ILooseConditionDecl>
138
- ): Result<Normalized.IImporterResourceCandidateDecl> {
139
- if (baseName || Json.isLooseResourceCandidateDecl(candidate)) {
140
- const candidateId = 'id' in candidate ? candidate.id : '';
141
- return CommonHelpers.joinResourceIds(baseName, candidateId).onSuccess((id) => {
142
- /* c8 ignore next 1 - defense in depth */
143
- const conditions = [...(baseConditions ?? []), ...(candidate.conditions ?? [])];
144
- return succeed({ ...candidate, id, conditions });
145
- });
146
- } else {
147
- /* c8 ignore next 1 - defense in depth */
148
- const conditions = [...(baseConditions ?? []), ...(candidate.conditions ?? [])];
149
- return succeed({ ...candidate, conditions });
150
- }
151
- }
152
-
153
- /**
154
- * Helper method to merge a child candidate with base conditions.
155
- * @param candidate - The candidate to merge.
156
- * @param baseConditions - The base conditions to merge with the candidate.
157
- * @returns `Success` with the merged candidate if successful, otherwise `Failure`.
158
- * @public
159
- */
160
- export function mergeChildCandidate(
161
- candidate: Normalized.IChildResourceCandidateDecl,
162
- baseConditions?: ReadonlyArray<Json.ILooseConditionDecl>
163
- ): Result<Normalized.IChildResourceCandidateDecl> {
164
- /* c8 ignore next 1 - defense in depth */
165
- const conditions = [...(baseConditions ?? []), ...(candidate.conditions ?? [])];
166
- return succeed({ ...candidate, conditions });
167
- }
168
-
169
- /**
170
- * Helper method to merge a loose resource with a base name and conditions.
171
- * @param resource - The resource to merge.
172
- * @param baseName - The base name to merge with the resource.
173
- * @param baseConditions - The base conditions to merge with the resource.
174
- * @returns `Success` with the merged resource if successful, otherwise `Failure`.
175
- * @public
176
- */
177
- export function mergeLooseResource(
178
- resource: Normalized.IImporterResourceDecl,
179
- baseName?: string,
180
- baseConditions?: ReadonlyArray<Json.ILooseConditionDecl>
181
- ): Result<Normalized.ILooseResourceDecl> {
182
- /* c8 ignore next 1 - defense in depth */
183
- const resourceId = Json.isLooseResourceDecl(resource) ? resource.id : '';
184
- if (!baseName && !Json.isLooseResourceDecl(resource)) {
185
- return fail('id is required in mergeLooseResource');
186
- }
187
-
188
- return CommonHelpers.joinResourceIds(baseName, resourceId).onSuccess((id) => {
189
- return mapResults(
190
- /* c8 ignore next 1 - defense in depth */
191
- (resource.candidates ?? []).map((candidate) => mergeChildCandidate(candidate, baseConditions))
192
- ).onSuccess((candidates) => {
193
- return succeed({ ...resource, id, candidates });
194
- });
195
- });
196
- }
197
-
198
- /**
199
- * Helper method to merge a resource with a base name and conditions from import context.
200
- * This function enables name inheritance where resources can automatically inherit their
201
- * resource ID from the import context when no explicit ID is provided in the resource declaration.
202
- *
203
- * @param resource - The resource to merge. Can be either a loose resource (with optional ID)
204
- * or a child resource (without ID).
205
- * @param baseName - The base name from import context to merge with the resource.
206
- * When provided, this will be used as the parent component of the resource ID.
207
- * @param baseConditions - The base conditions from import context to merge with the resource's conditions.
208
- * @returns `Success` with the merged resource if successful, otherwise `Failure`.
209
- *
210
- * @remarks
211
- * This function supports several scenarios for name inheritance:
212
- * - **Explicit ID + Base Name**: Joins baseName.resourceId (e.g., "pages.home" + "greeting" = "pages.home.greeting")
213
- * - **No ID + Base Name**: Uses baseName as the resource ID (enables name inheritance from import context)
214
- * - **Explicit ID + No Base Name**: Uses the resource's existing ID
215
- * - **No ID + No Base Name**: Returns resource without ID (for child resources)
216
- *
217
- * Base conditions are always merged with the resource's existing conditions.
218
- *
219
- * @example
220
- * ```typescript
221
- * // Resource without ID inherits name from import context
222
- * const resource = { candidates: [...] }; // No id field
223
- * const result = mergeImporterResource(resource, "pages.home", []);
224
- * // Result: { id: "pages.home", candidates: [...] }
225
- *
226
- * // Resource with ID gets joined with base name
227
- * const resource = { id: "greeting", candidates: [...] };
228
- * const result = mergeImporterResource(resource, "pages.home", []);
229
- * // Result: { id: "pages.home.greeting", candidates: [...] }
230
- * ```
231
- *
232
- * @public
233
- */
234
- export function mergeImporterResource(
235
- resource: Normalized.IImporterResourceDecl,
236
- baseName?: string,
237
- baseConditions?: ReadonlyArray<Json.ILooseConditionDecl>
238
- ): Result<Normalized.IImporterResourceDecl> {
239
- if (baseName || `id` in resource) {
240
- const resourceId = 'id' in resource ? resource.id : '';
241
- // If we have a base name or the resource has no id, we can just
242
- return CommonHelpers.joinResourceIds(baseName, resourceId).onSuccess((id) => {
243
- return mapResults(
244
- /* c8 ignore next 1 - defense in depth */
245
- (resource.candidates ?? []).map((candidate) => mergeChildCandidate(candidate, baseConditions))
246
- ).onSuccess((candidates) => {
247
- return succeed({ ...resource, id, candidates });
248
- });
249
- });
250
- } else {
251
- return mapResults(
252
- /* c8 ignore next 1 - defense in depth */
253
- (resource.candidates ?? []).map((candidate) => mergeChildCandidate(candidate, baseConditions))
254
- ).onSuccess((candidates) => {
255
- return succeed({ ...resource, candidates });
256
- });
257
- }
258
- }
259
-
260
- /**
261
- * Helper method to merge a child resource with a parent name and conditions.
262
- * @param resource - The resource to merge.
263
- * @param name - The name of the resource.
264
- *
265
- * @param parentName - The name of the parent resource.
266
- * @param parentConditions - The conditions of the parent resource.
267
- * @returns `Success` with the merged resource if successful, otherwise `Failure`.
268
- * @public
269
- */
270
- export function mergeChildResource(
271
- resource: Normalized.IChildResourceDecl,
272
- name: string,
273
- parentName?: string,
274
- parentConditions?: ReadonlyArray<Json.ILooseConditionDecl>
275
- ): Result<Normalized.ILooseResourceDecl> {
276
- return CommonHelpers.joinResourceIds(parentName, name).onSuccess((id) => {
277
- return mapResults(
278
- /* c8 ignore next 1 - defense in depth */
279
- (resource.candidates ?? []).map((candidate) => mergeChildCandidate(candidate, parentConditions))
280
- ).onSuccess((candidates) => {
281
- return succeed({ ...resource, id, candidates });
282
- });
283
- });
284
- }
@@ -1,33 +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 * as Compiled from './compiled';
24
- import * as Convert from './convert';
25
- import * as Helpers from './helpers';
26
- import * as Json from './json';
27
- import * as Normalized from './normalized';
28
-
29
- export { Compiled, Convert, Helpers, Json, Normalized };
30
-
31
- export * from './resourceDeclContainer';
32
- export * from './resourceDeclCollection';
33
- export * from './resourceDeclTree';