diff --git a/types/validator/index.d.ts b/types/validator/index.d.ts index 22ece45cd6adfb..41d29b0181ce73 100644 --- a/types/validator/index.d.ts +++ b/types/validator/index.d.ts @@ -289,9 +289,11 @@ declare namespace validator { /** * Check if the string's length (in UTF-8 bytes) falls in a range. * - * @param [options] - Options + * @param [optionsOrMin] - Options, or the minimum byte length allowed. + * @param [max] - The maximum byte length allowed. */ - export function isByteLength(str: string, options?: IsByteLengthOptions): boolean; + export function isByteLength(str: string, optionsOrMin?: number | IsByteLengthOptions): boolean; + export function isByteLength(str: string, min: number, max: number): boolean; export interface IsCreditCardOptions { /** diff --git a/types/validator/validator-tests.ts b/types/validator/validator-tests.ts index 3788f6da21a8e6..2aea101679f22d 100644 --- a/types/validator/validator-tests.ts +++ b/types/validator/validator-tests.ts @@ -21,7 +21,7 @@ import isBeforeFunc, { IsBeforeOptions } from "validator/lib/isBefore"; import isBICFunc from "validator/lib/isBIC"; import isBooleanFunc from "validator/lib/isBoolean"; import isBtcAddressFunc from "validator/lib/isBtcAddress"; -import isByteLengthFunc from "validator/lib/isByteLength"; +import isByteLengthFunc, { IsByteLengthOptions } from "validator/lib/isByteLength"; import isCreditCardFunc from "validator/lib/isCreditCard"; import isCurrencyFunc from "validator/lib/isCurrency"; import isDataURIFunc from "validator/lib/isDataURI"; @@ -428,7 +428,7 @@ import isBeforeFuncEs, { IsBeforeOptions as IsBeforeOptionsEs } from "validator/ import isBICFuncEs from "validator/es/lib/isBIC"; import isBooleanFuncEs from "validator/es/lib/isBoolean"; import isBtcAddressFuncEs from "validator/es/lib/isBtcAddress"; -import isByteLengthFuncEs from "validator/es/lib/isByteLength"; +import isByteLengthFuncEs, { IsByteLengthOptions as IsByteLengthOptionsEs } from "validator/es/lib/isByteLength"; import isCreditCardFuncEs from "validator/es/lib/isCreditCard"; import isCurrencyFuncEs from "validator/es/lib/isCurrency"; import isDataURIFuncEs from "validator/es/lib/isDataURI"; @@ -762,8 +762,17 @@ const any: any = null; result = validator.isBoolean("sample"); - const isByteLengthOptions: validator.IsByteLengthOptions = {}; - result = validator.isByteLength("sample", isByteLengthOptions); + result = validator.isByteLength("sample"); + result = validator.isByteLength("sample", {}); + result = validator.isByteLength("sample", { min: 16, max: 64 } satisfies IsByteLengthOptions); + result = validator.isByteLength("sample", 16); + result = validator.isByteLength("sample", 16, 64); + // Both overloads happen to allow using exactly two argument, [str, number] & [str, object] + // Hence if 2nd arg is of union type `number | object`, typechecking can pass. + result = validator.isByteLength("sample", result ? 16 : { min: 16 }); + // @ts-expect-error + // Using 3rd arg here is problematic, without first ensuring that the 2nd argument is a number. + result = validator.isByteLength("sample", result ? 16 : { min: 16 }, 64); const isCreditCardOptions: validator.IsCreditCardOptions = {}; result = validator.isCreditCard("sample"); // $ExpectType boolean diff --git a/types/vscode/index.d.ts b/types/vscode/index.d.ts index e4d1fbf5230298..011f68eec7df36 100644 --- a/types/vscode/index.d.ts +++ b/types/vscode/index.d.ts @@ -1,11 +1,10 @@ /*--------------------------------------------------------------------------------------------- * Copyright (c) Microsoft Corporation. All rights reserved. - * Licensed under the MIT License. - * See License.txt in the project root for license information. + * Licensed under the MIT License. See License.txt in the project root for license information. *--------------------------------------------------------------------------------------------*/ /** - * Type Definition for Visual Studio Code 1.105 Extension API + * Type Definition for Visual Studio Code 1.106 Extension API * See https://code.visualstudio.com/api for more information */ @@ -1878,89 +1877,105 @@ declare module 'vscode' { } /** - * The kind of {@link QuickPickItem quick pick item}. + * Defines the kind of {@link QuickPickItem quick pick item}. */ export enum QuickPickItemKind { /** - * When a {@link QuickPickItem} has a kind of {@link Separator}, the item is just a visual separator and does not represent a real item. - * The only property that applies is {@link QuickPickItem.label label }. All other properties on {@link QuickPickItem} will be ignored and have no effect. + * A separator item that provides a visual grouping. + * + * When a {@link QuickPickItem} has a kind of {@link Separator}, the item is just a visual separator + * and does not represent a selectable item. The only property that applies is + * {@link QuickPickItem.label label}. All other properties on {@link QuickPickItem} will be ignored + * and have no effect. */ Separator = -1, /** - * The default {@link QuickPickItem.kind} is an item that can be selected in the quick pick. + * The default kind for an item that can be selected in the quick pick. */ Default = 0, } /** - * Represents an item that can be selected from - * a list of items. + * Represents an item that can be selected from a list of items. */ export interface QuickPickItem { /** - * A human-readable string which is rendered prominent. Supports rendering of {@link ThemeIcon theme icons} via - * the `$()`-syntax. + * A human-readable string which is rendered prominently. + * + * Supports rendering of {@link ThemeIcon theme icons} via the `$()`-syntax. * - * Note: When {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Default} (so a regular item - * instead of a separator), it supports rendering of {@link ThemeIcon theme icons} via the `$()`-syntax. + * **Note:** When {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Default} (so a regular + * item instead of a separator), it supports rendering of {@link ThemeIcon theme icons} via the + * `$()`-syntax. */ label: string; /** - * The kind of QuickPickItem that will determine how this item is rendered in the quick pick. When not specified, - * the default is {@link QuickPickItemKind.Default}. + * The kind of this item that determines how it is rendered in the quick pick. + * + * When not specified, the default is {@link QuickPickItemKind.Default}. */ kind?: QuickPickItemKind; /** - * The icon path or {@link ThemeIcon} for the QuickPickItem. + * The icon for the item. */ iconPath?: IconPath; /** - * A human-readable string which is rendered less prominent in the same line. Supports rendering of - * {@link ThemeIcon theme icons} via the `$()`-syntax. + * A human-readable string which is rendered less prominently in the same line. * - * Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator} + * Supports rendering of {@link ThemeIcon theme icons} via the `$()`-syntax. + * + * **Note:** This property is ignored when {@link QuickPickItem.kind kind} is set to + * {@link QuickPickItemKind.Separator}. */ description?: string; /** - * A human-readable string which is rendered less prominent in a separate line. Supports rendering of - * {@link ThemeIcon theme icons} via the `$()`-syntax. + * A human-readable string which is rendered less prominently in a separate line. + * + * Supports rendering of {@link ThemeIcon theme icons} via the `$()`-syntax. * - * Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator} + * **Note:** This property is ignored when {@link QuickPickItem.kind kind} is set to + * {@link QuickPickItemKind.Separator}. */ detail?: string; /** - * Optional flag indicating if this item is picked initially. This is only honored when using - * the {@link window.showQuickPick showQuickPick()} API. To do the same thing with - * the {@link window.createQuickPick createQuickPick()} API, simply set the {@link QuickPick.selectedItems} - * to the items you want picked initially. - * (*Note:* This is only honored when the picker allows multiple selections.) + * Optional flag indicating if this item is initially selected. + * + * This is only honored when using the {@link window.showQuickPick showQuickPick} API. To do the same + * thing with the {@link window.createQuickPick createQuickPick} API, simply set the + * {@link QuickPick.selectedItems selectedItems} to the items you want selected initially. + * + * **Note:** This is only honored when the picker allows multiple selections. * * @see {@link QuickPickOptions.canPickMany} * - * Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator} + * **Note:** This property is ignored when {@link QuickPickItem.kind kind} is set to + * {@link QuickPickItemKind.Separator}. */ picked?: boolean; /** - * Always show this item. + * Determines if this item is always shown, even when filtered out by the user's input. * - * Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator} + * **Note:** This property is ignored when {@link QuickPickItem.kind kind} is set to + * {@link QuickPickItemKind.Separator}. */ alwaysShow?: boolean; /** - * Optional buttons that will be rendered on this particular item. These buttons will trigger - * an {@link QuickPickItemButtonEvent} when clicked. Buttons are only rendered when using a quickpick - * created by the {@link window.createQuickPick createQuickPick()} API. Buttons are not rendered when using - * the {@link window.showQuickPick showQuickPick()} API. + * Optional buttons that will be rendered on this particular item. + * + * These buttons will trigger an {@link QuickPickItemButtonEvent} when pressed. Buttons are only rendered + * when using a quick pick created by the {@link window.createQuickPick createQuickPick} API. Buttons are + * not rendered when using the {@link window.showQuickPick showQuickPick} API. * - * Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator} + * **Note:** This property is ignored when {@link QuickPickItem.kind kind} is set to + * {@link QuickPickItemKind.Separator}. */ buttons?: readonly QuickInputButton[]; } @@ -1971,33 +1986,33 @@ declare module 'vscode' { export interface QuickPickOptions { /** - * An optional string that represents the title of the quick pick. + * An optional title for the quick pick. */ title?: string; /** - * An optional flag to include the description when filtering the picks. + * Determines if the {@link QuickPickItem.description description} should be included when filtering items. Defaults to `false`. */ matchOnDescription?: boolean; /** - * An optional flag to include the detail when filtering the picks. + * Determines if the {@link QuickPickItem.detail detail} should be included when filtering items. Defaults to `false`. */ matchOnDetail?: boolean; /** - * An optional string to show as placeholder in the input box to guide the user what to pick on. + * An optional string to show as placeholder in the input box to guide the user. */ placeHolder?: string; /** * Set to `true` to keep the picker open when focus moves to another part of the editor or to another window. - * This setting is ignored on iPad and is always false. + * This setting is ignored on iPad and is always `false`. */ ignoreFocusOut?: boolean; /** - * An optional flag to make the picker accept multiple selections, if true the result is an array of picks. + * Determines if the picker allows multiple selections. When `true`, the result is an array of picks. */ canPickMany?: boolean; @@ -2008,24 +2023,24 @@ declare module 'vscode' { } /** - * Options to configure the behaviour of the {@link WorkspaceFolder workspace folder} pick UI. + * Options to configure the behavior of the {@link WorkspaceFolder workspace folder} pick UI. */ export interface WorkspaceFolderPickOptions { /** - * An optional string to show as placeholder in the input box to guide the user what to pick on. + * An optional string to show as placeholder in the input box to guide the user. */ placeHolder?: string; /** * Set to `true` to keep the picker open when focus moves to another part of the editor or to another window. - * This setting is ignored on iPad and is always false. + * This setting is ignored on iPad and is always `false`. */ ignoreFocusOut?: boolean; } /** - * Options to configure the behaviour of a file open dialog. + * Options to configure the behavior of a file open dialog. * * * Note 1: On Windows and Linux, a file dialog cannot be both a file selector and a folder selector, so if you * set both `canSelectFiles` and `canSelectFolders` to `true` on these platforms, a folder selector will be shown. @@ -2161,39 +2176,38 @@ declare module 'vscode' { } /** - * Impacts the behavior and appearance of the validation message. - */ - /** - * The severity level for input box validation. + * Severity levels for input box validation messages. */ export enum InputBoxValidationSeverity { /** - * Informational severity level. + * Indicates an informational message that does not prevent input acceptance. */ Info = 1, /** - * Warning severity level. + * Indicates a warning message that does not prevent input acceptance. */ Warning = 2, /** - * Error severity level. + * Indicates an error message that prevents the user from accepting the input. */ Error = 3 } /** - * Object to configure the behavior of the validation message. + * Represents a validation message for an {@link InputBox}. */ export interface InputBoxValidationMessage { /** - * The validation message to display. + * The validation message to display to the user. */ readonly message: string; /** - * The severity of the validation message. - * NOTE: When using `InputBoxValidationSeverity.Error`, the user will not be allowed to accept (hit ENTER) the input. - * `Info` and `Warning` will still allow the InputBox to accept the input. + * The severity level of the validation message. + * + * **Note:** When using {@link InputBoxValidationSeverity.Error}, the user will not be able to accept + * the input (e.g., by pressing Enter). {@link InputBoxValidationSeverity.Info Info} and + * {@link InputBoxValidationSeverity.Warning Warning} severities will still allow the input to be accepted. */ readonly severity: InputBoxValidationSeverity; } @@ -4470,6 +4484,12 @@ declare module 'vscode' { * semantic tokens. */ export interface DocumentRangeSemanticTokensProvider { + + /** + * An optional event to signal that the semantic tokens from this provider have changed. + */ + onDidChangeSemanticTokens?: Event; + /** * @see {@link DocumentSemanticTokensProvider.provideDocumentSemanticTokens provideDocumentSemanticTokens}. */ @@ -7791,6 +7811,8 @@ declare module 'vscode' { * @param commandLine The command line to execute, this is the exact text that will be sent * to the terminal. * + * @throws When run on a terminal doesn't support this API, such as task terminals. + * * @example * // Execute a command in a terminal immediately after being created * const myTerm = window.createTerminal(); @@ -11357,7 +11379,7 @@ declare module 'vscode' { * @param items An array of strings, or a promise that resolves to an array of strings. * @param options Configures the behavior of the selection list. * @param token A token that can be used to signal cancellation. - * @returns A promise that resolves to the selected items or `undefined`. + * @returns A thenable that resolves to the selected items or `undefined`. */ export function showQuickPick(items: readonly string[] | Thenable, options: QuickPickOptions & { /** literal-type defines return type */canPickMany: true }, token?: CancellationToken): Thenable; @@ -11367,7 +11389,7 @@ declare module 'vscode' { * @param items An array of strings, or a promise that resolves to an array of strings. * @param options Configures the behavior of the selection list. * @param token A token that can be used to signal cancellation. - * @returns A promise that resolves to the selection or `undefined`. + * @returns A thenable that resolves to the selected string or `undefined`. */ export function showQuickPick(items: readonly string[] | Thenable, options?: QuickPickOptions, token?: CancellationToken): Thenable; @@ -11377,7 +11399,7 @@ declare module 'vscode' { * @param items An array of items, or a promise that resolves to an array of items. * @param options Configures the behavior of the selection list. * @param token A token that can be used to signal cancellation. - * @returns A promise that resolves to the selected items or `undefined`. + * @returns A thenable that resolves to the selected items or `undefined`. */ export function showQuickPick(items: readonly T[] | Thenable, options: QuickPickOptions & { /** literal-type defines return type */ canPickMany: true }, token?: CancellationToken): Thenable; @@ -11387,7 +11409,7 @@ declare module 'vscode' { * @param items An array of items, or a promise that resolves to an array of items. * @param options Configures the behavior of the selection list. * @param token A token that can be used to signal cancellation. - * @returns A promise that resolves to the selected item or `undefined`. + * @returns A thenable that resolves to the selected item or `undefined`. */ export function showQuickPick(items: readonly T[] | Thenable, options?: QuickPickOptions, token?: CancellationToken): Thenable; @@ -11421,23 +11443,22 @@ declare module 'vscode' { /** * Opens an input box to ask the user for input. * - * The returned value will be `undefined` if the input box was canceled (e.g. pressing ESC). Otherwise the + * The returned value will be `undefined` if the input box was canceled (e.g., pressing ESC). Otherwise the * returned value will be the string typed by the user or an empty string if the user did not type * anything but dismissed the input box with OK. * * @param options Configures the behavior of the input box. * @param token A token that can be used to signal cancellation. - * @returns A promise that resolves to a string the user provided or to `undefined` in case of dismissal. + * @returns A thenable that resolves to a string the user provided or to `undefined` in case of dismissal. */ export function showInputBox(options?: InputBoxOptions, token?: CancellationToken): Thenable; /** - * Creates a {@link QuickPick} to let the user pick an item from a list - * of items of type T. + * Creates a {@link QuickPick} to let the user pick an item from a list of items of type `T`. * - * Note that in many cases the more convenient {@link window.showQuickPick} - * is easier to use. {@link window.createQuickPick} should be used - * when {@link window.showQuickPick} does not offer the required flexibility. + * Note that in many cases the more convenient {@link window.showQuickPick} is easier to use. + * {@link window.createQuickPick} should be used when {@link window.showQuickPick} does not offer + * the required flexibility. * * @returns A new {@link QuickPick}. */ @@ -11446,9 +11467,9 @@ declare module 'vscode' { /** * Creates a {@link InputBox} to let the user enter some text input. * - * Note that in many cases the more convenient {@link window.showInputBox} - * is easier to use. {@link window.createInputBox} should be used - * when {@link window.showInputBox} does not offer the required flexibility. + * Note that in many cases the more convenient {@link window.showInputBox} is easier to use. + * {@link window.createInputBox} should be used when {@link window.showInputBox} does not offer + * the required flexibility. * * @returns A new {@link InputBox}. */ @@ -13001,115 +13022,115 @@ declare module 'vscode' { } /** - * A light-weight user input UI that is initially not visible. After - * configuring it through its properties the extension can make it - * visible by calling {@link QuickInput.show}. + * The base interface for all quick input types. + * + * Quick input provides a unified way for extensions to interact with users through simple UI elements. + * A quick input UI is initially not visible. After configuring it through its properties the extension + * can make it visible by calling {@link QuickInput.show show}. * - * There are several reasons why this UI might have to be hidden and - * the extension will be notified through {@link QuickInput.onDidHide}. - * (Examples include: an explicit call to {@link QuickInput.hide}, - * the user pressing Esc, some other input UI opening, etc.) + * There are several reasons why this UI might have to be hidden and the extension will be notified + * through {@link QuickInput.onDidHide onDidHide}. Examples include: an explicit call to + * {@link QuickInput.hide hide}, the user pressing Esc, some other input UI opening, etc. * - * A user pressing Enter or some other gesture implying acceptance - * of the current state does not automatically hide this UI component. - * It is up to the extension to decide whether to accept the user's input - * and if the UI should indeed be hidden through a call to {@link QuickInput.hide}. + * A user pressing Enter or some other gesture implying acceptance of the current state does not + * automatically hide this UI component. It is up to the extension to decide whether to accept the + * user's input and if the UI should indeed be hidden through a call to {@link QuickInput.hide hide}. * - * When the extension no longer needs this input UI, it should - * {@link QuickInput.dispose} it to allow for freeing up - * any resources associated with it. + * When the extension no longer needs this input UI, it should {@link QuickInput.dispose dispose} it + * to allow for freeing up any resources associated with it. * * See {@link QuickPick} and {@link InputBox} for concrete UIs. */ export interface QuickInput { /** - * An optional title. + * An optional title for the input UI. */ title: string | undefined; /** - * An optional current step count. + * An optional current step count for multi-step input flows. */ step: number | undefined; /** - * An optional total step count. + * An optional total step count for multi-step input flows. */ totalSteps: number | undefined; /** - * If the UI should allow for user input. Defaults to true. + * Determines if the UI should allow for user input. Defaults to `true`. * - * Change this to false, e.g., while validating user input or - * loading data for the next step in user input. + * Change this to `false`, for example, while validating user input or loading data for the next + * step in user input. */ enabled: boolean; /** - * If the UI should show a progress indicator. Defaults to false. + * Determines if the UI should show a progress indicator. Defaults to `false`. * - * Change this to true, e.g., while loading more data or validating - * user input. + * Change this to `true`, for example, while loading more data or validating user input. */ busy: boolean; /** - * If the UI should stay open even when loosing UI focus. Defaults to false. - * This setting is ignored on iPad and is always false. + * Determines if the UI should stay open even when losing UI focus. Defaults to `false`. + * This setting is ignored on iPad and is always `false`. */ ignoreFocusOut: boolean; /** - * Makes the input UI visible in its current configuration. Any other input - * UI will first fire an {@link QuickInput.onDidHide} event. + * Makes the input UI visible in its current configuration. + * + * Any other input UI will first fire an {@link QuickInput.onDidHide onDidHide} event. */ show(): void; /** - * Hides this input UI. This will also fire an {@link QuickInput.onDidHide} - * event. + * Hides this input UI. + * + * This will also fire an {@link QuickInput.onDidHide onDidHide} event. */ hide(): void; /** * An event signaling when this input UI is hidden. * - * There are several reasons why this UI might have to be hidden and - * the extension will be notified through {@link QuickInput.onDidHide}. - * (Examples include: an explicit call to {@link QuickInput.hide}, - * the user pressing Esc, some other input UI opening, etc.) + * There are several reasons why this UI might have to be hidden and the extension will be notified + * through {@link QuickInput.onDidHide onDidHide}. Examples include: an explicit call to + * {@link QuickInput.hide hide}, the user pressing Esc, some other input UI opening, etc. */ readonly onDidHide: Event; /** - * Dispose of this input UI and any associated resources. If it is still - * visible, it is first hidden. After this call the input UI is no longer - * functional and no additional methods or properties on it should be - * accessed. Instead a new input UI should be created. + * Dispose of this input UI and any associated resources. + * + * If it is still visible, it is first hidden. After this call the input UI is no longer functional + * and no additional methods or properties on it should be accessed. Instead a new input UI should + * be created. */ dispose(): void; } /** - * A concrete {@link QuickInput} to let the user pick an item from a - * list of items of type T. The items can be filtered through a filter text field and - * there is an option {@link QuickPick.canSelectMany canSelectMany} to allow for - * selecting multiple items. + * A concrete {@link QuickInput} to let the user pick an item from a list of items of type `T`. + * + * The items can be filtered through a filter text field and there is an option + * {@link QuickPick.canSelectMany canSelectMany} to allow for selecting multiple items. * - * Note that in many cases the more convenient {@link window.showQuickPick} - * is easier to use. {@link window.createQuickPick} should be used - * when {@link window.showQuickPick} does not offer the required flexibility. + * Note that in many cases the more convenient {@link window.showQuickPick} is easier to use. + * {@link window.createQuickPick} should be used when {@link window.showQuickPick} does not offer + * the required flexibility. */ export interface QuickPick extends QuickInput { /** - * Current value of the filter text. + * The current value of the filter text. */ value: string; /** - * Optional placeholder shown in the filter textbox when no filter has been entered. + * Optional placeholder text displayed in the filter text box when no value has been entered. */ placeholder: string | undefined; @@ -13129,14 +13150,17 @@ declare module 'vscode' { buttons: readonly QuickInputButton[]; /** - * An event signaling when a top level button (buttons stored in {@link buttons}) was triggered. - * This event does not fire for buttons on a {@link QuickPickItem}. + * An event signaling when a button was triggered. + * + * This event fires for buttons stored in the {@link QuickPick.buttons buttons} array. This event does + * not fire for buttons on a {@link QuickPickItem}. */ readonly onDidTriggerButton: Event; /** * An event signaling when a button in a particular {@link QuickPickItem} was triggered. - * This event does not fire for buttons in the title bar. + * + * This event does not fire for buttons in the title bar which are part of {@link QuickPick.buttons buttons}. */ readonly onDidTriggerItemButton: Event>; @@ -13146,22 +13170,22 @@ declare module 'vscode' { items: readonly T[]; /** - * If multiple items can be selected at the same time. Defaults to false. + * Determines if multiple items can be selected at the same time. Defaults to `false`. */ canSelectMany: boolean; /** - * If the filter text should also be matched against the description of the items. Defaults to false. + * Determines if the filter text should also be matched against the {@link QuickPickItem.description description} of the items. Defaults to `false`. */ matchOnDescription: boolean; /** - * If the filter text should also be matched against the detail of the items. Defaults to false. + * Determines if the filter text should also be matched against the {@link QuickPickItem.detail detail} of the items. Defaults to `false`. */ matchOnDetail: boolean; /** - * An optional flag to maintain the scroll position of the quick pick when the quick pick items are updated. Defaults to false. + * Determines if the scroll position is maintained when the quick pick items are updated. Defaults to `false`. */ keepScrollPosition?: boolean; @@ -13189,35 +13213,36 @@ declare module 'vscode' { /** * A concrete {@link QuickInput} to let the user input a text value. * - * Note that in many cases the more convenient {@link window.showInputBox} - * is easier to use. {@link window.createInputBox} should be used - * when {@link window.showInputBox} does not offer the required flexibility. + * Note that in many cases the more convenient {@link window.showInputBox} is easier to use. + * {@link window.createInputBox} should be used when {@link window.showInputBox} does not offer + * the required flexibility. */ export interface InputBox extends QuickInput { /** - * Current input value. + * The current input value. */ value: string; /** - * Selection range in the input value. Defined as tuple of two number where the - * first is the inclusive start index and the second the exclusive end index. When `undefined` the whole - * pre-filled value will be selected, when empty (start equals end) only the cursor will be set, - * otherwise the defined range will be selected. + * Selection range in the input value. + * + * Defined as tuple of two numbers where the first is the inclusive start index and the second the + * exclusive end index. When `undefined` the whole pre-filled value will be selected, when empty + * (start equals end) only the cursor will be set, otherwise the defined range will be selected. * - * This property does not get updated when the user types or makes a selection, - * but it can be updated by the extension. + * This property does not get updated when the user types or makes a selection, but it can be updated + * by the extension. */ valueSelection: readonly [number, number] | undefined; /** - * Optional placeholder shown when no value has been input. + * Optional placeholder text shown when no value has been input. */ placeholder: string | undefined; /** - * If the input value should be hidden. Defaults to false. + * Determines if the input value should be hidden. Defaults to `false`. */ password: boolean; @@ -13248,23 +13273,24 @@ declare module 'vscode' { /** * An optional validation message indicating a problem with the current input value. - * By returning a string, the InputBox will use a default {@link InputBoxValidationSeverity} of Error. - * Returning undefined clears the validation message. + * + * By setting a string, the InputBox will use a default {@link InputBoxValidationSeverity} of Error. + * Returning `undefined` clears the validation message. */ validationMessage: string | InputBoxValidationMessage | undefined; } /** - * Button for an action in a {@link QuickPick} or {@link InputBox}. + * A button for an action in a {@link QuickPick} or {@link InputBox}. */ export interface QuickInputButton { - /** - * Icon for the button. + * The icon for the button. */ readonly iconPath: IconPath; + /** - * An optional tooltip. + * An optional tooltip displayed when hovering over the button. */ readonly tooltip?: string | undefined; } @@ -13273,12 +13299,11 @@ declare module 'vscode' { * Predefined buttons for {@link QuickPick} and {@link InputBox}. */ export class QuickInputButtons { - /** - * A back button for {@link QuickPick} and {@link InputBox}. + * A predefined back button for {@link QuickPick} and {@link InputBox}. * - * When a navigation 'back' button is needed this one should be used for consistency. - * It comes with a predefined icon, tooltip and location. + * This button should be used for consistency when a navigation back button is needed. It comes + * with a predefined icon, tooltip, and location. */ static readonly Back: QuickInputButton; @@ -13289,12 +13314,11 @@ declare module 'vscode' { } /** - * An event signaling when a button in a particular {@link QuickPickItem} was triggered. - * This event does not fire for buttons in the title bar. + * An event describing a button that was pressed on a {@link QuickPickItem}. */ export interface QuickPickItemButtonEvent { /** - * The button that was clicked. + * The button that was pressed. */ readonly button: QuickInputButton; /** @@ -13874,6 +13898,14 @@ declare module 'vscode' { * * To stop listening to events the watcher must be disposed. * + * *Note* that file events from deleting a folder may not include events for the contained files. + * For example, when a folder is moved to the trash, only one event is reported because technically + * this is a rename/move operation and not a delete operation for each files within. + * On top of that, performance optimisations are in place to fold multiple events that all belong + * to the same parent operation (e.g. delete folder) into one event for that parent. As such, if + * you need to know about all deleted files, you have to watch with `**` and deal with all file + * events yourself. + * * *Note* that file events from recursive file watchers may be excluded based on user configuration. * The setting `files.watcherExclude` helps to reduce the overhead of file events from folders * that are known to produce many file changes at once (such as `.git` folders). As such, @@ -13894,11 +13926,6 @@ declare module 'vscode' { * In the same way, symbolic links are preserved, i.e. the file event will report the path of the * symbolic link as it was provided for watching and not the target. * - * *Note* that file events from deleting a folder may not include events for contained files but - * only the most top level folder that was deleted. This is a performance optimisation to reduce - * the overhead of file events being sent. If you need to know about all deleted files, you have - * to watch with `**` and deal with all file events yourself. - * * ### Examples * * The basic anatomy of a file watcher is as follows: @@ -17701,10 +17728,17 @@ declare module 'vscode' { readonly id: string; /** - * The access token. + * The access token. This token should be used to authenticate requests to a service. Popularized by OAuth. + * @reference https://oauth.net/2/access-tokens/ */ readonly accessToken: string; + /** + * The ID token. This token contains identity information about the user. Popularized by OpenID Connect. + * @reference https://openid.net/specs/openid-connect-core-1_0.html#IDToken + */ + readonly idToken?: string; + /** * The account associated with the session. */ @@ -20023,7 +20057,7 @@ declare module 'vscode' { * @param content The content of the message. * @param name The optional name of a user for the message. */ - static User(content: string | Array, name?: string): LanguageModelChatMessage; + static User(content: string | Array, name?: string): LanguageModelChatMessage; /** * Utility to create a new assistant message. @@ -20031,7 +20065,7 @@ declare module 'vscode' { * @param content The content of the message. * @param name The optional name of a user for the message. */ - static Assistant(content: string | Array, name?: string): LanguageModelChatMessage; + static Assistant(content: string | Array, name?: string): LanguageModelChatMessage; /** * The role of this message. @@ -20097,7 +20131,7 @@ declare module 'vscode' { * } * ``` */ - stream: AsyncIterable; + stream: AsyncIterable; /** * This is equivalent to filtering everything except for text parts from a {@link LanguageModelChatResponse.stream}. @@ -20545,12 +20579,12 @@ declare module 'vscode' { /** * The various message types which a {@linkcode LanguageModelChatProvider} can emit in the chat response stream */ - export type LanguageModelResponsePart = LanguageModelTextPart | LanguageModelToolResultPart | LanguageModelToolCallPart; + export type LanguageModelResponsePart = LanguageModelTextPart | LanguageModelToolResultPart | LanguageModelToolCallPart | LanguageModelDataPart; /** * The various message types which can be sent via {@linkcode LanguageModelChat.sendRequest } and processed by a {@linkcode LanguageModelChatProvider} */ - export type LanguageModelInputPart = LanguageModelTextPart | LanguageModelToolResultPart | LanguageModelToolCallPart; + export type LanguageModelInputPart = LanguageModelTextPart | LanguageModelToolResultPart | LanguageModelToolCallPart | LanguageModelDataPart; /** * A LanguageModelChatProvider implements access to language models, which users can then use through the chat view, or through extension API by acquiring a LanguageModelChat. @@ -20702,9 +20736,11 @@ declare module 'vscode' { * } * ``` * - * When a new McpServerDefinitionProvider is available, the editor will present a 'refresh' - * action to the user to discover new servers. To enable this flow, extensions should - * call `registerMcpServerDefinitionProvider` during activation. + * When a new McpServerDefinitionProvider is available, the editor will, by default, + * automatically invoke it to discover new servers and tools when a chat message is + * submitted. To enable this flow, extensions should call + * `registerMcpServerDefinitionProvider` during activation. + * * @param id The ID of the provider, which is unique to the extension. * @param provider The provider to register * @returns A disposable that unregisters the provider when disposed. @@ -20825,13 +20861,13 @@ declare module 'vscode' { /** * The value of the tool result. */ - content: Array; + content: Array; /** * @param callId The ID of the tool call. * @param content The content of the tool result. */ - constructor(callId: string, content: Array); + constructor(callId: string, content: Array); } /** @@ -20876,13 +20912,63 @@ declare module 'vscode' { * the future. * @see {@link lm.invokeTool}. */ - content: Array; + content: Array; /** * Create a LanguageModelToolResult * @param content A list of tool result content parts */ - constructor(content: Array); + constructor(content: Array); + } + + /** + * A language model response part containing arbitrary data. Can be used in {@link LanguageModelChatResponse responses}, + * {@link LanguageModelChatMessage chat messages}, {@link LanguageModelToolResult tool results}, and other language model interactions. + */ + export class LanguageModelDataPart { + /** + * Create a new {@linkcode LanguageModelDataPart} for an image. + * @param data Binary image data + * @param mime The MIME type of the image. Common values are `image/png` and `image/jpeg`. + */ + static image(data: Uint8Array, mime: string): LanguageModelDataPart; + + /** + * Create a new {@linkcode LanguageModelDataPart} for a json. + * + * *Note* that this function is not expecting "stringified JSON" but + * an object that can be stringified. This function will throw an error + * when the passed value cannot be JSON-stringified. + * @param value A JSON-stringifyable value. + * @param mime Optional MIME type, defaults to `application/json` + */ + static json(value: any, mime?: string): LanguageModelDataPart; + + /** + * Create a new {@linkcode LanguageModelDataPart} for text. + * + * *Note* that an UTF-8 encoder is used to create bytes for the string. + * @param value Text data + * @param mime The MIME type if any. Common values are `text/plain` and `text/markdown`. + */ + static text(value: string, mime?: string): LanguageModelDataPart; + + /** + * The mime type which determines how the data property is interpreted. + */ + mimeType: string; + + /** + * The byte data for this part. + */ + data: Uint8Array; + + /** + * Construct a generic data part with the given content. + * @param data The byte data for this part. + * @param mimeType The mime type of the data. + */ + constructor(data: Uint8Array, mimeType: string); } /** diff --git a/types/vscode/package.json b/types/vscode/package.json index 1d3b45f7770f1f..4de8dbb145fb90 100644 --- a/types/vscode/package.json +++ b/types/vscode/package.json @@ -1,7 +1,7 @@ { "private": true, "name": "@types/vscode", - "version": "1.105.9999", + "version": "1.106.9999", "projects": [ "https://github.com/microsoft/vscode" ],