Update names in cosmos for consistency (#6110)

* Update names in cosmos for consistency

Fixes #5263 by updating names to align better with other packages, but leave old names for backwards compatibility until the next major version bump.

sdk/cosmosdb/cosmos/review/cosmos.api.md

@@ -168,6 +168,7 @@ export const Constants: {
         CollectionPartitionInfo: string;
         CollectionServiceInfo: string;
         RetryAfterInMilliseconds: string;
+        RetryAfterInMs: string;
         IsFeedUnfiltered: string;
         ResourceTokenExpiry: string;
         EnableScanInQuery: string;
@@ -257,6 +258,7 @@ export class Container {
     // (undocumented)
     readonly database: Database;
     delete(options?: RequestOptions): Promise<ContainerResponse>;
+    // @deprecated
     getPartitionKeyDefinition(): Promise<ResourceResponse<PartitionKeyDefinition>>;
     // Warning: (ae-forgotten-export) The symbol "PartitionedQueryExecutionInfo" needs to be exported by the entry point index.d.ts
     // 
@@ -267,6 +269,7 @@ export class Container {
     item(id: string, partitionKey: any): Item;
     readonly items: Items;
     read(options?: RequestOptions): Promise<ContainerResponse>;
+    readPartitionKeyDefinition(): Promise<ResourceResponse<PartitionKeyDefinition>>;
     // (undocumented)
     readPartitionKeyRanges(feedOptions?: FeedOptions): QueryIterator<PartitionKeyRange>;
     replace(body: ContainerDefinition, options?: RequestOptions): Promise<ContainerResponse>;
@@ -364,13 +367,23 @@ export class DatabaseAccount {
     constructor(body: {
         [key: string]: any;
     }, headers: CosmosHeaders);
+    // @deprecated
     readonly ConsistencyPolicy: ConsistencyLevel;
+    readonly consistencyPolicy: ConsistencyLevel;
+    // @deprecated
     readonly CurrentMediaStorageUsageInMB: number;
+    readonly currentMediaStorageUsageInMB: number;
+    // @deprecated
     readonly DatabasesLink: string;
+    readonly databasesLink: string;
     // (undocumented)
     readonly enableMultipleWritableLocations: boolean;
-    readonly MaxMediaStorageUsageInMB: number;
+    // @deprecated
+    readonly MaxMediaStorageUsageInMB: string;
+    readonly maxMediaStorageUsageInMB: number;
+    // @deprecated
     readonly MediaLink: string;
+    readonly mediaLink: string;
     readonly readableLocations: Location[];
     readonly writableLocations: Location[];
 }
@@ -429,6 +442,8 @@ export interface ErrorResponse extends Error {
     // (undocumented)
     retryAfterInMilliseconds?: number;
     // (undocumented)
+    retryAfterInMs?: number;
+    // (undocumented)
     substatus?: number;
 }
 
@@ -444,7 +459,9 @@ export interface FeedOptions extends SharedOptions {
         condition: string;
     };
     bufferItems?: boolean;
+    // @deprecated
     continuation?: string;
+    continuationToken?: string;
     continuationTokenLimitInKB?: number;
     enableScanInQuery?: boolean;
     forceQueryPlan?: boolean;
@@ -462,6 +479,8 @@ export class FeedResponse<TResource> {
     // (undocumented)
     readonly continuation: string;
     // (undocumented)
+    readonly continuationToken: string;
+    // (undocumented)
     readonly hasMoreResults: boolean;
     // (undocumented)
     readonly queryMetrics: string;
@@ -542,6 +561,10 @@ export class ItemResponse<T extends ItemDefinition> extends ResourceResponse<T &
 // @public
 export class Items {
     constructor(container: Container, clientContext: ClientContext);
+    changeFeed(partitionKey: string | number | boolean, changeFeedOptions: ChangeFeedOptions): ChangeFeedIterator<any>;
+    changeFeed(changeFeedOptions?: ChangeFeedOptions): ChangeFeedIterator<any>;
+    changeFeed<T>(partitionKey: string | number | boolean, changeFeedOptions: ChangeFeedOptions): ChangeFeedIterator<T>;
+    changeFeed<T>(changeFeedOptions?: ChangeFeedOptions): ChangeFeedIterator<T>;
     // (undocumented)
     readonly container: Container;
     create<T extends ItemDefinition = any>(body: T, options?: RequestOptions): Promise<ItemResponse<T>>;
@@ -551,9 +574,14 @@ export class Items {
     readAll<T extends ItemDefinition>(options?: FeedOptions): QueryIterator<T>;
     // Warning: (ae-forgotten-export) The symbol "ChangeFeedOptions" needs to be exported by the entry point index.d.ts
     // Warning: (ae-forgotten-export) The symbol "ChangeFeedIterator" needs to be exported by the entry point index.d.ts
+    // 
+    // @deprecated
     readChangeFeed(partitionKey: string | number | boolean, changeFeedOptions: ChangeFeedOptions): ChangeFeedIterator<any>;
+    // @deprecated
     readChangeFeed(changeFeedOptions?: ChangeFeedOptions): ChangeFeedIterator<any>;
+    // @deprecated
     readChangeFeed<T>(partitionKey: string | number | boolean, changeFeedOptions: ChangeFeedOptions): ChangeFeedIterator<T>;
+    // @deprecated
     readChangeFeed<T>(changeFeedOptions?: ChangeFeedOptions): ChangeFeedIterator<T>;
     upsert(body: any, options?: RequestOptions): Promise<ItemResponse<ItemDefinition>>;
     upsert<T extends ItemDefinition>(body: T, options?: RequestOptions): Promise<ItemResponse<T>>;

sdk/cosmosdb/cosmos/samples/ChangeFeed.ts

@@ -22,7 +22,9 @@ function doesMatch(actual: any[], expected: any[]) {
 
 function logResult(scenario: string, actual: any[], expected: any[]) {
   const status = doesMatch(actual, expected);
-  console.log(`  ${status} ${scenario} - expected: [${expected.join(", ")}] - actual: [${actual.join(", ")}]`);
+  console.log(
+    `  ${status} ${scenario} - expected: [${expected.join(", ")}] - actual: [${actual.join(", ")}]`
+  );
 }
 
 async function run() {
@@ -68,35 +70,49 @@ async function run() {
 
     console.log(`  👉 Inserted id=3`);
 
-    const specificContinuationIterator = container.items.readChangeFeed(pk, { continuation: lsn.toString() });
-    const specificPointInTimeIterator = container.items.readChangeFeed(pk, { startTime: now });
-    const fromBeginningIterator = container.items.readChangeFeed(pk, { startFromBeginning: true });
-    const fromNowIterator = container.items.readChangeFeed(pk, {});
+    const specificContinuationIterator = container.items.changeFeed(pk, {
+      continuation: lsn.toString()
+    });
+    const specificPointInTimeIterator = container.items.changeFeed(pk, { startTime: now });
+    const fromBeginningIterator = container.items.changeFeed(pk, { startFromBeginning: true });
+    const fromNowIterator = container.items.changeFeed(pk, {});
 
     const { result: specificContinuationResult } = await specificContinuationIterator.fetchNext();
 
-    logResult("initial specific Continuation scenario", [3], specificContinuationResult.map(v => parseInt(v.id)));
+    logResult(
+      "initial specific Continuation scenario",
+      [3],
+      specificContinuationResult.map((v) => parseInt(v.id))
+    );
 
     // First page is empty. It is catching up to a valid continuation.
     const { result: shouldBeEmpty } = await specificPointInTimeIterator.fetchNext();
     logResult(
       "initial specific point in time scenario should be empty while it finds the right continuation",
       [],
-      shouldBeEmpty.map(v => parseInt(v.id))
+      shouldBeEmpty.map((v) => parseInt(v.id))
     );
     // Second page should have results
     const { result: specificPointInTimeResults } = await specificPointInTimeIterator.fetchNext();
     logResult(
       "second specific point in time scenario should have caught up now",
       [2, 3],
-      specificPointInTimeResults.map(v => parseInt(v.id))
+      specificPointInTimeResults.map((v) => parseInt(v.id))
     );
 
     const { result: fromBeginningResults } = await fromBeginningIterator.fetchNext();
-    logResult("initial from beginning scenario", [1, 2, 3], fromBeginningResults.map(v => parseInt(v.id)));
+    logResult(
+      "initial from beginning scenario",
+      [1, 2, 3],
+      fromBeginningResults.map((v) => parseInt(v.id))
+    );
 
     const { result: fromNowResultsShouldBeEmpty } = await fromNowIterator.fetchNext();
-    logResult("initial from now scenario should be empty", [], fromNowResultsShouldBeEmpty.map(v => parseInt(v.id)));
+    logResult(
+      "initial from now scenario should be empty",
+      [],
+      fromNowResultsShouldBeEmpty.map((v) => parseInt(v.id))
+    );
 
     // Now they should all be caught up to the point after id=3, so if we insert a id=4, they should all get it.
     console.log("📢 Phase 2: All scenarios are caught up and should see the same results");
@@ -108,21 +124,25 @@ async function run() {
     logResult(
       "after insert, Specific Continuation scenario",
       [4],
-      specificContinuationResult2.map(v => parseInt(v.id))
+      specificContinuationResult2.map((v) => parseInt(v.id))
     );
 
     const { result: specificPointInTimeResults2 } = await specificPointInTimeIterator.fetchNext();
     logResult(
       "after insert, specific point in time scenario",
       [4],
-      specificPointInTimeResults2.map(v => parseInt(v.id))
+      specificPointInTimeResults2.map((v) => parseInt(v.id))
     );
 
     const { result: fromBeginningResults2 } = await fromBeginningIterator.fetchNext();
-    logResult("after insert, from beginning scenario", [4], fromBeginningResults2.map(v => parseInt(v.id)));
+    logResult(
+      "after insert, from beginning scenario",
+      [4],
+      fromBeginningResults2.map((v) => parseInt(v.id))
+    );
 
     const { result: fromNowResults2 } = await fromNowIterator.fetchNext();
-    logResult("after insert, from now scenario", [4], fromNowResults2.map(v => parseInt(v.id)));
+    logResult("after insert, from now scenario", [4], fromNowResults2.map((v) => parseInt(v.id)));
   } catch (err) {
     handleError(err);
   } finally {

sdk/cosmosdb/cosmos/src/ChangeFeedIterator.ts

@@ -12,7 +12,7 @@ import { Response } from "./request";
 /**
  * Provides iterator for change feed.
  *
- * Use `Items.readChangeFeed()` to get an instance of the iterator.
+ * Use `Items.changeFeed()` to get an instance of the iterator.
  */
 export class ChangeFeedIterator<T> {
   private static readonly IfNoneMatchAllHeaderValue = "*";

sdk/cosmosdb/cosmos/src/ChangeFeedResponse.ts

@@ -69,7 +69,7 @@ export class ChangeFeedResponse<T> {
    * Gets the entity tag associated with last transaction in the Azure Cosmos DB service,
    * which can be used as If-Non-Match Access condition for ReadFeed REST request or
    * `continuation` property of `ChangeFeedOptions` parameter for
-   * `Items.readChangeFeed()`
+   * `Items.changeFeed()`
    * to get feed changes since the transaction specified by this entity tag.
    *
    * This is equivalent to the `continuation` property.

sdk/cosmosdb/cosmos/src/client/Container/Container.ts

@@ -171,12 +171,23 @@ export class Container {
 
   /**
    * Gets the partition key definition first by looking into the cache otherwise by reading the collection.
-   * @ignore
+   * @deprecated This method has been renamed to readPartitionKeyDefinition.
    * @param {string} collectionLink   - Link to the collection whose partition key needs to be extracted.
    * @param {function} callback       - \
    * The arguments to the callback are(in order): error, partitionKeyDefinition, response object and response headers
    */
   public async getPartitionKeyDefinition(): Promise<ResourceResponse<PartitionKeyDefinition>> {
+    return this.readPartitionKeyDefinition();
+  }
+
+  /**
+   * Gets the partition key definition first by looking into the cache otherwise by reading the collection.
+   * @ignore
+   * @param {string} collectionLink   - Link to the collection whose partition key needs to be extracted.
+   * @param {function} callback       - \
+   * The arguments to the callback are(in order): error, partitionKeyDefinition, response object and response headers
+   */
+  public async readPartitionKeyDefinition(): Promise<ResourceResponse<PartitionKeyDefinition>> {
     // $ISSUE-felixfan-2016-03-17: Make name based path and link based path use the same key
     // $ISSUE-felixfan-2016-03-17: Refresh partitionKeyDefinitionCache when necessary
     if (this.url in this.clientContext.partitionKeyDefinitionCache) {

sdk/cosmosdb/cosmos/src/client/Item/Item.ts

@@ -75,7 +75,9 @@ export class Item {
     options: RequestOptions = {}
   ): Promise<ItemResponse<T>> {
     if (this.partitionKey === undefined) {
-      const { resource: partitionKeyDefinition } = await this.container.getPartitionKeyDefinition();
+      const {
+        resource: partitionKeyDefinition
+      } = await this.container.readPartitionKeyDefinition();
       this.partitionKey = undefinedPartitionKey(partitionKeyDefinition);
     }
     const path = getPathFromLink(this.url);
@@ -137,7 +139,9 @@ export class Item {
     options: RequestOptions = {}
   ): Promise<ItemResponse<T>> {
     if (this.partitionKey === undefined) {
-      const { resource: partitionKeyDefinition } = await this.container.getPartitionKeyDefinition();
+      const {
+        resource: partitionKeyDefinition
+      } = await this.container.readPartitionKeyDefinition();
       this.partitionKey = extractPartitionKey(body, partitionKeyDefinition);
     }
 
@@ -178,7 +182,9 @@ export class Item {
     options: RequestOptions = {}
   ): Promise<ItemResponse<T>> {
     if (this.partitionKey === undefined) {
-      const { resource: partitionKeyDefinition } = await this.container.getPartitionKeyDefinition();
+      const {
+        resource: partitionKeyDefinition
+      } = await this.container.readPartitionKeyDefinition();
       this.partitionKey = undefinedPartitionKey(partitionKeyDefinition);
     }
 

sdk/cosmosdb/cosmos/src/client/Item/Items.ts

@@ -103,6 +103,7 @@ export class Items {
    *
    * @param partitionKey
    * @param changeFeedOptions
+   * @deprecated Use `changeFeed` instead.
    *
    * @example Read from the beginning of the change feed.
    * ```javascript
@@ -118,12 +119,14 @@ export class Items {
   ): ChangeFeedIterator<any>;
   /**
    * Create a `ChangeFeedIterator` to iterate over pages of changes
+   * @deprecated Use `changeFeed` instead.
    *
    * @param changeFeedOptions
    */
   public readChangeFeed(changeFeedOptions?: ChangeFeedOptions): ChangeFeedIterator<any>;
   /**
    * Create a `ChangeFeedIterator` to iterate over pages of changes
+   * @deprecated Use `changeFeed` instead.
    *
    * @param partitionKey
    * @param changeFeedOptions
@@ -134,13 +137,65 @@ export class Items {
   ): ChangeFeedIterator<T>;
   /**
    * Create a `ChangeFeedIterator` to iterate over pages of changes
+   * @deprecated Use `changeFeed` instead.
    *
    * @param changeFeedOptions
    */
   public readChangeFeed<T>(changeFeedOptions?: ChangeFeedOptions): ChangeFeedIterator<T>;
   public readChangeFeed<T>(
     partitionKeyOrChangeFeedOptions?: string | number | boolean | ChangeFeedOptions,
     changeFeedOptions?: ChangeFeedOptions
+  ): ChangeFeedIterator<T> {
+    if (isChangeFeedOptions(partitionKeyOrChangeFeedOptions)) {
+      return this.changeFeed(partitionKeyOrChangeFeedOptions);
+    } else {
+      return this.changeFeed(partitionKeyOrChangeFeedOptions, changeFeedOptions);
+    }
+  }
+
+  /**
+   * Create a `ChangeFeedIterator` to iterate over pages of changes
+   *
+   * @param partitionKey
+   * @param changeFeedOptions
+   *
+   * @example Read from the beginning of the change feed.
+   * ```javascript
+   * const iterator = items.readChangeFeed({ startFromBeginning: true });
+   * const firstPage = await iterator.fetchNext();
+   * const firstPageResults = firstPage.result
+   * const secondPage = await iterator.fetchNext();
+   * ```
+   */
+  public changeFeed(
+    partitionKey: string | number | boolean,
+    changeFeedOptions: ChangeFeedOptions
+  ): ChangeFeedIterator<any>;
+  /**
+   * Create a `ChangeFeedIterator` to iterate over pages of changes
+   *
+   * @param changeFeedOptions
+   */
+  public changeFeed(changeFeedOptions?: ChangeFeedOptions): ChangeFeedIterator<any>;
+  /**
+   * Create a `ChangeFeedIterator` to iterate over pages of changes
+   *
+   * @param partitionKey
+   * @param changeFeedOptions
+   */
+  public changeFeed<T>(
+    partitionKey: string | number | boolean,
+    changeFeedOptions: ChangeFeedOptions
+  ): ChangeFeedIterator<T>;
+  /**
+   * Create a `ChangeFeedIterator` to iterate over pages of changes
+   *
+   * @param changeFeedOptions
+   */
+  public changeFeed<T>(changeFeedOptions?: ChangeFeedOptions): ChangeFeedIterator<T>;
+  public changeFeed<T>(
+    partitionKeyOrChangeFeedOptions?: string | number | boolean | ChangeFeedOptions,
+    changeFeedOptions?: ChangeFeedOptions
   ): ChangeFeedIterator<T> {
     let partitionKey: string | number | boolean;
     if (!changeFeedOptions && isChangeFeedOptions(partitionKeyOrChangeFeedOptions)) {
@@ -208,7 +263,7 @@ export class Items {
     body: T,
     options: RequestOptions = {}
   ): Promise<ItemResponse<T>> {
-    const { resource: partitionKeyDefinition } = await this.container.getPartitionKeyDefinition();
+    const { resource: partitionKeyDefinition } = await this.container.readPartitionKeyDefinition();
     const partitionKey = extractPartitionKey(body, partitionKeyDefinition);
 
     // Generate random document id if the id is missing in the payload and
@@ -277,7 +332,7 @@ export class Items {
     body: T,
     options: RequestOptions = {}
   ): Promise<ItemResponse<T>> {
-    const { resource: partitionKeyDefinition } = await this.container.getPartitionKeyDefinition();
+    const { resource: partitionKeyDefinition } = await this.container.readPartitionKeyDefinition();
     const partitionKey = extractPartitionKey(body, partitionKeyDefinition);
 
     // Generate random document id if the id is missing in the payload and

sdk/cosmosdb/cosmos/src/client/StoredProcedure/StoredProcedure.ts

@@ -118,7 +118,9 @@ export class StoredProcedure {
     options?: RequestOptions
   ): Promise<ResourceResponse<T>> {
     if (partitionKey === undefined) {
-      const { resource: partitionKeyDefinition } = await this.container.getPartitionKeyDefinition();
+      const {
+        resource: partitionKeyDefinition
+      } = await this.container.readPartitionKeyDefinition();
       partitionKey = undefinedPartitionKey(partitionKeyDefinition);
     }
     const response = await this.clientContext.execute<T>({