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.9.1

---

Release Notes

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

v4.9.1

Compare Source

v4.9.0

Compare Source

v4.8.0

Compare Source

v4.7.0

Compare Source

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

4.1.0 (2024-08-07)

Features Added

• Vector Search: This feature introduces vector indexes, vector embedding policy and vector queries to enable vector similarity search in JS SDK. docs
• All versions and deletes mode in change feed: The All versions and deletes mode is added in change feed mode which captures every version and every change (create, update, and delete) made to items. docs
• Bypassing integrated cache: The option to bypass integrated cache is now available in RequestOptions. docs
• Computed Properties: Support for adding Computed Properties in items is added. docs
• Composite Indexing: The JS SDK now supports including composite indexes in the indexing policy, improving query performance on multiple fields. docs
• Correlated Activity Id: Correlated Activity Id is added in header of every query request on Items. This helps in troubleshooting by linking all requests for a query that involves multiple server interactions and partitions. Correlated Activity Id can be accessed through query response headers or response.correlatedActivityId.
• Split proof Bulk API: Earlier, whenever Bulk API encountered a partition split during processing, it would return an error message. Now, JS SDK ensures that the Bulk API is resistant to partition split. #​18682
• Improved samples: The samples have been updated in this release, now organized into two folders: v3 for features up to the v3 release, and v4 for features up to the v4 release.
• Added support for MakeList and MakeSet query aggregators

Vector Search

• The following sample shows how to create a container with vector embedding and indexing policies.

// define vector indexing policy
const vectorEmbeddingPolicy = {
  vectorEmbeddings: [
    {
      path: "/vector1",
      dataType: VectorEmbeddingDataType.UInt8,
      dimensions: 1000,
      distanceFunction: VectorEmbeddingDistanceFunction.Euclidean,
    },
    {
      path: "/vector2",
      dataType: VectorEmbeddingDataType.Int8,
      dimensions: 200,
      distanceFunction: VectorEmbeddingDistanceFunction.DotProduct,
    },
    {
      path: "/vector3",
      dataType: VectorEmbeddingDataType.UInt8,
      dimensions: 400,
      distanceFunction: VectorEmbeddingDistanceFunction.Cosine,
    },
  ],
};

// add vector indexes in Indexing Policy
const indexingPolicy = {
  automatic: true,
  indexingMode: "consistent",
  vectorIndexes: [
    { path: "/vector1", type: VectorIndexType.Flat },
    { path: "/vector2", type: VectorIndexType.QuantizedFlat },
    { path: "/vector3", type: VectorIndexType.DiskANN },
  ],
};

// define and create container with vector Embedding Policy
const containerDefinition = {
  id: containerId,
  partitionKey: { paths: ["/id"] },
  indexingPolicy: indexingPolicy,
  vectorEmbeddingPolicy: vectorEmbeddingPolicy,
};
await database.containers.createIfNotExists(containerDefinition);

• Vector Search queries without TOP or LIMIT+OFFSET are blocked by default, with an option to disable this check using allowUnboundedNonStreamingQueries in query FeedOptions. Also added an internal buffer size check to prevent excessive memory consumption, throwing errors if the buffer size exceeds the default. The max buffer size can be increased using the vectorSearchBufferSize option from query FeedOptions.

Change Feed - All versions and deletes mode

• The AllVersionsAndDeletes mode is only supported with ChangeFeedStartFrom.Now and ChangeFeedStartFrom.Continuation.
• To read from the change feed in all versions and deletes mode, include changeFeedMode in changeFeedIteratorOptions:

    const changeFeedIteratorOptions: ChangeFeedIteratorOptions = {
      maxItemCount: 5,
      changeFeedStartFrom: ChangeFeedStartFrom.Now(),
      changeFeedMode: ChangeFeedMode.AllVersionsAndDeletes,
    };
    const iterator = container.items.getChangeFeedIterator(changeFeedIteratorOptions);

Bypassing Integrated Cache

• Here is a sample showing how to enable bypassIntegratedCache in RequestOptions.

  const options: RequestOptions = {bypassIntegratedCache: true};
  const response = await container.item("1").read(options);

Computed Properties

• The following snippet configures computed properties for a container:

    const computedProperties: ComputedProperty[] = [{
      name: "lowerLastName",
      query:
        "SELECT VALUE LOWER(IS_DEFINED(c.lastName) ? c.lastName : c.parents[0].familyName) FROM c",
    },];
    const { resource: containerdef } = await database.containers.createIfNotExists({
      id: containerName,
      computedProperties: computedProperties,
      indexingPolicy: indexingPolicy,
    });
    const container: Container = database.container(containerdef.id);

Composite Indexing

• Here's a sample of adding composite indexes for a container:

    const containerDefinition: ContainerDefinition = {
      id: "containerWithCompositeIndexingPolicy",
      indexingPolicy: {
        automatic: true,
        indexingMode: IndexingMode.consistent,
        includedPaths: [
          {
            path: "/*",
          },
        ],
        excludedPaths: [],
        compositeIndexes: [
          [
            { path: "/key", order: "ascending" },
            { path: "/field", order: "ascending" },
          ],
        ],
      },
    };
    await database.containers.create(containerDefinition);

• Added support for passing a custom HttpClient when constructing a CosmosClient.

Breaking Changes

Dropped Support for TypeScript 4.1

• We have opted to discontinue support for TypeScript version 4.1. Consequently, the minimum supported TypeScript version has been elevated to 4.2. Kindly ensure that your environment is promptly updated to align with these changes.

Bugs Fixed

• Fix Bulk operations(Read, Delete, and Patch) failing due to wrong format of partition key in non-partitioned container.

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

Details

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

Details

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

Details

• 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.