yamlock 0.2.9 → 0.3.0

package/README.md

@@ -60,6 +60,9 @@ yamlock algorithms
 
 # Generate a random key for YAMLOCK_KEY
 yamlock keygen --length 64 --format base64
+
+# Preview changes without touching files
+yamlock encrypt config.yml -o config.enc.yml -p db.password -k "my-secret-key" -d
 ```
 
 The CLI detects YAML (`.yaml`/`.yml`) and JSON extensions automatically and writes the file back in the same format.
@@ -117,11 +120,36 @@ const restored = processConfig(processed, {
   key: KEY,
   algorithm: { algorithm: 'aes-192-cbc', ivLength: 24 }
 });
+
+// Control what happens when encountering non-string values and customize path IDs
+const mixedConfig = { db: { password: 'secret', retries: 3 } };
+const lockedMixed = processConfig(mixedConfig, {
+  mode: 'encrypt',
+  key: KEY,
+  nonStringPolicy: 'stringify', // stringifies numbers/objects before encrypting
+  pathSerializer: (segments) => segments.join('/') // custom path naming (db/password instead of dot notation)
+});
+
+// Example of a path serializer that includes array indexes explicitly
+const lockedUsers = processConfig(
+  { users: [{ tokens: ['abc'] }] },
+  {
+    mode: 'encrypt',
+    key: KEY,
+    pathSerializer: (segments) =>
+      segments
+        .map((segment, index) =>
+          typeof segment === 'number' ? `[${segment}]` : index === 0 ? segment : `/${segment}`
+        )
+        .join('')
+  }
+);
 ```
 
 ## Advanced usage
 
 - **Selective encryption**: combine `--paths` on the CLI or `paths: []` in `processConfig` to encrypt only sensitive sections of a config file.
+- **Non-string handling**: use `nonStringPolicy: 'ignore' | 'stringify' | 'error'` to control how numbers/objects are treated, and `pathSerializer` to change how traversal paths are represented (e.g., `db/password` instead of dot notation).
 - **CI/CD flows**: see [examples/docs/ci-cd.md](examples/docs/ci-cd.md) for a GitHub Actions job that decrypts configs for builds and re-encrypts them before publishing artifacts.
 - **Key rotation**: follow [examples/docs/key-rotation.md](examples/docs/key-rotation.md) for a step-by-step process, including scripting tips for large repos.
 

package/dist/utils/config.js

@@ -15,6 +15,8 @@ const MODES = {
  * @param {string|Buffer} options.key
  * @param {string|object} [options.algorithm]
  * @param {object} [options.algorithmOptions]
+ * @param {"ignore"|"stringify"|"error"} [options.nonStringPolicy]
+ * @param {(segments: Array<string|number>) => string} [options.pathSerializer]
  * @param {string[]} [options.paths]
  * @param {Array<string|number>} [options.parentPath]
  * @returns {Object|Array}
@@ -37,11 +39,13 @@ export function processConfig(node, options) {
     ...options,
     mode,
     parentPath: options.parentPath ?? [],
-    normalizedPaths
+    normalizedPaths,
+    nonStringPolicy: options.nonStringPolicy ?? 'ignore',
+    pathSerializer: options.pathSerializer
   });
 }
 
-function traverseConfig(node, { mode, key, algorithm, algorithmOptions, parentPath, normalizedPaths }) {
+function traverseConfig(node, { mode, key, algorithm, algorithmOptions, parentPath, normalizedPaths, nonStringPolicy, pathSerializer }) {
   const isArrayNode = Array.isArray(node);
   const result = isArrayNode ? [] : {};
   const cryptoOptions = algorithmOptions ?? algorithm;
@@ -49,7 +53,9 @@ function traverseConfig(node, { mode, key, algorithm, algorithmOptions, parentPa
   Object.entries(node).forEach(([rawKey, value]) => {
     const segment = isArrayNode ? Number(rawKey) : rawKey;
     const targetKey = isArrayNode ? segment : rawKey;
-    const currentPath = buildPath(parentPath, segment);
+    const currentPath = pathSerializer
+      ? pathSerializer([...parentPath, segment])
+      : buildPath(parentPath, segment);
 
     if (value !== null && typeof value === 'object') {
       result[targetKey] = traverseConfig(value, {
@@ -58,14 +64,22 @@ function traverseConfig(node, { mode, key, algorithm, algorithmOptions, parentPa
         algorithm: cryptoOptions,
         algorithmOptions: cryptoOptions,
         parentPath: [...parentPath, segment],
-        normalizedPaths
+        normalizedPaths,
+        nonStringPolicy,
+        pathSerializer
       });
       return;
     }
 
     if (typeof value !== 'string') {
-      result[targetKey] = value;
-      return;
+      if (nonStringPolicy === 'stringify') {
+        value = JSON.stringify(value);
+      } else if (nonStringPolicy === 'error') {
+        throw new Error(`Non-string value encountered at ${currentPath}`);
+      } else {
+        result[targetKey] = value;
+        return;
+      }
     }
 
     const shouldProcess = !normalizedPaths || normalizedPaths.has(currentPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yamlock",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "author": "PAVEL TKACHEV (phoenixweiss) <mail@phoenixweiss.me>",
   "description": "Value-level encryption for YAML/JSON configuration files with CLI + Node.js APIs.",
   "license": "MIT",