fix(NODE-6029): update types for collection listing indexes

[prenaissance]

Description

What is changing?

Update the return type of Collection.prototype.indexes and Collection.prototype.indexInformation to an array of indexes with full properties when the full option is true and to a Record of <index name> - <keys and direction> when the full option is false.

Is there new documentation needed for these changes?

No.

What is the motivation for this change?

The old types were incorrect in regards to the full option and were very wide. This will avoid making some type mistakes when using these methods.

Release Highlight

Index information helpers have accurate Typescript return types

Collection.indexInformation(), Collection.indexes() and Db.indexInformation() are helpers that return index information for a given collection or database. These helpers take an option, full, that configures whether the return value contains full index descriptions or a compact summary:

collection.indexes({ full: true });   // returns an array of index descriptions
collection.indexes({ full: false });  // returns an object, mapping index names to index keys

However, the Typescript return type of these helpers was always Document. Thanks to @prenaissance, these helpers now have accurate type information! The helpers return a new type, IndexDescriptionCompact | IndexDescriptionInfo[], which accurately reflects the return type of these helpers. The helpers also support type narrowing by providing a boolean literal as an option to the API:

collection.indexes();   // returns `IndexDescriptionCompact | IndexDescriptionInfo[]`
collection.indexes({ full: false });  // returns an `IndexDescriptionCompact`
collection.indexes({ full: true });  // returns an `IndexDescriptionInfo[]`

collection.indexInfo();   // returns `IndexDescriptionCompact | IndexDescriptionInfo[]`
collection.indexInfo({ full: false });  // returns an `IndexDescriptionCompact`
collection.indexInfo({ full: true });  // returns an `IndexDescriptionInfo[]`

db.indexInfo();   // returns `IndexDescriptionCompact | IndexDescriptionInfo[]`
db.indexInfo({ full: false });  // returns an `IndexDescriptionCompact`
db.indexInfo({ full: true });  // returns an `IndexDescriptionInfo[]`

Double check the following

• Ran npm run check:lint script
• Self-review completed using the steps outlined here
• PR title follows the correct format: type(NODE-xxxx)[!]: description
  • Example: feat(NODE-1234)!: rewriting everything in coffeescript
• Changes are covered by tests
• New TODOs have a related JIRA ticket

[baileympearson]

Hey @prenaissance - thanks for the submission! I left some comments about the implementation.

[baileympearson]

We generally try to keep our type definitions for server responses flexible so that if the server modifies a response in a future server version the driver is still compatible with it. Could we & Document here? I think that will provide type safety on known keys but will allow unknown keys without a Typescript error.

[baileympearson]

It's preferrable to avoid computed types as the return types from our APIs, since they don't provided users with information about the return type of a function until a user 1) reads the source of the computed type or 2) writes code using the API and checks the computed return type. Could we accomplish the same here using overloads and removing all TFull generics? Something like:

  indexInformation(
    options: IndexInformationOptions & { full: true }
  ): Promise<IndexDescriptionInfo[]>;
  indexInformation(
    options: IndexInformationOptions & { full: false }
  ): Promise<IndexDescriptionCompact>;
  indexInformation(
    options: IndexInformationOptions & { full: boolean }
  ): Promise<IndexDescriptionCompact | IndexDescriptionInfo[]>;

This has the additional benefits of

• better documentation, because our tooling will generate a doc entry for each overload
• clearly defined overloads with existing IDE tooling
• each overload can be documented originally (if desired).

for example - here's what VSCode could hypothetically display if we used overloads:

[baileympearson]

We could consider this a breaking change, since existing users' code that makes use of IndexInformationOptions would break because they wouldn't be providing a generic argument. We could fix this by providing a default, but I think overloads are preferable (see my comment on Collection.indexInformation()).

[prenaissance]

Hey @prenaissance - thanks for the submission! I left some comments about the implementation.

Thank you for the feedback. I fixed the comments and also added tests for Db.prototype.indexInformation

[baileympearson]

one last round of small comments, otherwise LGTM

[durran]

I just updated the description from Document.prototype call outs to Collection.prototype