@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 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 three syntaxes:
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
- return value.replace(ENV_VAR_REGEX, (match, varName, modifier, defaultOrMsg) => {
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 three syntaxes:
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aspruyt/json-config-sync",
3
- "version": "3.6.0",
3
+ "version": "3.7.0",
4
4
  "description": "CLI tool to sync JSON or YAML configuration files across multiple GitHub and Azure DevOps repositories",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",