[Cosmos] Naming Consistency

[southpolesteve]

Cosmos needs to alias some of our methods and options to match with other Azure SDKs. Some that have been identified already:

• maxRetryAttemptCount -> maxTries
• maxWaitTimeInSeconds -> timeoutInMs / timeoutInSeconds
• FixedRetryIntervalInMilliseconds -> retryIntervalInMs
• InMilliseconds -> InMs (in many places)

TODO:

• Full API audit with @bterlson to expand on the above list
• Alias old names to new names

[southpolesteve]

Additional notes from our last meetings:

• getPartitionKeyDefinition -> readPartitionKeyDefinition

• Top level CosmosClient methods

  • get -> read

• CosmosClientOptions

  • Should add pipelineOptions on move to core-http

• De-pascal case everything external. If it is internal, does not matter

• Actual constants -> SCREAMING SNAKE CASE if top level

• InMilliseconds -> InMs everywhere

• FeedOptions

  • continuation -> continuationToken

• readChangeFeed -> items.changeFeed.read()

• QueryIterator - Known issue. Make iterator a async iterator

• Brian to follow up on accessCondition vs accessConditions

[xirzec]

• Top level CosmosClient methods
  • get -> read

There are only three such methods on CosmosClient, getDatabaseAccount, getWriteEndpoint, and
getReadEndpoint.

None of them sound particularly improved by this conversion, especially the last two: readDatabaseAccount, readWriteEndpoint, readReadEndpoint

• CosmosClientOptions

  • Should add pipelineOptions on move to core-http

This seems like longer-lead work than simple renames. Is it really something we want to bundle with the other work?

• De-pascal case everything external. If it is internal, does not matter

I'm not seeing where we have PascalCase methods/properties?

• Actual constants -> SCREAMING SNAKE CASE if top level

Is this referring to things like const WindowsInterruptedFunctionCall = 10004; ?

• readChangeFeed -> items.changeFeed.read()

I'm confused about this one. Is the idea that readChangeFeed() becomes a getter named changeFeed that still returns a ChangeFeedIterator? Does something in ChangeFeedIterator need to change so it has read instead of fetchNext ?

• Brian to follow up on accessCondition vs accessConditions

@bterlson ?

[xirzec]

I'd also appreciate if @southpolesteve or @bterlson could clarify what is meant by 'aliasing'.

For example, I could leave the method getPartitionKeyDefinition and have it simply return the result of calling readPartitionKeyDefinition, but it's subtler what we should do for interfaces.

Like for ErrorResponse if we rename retryAfterInMilliseconds to retryAfterInMs, do we have to go to every implementer and make sure both properties exist and are in sync? Except since it's an optional property, this is tricky to enforce, since it would still be valid to the interface if only one existed.

TBH, it feels weird to strive for backcompat here, either take a major version bump or abandon consistency.

[xirzec]

Notes from chatting about this:

• alias changes as best we can (getters, mostly)
• skip retryoptions changes
• add issue tracking refactoring retryoptions and renaming [Created [cosmosdb] Rename RetryOptions parameters #6149]
• skip cosmosclient method renames, add issue for refactoring later [Created [cosmosdb] Rename CosmosClient methods #6150]
• add issue for moving to core-http, link to retryoptions [Created [cosmosdb] Move to use core-http #6151]
• rename readChangeFeed() to changeFeed()