@cloudcannon/configuration-loader 0.0.7 → 0.0.8

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.
package/src/loader.ts DELETED
@@ -1,525 +0,0 @@
1
- import type { Configuration, StructureValue } from '@cloudcannon/configuration-types';
2
- import type {
3
- GlobLoaderWarnings,
4
- GlobResult,
5
- GlobTypeKey,
6
- MergeConfigurationOptions,
7
- } from './types.ts';
8
-
9
- export type { GlobLoaderWarnings, GlobResult, GlobTypeKey, MergeConfigurationOptions };
10
-
11
- function isObject<T = unknown>(maybeObject?: unknown): maybeObject is Record<string, T> {
12
- return maybeObject !== null && typeof maybeObject === 'object' && !Array.isArray(maybeObject);
13
- }
14
-
15
- class ConfigurationLoader {
16
- warnings: GlobLoaderWarnings;
17
- pathsToGlobKey: Record<string, GlobTypeKey> = {};
18
- globKeyToPaths: Record<GlobTypeKey, Set<string>> = {
19
- _structures_from_glob: new Set(),
20
- values_from_glob: new Set(),
21
- _snippets_from_glob: new Set(),
22
- _snippets_imports_from_glob: new Set(),
23
- _snippets_templates_from_glob: new Set(),
24
- _snippets_definitions_from_glob: new Set(),
25
- _inputs_from_glob: new Set(),
26
- _editables_from_glob: new Set(),
27
- collections_config_from_glob: new Set(),
28
- schemas_from_glob: new Set(),
29
- };
30
-
31
- globPatterns: Set<string>;
32
-
33
- findFilesMatchingGlobs: (globs: string[]) => string[];
34
- loadConfigFile: (filePath: string) => Promise<unknown>;
35
-
36
- constructor(
37
- findFilesMatchingGlobs: (globs: string[]) => string[],
38
- loadConfigFile: (filePath: string) => Promise<unknown>
39
- ) {
40
- this.warnings = {
41
- cycles: [],
42
- multipleGlobKeys: [],
43
- arrayValues: [],
44
- };
45
- this.globPatterns = new Set();
46
- this.findFilesMatchingGlobs = findFilesMatchingGlobs;
47
- this.loadConfigFile = loadConfigFile;
48
- }
49
-
50
- /**
51
- * Loads and merges configuration from files matching glob patterns.
52
- * Processes all *_from_glob keys in the configuration.
53
- * Recursively processes globs in loaded files as well.
54
- * Also extracts glob patterns from loaded files for change detection.
55
- */
56
- public async mergeConfiguration(config: Configuration): Promise<Configuration> {
57
- this.warnings = {
58
- cycles: [],
59
- multipleGlobKeys: [],
60
- arrayValues: [],
61
- };
62
- this.globPatterns.clear();
63
-
64
- // Process root-level glob keys in the correct order
65
- await this.importFromGlobKey(config, '_snippets_from_glob', '_snippets', false);
66
- await this.importFromGlobKey(config, '_snippets_imports_from_glob', '_snippets_imports', false);
67
- await this.importFromGlobKey(
68
- config,
69
- '_snippets_templates_from_glob',
70
- '_snippets_templates',
71
- false
72
- );
73
- await this.importFromGlobKey(
74
- config,
75
- '_snippets_definitions_from_glob',
76
- '_snippets_definitions',
77
- false
78
- );
79
- await this.importFromGlobKey(
80
- config,
81
- 'collections_config_from_glob',
82
- 'collections_config',
83
- false
84
- );
85
- await this.importFromGlobKey(config, '_inputs_from_glob', '_inputs', false);
86
- await this.importFromGlobKey(config, '_structures_from_glob', '_structures', false);
87
-
88
- await this.processInputsKey(config._inputs);
89
- await this.processStructuresKey(config._structures);
90
-
91
- // Process nested globs in collections_config
92
- // Collections can have: schemas_from_glob, _inputs_from_glob, _structures_from_glob
93
- if (config.collections_config && isObject(config.collections_config)) {
94
- for (const [collectionKey, collectionConfig] of Object.entries(config.collections_config)) {
95
- if (isObject(collectionConfig)) {
96
- // Process schemas_from_glob (first in collections)
97
- if ('schemas_from_glob' in collectionConfig) {
98
- await this.importFromGlobKey(collectionConfig, 'schemas_from_glob', 'schemas', false);
99
- }
100
-
101
- const collection = (config.collections_config as Record<string, unknown>)[collectionKey];
102
- await this.importFromGlobKey(
103
- collection as Record<string, unknown>,
104
- '_inputs_from_glob',
105
- '_inputs',
106
- false
107
- );
108
- await this.importFromGlobKey(
109
- collection as Record<string, unknown>,
110
- '_structures_from_glob',
111
- '_structures',
112
- false
113
- );
114
-
115
- await this.processInputsKey(
116
- (collection as Record<string, unknown>)._inputs as Configuration['_inputs']
117
- );
118
- await this.processStructuresKey(
119
- (collection as Record<string, unknown>)._structures as Configuration['_structures']
120
- );
121
-
122
- // Process recursive globs in schemas
123
- if (isObject((collection as Record<string, unknown>).schemas)) {
124
- for (const schemaValue of Object.values(
125
- (collection as Record<string, unknown>).schemas as Record<string, unknown>
126
- )) {
127
- if (isObject(schemaValue)) {
128
- await this.importFromGlobKey(schemaValue, '_inputs_from_glob', '_inputs', false);
129
- await this.importFromGlobKey(
130
- schemaValue,
131
- '_structures_from_glob',
132
- '_structures',
133
- false
134
- );
135
-
136
- await this.processInputsKey(schemaValue._inputs as Configuration['_inputs']);
137
- await this.processStructuresKey(
138
- schemaValue._structures as Configuration['_structures']
139
- );
140
- }
141
- }
142
- }
143
- }
144
- }
145
- }
146
-
147
- // Process recursive globs in _snippets (can have _inputs_from_glob)
148
- if (config._snippets && isObject(config._snippets)) {
149
- await this.importFromGlobKey(config._snippets, '_inputs_from_glob', '_inputs', false);
150
-
151
- for (const snippetConfig of Object.values(config._snippets)) {
152
- if (isObject(snippetConfig)) {
153
- await this.importFromGlobKey(snippetConfig, '_inputs_from_glob', '_inputs', false);
154
- await this.importFromGlobKey(
155
- snippetConfig,
156
- '_structures_from_glob',
157
- '_structures',
158
- false
159
- );
160
-
161
- await this.processInputsKey(snippetConfig._inputs as Configuration['_inputs']);
162
- await this.processStructuresKey(
163
- snippetConfig._structures as Configuration['_structures']
164
- );
165
- }
166
- }
167
- }
168
-
169
- return config;
170
- }
171
-
172
- /*
173
- * Process recursive globs in _inputs (can have _structures_from_glob)
174
- * @param inputs - The _inputs key to process
175
- * @returns A promise that resolves when the inputs key has been processed
176
- */
177
- private async processInputsKey(
178
- inputs: Configuration['_inputs'],
179
- visited?: Set<string>
180
- ): Promise<void> {
181
- if (inputs && isObject(inputs)) {
182
- for (const inputValue of Object.values(inputs)) {
183
- if (isObject(inputValue) && isObject((inputValue as Record<string, unknown>).options)) {
184
- const structures = (
185
- (inputValue as Record<string, unknown>).options as Record<string, unknown>
186
- )?.structures;
187
- const visitedLocal = visited || new Set<string>();
188
-
189
- if (structures && isObject(structures)) {
190
- if (structures.values_from_glob) {
191
- await this.importFromGlobKey(
192
- structures,
193
- 'values_from_glob',
194
- 'values',
195
- true,
196
- visitedLocal
197
- );
198
- }
199
-
200
- if (Array.isArray(structures.values)) {
201
- await Promise.all(
202
- structures.values.map(async (value: StructureValue) =>
203
- this.processStructureValue(value, visitedLocal)
204
- )
205
- );
206
- }
207
- }
208
- }
209
- }
210
- }
211
- }
212
-
213
- private async processStructuresKey(
214
- structures: Configuration['_structures'],
215
- visited?: Set<string>
216
- ): Promise<void> {
217
- if (!structures || !isObject(structures)) {
218
- return;
219
- }
220
-
221
- await Promise.all(
222
- Object.values(structures).map(async (structure) => {
223
- if (!isObject(structure)) {
224
- return;
225
- }
226
- const visitedLocal = visited || new Set<string>();
227
-
228
- await this.importFromGlobKey(structure, 'values_from_glob', 'values', true, visitedLocal);
229
-
230
- if (structure.values && Array.isArray(structure.values)) {
231
- await Promise.all(
232
- structure.values.map(async (value) =>
233
- this.processStructureValue(value as StructureValue, visitedLocal)
234
- )
235
- );
236
- }
237
- })
238
- );
239
- }
240
-
241
- private async processStructureValue(
242
- structureValue: StructureValue,
243
- visited: Set<string>
244
- ): Promise<void> {
245
- if (!structureValue || !isObject(structureValue)) {
246
- return;
247
- }
248
-
249
- if ((structureValue as Record<string, unknown>)._inputs_from_glob) {
250
- await this.importFromGlobKey(
251
- structureValue as Record<string, unknown>,
252
- '_inputs_from_glob',
253
- '_inputs',
254
- false,
255
- visited
256
- );
257
- }
258
-
259
- if (structureValue._inputs) {
260
- await this.processInputsKey(structureValue._inputs, visited);
261
- }
262
- }
263
-
264
- /**
265
- * Processes a glob key by loading files and merging them with the target key.
266
- * Supports recursive processing with cycle detection.
267
- */
268
- private async importFromGlobKey(
269
- config: Record<string, unknown>,
270
- globKey: GlobTypeKey,
271
- targetKey: string,
272
- isArray: boolean,
273
- visited?: Set<string>
274
- ): Promise<void> {
275
- const globs = config[globKey];
276
-
277
- if (!Array.isArray(globs)) {
278
- return;
279
- }
280
-
281
- globs.forEach((pattern) => {
282
- if (typeof pattern === 'string' && !pattern.startsWith('!')) {
283
- this.globPatterns.add(pattern);
284
- }
285
- });
286
- const loadedDataWithSources = await this.loadFilesFromGlobs(
287
- globs as string[],
288
- globKey,
289
- visited
290
- );
291
-
292
- if (isArray) {
293
- config[targetKey] = this.mergeArrayValues(
294
- (config[targetKey] || []) as unknown[],
295
- loadedDataWithSources
296
- );
297
- } else {
298
- config[targetKey] = this.mergeObjectValues(
299
- (config[targetKey] || {}) as Record<string, unknown>,
300
- loadedDataWithSources
301
- );
302
- }
303
-
304
- delete config[globKey];
305
- }
306
-
307
- /**
308
- * Loads configuration data from files matching the given glob patterns.
309
- * Returns an array of parsed configuration objects with source tracking.
310
- */
311
- private async loadFilesFromGlobs(
312
- globs: string[],
313
- globKey: GlobTypeKey,
314
- visited?: Set<string>
315
- ): Promise<Array<{ data: unknown; source: string }>> {
316
- const matchingFiles = this.findFilesMatchingGlobs(globs);
317
- // Sort by path to ensure consistent ordering
318
- matchingFiles.sort((a, b) => a.localeCompare(b));
319
- const loadedData: Array<{ data: unknown; source: string }> = [];
320
-
321
- for (const filePath of matchingFiles) {
322
- if (visited?.has(filePath)) {
323
- this.warnings.cycles.push({
324
- path: filePath,
325
- chain: Array.from(visited),
326
- });
327
- continue;
328
- }
329
-
330
- const existingGlobKey = this.pathsToGlobKey[filePath];
331
- if (existingGlobKey && existingGlobKey !== globKey) {
332
- this.warnings.multipleGlobKeys.push({
333
- path: filePath,
334
- type1: existingGlobKey,
335
- type2: globKey,
336
- });
337
- continue;
338
- }
339
-
340
- this.pathsToGlobKey[filePath] = globKey;
341
- this.globKeyToPaths[globKey].add(filePath);
342
-
343
- visited?.add(filePath);
344
-
345
- try {
346
- const data = await this.loadConfigFile(filePath);
347
-
348
- if (data !== undefined && data !== null) {
349
- const clonedData = JSON.parse(JSON.stringify(data)) as unknown;
350
- // Handle both single objects and arrays
351
-
352
- if (Array.isArray(clonedData)) {
353
- this.warnings.arrayValues.push({
354
- path: filePath,
355
- });
356
- } else {
357
- loadedData.push({ data: clonedData, source: filePath });
358
- }
359
- }
360
- } catch {
361
- // Log error but continue processing other files
362
- }
363
- }
364
-
365
- return loadedData;
366
- }
367
-
368
- /**
369
- * Merges object values from globbed files.
370
- * Later files overwrite earlier ones for the same keys.
371
- * Adds __source__ metadata to track where each key came from.
372
- */
373
- private mergeObjectValues(
374
- base: Record<string, unknown>,
375
- loaded: Array<{ data: unknown; source: string }>
376
- ): Record<string, unknown> {
377
- const result = { ...base };
378
-
379
- for (const { data: item, source } of loaded) {
380
- if (isObject(item)) {
381
- // For objects, merge keys (later overwrites earlier)
382
- // Add __source__ to each key that gets added/overwritten
383
- for (const [key, value] of Object.entries(item)) {
384
- if (isObject(value)) {
385
- // Add __source__ to nested objects (e.g., input definitions, schema configs)
386
- result[key] = {
387
- ...value,
388
- __source__: source,
389
- };
390
- } else {
391
- // For primitive values, just assign the value
392
- // The source is tracked at the key level via __sources__ if needed
393
- result[key] = value;
394
- }
395
- }
396
- }
397
- }
398
-
399
- return result;
400
- }
401
-
402
- /**
403
- * Merges array values from globbed files.
404
- * Arrays are appended (no overwriting since arrays aren't keyed).
405
- * Adds __source__ metadata to track where each item came from.
406
- */
407
- private mergeArrayValues(
408
- base: unknown[],
409
- loaded: Array<{ data: unknown; source: string }>
410
- ): unknown[] {
411
- const result = [...base];
412
-
413
- for (const { data: item, source } of loaded) {
414
- if (Array.isArray(item)) {
415
- // If the loaded item is an array, add source to each element
416
- for (const element of item) {
417
- if (isObject(element)) {
418
- result.push({
419
- ...element,
420
- __source__: source,
421
- });
422
- } else {
423
- // Otherwise, add it as a single item
424
- // This cannot be tracked with __source__ since it's not an object
425
- result.push(element);
426
- }
427
- }
428
- } else if (isObject(item)) {
429
- // Add __source__ to object items
430
- result.push({
431
- ...item,
432
- __source__: source,
433
- });
434
- } else {
435
- // Otherwise, add it as a single item
436
- // This cannot be tracked with __source__ since it's not an object
437
- result.push(item);
438
- }
439
- }
440
-
441
- return result;
442
- }
443
- }
444
-
445
- function removeDuplicateWarnings(warnings: GlobLoaderWarnings): GlobLoaderWarnings {
446
- const result: GlobLoaderWarnings = {
447
- cycles: [],
448
- multipleGlobKeys: [],
449
- arrayValues: [],
450
- };
451
-
452
- for (const warning of warnings.cycles) {
453
- if (
454
- !result.cycles.some(
455
- (w) => w.path === warning.path && w.chain.join(' → ') === warning.chain.join(' → ')
456
- )
457
- ) {
458
- result.cycles.push(warning);
459
- }
460
- }
461
-
462
- for (const warning of warnings.multipleGlobKeys) {
463
- if (
464
- !result.multipleGlobKeys.some(
465
- (w) => w.path === warning.path && w.type1 === warning.type1 && w.type2 === warning.type2
466
- )
467
- ) {
468
- result.multipleGlobKeys.push(warning);
469
- }
470
- }
471
-
472
- for (const warning of warnings.arrayValues) {
473
- if (!result.arrayValues.some((w) => w.path === warning.path)) {
474
- result.arrayValues.push(warning);
475
- }
476
- }
477
-
478
- return result;
479
- }
480
-
481
- /**
482
- * Merges split CloudCannon configuration files into a single configuration object.
483
- *
484
- * This function processes `*_from_glob` keys in the configuration, loading and merging
485
- * configuration from files matching the specified glob patterns. This allows you to
486
- * split your CloudCannon configuration across multiple files for better organization.
487
- *
488
- * @param config - The base CloudCannon configuration object
489
- * @param options - Options for loading configuration files
490
- * @returns A promise resolving to the merged configuration with metadata
491
- *
492
- * @example
493
- * ```typescript
494
- * import { mergeConfiguration } from '@cloudcannon/configuration-loader';
495
- * import { globSync } from 'glob';
496
- * import { readFileSync } from 'fs';
497
- * import YAML from 'yaml';
498
- *
499
- * const baseConfig = YAML.parse(readFileSync('cloudcannon.config.yml', 'utf8'));
500
- *
501
- * const result = await mergeConfiguration(baseConfig, {
502
- * findFilesMatchingGlobs: (globs) => globSync(globs, { ignore: globs.filter(g => g.startsWith('!')).map(g => g.slice(1)) }),
503
- * loadConfigFile: async (filePath) => YAML.parse(readFileSync(filePath, 'utf8'))
504
- * });
505
- *
506
- * console.log(result.config); // Merged configuration
507
- * ```
508
- */
509
- export async function mergeConfiguration(
510
- config: Configuration,
511
- options: MergeConfigurationOptions
512
- ): Promise<GlobResult> {
513
- const loader = new ConfigurationLoader(options.findFilesMatchingGlobs, options.loadConfigFile);
514
- const result = await loader.mergeConfiguration(
515
- JSON.parse(JSON.stringify(config)) as Configuration
516
- );
517
-
518
- return {
519
- config: result,
520
- warnings: removeDuplicateWarnings(loader.warnings),
521
- globPatterns: Array.from(loader.globPatterns),
522
- pathsToGlobKey: loader.pathsToGlobKey,
523
- globKeyToPaths: loader.globKeyToPaths,
524
- };
525
- }
package/src/types.ts DELETED
@@ -1,101 +0,0 @@
1
- import type { Configuration } from '@cloudcannon/configuration-types';
2
-
3
- /**
4
- * All supported glob key types that can be used to split configuration.
5
- */
6
- export type GlobTypeKey =
7
- | '_structures_from_glob'
8
- | 'values_from_glob'
9
- | '_snippets_from_glob'
10
- | '_snippets_imports_from_glob'
11
- | '_snippets_templates_from_glob'
12
- | '_snippets_definitions_from_glob'
13
- | '_inputs_from_glob'
14
- | '_editables_from_glob'
15
- | 'collections_config_from_glob'
16
- | 'schemas_from_glob';
17
-
18
- /**
19
- * Warnings generated during configuration loading.
20
- * These indicate potential issues that may cause unexpected behavior.
21
- */
22
- export interface GlobLoaderWarnings {
23
- /**
24
- * Circular references detected in configuration files.
25
- *
26
- * This occurs when a structure value loaded via `values_from_glob` contains
27
- * nested structures that reference a file already being processed in the
28
- * current chain. The file is skipped to prevent infinite recursion.
29
- *
30
- * To fix: restructure your configuration to avoid self-referencing patterns,
31
- * or use separate files for nested structure definitions.
32
- *
33
- * @property path - The file path that caused the cycle
34
- * @property chain - The sequence of files that led to this cycle
35
- */
36
- cycles: { path: string; chain: string[] }[];
37
-
38
- /**
39
- * Files that were matched by multiple different glob key types.
40
- *
41
- * This occurs when the same file matches glob patterns for different
42
- * configuration sections (e.g., both `collections_config_from_glob` and
43
- * `_inputs_from_glob`). The file is only processed for the first matching
44
- * glob key type; subsequent matches are skipped.
45
- *
46
- * To fix: use more specific glob patterns to ensure each file is only
47
- * matched by one glob key type, or organize files into separate directories.
48
- *
49
- * @property path - The file path that matched multiple glob types
50
- * @property type1 - The first glob key type that matched (file was processed for this)
51
- * @property type2 - The second glob key type that matched (file was skipped)
52
- */
53
- multipleGlobKeys: { path: string; type1: GlobTypeKey; type2: GlobTypeKey }[];
54
-
55
- /**
56
- * Files containing arrays instead of objects.
57
- *
58
- * Configuration files loaded via `*_from_glob` keys must contain objects
59
- * (key-value pairs), not arrays. Files containing arrays are skipped and
60
- * not merged into the configuration.
61
- *
62
- * To fix: ensure your configuration files export objects. For example,
63
- * use `posts: { path: "..." }` instead of `[{ posts: { path: "..." } }]`.
64
- *
65
- * @property path - The file path containing an array
66
- */
67
- arrayValues: { path: string }[];
68
- }
69
-
70
- /**
71
- * Result of merging split configuration files.
72
- */
73
- export interface GlobResult {
74
- /** The merged configuration object */
75
- config: Configuration;
76
- /** Warnings about potential issues encountered during loading */
77
- warnings: GlobLoaderWarnings;
78
- /** All glob patterns found (useful for file watching) */
79
- globPatterns: string[];
80
- /** Mapping from file paths to the glob key type that loaded them */
81
- pathsToGlobKey: Record<string, GlobTypeKey>;
82
- /** Mapping from glob key types to the set of file paths they loaded */
83
- globKeyToPaths: Record<GlobTypeKey, Set<string>>;
84
- }
85
-
86
- /**
87
- * Options for the mergeConfiguration function.
88
- */
89
- export interface MergeConfigurationOptions {
90
- /**
91
- * Function to find files matching glob patterns.
92
- * Receives an array of glob patterns (including negation patterns starting with '!')
93
- * and should return an array of matching file paths.
94
- */
95
- findFilesMatchingGlobs: (globs: string[]) => string[];
96
- /**
97
- * Function to load and parse a configuration file.
98
- * Should return the parsed content of the file (typically YAML or JSON).
99
- */
100
- loadConfigFile: (filePath: string) => Promise<unknown>;
101
- }