Provide better documentation

Oct 13, 2025 by wbrum.org 42 views

Introduction

In this article, we will discuss a peculiar issue encountered while using the Chat Confirmation API in a specific codebase. The problem arose when passing undefined as data to the confirmation method, resulting in unexpected behavior and errors. We will delve into the code, identify the root cause, and propose improvements to make the API more robust and user-friendly.

The Issue

The problematic code snippet is as follows:

outputStream.confirmation(
  l10n.t('Pick a testing framework'),
  l10n.t('Pick from these options, or use chat to tell me what you\'d prefer:'),
  undefined,
  frameworks,
);

Here, undefined is passed as the third argument to the confirmation method. This method is defined in the vscode.proposed.chatParticipantAdditions.d.ts file, which can be found in the VS Code repository.

When the user chooses a choice, the acceptedConfirmationData is received as an array with a single null entry. This is because the confirmation method returns an array containing the accepted data, which is null in this case. The code that handles this data is as follows:

this.request.acceptedConfirmationData?.find(ref => ref.foo);

However, this code throws an error because we are not safely referencing foo on ref with ref?.foo. This is due to the fact that ref is null, and we are trying to access a property on it.

The Root Cause

The root cause of this issue is the use of any in the Chat Confirmation API. The confirmation method returns an array of any type, which means it can contain any type of data, including null. This makes the API hard to use and prone to extension author mistakes.

Improvements

To improve the Chat Confirmation API, we can make the following changes:

Specify the return type: Instead of returning an array of any, we can specify the return type as an array of a specific type, such as string[] or object[]. This will make it clear what type of data the method returns and will help prevent errors.
Handle null values: We can add a check to handle null values in the acceptedConfirmationData array. For example, we can use the ?. optional chaining operator to safely access properties on ref only if it is not null.
Provide better documentation: We can improve the documentation for the Chat Confirmation API to make it clear what type of data the method returns and how to handle null values.

Conclusion

In conclusion, the Chat Confirmation API had odd behavior when using undefined for data. The root cause of this issue was the use of any in the API, which made it hard to use and prone to extension author mistakes. By specifying the return type, handling null values, and providing better documentation, we can improve the Chat Confirmation API and make it more robust and user-friendly.

Recommendations

Based on our analysis, we recommend the following:

Use specific return types: Instead of using any as the return type, specify the return type as an array of a specific type.
Handle null values: Add checks to handle null values in the acceptedConfirmationData array.
Provide better documentation: Improve the documentation for the Chat Confirmation API to make it clear what type of data the method returns and how to handle null values.

By following these recommendations, we can improve the Chat Confirmation API and make it more robust and user-friendly.

Future Work

In the future, we can further improve the Chat Confirmation API by:

Adding type guards: Add type guards to ensure that the acceptedConfirmationData array contains only the expected type of data.
Providing more robust error handling: Improve error handling to provide more informative error messages and to prevent errors from occurring in the first place.

Frequently Asked Questions

In this article, we will answer some frequently asked questions about the Chat Confirmation API and its behavior when using undefined for data.

Q: What is the Chat Confirmation API?

A: The Chat Confirmation API is a part of the VS Code extension API that allows developers to create chat-based interfaces for their extensions. It provides a way to confirm user input and receive data from the user.

Q: What is the issue with using `undefined` for data in the Chat Confirmation API?

A: When using undefined for data in the Chat Confirmation API, it can cause unexpected behavior and errors. Specifically, when the user chooses a choice, the acceptedConfirmationData is received as an array with a single null entry. This can cause code like this.request.acceptedConfirmationData?.find(ref => ref.foo) to throw an error because we are not safely referencing foo on ref with ref?.foo.

Q: Why is the Chat Confirmation API returning an array with a single `null` entry?

A: The Chat Confirmation API is returning an array with a single null entry because the confirmation method returns an array containing the accepted data, which is null in this case.

Q: How can I fix the issue with using `undefined` for data in the Chat Confirmation API?

A: To fix the issue with using undefined for data in the Chat Confirmation API, you can specify the return type as an array of a specific type, such as string[] or object[]. You can also add a check to handle null values in the acceptedConfirmationData array.

Q: What are some best practices for using the Chat Confirmation API?

A: Some best practices for using the Chat Confirmation API include:

Specify the return type: Instead of using any as the return type, specify the return type as an array of a specific type.
Handle null values: Add checks to handle null values in the acceptedConfirmationData array.
Provide better documentation: Improve the documentation for the Chat Confirmation API to make it clear what type of data the method returns and how to handle null values.

Q: How can I improve the Chat Confirmation API?

A: To improve the Chat Confirmation API, you can:

Add type guards: Add type guards to ensure that the acceptedConfirmationData array contains only the expected type of data.
Provide more robust error handling: Improve error handling to provide more informative error messages and to prevent errors from occurring in the first place.

Q: Where can I find more information about the Chat Confirmation API?

A: You can find more information about the Chat Confirmation API in the VS Code documentation.

Conclusion

In conclusion, the Chat Confirmation API had odd behavior when using undefined for data. By understanding the root cause of the issue and following best practices, we can improve the Chat Confirmation API and make it more robust and user-friendly.

Recommendations

Based on our analysis, we recommend the following:

Use specific return types: Instead of using any as the return type, specify the return type as an array of a specific type.
Handle null values: Add checks to handle null values in the acceptedConfirmationData array.
Provide better documentation: Improve the documentation for the Chat Confirmation API to make it clear what type of data the method returns and how to handle null values.

By following these recommendations, we can improve the Chat Confirmation API and make it more reliable and easier to use.