@aspruyt/json-config-sync 3.6.0 → 3.7.0
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/README.md +32 -0
- package/dist/env.d.ts +3 -1
- package/dist/env.js +30 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -223,6 +223,38 @@ repos:
|
|
|
223
223
|
- git: git@github.com:org/backend.git
|
|
224
224
|
```
|
|
225
225
|
|
|
226
|
+
#### Escaping Variable Syntax
|
|
227
|
+
|
|
228
|
+
If your target file needs literal `${VAR}` syntax (e.g., for devcontainer.json, shell scripts, or other templating systems), use `$$` to escape:
|
|
229
|
+
|
|
230
|
+
```yaml
|
|
231
|
+
files:
|
|
232
|
+
.devcontainer/devcontainer.json:
|
|
233
|
+
content:
|
|
234
|
+
name: my-dev-container
|
|
235
|
+
remoteEnv:
|
|
236
|
+
# Escaped - outputs literal ${localWorkspaceFolder} for VS Code
|
|
237
|
+
LOCAL_WORKSPACE_FOLDER: "$${localWorkspaceFolder}"
|
|
238
|
+
CONTAINER_WORKSPACE: "$${containerWorkspaceFolder}"
|
|
239
|
+
# Interpolated - replaced with actual env value
|
|
240
|
+
API_KEY: "${API_KEY}"
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
Output:
|
|
244
|
+
|
|
245
|
+
```json
|
|
246
|
+
{
|
|
247
|
+
"name": "my-dev-container",
|
|
248
|
+
"remoteEnv": {
|
|
249
|
+
"LOCAL_WORKSPACE_FOLDER": "${localWorkspaceFolder}",
|
|
250
|
+
"CONTAINER_WORKSPACE": "${containerWorkspaceFolder}",
|
|
251
|
+
"API_KEY": "actual-api-key-value"
|
|
252
|
+
}
|
|
253
|
+
}
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
This follows the same escape convention used by Docker Compose.
|
|
257
|
+
|
|
226
258
|
### Merge Directives
|
|
227
259
|
|
|
228
260
|
Control array merging with the `$arrayMerge` directive:
|
package/dist/env.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Environment variable interpolation utilities.
|
|
3
3
|
* Supports ${VAR}, ${VAR:-default}, and ${VAR:?message} syntax.
|
|
4
|
+
* Use $${VAR} to escape and output literal ${VAR}.
|
|
4
5
|
*/
|
|
5
6
|
export interface EnvInterpolationOptions {
|
|
6
7
|
/**
|
|
@@ -12,10 +13,11 @@ export interface EnvInterpolationOptions {
|
|
|
12
13
|
/**
|
|
13
14
|
* Interpolate environment variables in a JSON object.
|
|
14
15
|
*
|
|
15
|
-
* Supports
|
|
16
|
+
* Supports these syntaxes:
|
|
16
17
|
* - ${VAR} - Replace with env value, error if missing (in strict mode)
|
|
17
18
|
* - ${VAR:-default} - Replace with env value, or use default if missing
|
|
18
19
|
* - ${VAR:?message} - Replace with env value, or throw error with message if missing
|
|
20
|
+
* - $${VAR} - Escape: outputs literal ${VAR} without interpolation
|
|
19
21
|
*
|
|
20
22
|
* @param json - The JSON object to process
|
|
21
23
|
* @param options - Interpolation options (default: strict mode)
|
package/dist/env.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Environment variable interpolation utilities.
|
|
3
3
|
* Supports ${VAR}, ${VAR:-default}, and ${VAR:?message} syntax.
|
|
4
|
+
* Use $${VAR} to escape and output literal ${VAR}.
|
|
4
5
|
*/
|
|
5
6
|
const DEFAULT_OPTIONS = {
|
|
6
7
|
strict: true,
|
|
@@ -18,6 +19,17 @@ const DEFAULT_OPTIONS = {
|
|
|
18
19
|
* - ${VAR:?message} -> varName=VAR, modifier=?, value=message
|
|
19
20
|
*/
|
|
20
21
|
const ENV_VAR_REGEX = /\$\{([^}:]+)(?::([?-])([^}]*))?\}/g;
|
|
22
|
+
/**
|
|
23
|
+
* Regex to match escaped environment variable placeholders.
|
|
24
|
+
* $${...} outputs literal ${...} without interpolation.
|
|
25
|
+
* Example: $${VAR} -> ${VAR}, $${VAR:-default} -> ${VAR:-default}
|
|
26
|
+
*/
|
|
27
|
+
const ESCAPED_VAR_REGEX = /\$\$\{([^}]+)\}/g;
|
|
28
|
+
/**
|
|
29
|
+
* Placeholder prefix for temporarily storing escaped sequences.
|
|
30
|
+
* Uses null bytes which won't appear in normal content.
|
|
31
|
+
*/
|
|
32
|
+
const ESCAPE_PLACEHOLDER = "\x00ESCAPED_VAR\x00";
|
|
21
33
|
/**
|
|
22
34
|
* Check if a value is a plain object (not null, not array).
|
|
23
35
|
*/
|
|
@@ -26,9 +38,18 @@ function isPlainObject(val) {
|
|
|
26
38
|
}
|
|
27
39
|
/**
|
|
28
40
|
* Process a single string value, replacing environment variable placeholders.
|
|
41
|
+
* Supports escaping with $${VAR} syntax to output literal ${VAR}.
|
|
29
42
|
*/
|
|
30
43
|
function processString(value, options) {
|
|
31
|
-
|
|
44
|
+
// Phase 1: Replace escaped $${...} with placeholders
|
|
45
|
+
const escapedContent = [];
|
|
46
|
+
let processed = value.replace(ESCAPED_VAR_REGEX, (_match, content) => {
|
|
47
|
+
const index = escapedContent.length;
|
|
48
|
+
escapedContent.push(content);
|
|
49
|
+
return `${ESCAPE_PLACEHOLDER}${index}\x00`;
|
|
50
|
+
});
|
|
51
|
+
// Phase 2: Interpolate remaining ${...}
|
|
52
|
+
processed = processed.replace(ENV_VAR_REGEX, (match, varName, modifier, defaultOrMsg) => {
|
|
32
53
|
const envValue = process.env[varName];
|
|
33
54
|
// Variable exists - use its value
|
|
34
55
|
if (envValue !== undefined) {
|
|
@@ -50,6 +71,12 @@ function processString(value, options) {
|
|
|
50
71
|
// Non-strict mode - leave placeholder as-is
|
|
51
72
|
return match;
|
|
52
73
|
});
|
|
74
|
+
// Phase 3: Restore escaped sequences as literal ${...}
|
|
75
|
+
processed = processed.replace(new RegExp(`${ESCAPE_PLACEHOLDER}(\\d+)\x00`, "g"), (_match, indexStr) => {
|
|
76
|
+
const index = parseInt(indexStr, 10);
|
|
77
|
+
return `\${${escapedContent[index]}}`;
|
|
78
|
+
});
|
|
79
|
+
return processed;
|
|
53
80
|
}
|
|
54
81
|
/**
|
|
55
82
|
* Recursively process a value, interpolating environment variables in strings.
|
|
@@ -74,10 +101,11 @@ function processValue(value, options) {
|
|
|
74
101
|
/**
|
|
75
102
|
* Interpolate environment variables in a JSON object.
|
|
76
103
|
*
|
|
77
|
-
* Supports
|
|
104
|
+
* Supports these syntaxes:
|
|
78
105
|
* - ${VAR} - Replace with env value, error if missing (in strict mode)
|
|
79
106
|
* - ${VAR:-default} - Replace with env value, or use default if missing
|
|
80
107
|
* - ${VAR:?message} - Replace with env value, or throw error with message if missing
|
|
108
|
+
* - $${VAR} - Escape: outputs literal ${VAR} without interpolation
|
|
81
109
|
*
|
|
82
110
|
* @param json - The JSON object to process
|
|
83
111
|
* @param options - Interpolation options (default: strict mode)
|
package/package.json
CHANGED