chore(deps): update dependency @azure/cosmos to v4

[renovate]

This PR contains the following updates:

Package	Change	Age	Confidence
@azure/cosmos (source)	^3.17.3 -> ^3.17.3 || ^4.0.0
@azure/cosmos (source)	3.17.3 -> 4.6.0

---

Release Notes

Azure/azure-sdk-for-js (@​azure/cosmos)

v4.6.0

Compare Source

v4.5.1

Compare Source

v4.5.0

Compare Source

v4.4.1

Compare Source

v4.4.0

Compare Source

v4.3.0

Compare Source

4.3.0 (2025-03-18)

Features Added

Client-side Encryption (Preview) #​28760

Add support for Client-Side Encryption. Read more here: docs

Example of using Client-Side Encryption:

 const credentials = new DefaultAzureCredential();
 const keyResolver = new AzureKeyVaultEncryptionKeyResolver(credentials);
 const cosmosClient = new CosmosClient({connectionString: "<ConnectionString>", clientEncryptionOptions: { keyEncryptionKeyResolver: keyResolver }});
 const database = cosmosClient.database("my-database");
 const metadata: EncryptionKeyWrapMetadata = {
     type: EncryptionKeyResolverName.AzureKeyVault, 
     name: "akvKey", 
     value: "https://<my-key-vault>.vault.azure.net/keys/<key>/<version>",
     algorithm: KeyEncryptionAlgorithm.RSA_OAEP
 };

 await database.createClientEncryptionKey(
     "my-key",
     EncryptionAlgorithm.AEAD_AES_256_CBC_HMAC_SHA256,
     metadata);

 const path1 : ClientEncryptionIncludedPath = {
   path: "/property1",
   clientEncryptionKeyId: "my-key",
   encryptionType: EncryptionType.DETERMINISTIC,
   encryptionAlgorithm: EncryptionAlgorithm.AEAD_AES_256_CBC_HMAC_SHA256,
 };
 const path2 : ClientEncryptionIncludedPath = {
   path: "/property2",
   clientEncryptionKeyId: "my-key",
   encryptionType: EncryptionType.DETERMINISTIC,
   encryptionAlgorithm: EncryptionAlgorithm.AEAD_AES_256_CBC_HMAC_SHA256,
 };
 const paths = [path1, path2];
 const clientEncryptionPolicy = {
     includedPaths: [path],
     policyFormatVersion: 2,
 };
 const containerDefinition = {
     id: "my-container",
     partitionKey: {
       paths: ["/id"],
     },
     clientEncryptionPolicy: clientEncryptionPolicy,
 };
 await database.containers.createIfNotExists(containerDefinition);

New Query Pipeline

Introduced enableQueryControl flag to enhance query pipeline, giving users more control over their query execution.

By default, value of enableQueryControl is set as false keeping query pipeline older behavior as default, as explained below:

Previously, the SDK guaranteed that each fetchNext call would return maxItemCount number of results, provided those many results existed in the backend. While this behavior ensured a predictable output, the SDK may query backend partitions multiple times in a single fetchNext iteration. This can sometimes lead to higher RU consumption with no user control, especially when results are scattered across partitions. Also queries could run for extended periods as the SDK worked to fulfil the maxItemCount guarantee.

When enableQueryControl is set to true, Each fetchNext call will now query up to maxDegreeOfParallelism physical partitions. If no results are found, the SDK will return empty pages instead of continuing to search all partitions. Returning fewer or empty results in each iteration consumes less RUs and hands control back to the users, allowing them to decide whether to continue fetching more data. This approach provides more granular control over RU consumption.

Eg. usage of this flag to enable new query pipeline:

const options : FeedOptions = {
  enableQueryControl: true, // Flag to enable new query pipeline. Default value is false
  maxItemCount: 100,
  maxDegreeOfParallelism: 10,
  forceQueryPlan: true,
}
const queryIterator = container.items.query("query text", options);
const res = await queryIterator.fetchNext();

Partition merge support

This feature adds support for Partition merge (preview) feature. Requests from SDK will not be blocked, when the feature is enabled on the CosmosDB account.
Read more about merge here: docs

RU Bucketing (Preview)

Read more about RU Bucketing here: https://aka.ms/cosmsodb-bucketing

Partial hierarchical partition key support in Change Feed #​27059

This feature adds support for partial hierarchical partition key in Change Feed allowing the SDK to work seamlessly with partial Hierarchical partition keys, returning accurate change feed results regardless of which partition key components are provided in the iterator.

Eg. Container has partition key ["/name", "/zip", "/state"], change feed will work if, only value of name and zip is provided eg: ["john", "11011"]

Index Metrics V2 support

This feature adds support for V2 version of index metrics that returns the response in JSON format.

Example output of older version

Index Utilization Information
  Utilized Single Indexes
    Index Spec: /Item/?
    Index Impact Score: High
    ---
    Index Spec: /Price/?
    Index Impact Score: High
    ---
  Potential Single Indexes
  Utilized Composite Indexes
  Potential Composite Indexes
    Index Spec: /Item ASC, /Price ASC
    Index Impact Score: High
    ---

Example output of version V2

{"UtilizedIndexes":{"SingleIndexes":[{"IndexSpec":"/Item/?"},{"IndexSpec":"/Price/?"}],"CompositeIndexes":[]},"PotentialIndexes":{"SingleIndexes":[],"CompositeIndexes":[{"IndexSpecs":["/Item ASC","/Price ASC"],"IndexImpactScore":"High"}]}}

Add connectionString in CosmosClientOptions

ConnectionString can now be configured in CosmosClientOptions along with other configurations for client initialization.
Eg. usage:

const options = {
  connectionString: "<ConnectionString>",
  consistencyLevel: ConsistencyLevel.Strong
}

Bugs Fixed

• Fixed issue for incorrect ParallelizeCrossPartitionQuery header value. It was set to true if maxDegreeOfParallelism was set to 0 or 1 in FeedOptions while executing a query. #​31232
• Fixed the issue for incorrect results in Changefeed in case of internal TimeoutErrors #​32652
• Fix RequestOptions and SharedOptions #​27336
• Set default values in RetryOptions #​27312

Other Changes

• Deprecate the older changeFeed iterator in favor of the newer getChangeFeedIterator() method. #​32650

v4.2.0

Compare Source

v4.1.1

Compare Source

4.1.1 (2024-08-30)

Bugs Fixed

• Fixed a issue caused by accessing process without checking its existence in the global scope, it was leading to crashes in non-Node environments.
• The default value of continueOnError of BulkRequestOptions is now set to true. Pass { continueOnError: false } in bulkOptions to stop executing operations when one fails.

v4.1.0

Compare Source

v4.0.0

Compare Source

---

Configuration

📅 Schedule: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).

🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.

♻ Rebasing: Whenever PR is behind base branch, or you tick the rebase/retry checkbox.

🔕 Ignore: Close this PR and you won't be reminded about these updates again.

---

• If you want to rebase/retry this PR, check this box

---

This PR was generated by Mend Renovate. View the repository job log.

[llamapreview]

Auto Pull Request Review from LlamaPReview

1. Overview

1.1 Core Changes

• Primary purpose and scope: Update the dependency @azure/cosmos from version 3.17.3 to 4.2.0.
• Key components modified: The package.json and package-lock.json files to reflect the new dependency version.
• Cross-component impacts: Potential impacts on any component that interacts with Azure Cosmos DB, including data retrieval, indexing, and querying mechanisms.
• Business value alignment: Ensures the system leverages the latest features and improvements from the Azure Cosmos DB SDK, enhancing functionality and performance.

1.2 Technical Architecture

• System design modifications: The update introduces new features such as full text search, vector search, and composite indexing, which may require adjustments in how data is indexed and queried.
• Component interaction changes: Components interacting with Cosmos DB will need to be reviewed to ensure compatibility with the new SDK version.
• Integration points impact: Integration points with Cosmos DB will need to be tested to ensure they function correctly with the new SDK version.
• Dependency changes and implications: The update to @azure/cosmos v4.2.0 introduces new features and breaking changes that need to be addressed in the codebase.

2. Deep Technical Analysis

2.1 Code Logic Analysis

package.json - Dependency Update

• Submitted PR Code:

  "peerDependencies": {
-    "@azure/cosmos": "^3.17.3"
+    "@azure/cosmos": "^3.17.3 || ^4.0.0"
  }

• Analysis:
  • Current logic and potential issues: The current logic updates the @azure/cosmos dependency to support both version 3.17.3 and 4.0.0. This change introduces new features and breaking changes that need to be handled.
  • Edge cases and error handling: The update may introduce edge cases related to new features like vector search and composite indexing. Error handling for these new features needs to be implemented.
  • Cross-component impact: Components that interact with Cosmos DB will need to be updated to handle the new features and breaking changes.
  • Business logic considerations: The business logic for data retrieval and indexing may need to be adjusted to leverage the new features introduced in the SDK.
• LlamaPReview Suggested Improvements:

    "peerDependencies": {
      "@azure/cosmos": "^4.0.0"
    }

• Improvement rationale:
  • Technical benefits: Ensures that the application leverages the latest features and improvements from the Azure Cosmos DB SDK.
  • Business value: Enhances the functionality and performance of the application by leveraging the latest SDK features.
  • Risk assessment: There is a risk of introducing breaking changes that need to be addressed in the codebase.

2.2 Implementation Quality

• Code Structure:

  • Organization and modularity: The update is well-organized and modular, affecting only the dependency management files.
  • Design pattern adherence: The update adheres to standard dependency management practices.
  • Reusability aspects: The update does not introduce new code but ensures that the application can leverage new features from the SDK.
  • Maintainability factors: The update improves maintainability by ensuring that the application uses the latest SDK version.

• Error Handling:

  • Exception scenarios coverage: The update introduces new features that may require additional error handling.
  • Recovery mechanisms: Recovery mechanisms for new features like vector search and composite indexing need to be implemented.
  • Logging and monitoring: Logging and monitoring need to be updated to handle the new features introduced in the SDK.
  • User experience impact: The update may introduce new user experience considerations related to the new features.

• Performance Considerations:

  • Resource utilization: The update may introduce new performance considerations related to the new features.
  • Scalability aspects: The update improves scalability by leveraging the latest SDK features.
  • Bottleneck analysis: Bottlenecks related to the new features need to be analyzed and addressed.
  • Optimization opportunities: The update introduces optimization opportunities related to the new features.

3. Risk Assessment

3.1 Critical Issues

🔴 P0 (Must Fix):

• Issue: Breaking changes in the SDK may affect existing functionality.
• Impact:
  • Technical implications: Existing functionality that relies on the old SDK version may break.
  • Business consequences: Business operations that rely on the affected functionality may be disrupted.
  • User experience effects: Users may experience disruptions in functionality that relies on the affected components.
• Resolution:
  • Specific code changes: Update the codebase to handle the breaking changes introduced in the new SDK version.
  • Configuration updates: Update configurations to leverage the new features introduced in the SDK.
  • Testing requirements: Thoroughly test the application to ensure that the breaking changes are handled correctly.

3.2 Important Improvements

🟡 P1 (Should Fix):

• Issue: New features introduced in the SDK may require additional error handling and logging.
• Current Impact:
  • Performance implications: The new features may introduce performance considerations that need to be addressed.
  • Maintenance overhead: The new features may introduce maintenance overhead related to error handling and logging.
  • Future scalability: The new features improve future scalability by leveraging the latest SDK improvements.
• Suggested Solution:
  • Implementation approach: Implement additional error handling and logging for the new features introduced in the SDK.
  • Migration strategy: Migrate the codebase to leverage the new features introduced in the SDK.
  • Testing considerations: Thoroughly test the new features to ensure they function correctly and handle edge cases.

3.3 Minor Suggestions

🟢 P2 (Consider):

• Area: Documentation updates.
• Improvement Opportunity:
  • Code quality enhancement: Update the documentation to reflect the new features and breaking changes introduced in the SDK.
  • Best practice alignment: Ensure that the documentation aligns with best practices for using the new SDK version.
  • Documentation updates: Update the documentation to provide guidance on leveraging the new features introduced in the SDK.

4. Requirements Analysis

4.1 Functional Coverage

• Requirements mapping:
  • Implemented features: The update implements the new features introduced in the @azure/cosmos SDK version 4.2.0.
  • Missing elements: Ensure that all new features are leveraged and that breaking changes are handled.
  • Edge cases handling: Implement error handling for edge cases related to the new features.
• Business Logic:
  • Use case coverage: The update covers use cases related to the new features introduced in the SDK.
  • Business rule implementation: Ensure that business rules are implemented correctly for the new features.
  • Data flow correctness: Ensure that data flow is correct for the new features introduced in the SDK.

4.2 Non-functional Aspects

• Performance metrics: Monitor performance metrics related to the new features introduced in the SDK.
• Security considerations: Ensure that the new features do not introduce security vulnerabilities.
• Scalability factors: The new features improve scalability by leveraging the latest SDK improvements.
• Maintainability aspects: The update improves maintainability by ensuring that the application uses the latest SDK version.

5. Testing Strategy

• Test Coverage:
  • Unit test requirements: Implement unit tests for the new features introduced in the SDK.
  • Integration test scenarios: Implement integration tests to ensure that the new features function correctly with existing components.
  • Edge case validation: Validate edge cases related to the new features to ensure they are handled correctly.
• Quality Metrics:
  • Current coverage: Ensure that the current test coverage includes the new features introduced in the SDK.
  • Critical paths: Identify critical paths related to the new features and ensure they are thoroughly tested.
  • Performance benchmarks: Implement performance benchmarks to ensure that the new features meet performance requirements.

6. Final Assessment

6.1 Key Action Items

1. Critical Changes (P0):

   • Update the codebase to handle the breaking changes introduced in the new SDK version.
   • Thoroughly test the application to ensure that the breaking changes are handled correctly.

2. Important Improvements (P1):

   • Implement additional error handling and logging for the new features introduced in the SDK.
   • Migrate the codebase to leverage the new features introduced in the SDK.
   • Thoroughly test the new features to ensure they function correctly and handle edge cases.

3. Suggested Enhancements (P2):

   • Update the documentation to reflect the new features and breaking changes introduced in the SDK.
   • Ensure that the documentation aligns with best practices for using the new SDK version.
   • Provide guidance on leveraging the new features introduced in the SDK.

6.2 Overall Evaluation

• Technical assessment: The update introduces new features and breaking changes that need to be handled in the codebase.
• Business impact: The update enhances the functionality and performance of the application by leveraging the latest SDK features.
• Risk evaluation: There is a risk of introducing breaking changes that need to be addressed in the codebase.
• Implementation quality: The update improves the implementation quality by ensuring that the application uses the latest SDK version.

---

💡 LlamaPReview Community
Have feedback on this AI Code review tool? Join our GitHub Discussions to share your thoughts and help shape the future of LlamaPReview.