Skip to content
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

fix(api-extractor): More predictable merging of arrays in configuration #5071

Open
wants to merge 5 commits into
base: main
Choose a base branch
from

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
{
"packageName": "@microsoft/api-extractor",
"comment": "Update merge behavior for derived configurations to allow overriding array properties",
"type": "minor"
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@octogonz per your suggestion, I made this a minor-level change. This change is technically breaking, but the new behavior is much more predictable.

@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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Status: AE/AD
Development

Successfully merging this pull request may close these issues.

1 participant