feat: dereference.preservedProperties for preserving data during dereferencing

[erunion]

This introduces a new dereference.preservedProperties configuration that allows for custom $ref dereferencing behavior to happen where if you want to preserve, and prioritize an existing, property you can.

The use case for this is theOpenAPI 3.1 specification where because it allows you to define a description and/or summary alongside a $ref pointer, and require that that description and summary take precedence over any that may be inside of the referenced schema there is currently no way to handle this within the library currently.

For example, the following schema:

{
  required: ['name'],
  type: 'object',
  definitions: {
    name: {
      type: 'string',
      description: "Someone's name",
    },
  },
  properties: {
    name: {
      $ref: '#/definitions/name',
    },
    secretName: {
      $ref: '#/definitions/name',
      description: "Someone's secret name",
    },
  },
  title: 'Person',
}

With the existing dereferencing behavior this schema is dereferenced into the following:

{
  required: [ 'name' ],
  type: 'object',
  definitions: { name: { type: 'string', description: "Someone's name" } },
  properties: {
    name: { type: 'string', description: "Someone's name" },
    secretName: { type: 'string', description: "Someone's name" }
  },
  title: 'Person'
}

However, because in an OpenAPI 3.1 definition I would want to use "Someone's secret name" instead of "Someone's name" on the secretName property, using this new configuration I can do that:

await $RefParser.dereference(schema, {
  dereference: {
    preservedProperties: ['description'],
  }
});

{
  required: [ 'name' ],
  type: 'object',
  definitions: { name: { type: 'string', description: "Someone's name" } },
  properties: {
    name: { type: 'string', description: "Someone's name" },
    secretName: { type: 'string', description: "Someone's secret name" }
  },
  title: 'Person'
}

1. Why make this configurable instead of the default behavior? Because this seems to be specific to OpenAPI 3.1 and it could potentially be a big breaking change to how people are currently handling these sorts of cases.
2. This config is generic and has nothing specific to OpenAPI 3.1 though. Correct. This behavior would be handled upstream in consumers of the library (like swagger-parser) and conditionally feed in this config for OpenAPI 3.1 definitions.

Closes #365

[jonluca]

nit: can we wrap this logic and this object allocation inside a check for if derefOptions?.preservedProperties is set? if its not set we can skip a lot of this logic.

[erunion]

Absolutely!

[coveralls]

Pull Request Test Coverage Report for Build 13020401245

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

• For more information on this, see Tracking coverage changes with pull request builds.
• To avoid this issue with future PRs, see these Recommended CI Configurations.
• For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

• 17 of 17 (100.0%) changed or added relevant lines in 1 file are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage increased (+0.6%) to 92.739%

---

Totals
Change from base Build 13011635299:	0.6%
Covered Lines:	1624
Relevant Lines:	1722

---

💛 - Coveralls

[jonluca]

This lgtm - if you can address the minor comment then I'll merge it in. Thanks!

[erunion]

@jonluca I've just pushed up your recs. Thanks for the speedy review! 💨

[github-actions]

🎉 This PR is included in version 11.9.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀