Skip to content

Conversation

@Josmithr
Copy link
Contributor

@Josmithr Josmithr commented Jan 9, 2025

Fix for #4786

Merging of API-Extractor configurations leverages Lodash's merge functionality. For object / primitive properties, the resulting behavior is sensible. But for array properties, Lodash's merge behavior is very unintuitive.

Consider a base API-Extractor configuration with the following properties:

{
  "apiReport": {
    "enabled": true,
    "reportVariants": ["alpha", "beta", "public"]
  },
}

And a derived configuration with the following properties:

{
  "apiReport": {
    "reportVariants": ["complete"]
  },
}

What would you expect the merged configuration to look like? There are a couple of reasonable options here, but Lodash would yield:

{
  "apiReport": {
    "enabled": true,
    "reportVariants": ["complete", "beta", "public"]
  },
}

Where each value is overridden on a by-index basis.

This is incredibly unintuitive behavior. Per the discussion in #4786, the merge logic has been updated such that array properties in derived configurations override array properties in base configurations. So for our example above, the merged configuration would look like:

{
  "apiReport": {
    "enabled": true,
    "reportVariants": ["complete"]
  },
}

Which is a predictable and intelligible behavior.

In the future, we may want to offer more user options for how to merge arrays, but in the short term this solution prevents confusing and error-prone behavior.

@Josmithr Josmithr changed the title fix(api-extractor): Override lodash's array-merging behavior to make config inheritance intelligible fix(api-extractor): Update merge behavior for derived configurations to allow overriding array properties Jan 9, 2025
@Josmithr Josmithr changed the title fix(api-extractor): Update merge behavior for derived configurations to allow overriding array properties fix(api-extractor): More predictable merging of arrays in configuration Jan 13, 2025
@octogonz octogonz changed the title fix(api-extractor): More predictable merging of arrays in configuration [api-extractor] More predictable merging of arrays in configuration Feb 7, 2025
@iclanton iclanton merged commit 7b86640 into microsoft:main Feb 11, 2025
5 checks passed
@Josmithr Josmithr deleted the josmithr/api-extractor/fix-config-inheritence branch February 12, 2025 23:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Closed

Development

Successfully merging this pull request may close these issues.

2 participants