Add Merge-Toml function to combine TOML documents

[MariusStorhaug]

Scripts that work with layered configuration — defaults + environment overrides, base + local — need to merge TOML documents without writing ad-hoc hashtable loops. Merge-Toml combines two or more TOML documents into one, mirroring the pattern of Merge-Hashtable in the PSModule ecosystem.

Request

Desired capability

# Merge two strings
Merge-Toml -BaseObject $defaults -OverrideObject $overrides

# Merge files
Merge-Toml -Path base.toml -Override override.toml

# Pipeline: merge a stream of documents
$docs | Merge-Toml

Parameters

Parameter	Description
-BaseObject	Base TOML string or TomlDocument (default parameter set)
-OverrideObject	Override TOML string or TomlDocument applied on top of base
-Path	File path(s) to merge in order (first = base, rest = overrides)
-LiteralPath	Literal file path(s), same order semantics
-Strategy	Merge strategy: LastWins (default), FirstWins, ErrorOnConflict

Merge semantics

• Scalar keys: controlled by -Strategy (default: last value wins)
• Nested tables: deep-merged recursively
• Arrays of tables ([[...]]): appended in order
• Inline arrays: treated as scalars (replaced, not merged)
• Output is always a [string] (canonical TOML)

Acceptance criteria

• Merge-Toml $a $b produces TOML containing all keys from both; overlapping scalars obey -Strategy
• Deep tables are recursively merged
• Arrays of tables are concatenated
• All output is parseable by ConvertFrom-Toml
• -ErrorOnConflict throws on any duplicate scalar key

---

Technical decisions

Implementation: Parse both inputs with ConvertFrom-Toml, walk the resulting ordered dictionaries recursively with a private helper Merge-TomlTableObject, then re-serialize with ConvertTo-Toml.

Function placement: src/functions/public/Merge-Toml.ps1; private helper src/functions/private/Merge-TomlTableObject.ps1.

Output type: [string] — canonical merged TOML text.

---

Implementation plan

• Add private helper Merge-TomlTableObject for recursive merge logic
• Add Merge-Toml in src/functions/public/Merge-Toml.ps1
• Add Pester tests — scalar merge, deep table merge, AoT append, strategy variants, file input, pipeline
• Update README with usage example

Related

• Add ConvertFrom-Toml and ConvertTo-Toml functions with full TOML v1.1.0 spec coverage #2 — ConvertFrom-Toml / ConvertTo-Toml (prerequisite)