Add configurable array merge behaviour (concat|replace)

Author: jameswiltshire

README.md

@@ -52,6 +52,7 @@ Options:
       --dry-run       Preview without writing files      [boolean] [default: false]
       --backup        Create .bak before overwriting     [boolean] [default: false]
       --indent        Custom indentation spaces          [number]
+      --array-merge   Array merge strategy               [choices: "replace", "concat"] [default: "replace"]
   -h, --help          Show help
   -v, --version       Show version
 ```
@@ -65,13 +66,73 @@ const result = mergeJsonc({
   inputs: ["base.json", "dev.jsonc", "local.json5"],
   out: "config.json",
   skipMissing: true,
+  arrayMerge: "replace", // or "concat"
 });
 
 console.log(result.wrote ? "Merged!" : result.reason);
 ```
 
 ---
 
+## 🔀 Array Merge Strategies
+
+By default, `merge-jsonc` **replaces** arrays when merging. You can configure this behavior:
+
+### Replace (default)
+
+Arrays from later files completely replace arrays from earlier files:
+
+```json
+// base.json
+{ "items": [1, 2, 3] }
+
+// override.json
+{ "items": [4, 5] }
+
+// Result with --array-merge replace (default)
+{ "items": [4, 5] }
+```
+
+```bash
+merge-jsonc base.json override.json --out result.json
+# or explicitly:
+merge-jsonc base.json override.json --out result.json --array-merge replace
+```
+
+### Concat
+
+Arrays are concatenated together:
+
+```json
+// base.json
+{ "items": [1, 2, 3] }
+
+// override.json
+{ "items": [4, 5] }
+
+// Result with --array-merge concat
+{ "items": [1, 2, 3, 4, 5] }
+```
+
+```bash
+merge-jsonc base.json override.json --out result.json --array-merge concat
+```
+
+### Configuration File
+
+You can also set the array merge strategy in your config file:
+
+```javascript
+// .merge-jsonc.config.mjs
+export default {
+  arrayMerge: "concat",
+  backup: true,
+  pretty: true,
+};
+```
+
+---
+
 ## 🧪 Examples
 
 See the [`examples/`](./examples/) directory for real-world usage patterns:

src/cli.ts

@@ -14,6 +14,7 @@ interface ParsedArgs {
   dryRun?: boolean;
   backup?: boolean;
   indent?: number;
+  arrayMerge?: "replace" | "concat";
   inputs: string[];
 }
 
@@ -48,6 +49,7 @@ function mergeArgsWithConfig(args: ParsedArgs, config: ConfigOptions): MergeOpti
     dryRun: args.dryRun ?? config.dryRun ?? false,
     backup: args.backup ?? config.backup ?? false,
     indent: args.indent ?? config.indent,
+    arrayMerge: args.arrayMerge ?? config.arrayMerge ?? "replace",
   };
 }
 
@@ -87,6 +89,12 @@ async function run() {
         describe: "Custom indentation spaces (overrides --min)",
         type: "number",
       })
+      .option("array-merge", {
+        describe: "Array merge strategy: 'replace' (default) or 'concat'",
+        type: "string",
+        choices: ["replace", "concat"],
+        default: "replace",
+      })
       .help("help")
       .alias("help", "h")
       .version(version)
@@ -124,6 +132,7 @@ async function run() {
       dryRun: argv["dry-run"],
       backup: argv.backup,
       indent: argv.indent,
+      arrayMerge: argv["array-merge"] as "replace" | "concat" | undefined,
       inputs: Array.from(argv._, (value) => String(value)),
     };
 

src/config.ts

@@ -9,6 +9,7 @@ export interface ConfigOptions {
   dryRun?: boolean;
   backup?: boolean;
   indent?: number;
+  arrayMerge?: "replace" | "concat";
 }
 
 type ConfigKey = keyof ConfigOptions;
@@ -52,6 +53,12 @@ const validators: { [K in ConfigKey]-?: ConfigValidator<K> } = {
     }
     return value;
   },
+  arrayMerge: (value, source) => {
+    if (value !== "replace" && value !== "concat") {
+      throw new Error(`Invalid 'arrayMerge' value in '${source}'. Expected 'replace' or 'concat'.`);
+    }
+    return value;
+  },
 };
 
 function setConfigValue<K extends ConfigKey>(

src/core.ts

@@ -12,6 +12,7 @@ export interface MergeOptions {
   dryRun?: boolean; // preview changes without writing
   backup?: boolean; // create .bak file before overwriting
   indent?: number; // custom indentation (overrides pretty)
+  arrayMerge?: "replace" | "concat"; // array merge strategy (default: replace)
 }
 
 export type MergeResult =
@@ -73,13 +74,23 @@ function parseJsonFile(filePath: string, content: string): Record<string, unknow
   }
 }
 
-function mergeFiles(inputAbs: string[]): Record<string, unknown> {
+function mergeFiles(
+  inputAbs: string[],
+  arrayMerge: "replace" | "concat" = "replace"
+): Record<string, unknown> {
   let combined: Record<string, unknown> = {};
 
+  const mergeOptions =
+    arrayMerge === "replace"
+      ? {
+          arrayMerge: (target: unknown[], source: unknown[]) => source,
+        }
+      : undefined;
+
   for (const abs of inputAbs) {
     const content = readText(abs);
     const parsed = parseJsonFile(abs, content);
-    combined = deepmerge<Record<string, unknown>>(combined, parsed);
+    combined = deepmerge<Record<string, unknown>>(combined, parsed, mergeOptions);
   }
 
   return combined;
@@ -110,6 +121,7 @@ export function mergeJsonc(opts: MergeOptions): MergeResult {
     dryRun = false,
     backup = false,
     indent,
+    arrayMerge = "replace",
   } = opts;
 
   const inputAbs = resolveInputPaths(inputs, skipMissing);
@@ -120,7 +132,7 @@ export function mergeJsonc(opts: MergeOptions): MergeResult {
 
   const outAbs = safeOutputPath(out);
 
-  const combined = mergeFiles(inputAbs);
+  const combined = mergeFiles(inputAbs, arrayMerge);
   const spaces = calculateIndentation(indent, pretty);
   const text = JSON.stringify(combined, null, spaces);
 

test/cli-module.test.ts

@@ -71,6 +71,7 @@ describe("CLI module", () => {
       dryRun: false,
       backup: true,
       indent: 4,
+      arrayMerge: "replace",
     });
     expect(logSpy).toHaveBeenCalledWith(
       expect.stringContaining("DRY RUN - would write to result.json")

test/core.test.ts

@@ -228,7 +228,7 @@ describe("mergeJsonc core functionality", () => {
     expect(content).toContain("\n");
   });
 
-  test("should merge arrays by concatenation (deepmerge default)", () => {
+  test("should replace arrays by default", () => {
     writeTestFile("a.jsonc", '{"items": [1, 2]}');
     writeTestFile("b.jsonc", '{"items": [3, 4]}');
 
@@ -239,6 +239,22 @@ describe("mergeJsonc core functionality", () => {
 
     expect(result.wrote).toBe(true);
 
+    const merged = readJsonObject("merged.jsonc");
+    expect(merged).toMatchObject({ items: [3, 4] });
+  });
+
+  test("should concatenate arrays when arrayMerge is 'concat'", () => {
+    writeTestFile("a.jsonc", '{"items": [1, 2]}');
+    writeTestFile("b.jsonc", '{"items": [3, 4]}');
+
+    const result = mergeJsonc({
+      inputs: [join(TEST_DIR, "a.jsonc"), join(TEST_DIR, "b.jsonc")],
+      out: join(TEST_DIR, "merged.jsonc"),
+      arrayMerge: "concat",
+    });
+
+    expect(result.wrote).toBe(true);
+
     const merged = readJsonObject("merged.jsonc");
     expect(merged).toMatchObject({ items: [1, 2, 3, 4] });
   });