We removed 4.2 support recently, so we may not need this method at all. Can you verify?

👀

Based on chat offline, deprecated here means discouraged but not removed. So the option remains until the next major version of the server removes it. At that time, we can remove it too.

Outstanding TODO.

This parameter is not used in this function, think line 518 should be commandOptions ?? indexOptions.

Done.

Optional params on a private constructor doesn't buy us anything and is detrimental, suggest making this mandatory. (Detrimental because "I forgot to pass a parameter" and "I don't have anything to specify" become indistinguishable.)

Good point. If clustered is only every present on the response*, why do we need to expose it on a request object.

*Side question: how/when do we return clustered to the user? I'm not finding it yet.

Hmm, I adopted it wholesale from the spec's IndexOptions interface (clustered seen here: https://github.com/mongodb/specifications/blob/a9adc41b6eed59fd1197e852a2d8dccc4eaf16fb/source/index-management/index-management.md?plain=1#L806) but I'm not seeing IndexOptions itself used as the return type on any function, so perhaps it's a leftover?

We could bring that and the deprecated 4.2 field to the maintainers and see if it just needs a little cleanup.

Good idea to bring this up with the maintainers. My thought is that we should remove clustered and background, but let's see.

For clustered, that information comes through on the Document in this signature:

export type IndexDescriptionInfo = Omit<IndexDescription, 'key' | 'version'> & {
  key: { [key: string]: IndexDirection };
  v?: IndexDescription['version'];
} & Document;          // ← here

So then you can retrieve that data like this:

await db.createCollection('c', {
  clusteredIndex: { key: { _id: 1 }, unique: true, name: 'my_clustered_id' }
});
await db.collection('c').listIndexes().toArray();
// [ { v: 2, key: { _id: 1 }, name: 'my_clustered_id', unique: true, clustered: true } ]

Reading clustered works now, so there's no reason to add it.

When calling createIndex, a user opts-in to the new behavior by specifying an object.
This is not the same approach for createIndexes, where opt-in behavior is signaled with a boolean.
Should we have the same approaches in both spots, that is, specify an object to get the new behavior.

With createIndex I was able to discriminate on parameter count (2 vs. 3) because the signature was changing. createIndexes on the other hand has the types it needs so I wasn't able to use a new signature vs. old signature to do the same discrimination

Discussed offline, the plan is to document this behavior for the upcoming release, then remove it in v8.

Good point. If clustered is only every present on the response*, why do we need to expose it on a request object.

*Side question: how/when do we return clustered to the user? I'm not finding it yet.

Think we need to test optionName !== 'key' here.

Done. Filtered out key even when allowUnknownIndexOptions is true because I saw it is re-added by the caller to resolveIndexDescription

This interface is missing finestIndexedLevel and coarsestIndexedLevel, which are called out in the AC.

And in a related question, do we have a DRIVERS ticket that updates the specifications repo with these additions as well? I'm having trouble finding these.

This interface is closed, unknown options cannot be added to it. (That's why we need to keep adding @ts-expect-error in the tests, because there is currently no way to specify extra fields.)

I think we may need to add extend from Document here, to allow arbitrary string-key values:

export interface IndexOptions extends Document {

This should allow us to specify new fields without needing to suppress TS issues.

This might be a feature? In this scenario where this happens, the driver is lagging in adding an option to the interface after the server adds support for it and that the user is on the bleeding edge by adding it themselves.

@ts-expect-error is an obvious hint that a property is being added that isn't declared in the interface. When the driver adds it, @ts-expect-error will itself start to error, sending the user a signal that they are no longer force-adding an unknown option.

That may or may not be a useful signal, in which case I can extend from Document.

It seems strange to need a suppression for a "routine" use of the Driver, where "routine" means "I want to use an index feature my driver version isn't aware of". I don't think there's any benefit to "requiring" this hint, so let's extend from Document.

Need to add @deprecated and a message here, something like:

 * @deprecated Use the three parameter overload, which separates index options from
 * command options. This overload will be removed in a future major release.

Should this also be deprecated then?