Skip to content

[api-extractor] More predictable merging of arrays in configuration #5071

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

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