@cloudcannon/configuration-loader 0.0.2
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/LICENSE +5 -0
- package/README.md +215 -0
- package/dist/browser.d.ts +20 -0
- package/dist/browser.d.ts.map +1 -0
- package/dist/index.d.ts +24 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/load.d.ts +36 -0
- package/dist/load.d.ts.map +1 -0
- package/dist/loader.d.ts +33 -0
- package/dist/loader.d.ts.map +1 -0
- package/dist/types.d.ts +95 -0
- package/dist/types.d.ts.map +1 -0
- package/package.json +69 -0
- package/src/browser.ts +30 -0
- package/src/index.ts +36 -0
- package/src/load.ts +125 -0
- package/src/loader.test.ts +528 -0
- package/src/loader.ts +525 -0
- package/src/types.ts +101 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
Copyright 2025 CloudCannon
|
|
2
|
+
|
|
3
|
+
Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
|
|
4
|
+
|
|
5
|
+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
# CloudCannon Configuration Loader
|
|
2
|
+
|
|
3
|
+
Load and merge CloudCannon configuration files that have been split across multiple files.
|
|
4
|
+
|
|
5
|
+
[<img src="https://img.shields.io/npm/v/@cloudcannon%2Fconfiguration-loader?logo=npm" alt="version badge">](https://www.npmjs.com/package/@cloudcannon%2Fconfiguration-loader)
|
|
6
|
+
|
|
7
|
+
This package brings the [configuration loading functionality](https://cloudcannon.com/documentation/articles/why-split-your-configuration-file/) from CloudCannon into your local development environment. It's particularly useful for:
|
|
8
|
+
|
|
9
|
+
- **Static site generators** that need access to CloudCannon configuration at build time
|
|
10
|
+
- **Custom integrations** like the [CloudCannon + Next.js starter](https://community.cloudcannon.com/t/a-cloudcannon-next-js-starter/305) that generate content schemas from CloudCannon config
|
|
11
|
+
- **Development tooling** that validates or processes CloudCannon configuration
|
|
12
|
+
|
|
13
|
+
## Requirements
|
|
14
|
+
|
|
15
|
+
- Node.js >= 22.6.0
|
|
16
|
+
|
|
17
|
+
## Installation
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npm install @cloudcannon/configuration-loader
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Usage
|
|
24
|
+
|
|
25
|
+
```typescript
|
|
26
|
+
import { loadConfiguration } from '@cloudcannon/configuration-loader';
|
|
27
|
+
|
|
28
|
+
const result = await loadConfiguration('cloudcannon.config.yml');
|
|
29
|
+
|
|
30
|
+
console.log(result.config);
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
That's it! The `loadConfiguration` function handles:
|
|
34
|
+
- Reading and parsing your configuration file (YAML or JSON)
|
|
35
|
+
- Finding all files matching `*_from_glob` patterns
|
|
36
|
+
- Merging everything into a single configuration object
|
|
37
|
+
|
|
38
|
+
### YAML Support
|
|
39
|
+
|
|
40
|
+
For YAML files, install `js-yaml`:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
npm install js-yaml
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
The loader will automatically detect and use it.
|
|
47
|
+
|
|
48
|
+
#### Why isn't the YAML parser included?
|
|
49
|
+
|
|
50
|
+
We don't bundle a YAML parser because:
|
|
51
|
+
|
|
52
|
+
1. **You likely already have one** — most projects using CloudCannon configuration already have `js-yaml` or similar installed for their build tooling
|
|
53
|
+
2. **Keeps the package lightweight** — no unnecessary dependencies if you only use JSON configs
|
|
54
|
+
3. **Flexibility** — you can use any YAML parser via the `parseFile` option if you prefer a different one
|
|
55
|
+
|
|
56
|
+
### Checking for Warnings
|
|
57
|
+
|
|
58
|
+
```typescript
|
|
59
|
+
const result = await loadConfiguration('cloudcannon.config.yml');
|
|
60
|
+
|
|
61
|
+
if (result.warnings.cycles.length > 0) {
|
|
62
|
+
console.warn('Circular references detected:', result.warnings.cycles);
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
if (result.warnings.arrayValues.length > 0) {
|
|
66
|
+
console.warn('Invalid array configs:', result.warnings.arrayValues);
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## API
|
|
71
|
+
|
|
72
|
+
### `loadConfiguration(configPath, options?)`
|
|
73
|
+
|
|
74
|
+
Loads and merges a CloudCannon configuration file with all its split configuration files.
|
|
75
|
+
|
|
76
|
+
```typescript
|
|
77
|
+
const result = await loadConfiguration('cloudcannon.config.yml');
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
#### Parameters
|
|
81
|
+
|
|
82
|
+
- `configPath` - Path to the CloudCannon configuration file
|
|
83
|
+
- `options.parseFile` - Optional custom parser function for file contents
|
|
84
|
+
|
|
85
|
+
#### Returns
|
|
86
|
+
|
|
87
|
+
### `mergeConfiguration(config, options)`
|
|
88
|
+
|
|
89
|
+
Lower-level API for custom implementations. Use this when you need full control over file loading and glob matching, or when running in a browser environment.
|
|
90
|
+
|
|
91
|
+
```typescript
|
|
92
|
+
import { mergeConfiguration } from '@cloudcannon/configuration-loader/browser';
|
|
93
|
+
|
|
94
|
+
const result = await mergeConfiguration(config, {
|
|
95
|
+
findFilesMatchingGlobs: (globs) => /* your glob implementation */,
|
|
96
|
+
loadConfigFile: async (path) => /* your file loader */
|
|
97
|
+
});
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
#### Parameters
|
|
101
|
+
|
|
102
|
+
- `config` - The base CloudCannon configuration object
|
|
103
|
+
- `options.findFilesMatchingGlobs` - Function that takes an array of glob patterns and returns matching file paths
|
|
104
|
+
- `options.loadConfigFile` - Async function that loads and parses a configuration file
|
|
105
|
+
|
|
106
|
+
#### Returns
|
|
107
|
+
|
|
108
|
+
A `GlobResult` object containing:
|
|
109
|
+
|
|
110
|
+
```typescript
|
|
111
|
+
interface GlobResult {
|
|
112
|
+
// The merged configuration
|
|
113
|
+
config: Configuration;
|
|
114
|
+
|
|
115
|
+
// Warnings about potential issues
|
|
116
|
+
warnings: {
|
|
117
|
+
// Circular references in configuration
|
|
118
|
+
cycles: { path: string; chain: string[] }[];
|
|
119
|
+
// Files matched by multiple different glob keys
|
|
120
|
+
multipleGlobKeys: { path: string; type1: GlobTypeKey; type2: GlobTypeKey }[];
|
|
121
|
+
// Files containing arrays instead of objects
|
|
122
|
+
arrayValues: { path: string }[];
|
|
123
|
+
};
|
|
124
|
+
|
|
125
|
+
// All glob patterns found (for file watching)
|
|
126
|
+
globPatterns: string[];
|
|
127
|
+
|
|
128
|
+
// Mapping from file paths to their glob key type
|
|
129
|
+
pathsToGlobKey: Record<string, GlobTypeKey>;
|
|
130
|
+
|
|
131
|
+
// Mapping from glob key types to matched file paths
|
|
132
|
+
globKeyToPaths: Record<GlobTypeKey, Set<string>>;
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## Browser Usage
|
|
137
|
+
|
|
138
|
+
For browser environments (or anywhere without Node.js `fs` APIs), use the `/browser` entry point:
|
|
139
|
+
|
|
140
|
+
```typescript
|
|
141
|
+
import { mergeConfiguration } from '@cloudcannon/configuration-loader/browser';
|
|
142
|
+
|
|
143
|
+
// You provide the implementations for glob matching and file loading
|
|
144
|
+
const result = await mergeConfiguration(config, {
|
|
145
|
+
findFilesMatchingGlobs: (globs) => {
|
|
146
|
+
// Your implementation - e.g., fetch from an API
|
|
147
|
+
return fetchMatchingFiles(globs);
|
|
148
|
+
},
|
|
149
|
+
loadConfigFile: async (filePath) => {
|
|
150
|
+
// Your implementation - e.g., fetch file contents
|
|
151
|
+
const response = await fetch(`/api/config/${filePath}`);
|
|
152
|
+
return response.json();
|
|
153
|
+
}
|
|
154
|
+
});
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
This entry point exports only `mergeConfiguration` and the types, with no Node.js dependencies.
|
|
158
|
+
|
|
159
|
+
## Supported Glob Keys
|
|
160
|
+
|
|
161
|
+
The loader processes the following `*_from_glob` keys:
|
|
162
|
+
|
|
163
|
+
| Key | Target | Description |
|
|
164
|
+
|-----|--------|-------------|
|
|
165
|
+
| `collections_config_from_glob` | `collections_config` | Collection configurations |
|
|
166
|
+
| `schemas_from_glob` | `schemas` | Schema configurations (within collections) |
|
|
167
|
+
| `_inputs_from_glob` | `_inputs` | Input configurations |
|
|
168
|
+
| `_structures_from_glob` | `_structures` | Structure configurations |
|
|
169
|
+
| `values_from_glob` | `values` | Structure values |
|
|
170
|
+
| `_snippets_from_glob` | `_snippets` | Snippet configurations |
|
|
171
|
+
| `_snippets_imports_from_glob` | `_snippets_imports` | Snippet imports |
|
|
172
|
+
| `_snippets_templates_from_glob` | `_snippets_templates` | Snippet templates |
|
|
173
|
+
| `_snippets_definitions_from_glob` | `_snippets_definitions` | Snippet definitions |
|
|
174
|
+
| `_editables_from_glob` | `_editables` | Editable region configurations |
|
|
175
|
+
|
|
176
|
+
## Source Tracking
|
|
177
|
+
|
|
178
|
+
Merged objects include a `__source__` property indicating which file they came from:
|
|
179
|
+
|
|
180
|
+
```typescript
|
|
181
|
+
const result = await loadConfiguration('cloudcannon.config.yml');
|
|
182
|
+
|
|
183
|
+
// Each merged input has a __source__ property
|
|
184
|
+
console.log(result.config._inputs?.title);
|
|
185
|
+
// { type: 'text', __source__: '/.cloudcannon/inputs/seo.yml' }
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
## Development
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
# Install dependencies
|
|
192
|
+
npm install
|
|
193
|
+
|
|
194
|
+
# Run type checking
|
|
195
|
+
npm run typecheck
|
|
196
|
+
|
|
197
|
+
# Run tests
|
|
198
|
+
npm test
|
|
199
|
+
|
|
200
|
+
# Build type declarations
|
|
201
|
+
npm run build
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
## How It Works
|
|
205
|
+
|
|
206
|
+
This package uses Node.js 22's native TypeScript support with type stripping (`--experimental-strip-types`). This means:
|
|
207
|
+
|
|
208
|
+
- TypeScript files run directly without compilation
|
|
209
|
+
- Type declarations are generated separately for package consumers
|
|
210
|
+
- No build step required for development
|
|
211
|
+
|
|
212
|
+
## License
|
|
213
|
+
|
|
214
|
+
MIT
|
|
215
|
+
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @cloudcannon/configuration-loader/browser
|
|
3
|
+
*
|
|
4
|
+
* Browser-compatible exports for the CloudCannon configuration loader.
|
|
5
|
+
* Use this entry point when you need to run in environments without Node.js APIs.
|
|
6
|
+
*
|
|
7
|
+
* @example
|
|
8
|
+
* ```typescript
|
|
9
|
+
* import { mergeConfiguration } from '@cloudcannon/configuration-loader/browser';
|
|
10
|
+
*
|
|
11
|
+
* const result = await mergeConfiguration(config, {
|
|
12
|
+
* findFilesMatchingGlobs: (globs) => yourGlobImplementation(globs),
|
|
13
|
+
* loadConfigFile: async (path) => yourFileLoader(path)
|
|
14
|
+
* });
|
|
15
|
+
* ```
|
|
16
|
+
*/
|
|
17
|
+
export type { Configuration, StructureValue } from '@cloudcannon/configuration-types';
|
|
18
|
+
export { mergeConfiguration } from './loader.ts';
|
|
19
|
+
export type { GlobLoaderWarnings, GlobResult, GlobTypeKey, MergeConfigurationOptions, } from './types.ts';
|
|
20
|
+
//# sourceMappingURL=browser.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAGtF,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,YAAY,EACX,kBAAkB,EAClB,UAAU,EACV,WAAW,EACX,yBAAyB,GACzB,MAAM,YAAY,CAAC"}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @cloudcannon/configuration-loader
|
|
3
|
+
*
|
|
4
|
+
* Load and merge CloudCannon configuration files that have been split across multiple files.
|
|
5
|
+
*
|
|
6
|
+
* This package provides utilities to work with CloudCannon's configuration splitting
|
|
7
|
+
* feature, allowing you to organize your configuration across multiple files and
|
|
8
|
+
* merge them together for use in your build tools or templates.
|
|
9
|
+
*
|
|
10
|
+
* @see https://cloudcannon.com/documentation/articles/why-split-your-configuration-file/
|
|
11
|
+
*
|
|
12
|
+
* @example
|
|
13
|
+
* ```typescript
|
|
14
|
+
* import { loadConfiguration } from '@cloudcannon/configuration-loader';
|
|
15
|
+
*
|
|
16
|
+
* const result = await loadConfiguration('cloudcannon.config.yml');
|
|
17
|
+
* console.log(result.config);
|
|
18
|
+
* ```
|
|
19
|
+
*/
|
|
20
|
+
export type { Configuration, StructureValue } from '@cloudcannon/configuration-types';
|
|
21
|
+
export { type LoadConfigurationOptions, loadConfiguration } from './load.ts';
|
|
22
|
+
export { mergeConfiguration } from './loader.ts';
|
|
23
|
+
export type { GlobLoaderWarnings, GlobResult, GlobTypeKey, MergeConfigurationOptions, } from './types.ts';
|
|
24
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAGtF,OAAO,EAAE,KAAK,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAG7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,YAAY,EACX,kBAAkB,EAClB,UAAU,EACV,WAAW,EACX,yBAAyB,GACzB,MAAM,YAAY,CAAC"}
|
package/dist/load.d.ts
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import type { GlobResult } from './types.ts';
|
|
2
|
+
/**
|
|
3
|
+
* Options for loadConfiguration.
|
|
4
|
+
*/
|
|
5
|
+
export interface LoadConfigurationOptions {
|
|
6
|
+
/**
|
|
7
|
+
* Custom function to parse file contents. Can be sync or async.
|
|
8
|
+
* Defaults to JSON.parse for .json files, and js-yaml for .yml/.yaml files.
|
|
9
|
+
* If not provided and a YAML file is encountered, an error will be thrown
|
|
10
|
+
* suggesting to install the 'js-yaml' package.
|
|
11
|
+
*/
|
|
12
|
+
parseFile?: (contents: string, filePath: string) => unknown | Promise<unknown>;
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* Loads and merges a CloudCannon configuration file with all its split configuration files.
|
|
16
|
+
*
|
|
17
|
+
* This is the simplest way to load CloudCannon configuration. It handles:
|
|
18
|
+
* - Reading the configuration file from disk
|
|
19
|
+
* - Parsing YAML and JSON files
|
|
20
|
+
* - Finding files matching glob patterns
|
|
21
|
+
* - Merging all configuration into a single object
|
|
22
|
+
*
|
|
23
|
+
* @param configPath - Path to the CloudCannon configuration file (e.g., 'cloudcannon.config.yml')
|
|
24
|
+
* @param options - Optional configuration options
|
|
25
|
+
* @returns A promise resolving to the merged configuration with metadata
|
|
26
|
+
*
|
|
27
|
+
* @example
|
|
28
|
+
* ```typescript
|
|
29
|
+
* import { loadConfiguration } from '@cloudcannon/configuration-loader';
|
|
30
|
+
*
|
|
31
|
+
* const result = await loadConfiguration('cloudcannon.config.yml');
|
|
32
|
+
* console.log(result.config);
|
|
33
|
+
* ```
|
|
34
|
+
*/
|
|
35
|
+
export declare function loadConfiguration(configPath: string, options?: LoadConfigurationOptions): Promise<GlobResult>;
|
|
36
|
+
//# sourceMappingURL=load.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../src/load.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAA6B,MAAM,YAAY,CAAC;AAExE;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACxC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/E;AAmDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,iBAAiB,CACtC,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,wBAAwB,GAChC,OAAO,CAAC,UAAU,CAAC,CA+BrB"}
|
package/dist/loader.d.ts
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import type { Configuration } from '@cloudcannon/configuration-types';
|
|
2
|
+
import type { GlobLoaderWarnings, GlobResult, GlobTypeKey, MergeConfigurationOptions } from './types.ts';
|
|
3
|
+
export type { GlobLoaderWarnings, GlobResult, GlobTypeKey, MergeConfigurationOptions };
|
|
4
|
+
/**
|
|
5
|
+
* Merges split CloudCannon configuration files into a single configuration object.
|
|
6
|
+
*
|
|
7
|
+
* This function processes `*_from_glob` keys in the configuration, loading and merging
|
|
8
|
+
* configuration from files matching the specified glob patterns. This allows you to
|
|
9
|
+
* split your CloudCannon configuration across multiple files for better organization.
|
|
10
|
+
*
|
|
11
|
+
* @param config - The base CloudCannon configuration object
|
|
12
|
+
* @param options - Options for loading configuration files
|
|
13
|
+
* @returns A promise resolving to the merged configuration with metadata
|
|
14
|
+
*
|
|
15
|
+
* @example
|
|
16
|
+
* ```typescript
|
|
17
|
+
* import { mergeConfiguration } from '@cloudcannon/configuration-loader';
|
|
18
|
+
* import { globSync } from 'glob';
|
|
19
|
+
* import { readFileSync } from 'fs';
|
|
20
|
+
* import YAML from 'yaml';
|
|
21
|
+
*
|
|
22
|
+
* const baseConfig = YAML.parse(readFileSync('cloudcannon.config.yml', 'utf8'));
|
|
23
|
+
*
|
|
24
|
+
* const result = await mergeConfiguration(baseConfig, {
|
|
25
|
+
* findFilesMatchingGlobs: (globs) => globSync(globs, { ignore: globs.filter(g => g.startsWith('!')).map(g => g.slice(1)) }),
|
|
26
|
+
* loadConfigFile: async (filePath) => YAML.parse(readFileSync(filePath, 'utf8'))
|
|
27
|
+
* });
|
|
28
|
+
*
|
|
29
|
+
* console.log(result.config); // Merged configuration
|
|
30
|
+
* ```
|
|
31
|
+
*/
|
|
32
|
+
export declare function mergeConfiguration(config: Configuration, options: MergeConfigurationOptions): Promise<GlobResult>;
|
|
33
|
+
//# sourceMappingURL=loader.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAkB,MAAM,kCAAkC,CAAC;AACtF,OAAO,KAAK,EACX,kBAAkB,EAClB,UAAU,EACV,WAAW,EACX,yBAAyB,EACzB,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,WAAW,EAAE,yBAAyB,EAAE,CAAC;AAwdvF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,kBAAkB,CACvC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,yBAAyB,GAChC,OAAO,CAAC,UAAU,CAAC,CAarB"}
|
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
import type { Configuration } from '@cloudcannon/configuration-types';
|
|
2
|
+
/**
|
|
3
|
+
* All supported glob key types that can be used to split configuration.
|
|
4
|
+
*/
|
|
5
|
+
export type GlobTypeKey = '_structures_from_glob' | 'values_from_glob' | '_snippets_from_glob' | '_snippets_imports_from_glob' | '_snippets_templates_from_glob' | '_snippets_definitions_from_glob' | '_inputs_from_glob' | '_editables_from_glob' | 'collections_config_from_glob' | 'schemas_from_glob';
|
|
6
|
+
/**
|
|
7
|
+
* Warnings generated during configuration loading.
|
|
8
|
+
* These indicate potential issues that may cause unexpected behavior.
|
|
9
|
+
*/
|
|
10
|
+
export interface GlobLoaderWarnings {
|
|
11
|
+
/**
|
|
12
|
+
* Circular references detected in configuration files.
|
|
13
|
+
*
|
|
14
|
+
* This occurs when a structure value loaded via `values_from_glob` contains
|
|
15
|
+
* nested structures that reference a file already being processed in the
|
|
16
|
+
* current chain. The file is skipped to prevent infinite recursion.
|
|
17
|
+
*
|
|
18
|
+
* To fix: restructure your configuration to avoid self-referencing patterns,
|
|
19
|
+
* or use separate files for nested structure definitions.
|
|
20
|
+
*
|
|
21
|
+
* @property path - The file path that caused the cycle
|
|
22
|
+
* @property chain - The sequence of files that led to this cycle
|
|
23
|
+
*/
|
|
24
|
+
cycles: {
|
|
25
|
+
path: string;
|
|
26
|
+
chain: string[];
|
|
27
|
+
}[];
|
|
28
|
+
/**
|
|
29
|
+
* Files that were matched by multiple different glob key types.
|
|
30
|
+
*
|
|
31
|
+
* This occurs when the same file matches glob patterns for different
|
|
32
|
+
* configuration sections (e.g., both `collections_config_from_glob` and
|
|
33
|
+
* `_inputs_from_glob`). The file is only processed for the first matching
|
|
34
|
+
* glob key type; subsequent matches are skipped.
|
|
35
|
+
*
|
|
36
|
+
* To fix: use more specific glob patterns to ensure each file is only
|
|
37
|
+
* matched by one glob key type, or organize files into separate directories.
|
|
38
|
+
*
|
|
39
|
+
* @property path - The file path that matched multiple glob types
|
|
40
|
+
* @property type1 - The first glob key type that matched (file was processed for this)
|
|
41
|
+
* @property type2 - The second glob key type that matched (file was skipped)
|
|
42
|
+
*/
|
|
43
|
+
multipleGlobKeys: {
|
|
44
|
+
path: string;
|
|
45
|
+
type1: GlobTypeKey;
|
|
46
|
+
type2: GlobTypeKey;
|
|
47
|
+
}[];
|
|
48
|
+
/**
|
|
49
|
+
* Files containing arrays instead of objects.
|
|
50
|
+
*
|
|
51
|
+
* Configuration files loaded via `*_from_glob` keys must contain objects
|
|
52
|
+
* (key-value pairs), not arrays. Files containing arrays are skipped and
|
|
53
|
+
* not merged into the configuration.
|
|
54
|
+
*
|
|
55
|
+
* To fix: ensure your configuration files export objects. For example,
|
|
56
|
+
* use `posts: { path: "..." }` instead of `[{ posts: { path: "..." } }]`.
|
|
57
|
+
*
|
|
58
|
+
* @property path - The file path containing an array
|
|
59
|
+
*/
|
|
60
|
+
arrayValues: {
|
|
61
|
+
path: string;
|
|
62
|
+
}[];
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* Result of merging split configuration files.
|
|
66
|
+
*/
|
|
67
|
+
export interface GlobResult {
|
|
68
|
+
/** The merged configuration object */
|
|
69
|
+
config: Configuration;
|
|
70
|
+
/** Warnings about potential issues encountered during loading */
|
|
71
|
+
warnings: GlobLoaderWarnings;
|
|
72
|
+
/** All glob patterns found (useful for file watching) */
|
|
73
|
+
globPatterns: string[];
|
|
74
|
+
/** Mapping from file paths to the glob key type that loaded them */
|
|
75
|
+
pathsToGlobKey: Record<string, GlobTypeKey>;
|
|
76
|
+
/** Mapping from glob key types to the set of file paths they loaded */
|
|
77
|
+
globKeyToPaths: Record<GlobTypeKey, Set<string>>;
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* Options for the mergeConfiguration function.
|
|
81
|
+
*/
|
|
82
|
+
export interface MergeConfigurationOptions {
|
|
83
|
+
/**
|
|
84
|
+
* Function to find files matching glob patterns.
|
|
85
|
+
* Receives an array of glob patterns (including negation patterns starting with '!')
|
|
86
|
+
* and should return an array of matching file paths.
|
|
87
|
+
*/
|
|
88
|
+
findFilesMatchingGlobs: (globs: string[]) => string[];
|
|
89
|
+
/**
|
|
90
|
+
* Function to load and parse a configuration file.
|
|
91
|
+
* Should return the parsed content of the file (typically YAML or JSON).
|
|
92
|
+
*/
|
|
93
|
+
loadConfigFile: (filePath: string) => Promise<unknown>;
|
|
94
|
+
}
|
|
95
|
+
//# sourceMappingURL=types.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAEtE;;GAEG;AACH,MAAM,MAAM,WAAW,GACpB,uBAAuB,GACvB,kBAAkB,GAClB,qBAAqB,GACrB,6BAA6B,GAC7B,+BAA+B,GAC/B,iCAAiC,GACjC,mBAAmB,GACnB,sBAAsB,GACtB,8BAA8B,GAC9B,mBAAmB,CAAC;AAEvB;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC;;;;;;;;;;;;OAYG;IACH,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IAE5C;;;;;;;;;;;;;;OAcG;IACH,gBAAgB,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,WAAW,CAAC;QAAC,KAAK,EAAE,WAAW,CAAA;KAAE,EAAE,CAAC;IAE7E;;;;;;;;;;;OAWG;IACH,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,sCAAsC;IACtC,MAAM,EAAE,aAAa,CAAC;IACtB,iEAAiE;IACjE,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,yDAAyD;IACzD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,oEAAoE;IACpE,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC5C,uEAAuE;IACvE,cAAc,EAAE,MAAM,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;CACjD;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACzC;;;;OAIG;IACH,sBAAsB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,CAAC;IACtD;;;OAGG;IACH,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACvD"}
|
package/package.json
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@cloudcannon/configuration-loader",
|
|
3
|
+
"version": "0.0.2",
|
|
4
|
+
"description": "Load and merge CloudCannon configuration files",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"engines": {
|
|
7
|
+
"node": ">=22.6.0"
|
|
8
|
+
},
|
|
9
|
+
"exports": {
|
|
10
|
+
".": {
|
|
11
|
+
"import": {
|
|
12
|
+
"types": "./dist/index.d.ts",
|
|
13
|
+
"default": "./src/index.ts"
|
|
14
|
+
}
|
|
15
|
+
},
|
|
16
|
+
"./browser": {
|
|
17
|
+
"import": {
|
|
18
|
+
"types": "./dist/browser.d.ts",
|
|
19
|
+
"default": "./src/browser.ts"
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
},
|
|
23
|
+
"types": "./dist/index.d.ts",
|
|
24
|
+
"files": [
|
|
25
|
+
"src",
|
|
26
|
+
"dist"
|
|
27
|
+
],
|
|
28
|
+
"scripts": {
|
|
29
|
+
"typecheck": "tsc --noEmit",
|
|
30
|
+
"build:types": "tsc --emitDeclarationOnly",
|
|
31
|
+
"build": "npm run build:types",
|
|
32
|
+
"test": "node --experimental-strip-types --test src/**/*.test.ts",
|
|
33
|
+
"test:watch": "node --experimental-strip-types --watch --test",
|
|
34
|
+
"test:coverage": "node --experimental-strip-types --experimental-test-coverage --test src/**/*.test.ts",
|
|
35
|
+
"lint": "biome check src/",
|
|
36
|
+
"lint:fix": "biome check --write src/",
|
|
37
|
+
"format": "biome format --write src/",
|
|
38
|
+
"prepublishOnly": "npm run build"
|
|
39
|
+
},
|
|
40
|
+
"keywords": [
|
|
41
|
+
"cloudcannon",
|
|
42
|
+
"configuration",
|
|
43
|
+
"cms",
|
|
44
|
+
"static-site"
|
|
45
|
+
],
|
|
46
|
+
"author": "CloudCannon",
|
|
47
|
+
"license": "MIT",
|
|
48
|
+
"repository": {
|
|
49
|
+
"type": "git",
|
|
50
|
+
"url": "git+https://github.com/CloudCannon/configuration-loader.git"
|
|
51
|
+
},
|
|
52
|
+
"homepage": "https://cloudcannon.com/documentation/articles/why-split-your-configuration-file/",
|
|
53
|
+
"dependencies": {
|
|
54
|
+
"@cloudcannon/configuration-types": "0.0.44"
|
|
55
|
+
},
|
|
56
|
+
"peerDependencies": {
|
|
57
|
+
"js-yaml": "^4.0.0"
|
|
58
|
+
},
|
|
59
|
+
"peerDependenciesMeta": {
|
|
60
|
+
"js-yaml": {
|
|
61
|
+
"optional": true
|
|
62
|
+
}
|
|
63
|
+
},
|
|
64
|
+
"devDependencies": {
|
|
65
|
+
"@biomejs/biome": "^2.3.8",
|
|
66
|
+
"@types/node": "^24.10.1",
|
|
67
|
+
"typescript": "^5.7.0"
|
|
68
|
+
}
|
|
69
|
+
}
|
package/src/browser.ts
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @cloudcannon/configuration-loader/browser
|
|
3
|
+
*
|
|
4
|
+
* Browser-compatible exports for the CloudCannon configuration loader.
|
|
5
|
+
* Use this entry point when you need to run in environments without Node.js APIs.
|
|
6
|
+
*
|
|
7
|
+
* @example
|
|
8
|
+
* ```typescript
|
|
9
|
+
* import { mergeConfiguration } from '@cloudcannon/configuration-loader/browser';
|
|
10
|
+
*
|
|
11
|
+
* const result = await mergeConfiguration(config, {
|
|
12
|
+
* findFilesMatchingGlobs: (globs) => yourGlobImplementation(globs),
|
|
13
|
+
* loadConfigFile: async (path) => yourFileLoader(path)
|
|
14
|
+
* });
|
|
15
|
+
* ```
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
// Re-export useful types from configuration-types for convenience
|
|
19
|
+
export type { Configuration, StructureValue } from '@cloudcannon/configuration-types';
|
|
20
|
+
|
|
21
|
+
// Export the core merge function (no Node.js dependencies)
|
|
22
|
+
export { mergeConfiguration } from './loader.ts';
|
|
23
|
+
|
|
24
|
+
// Export types from dedicated types file
|
|
25
|
+
export type {
|
|
26
|
+
GlobLoaderWarnings,
|
|
27
|
+
GlobResult,
|
|
28
|
+
GlobTypeKey,
|
|
29
|
+
MergeConfigurationOptions,
|
|
30
|
+
} from './types.ts';
|
package/src/index.ts
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @cloudcannon/configuration-loader
|
|
3
|
+
*
|
|
4
|
+
* Load and merge CloudCannon configuration files that have been split across multiple files.
|
|
5
|
+
*
|
|
6
|
+
* This package provides utilities to work with CloudCannon's configuration splitting
|
|
7
|
+
* feature, allowing you to organize your configuration across multiple files and
|
|
8
|
+
* merge them together for use in your build tools or templates.
|
|
9
|
+
*
|
|
10
|
+
* @see https://cloudcannon.com/documentation/articles/why-split-your-configuration-file/
|
|
11
|
+
*
|
|
12
|
+
* @example
|
|
13
|
+
* ```typescript
|
|
14
|
+
* import { loadConfiguration } from '@cloudcannon/configuration-loader';
|
|
15
|
+
*
|
|
16
|
+
* const result = await loadConfiguration('cloudcannon.config.yml');
|
|
17
|
+
* console.log(result.config);
|
|
18
|
+
* ```
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
// Re-export useful types from configuration-types for convenience
|
|
22
|
+
export type { Configuration, StructureValue } from '@cloudcannon/configuration-types';
|
|
23
|
+
|
|
24
|
+
// Export the simple high-level API
|
|
25
|
+
export { type LoadConfigurationOptions, loadConfiguration } from './load.ts';
|
|
26
|
+
|
|
27
|
+
// Export the lower-level API for custom implementations
|
|
28
|
+
export { mergeConfiguration } from './loader.ts';
|
|
29
|
+
|
|
30
|
+
// Export types from dedicated types file
|
|
31
|
+
export type {
|
|
32
|
+
GlobLoaderWarnings,
|
|
33
|
+
GlobResult,
|
|
34
|
+
GlobTypeKey,
|
|
35
|
+
MergeConfigurationOptions,
|
|
36
|
+
} from './types.ts';
|