@codingame/monaco-vscode-api 20.1.0 → 20.2.0

package/vscode/src/vs/base/common/numbers.d.ts

@@ -20,6 +20,51 @@ export declare class SlidingWindowAverage {
     update(value: number): number;
     get value(): number;
 }
+/** Returns whether the point is within the triangle formed by the following 6 x/y point pairs */
 export declare function isPointWithinTriangle(x: number, y: number, ax: number, ay: number, bx: number, by: number, cx: number, cy: number): boolean;
+/**
+ * Function to get a (pseudo)random integer from a provided `max`...[`min`] range.
+ * Both `min` and `max` values are inclusive. The `min` value is optional (defaults to `0`).
+ *
+ * @throws in the next cases:
+ * 	- if provided `min` or `max` is not a number
+ *  - if provided `min` or `max` is not finite
+ *  - if provided `min` is larger than `max` value
+ *
+ * ## Examples
+ *
+ * Specifying a `max` value only uses `0` as the `min` value by default:
+ *
+ * ```typescript
+ * // get a random integer between 0 and 10
+ * const randomInt = randomInt(10);
+ *
+ * assert(
+ *   randomInt >= 0,
+ *   'Should be greater than or equal to 0.',
+ * );
+ *
+ * assert(
+ *   randomInt <= 10,
+ *   'Should be less than or equal to 10.',
+ * );
+ * ```
+ * * Specifying both `max` and `min` values:
+ *
+ * ```typescript
+ * // get a random integer between 5 and 8
+ * const randomInt = randomInt(8, 5);
+ *
+ * assert(
+ *   randomInt >= 5,
+ *   'Should be greater than or equal to 5.',
+ * );
+ *
+ * assert(
+ *   randomInt <= 8,
+ *   'Should be less than or equal to 8.',
+ * );
+ * ```
+ */
 export declare function randomInt(max: number, min?: number): number;
 export declare function randomChance(p: number): boolean;

package/vscode/src/vs/base/common/oauth.d.ts

@@ -2,6 +2,9 @@ export declare const AUTH_PROTECTED_RESOURCE_METADATA_DISCOVERY_PATH = "/.well-k
 export declare const AUTH_SERVER_METADATA_DISCOVERY_PATH = "/.well-known/oauth-authorization-server";
 export declare const OPENID_CONNECT_DISCOVERY_PATH = "/.well-known/openid-configuration";
 export declare const AUTH_SCOPE_SEPARATOR = " ";
+/**
+ * Base OAuth 2.0 error codes as specified in RFC 6749.
+ */
 export declare enum AuthorizationErrorType {
     InvalidRequest = "invalid_request",
     InvalidClient = "invalid_client",
@@ -10,133 +13,483 @@ export declare enum AuthorizationErrorType {
     UnsupportedGrantType = "unsupported_grant_type",
     InvalidScope = "invalid_scope"
 }
+/**
+ * Device authorization grant specific error codes as specified in RFC 8628 section 3.5.
+ */
 export declare enum AuthorizationDeviceCodeErrorType {
+    /**
+     * The authorization request is still pending as the end user hasn't completed the user interaction steps.
+     */
     AuthorizationPending = "authorization_pending",
+    /**
+     * A variant of "authorization_pending", polling should continue but interval must be increased by 5 seconds.
+     */
     SlowDown = "slow_down",
+    /**
+     * The authorization request was denied.
+     */
     AccessDenied = "access_denied",
+    /**
+     * The "device_code" has expired and the device authorization session has concluded.
+     */
     ExpiredToken = "expired_token"
 }
+/**
+ * Dynamic client registration specific error codes as specified in RFC 7591.
+ */
 export declare enum AuthorizationRegistrationErrorType {
+    /**
+     * The value of one or more redirection URIs is invalid.
+     */
     InvalidRedirectUri = "invalid_redirect_uri",
+    /**
+     * The value of one of the client metadata fields is invalid and the server has rejected this request.
+     */
     InvalidClientMetadata = "invalid_client_metadata",
+    /**
+     * The software statement presented is invalid.
+     */
     InvalidSoftwareStatement = "invalid_software_statement",
+    /**
+     * The software statement presented is not approved for use by this authorization server.
+     */
     UnapprovedSoftwareStatement = "unapproved_software_statement"
 }
+/**
+ * Metadata about a protected resource.
+ */
 export interface IAuthorizationProtectedResourceMetadata {
+    /**
+     * REQUIRED. The protected resource's resource identifier URL that uses https scheme and has no fragment components.
+     */
     resource: string;
+    /**
+     * OPTIONAL. Human-readable name of the protected resource intended for display to the end user.
+     */
     resource_name?: string;
+    /**
+     * OPTIONAL. JSON array containing a list of OAuth authorization server identifiers.
+     */
     authorization_servers?: string[];
+    /**
+     * OPTIONAL. URL of the protected resource's JWK Set document.
+     */
     jwks_uri?: string;
+    /**
+     * RECOMMENDED. JSON array containing a list of the OAuth 2.0 scope values used in authorization requests.
+     */
     scopes_supported?: string[];
+    /**
+     * OPTIONAL. JSON array containing a list of the OAuth 2.0 Bearer Token presentation methods supported.
+     */
     bearer_methods_supported?: string[];
+    /**
+     * OPTIONAL. JSON array containing a list of the JWS signing algorithms supported.
+     */
     resource_signing_alg_values_supported?: string[];
+    /**
+     * OPTIONAL. JSON array containing a list of the JWE encryption algorithms supported.
+     */
     resource_encryption_alg_values_supported?: string[];
+    /**
+     * OPTIONAL. JSON array containing a list of the JWE encryption algorithms supported.
+     */
     resource_encryption_enc_values_supported?: string[];
+    /**
+     * OPTIONAL. URL of a page containing human-readable documentation.
+     */
     resource_documentation?: string;
+    /**
+     * OPTIONAL. URL that provides the resource's requirements on how clients can use the data.
+     */
     resource_policy_uri?: string;
+    /**
+     * OPTIONAL. URL that provides the resource's terms of service.
+     */
     resource_tos_uri?: string;
 }
+/**
+ * Metadata about an OAuth 2.0 Authorization Server.
+ */
 export interface IAuthorizationServerMetadata {
+    /**
+     * REQUIRED. The authorization server's issuer identifier URL that uses https scheme and has no query or fragment components.
+     */
     issuer: string;
+    /**
+     * URL of the authorization server's authorization endpoint.
+     * This is REQUIRED unless no grant types are supported that use the authorization endpoint.
+     */
     authorization_endpoint?: string;
+    /**
+     * URL of the authorization server's token endpoint.
+     * This is REQUIRED unless only the implicit grant type is supported.
+     */
     token_endpoint?: string;
+    /**
+     * OPTIONAL. URL of the authorization server's device code endpoint.
+     */
     device_authorization_endpoint?: string;
+    /**
+     * OPTIONAL. URL of the authorization server's JWK Set document containing signing keys.
+     */
     jwks_uri?: string;
+    /**
+     * OPTIONAL. URL of the authorization server's OAuth 2.0 Dynamic Client Registration endpoint.
+     */
     registration_endpoint?: string;
+    /**
+     * RECOMMENDED. JSON array containing a list of the OAuth 2.0 scope values supported.
+     */
     scopes_supported?: string[];
+    /**
+     * REQUIRED. JSON array containing a list of the OAuth 2.0 response_type values supported.
+     */
     response_types_supported: string[];
+    /**
+     * OPTIONAL. JSON array containing a list of the OAuth 2.0 response_mode values supported.
+     * Default is ["query", "fragment"].
+     */
     response_modes_supported?: string[];
+    /**
+     * OPTIONAL. JSON array containing a list of OAuth 2.0 grant type values supported.
+     * Default is ["authorization_code", "implicit"].
+     */
     grant_types_supported?: string[];
+    /**
+     * OPTIONAL. JSON array containing a list of client authentication methods supported by the token endpoint.
+     * Default is "client_secret_basic".
+     */
     token_endpoint_auth_methods_supported?: string[];
+    /**
+     * OPTIONAL. JSON array containing a list of JWS signing algorithms supported by the token endpoint.
+     */
     token_endpoint_auth_signing_alg_values_supported?: string[];
+    /**
+     * OPTIONAL. URL of a page containing human-readable documentation for developers.
+     */
     service_documentation?: string;
+    /**
+     * OPTIONAL. Languages and scripts supported for the user interface, as a JSON array of BCP 47 language tags.
+     */
     ui_locales_supported?: string[];
+    /**
+     * OPTIONAL. URL that the authorization server provides to read about the authorization server's requirements.
+     */
     op_policy_uri?: string;
+    /**
+     * OPTIONAL. URL that the authorization server provides to read about the authorization server's terms of service.
+     */
     op_tos_uri?: string;
+    /**
+     * OPTIONAL. URL of the authorization server's OAuth 2.0 revocation endpoint.
+     */
     revocation_endpoint?: string;
+    /**
+     * OPTIONAL. JSON array containing a list of client authentication methods supported by the revocation endpoint.
+     */
     revocation_endpoint_auth_methods_supported?: string[];
+    /**
+     * OPTIONAL. JSON array containing a list of JWS signing algorithms supported by the revocation endpoint.
+     */
     revocation_endpoint_auth_signing_alg_values_supported?: string[];
+    /**
+     * OPTIONAL. URL of the authorization server's OAuth 2.0 introspection endpoint.
+     */
     introspection_endpoint?: string;
+    /**
+     * OPTIONAL. JSON array containing a list of client authentication methods supported by the introspection endpoint.
+     */
     introspection_endpoint_auth_methods_supported?: string[];
+    /**
+     * OPTIONAL. JSON array containing a list of JWS signing algorithms supported by the introspection endpoint.
+     */
     introspection_endpoint_auth_signing_alg_values_supported?: string[];
+    /**
+     * OPTIONAL. JSON array containing a list of PKCE code challenge methods supported.
+     */
     code_challenge_methods_supported?: string[];
 }
+/**
+ * Response from the dynamic client registration endpoint.
+ */
 export interface IAuthorizationDynamicClientRegistrationResponse {
+    /**
+     * REQUIRED. The client identifier issued by the authorization server.
+     */
     client_id: string;
+    /**
+     * OPTIONAL. The client secret issued by the authorization server.
+     * Not returned for public clients.
+     */
     client_secret?: string;
+    /**
+     * OPTIONAL. Time at which the client secret will expire in seconds since the Unix Epoch.
+     */
     client_secret_expires_at?: number;
+    /**
+     * OPTIONAL. Client name as provided during registration.
+     */
     client_name?: string;
+    /**
+     * OPTIONAL. Client URI as provided during registration.
+     */
     client_uri?: string;
+    /**
+     * OPTIONAL. Array of redirection URIs as provided during registration.
+     */
     redirect_uris?: string[];
+    /**
+     * OPTIONAL. Array of grant types allowed for the client.
+     */
     grant_types?: string[];
+    /**
+     * OPTIONAL. Array of response types allowed for the client.
+     */
     response_types?: string[];
+    /**
+     * OPTIONAL. Type of authentication method used by the client.
+     */
     token_endpoint_auth_method?: string;
 }
+/**
+ * Response from the authorization endpoint.
+ * Typically returned as query parameters in a redirect.
+ */
 export interface IAuthorizationAuthorizeResponse {
+    /**
+     * REQUIRED. The authorization code generated by the authorization server.
+     */
     code: string;
+    /**
+     * REQUIRED. The state value that was sent in the authorization request.
+     * Used to prevent CSRF attacks.
+     */
     state: string;
 }
+/**
+ * Error response from the authorization endpoint.
+ */
 export interface IAuthorizationAuthorizeErrorResponse {
+    /**
+     * REQUIRED. Error code as specified in OAuth 2.0.
+     */
     error: string;
+    /**
+     * OPTIONAL. Human-readable description of the error.
+     */
     error_description?: string;
+    /**
+     * OPTIONAL. URI to a human-readable web page with more information about the error.
+     */
     error_uri?: string;
+    /**
+     * REQUIRED. The state value that was sent in the authorization request.
+     */
     state: string;
 }
+/**
+ * Response from the token endpoint.
+ */
 export interface IAuthorizationTokenResponse {
+    /**
+     * REQUIRED. The access token issued by the authorization server.
+     */
     access_token: string;
+    /**
+     * REQUIRED. The type of the token issued. Usually "Bearer".
+     */
     token_type: string;
+    /**
+     * RECOMMENDED. The lifetime in seconds of the access token.
+     */
     expires_in?: number;
+    /**
+     * OPTIONAL. The refresh token, which can be used to obtain new access tokens.
+     */
     refresh_token?: string;
+    /**
+     * OPTIONAL. The scope of the access token as a space-delimited list of strings.
+     */
     scope?: string;
+    /**
+     * OPTIONAL. ID Token value associated with the authenticated session for OpenID Connect flows.
+     */
     id_token?: string;
 }
+/**
+ * Error response from the token endpoint.
+ */
 export interface IAuthorizationTokenErrorResponse {
+    /**
+     * REQUIRED. Error code as specified in OAuth 2.0.
+     */
     error: string;
+    /**
+     * OPTIONAL. Human-readable description of the error.
+     */
     error_description?: string;
+    /**
+     * OPTIONAL. URI to a human-readable web page with more information about the error.
+     */
     error_uri?: string;
 }
+/**
+ * Response from the device authorization endpoint as per RFC 8628 section 3.2.
+ */
 export interface IAuthorizationDeviceResponse {
+    /**
+     * REQUIRED. The device verification code.
+     */
     device_code: string;
+    /**
+     * REQUIRED. The end-user verification code.
+     */
     user_code: string;
+    /**
+     * REQUIRED. The end-user verification URI on the authorization server.
+     */
     verification_uri: string;
+    /**
+     * OPTIONAL. A verification URI that includes the user_code, designed for non-textual transmission.
+     */
     verification_uri_complete?: string;
+    /**
+     * REQUIRED. The lifetime in seconds of the device_code and user_code.
+     */
     expires_in: number;
+    /**
+     * OPTIONAL. The minimum amount of time in seconds that the client should wait between polling requests.
+     * If no value is provided, clients must use 5 as the default.
+     */
     interval?: number;
 }
+/**
+ * Error response from the token endpoint when using device authorization grant.
+ * As defined in RFC 8628 section 3.5.
+ */
 export interface IAuthorizationErrorResponse {
+    /**
+     * REQUIRED. Error code as specified in OAuth 2.0 or in RFC 8628 section 3.5.
+     */
     error: AuthorizationErrorType | string;
+    /**
+     * OPTIONAL. Human-readable description of the error.
+     */
     error_description?: string;
+    /**
+     * OPTIONAL. URI to a human-readable web page with more information about the error.
+     */
     error_uri?: string;
 }
+/**
+ * Error response from the token endpoint when using device authorization grant.
+ * As defined in RFC 8628 section 3.5.
+ */
 export interface IAuthorizationDeviceTokenErrorResponse extends IAuthorizationErrorResponse {
+    /**
+     * REQUIRED. Error code as specified in OAuth 2.0 or in RFC 8628 section 3.5.
+     */
     error: AuthorizationErrorType | AuthorizationDeviceCodeErrorType | string;
 }
 export interface IAuthorizationRegistrationErrorResponse {
+    /**
+     * REQUIRED. Error code as specified in OAuth 2.0 or Dynamic Client Registration.
+     */
     error: AuthorizationRegistrationErrorType | string;
+    /**
+     * OPTIONAL. Human-readable description of the error.
+     */
     error_description?: string;
 }
 export interface IAuthorizationJWTClaims {
+    /**
+     * REQUIRED. JWT ID. Unique identifier for the token.
+     */
     jti: string;
+    /**
+     * REQUIRED. Subject. Principal about which the token asserts information.
+     */
     sub: string;
+    /**
+     * REQUIRED. Issuer. Entity that issued the token.
+     */
     iss: string;
+    /**
+     * OPTIONAL. Audience. Recipients that the token is intended for.
+     */
     aud?: string | string[];
+    /**
+     * OPTIONAL. Expiration time. Time after which the token is invalid (seconds since Unix epoch).
+     */
     exp?: number;
+    /**
+     * OPTIONAL. Not before time. Time before which the token is not valid (seconds since Unix epoch).
+     */
     nbf?: number;
+    /**
+     * OPTIONAL. Issued at time when the token was issued (seconds since Unix epoch).
+     */
     iat?: number;
+    /**
+     * OPTIONAL. Authorized party. The party to which the token was issued.
+     */
     azp?: string;
+    /**
+     * OPTIONAL. Scope values for which the token is valid.
+     */
     scope?: string;
+    /**
+     * OPTIONAL. Full name of the user.
+     */
     name?: string;
+    /**
+     * OPTIONAL. Given or first name of the user.
+     */
     given_name?: string;
+    /**
+     * OPTIONAL. Family name or last name of the user.
+     */
     family_name?: string;
+    /**
+     * OPTIONAL. Middle name of the user.
+     */
     middle_name?: string;
+    /**
+     * OPTIONAL. Preferred username or email the user wishes to be referred to.
+     */
     preferred_username?: string;
+    /**
+     * OPTIONAL. Email address of the user.
+     */
     email?: string;
+    /**
+     * OPTIONAL. True if the user's email has been verified.
+     */
     email_verified?: boolean;
+    /**
+     * OPTIONAL. User's profile picture URL.
+     */
     picture?: string;
+    /**
+     * OPTIONAL. Authentication time. Time when the user authentication occurred.
+     */
     auth_time?: number;
+    /**
+     * OPTIONAL. Authentication context class reference.
+     */
     acr?: string;
+    /**
+     * OPTIONAL. Authentication methods references.
+     */
     amr?: string[];
+    /**
+     * OPTIONAL. Session ID. String identifier for a session.
+     */
     sid?: string;
+    /**
+     * OPTIONAL. Address component.
+     */
     address?: {
         formatted?: string;
         street_address?: string;
@@ -145,8 +498,17 @@ export interface IAuthorizationJWTClaims {
         postal_code?: string;
         country?: string;
     };
+    /**
+     * OPTIONAL. Groups that the user belongs to.
+     */
     groups?: string[];
+    /**
+     * OPTIONAL. Roles assigned to the user.
+     */
     roles?: string[];
+    /**
+     * OPTIONAL. Handles optional claims that are not explicitly defined in the standard.
+     */
     [key: string]: unknown;
 }
 export declare function isAuthorizationProtectedResourceMetadata(obj: unknown): obj is IAuthorizationProtectedResourceMetadata;
@@ -158,6 +520,13 @@ export declare function isAuthorizationDeviceResponse(obj: unknown): obj is IAut
 export declare function isAuthorizationErrorResponse(obj: unknown): obj is IAuthorizationErrorResponse;
 export declare function isAuthorizationRegistrationErrorResponse(obj: unknown): obj is IAuthorizationRegistrationErrorResponse;
 export declare function getDefaultMetadataForUrl(authorizationServer: URL): IAuthorizationServerMetadata;
+/**
+ * Default port for the authorization flow. We try to use this port so that
+ * the redirect URI does not change when running on localhost. This is useful
+ * for servers that only allow exact matches on the redirect URI. The spec
+ * says that the port should not matter, but some servers do not follow
+ * the spec and require an exact match.
+ */
 export declare const DEFAULT_AUTH_FLOW_PORT = 33418;
 export declare function fetchDynamicRegistration(serverMetadata: IAuthorizationServerMetadata, clientName: string, scopes?: string[]): Promise<IAuthorizationDynamicClientRegistrationResponse>;
 export declare function parseWWWAuthenticateHeader(wwwAuthenticateHeaderValue: string): {

package/vscode/src/vs/base/common/objects.d.ts

@@ -1,12 +1,31 @@
 export declare function deepClone<T>(obj: T): T;
 export declare function deepFreeze<T>(obj: T): T;
 export declare function cloneAndChange(obj: any, changer: (orig: any) => any): any;
+/**
+ * Copies all properties of source into destination. The optional parameter "overwrite" allows to control
+ * if existing properties on the destination should be overwritten or not. Defaults to true (overwrite).
+ */
 export declare function mixin(destination: any, source: any, overwrite?: boolean): any;
 export declare function equals(one: any, other: any): boolean;
+/**
+ * Calls `JSON.Stringify` with a replacer to break apart any circular references.
+ * This prevents `JSON`.stringify` from throwing the exception
+ *  "Uncaught TypeError: Converting circular structure to JSON"
+ */
 export declare function safeStringify(obj: any): string;
 type obj = {
     [key: string]: any;
 };
+/**
+ * Returns an object that has keys for each value that is different in the base object. Keys
+ * that do not exist in the target but in the base object are not considered.
+ *
+ * Note: This is not a deep-diffing method, so the values are strictly taken into the resulting
+ * object if they differ.
+ *
+ * @param base the object to diff against
+ * @param obj the object to use for diffing
+ */
 export declare function distinct(base: obj, target: obj): obj;
 export declare function getCaseInsensitive(target: obj, key: string): unknown;
 export declare function filter(obj: obj, predicate: (key: string, value: any) => boolean): obj;