@codingame/monaco-vscode-api 20.1.1 → 20.2.0

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

@@ -2,6 +2,13 @@ export declare const LANGUAGE_DEFAULT = "en";
 export interface IProcessEnvironment {
     [key: string]: string | undefined;
 }
+/**
+ * This interface is intentionally not identical to node.js
+ * process because it also works in sandboxed environments
+ * where the process object is implemented differently. We
+ * define the properties here that we need for `platform`
+ * to work and nothing else.
+ */
 export interface INodeProcess {
     platform: string;
     arch: string;
@@ -33,19 +40,49 @@ export declare const isWebWorker: boolean;
 export declare const webWorkerOrigin: any;
 export declare const isIOS: boolean;
 export declare const isMobile: boolean;
+/**
+ * Whether we run inside a CI environment, such as
+ * GH actions or Azure Pipelines.
+ */
 export declare const isCI: boolean;
 export declare const platform: Platform;
 export declare const userAgent: string | undefined;
+/**
+ * The language used for the user interface. The format of
+ * the string is all lower case (e.g. zh-tw for Traditional
+ * Chinese or de for German)
+ */
 export declare const language: string;
 export declare namespace Language {
     function value(): string;
     function isDefaultVariant(): boolean;
     function isDefault(): boolean;
 }
+/**
+ * Desktop: The OS locale or the locale specified by --locale or `argv.json`.
+ * Web: matches `platformLocale`.
+ *
+ * The UI is not necessarily shown in the provided locale.
+ */
 export declare const locale: string | undefined;
+/**
+ * This will always be set to the OS/browser's locale regardless of
+ * what was specified otherwise. The format of the string is all
+ * lower case (e.g. zh-tw for Traditional Chinese). The UI is not
+ * necessarily shown in the provided locale.
+ */
 export declare const platformLocale: string;
+/**
+ * The translations that are available through language packs.
+ */
 export declare const translationsConfigFile: string | undefined;
 export declare const setTimeout0IsFaster: boolean;
+/**
+ * See https://html.spec.whatwg.org/multipage/timers-and-user-prompts.html#:~:text=than%204%2C%20then-,set%20timeout%20to%204,-.
+ *
+ * Works similarly to `setTimeout(0)` but doesn't suffer from the 4ms artificial delay
+ * that browsers set when the nesting level is > 5.
+ */
 export declare const setTimeout0: (callback: () => void) => void;
 export declare enum OperatingSystem {
     Windows = 1,

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

@@ -1,28 +1,51 @@
 declare const unset: unique symbol;
 export interface IPrefixTreeNode<T> {
+    /** Possible children of the node. */
     children?: ReadonlyMap<string, Node<T>>;
+    /** The value if data exists for this node in the tree. Mutable. */
     value: T | undefined;
 }
+/**
+ * A simple prefix tree implementation where a value is stored based on
+ * well-defined prefix segments.
+ */
 export declare class WellDefinedPrefixTree<V> {
     readonly root: Node<V>;
     private _size;
+    /** Tree size, not including the root. */
     get size(): number;
+    /** Gets the top-level nodes of the tree */
     get nodes(): Iterable<IPrefixTreeNode<V>>;
+    /** Gets the top-level nodes of the tree */
     get entries(): Iterable<[
         string,
         IPrefixTreeNode<V>
     ]>;
+    /**
+     * Inserts a new value in the prefix tree.
+     * @param onNode - called for each node as we descend to the insertion point,
+     * including the insertion point itself.
+     */
     insert(key: Iterable<string>, value: V, onNode?: (n: IPrefixTreeNode<V>) => void): void;
+    /** Mutates a value in the prefix tree. */
     mutate(key: Iterable<string>, mutate: (value?: V) => V): void;
+    /** Mutates nodes along the path in the prefix tree. */
     mutatePath(key: Iterable<string>, mutate: (node: IPrefixTreeNode<V>) => void): void;
+    /** Deletes a node from the prefix tree, returning the value it contained. */
     delete(key: Iterable<string>): V | undefined;
+    /** Deletes a subtree from the prefix tree, returning the values they contained. */
     deleteRecursive(key: Iterable<string>): Iterable<V>;
+    /** Gets a value from the tree. */
     find(key: Iterable<string>): V | undefined;
+    /** Gets whether the tree has the key, or a parent of the key, already inserted. */
     hasKeyOrParent(key: Iterable<string>): boolean;
+    /** Gets whether the tree has the given key or any children. */
     hasKeyOrChildren(key: Iterable<string>): boolean;
+    /** Gets whether the tree has the given key. */
     hasKey(key: Iterable<string>): boolean;
     private getPathToKey;
     private opNode;
+    /** Returns an iterable of the tree values in no defined order. */
     values(): Generator<V, void, unknown>;
 }
 declare class Node<T> implements IPrefixTreeNode<T> {

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

@@ -1,4 +1,27 @@
+/**
+ * Provides safe access to the `cwd` property in node.js, sandboxed or web
+ * environments.
+ *
+ * Note: in web, this property is hardcoded to be `/`.
+ *
+ * @skipMangle
+ */
 export declare const cwd: () => string;
+/**
+ * Provides safe access to the `env` property in node.js, sandboxed or web
+ * environments.
+ *
+ * Note: in web, this property is hardcoded to be `{}`.
+ */
 export declare const env: import("./platform.js").IProcessEnvironment;
+/**
+ * Provides safe access to the `platform` property in node.js, sandboxed or web
+ * environments.
+ */
 export declare const platform: string;
+/**
+ * Provides safe access to the `arch` method in node.js, sandboxed or web
+ * environments.
+ * Note: `arch` is `undefined` in web
+ */
 export declare const arch: string | undefined;

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

@@ -7,6 +7,10 @@ export interface IRangedGroup {
     size: number;
 }
 export declare namespace Range {
+    /**
+     * Returns the intersection between two ranges as a range itself.
+     * Returns `{ start: 0, end: 0 }` if the intersection is empty.
+     */
     function intersect(one: IRange, other: IRange): IRange;
     function isEmpty(range: IRange): boolean;
     function intersects(one: IRange, other: IRange): boolean;

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

@@ -1,23 +1,106 @@
 import { URI } from "./uri.js";
 export declare function originalFSPath(uri: URI): string;
 export interface IExtUri {
+    /**
+     * Compares two uris.
+     *
+     * @param uri1 Uri
+     * @param uri2 Uri
+     * @param ignoreFragment Ignore the fragment (defaults to `false`)
+     */
     compare(uri1: URI, uri2: URI, ignoreFragment?: boolean): number;
+    /**
+     * Tests whether two uris are equal
+     *
+     * @param uri1 Uri
+     * @param uri2 Uri
+     * @param ignoreFragment Ignore the fragment (defaults to `false`)
+     */
     isEqual(uri1: URI | undefined, uri2: URI | undefined, ignoreFragment?: boolean): boolean;
+    /**
+     * Tests whether a `candidate` URI is a parent or equal of a given `base` URI.
+     *
+     * @param base A uri which is "longer" or at least same length as `parentCandidate`
+     * @param parentCandidate A uri which is "shorter" or up to same length as `base`
+     * @param ignoreFragment Ignore the fragment (defaults to `false`)
+     */
     isEqualOrParent(base: URI, parentCandidate: URI, ignoreFragment?: boolean): boolean;
+    /**
+     * Creates a key from a resource URI to be used to resource comparison and for resource maps.
+     * @see {@link ResourceMap}
+     * @param uri Uri
+     * @param ignoreFragment Ignore the fragment (defaults to `false`)
+     */
     getComparisonKey(uri: URI, ignoreFragment?: boolean): string;
+    /**
+     * Whether the casing of the path-component of the uri should be ignored.
+     */
     ignorePathCasing(uri: URI): boolean;
     basenameOrAuthority(resource: URI): string;
+    /**
+     * Returns the basename of the path component of an uri.
+     * @param resource
+     */
     basename(resource: URI): string;
+    /**
+     * Returns the extension of the path component of an uri.
+     * @param resource
+     */
     extname(resource: URI): string;
+    /**
+     * Return a URI representing the directory of a URI path.
+     *
+     * @param resource The input URI.
+     * @returns The URI representing the directory of the input URI.
+     */
     dirname(resource: URI): URI;
+    /**
+     * Join a URI path with path fragments and normalizes the resulting path.
+     *
+     * @param resource The input URI.
+     * @param pathFragment The path fragment to add to the URI path.
+     * @returns The resulting URI.
+     */
     joinPath(resource: URI, ...pathFragment: string[]): URI;
+    /**
+     * Normalizes the path part of a URI: Resolves `.` and `..` elements with directory names.
+     *
+     * @param resource The URI to normalize the path.
+     * @returns The URI with the normalized path.
+     */
     normalizePath(resource: URI): URI;
+    /**
+     *
+     * @param from
+     * @param to
+     */
     relativePath(from: URI, to: URI): string | undefined;
+    /**
+     * Resolves an absolute or relative path against a base URI.
+     * The path can be relative or absolute posix or a Windows path
+     */
     resolvePath(base: URI, path: string): URI;
+    /**
+     * Returns true if the URI path is absolute.
+     */
     isAbsolutePath(resource: URI): boolean;
+    /**
+     * Tests whether the two authorities are the same
+     */
     isEqualAuthority(a1: string, a2: string): boolean;
+    /**
+     * Returns true if the URI path has a trailing path separator
+     */
     hasTrailingPathSeparator(resource: URI, sep?: string): boolean;
+    /**
+     * Removes a trailing path separator, if there's one.
+     * Important: Doesn't remove the first slash, it would make the URI invalid
+     */
     removeTrailingPathSeparator(resource: URI, sep?: string): URI;
+    /**
+     * Adds a trailing path separator to the URI if there isn't one already.
+     * For example, c:\ would be unchanged, but c:\users would become c:\users\
+     */
     addTrailingPathSeparator(resource: URI, sep?: string): URI;
 }
 export declare class ExtUri implements IExtUri {
@@ -42,8 +125,37 @@ export declare class ExtUri implements IExtUri {
     removeTrailingPathSeparator(resource: URI, sep?: string): URI;
     addTrailingPathSeparator(resource: URI, sep?: string): URI;
 }
+/**
+ * Unbiased utility that takes uris "as they are". This means it can be interchanged with
+ * uri#toString() usages. The following is true
+ * ```
+ * assertEqual(aUri.toString() === bUri.toString(), exturi.isEqual(aUri, bUri))
+ * ```
+ */
 export declare const extUri: ExtUri;
+/**
+ * BIASED utility that _mostly_ ignored the case of urs paths. ONLY use this util if you
+ * understand what you are doing.
+ *
+ * This utility is INCOMPATIBLE with `uri.toString()`-usages and both CANNOT be used interchanged.
+ *
+ * When dealing with uris from files or documents, `extUri` (the unbiased friend)is sufficient
+ * because those uris come from a "trustworthy source". When creating unknown uris it's always
+ * better to use `IUriIdentityService` which exposes an `IExtUri`-instance which knows when path
+ * casing matters.
+ */
 export declare const extUriBiasedIgnorePathCase: ExtUri;
+/**
+ * BIASED utility that always ignores the casing of uris paths. ONLY use this util if you
+ * understand what you are doing.
+ *
+ * This utility is INCOMPATIBLE with `uri.toString()`-usages and both CANNOT be used interchanged.
+ *
+ * When dealing with uris from files or documents, `extUri` (the unbiased friend)is sufficient
+ * because those uris come from a "trustworthy source". When creating unknown uris it's always
+ * better to use `IUriIdentityService` which exposes an `IExtUri`-instance which knows when path
+ * casing matters.
+ */
 export declare const extUriIgnorePathCase: ExtUri;
 export declare const isEqual: (uri1: URI | undefined, uri2: URI | undefined, ignoreFragment?: boolean) => boolean;
 export declare const isEqualOrParent: (base: URI, parentCandidate: URI, ignoreFragment?: boolean) => boolean;
@@ -62,6 +174,9 @@ export declare const hasTrailingPathSeparator: (resource: URI, sep?: string) =>
 export declare const removeTrailingPathSeparator: (resource: URI, sep?: string) => URI;
 export declare const addTrailingPathSeparator: (resource: URI, sep?: string) => URI;
 export declare function distinctParents<T>(items: T[], resourceAccessor: (item: T) => URI): T[];
+/**
+ * Data URI related helpers.
+ */
 export declare namespace DataUri {
     const META_DATA_LABEL = "label";
     const META_DATA_DESCRIPTION = "description";

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

@@ -70,8 +70,17 @@ export interface INewScrollPosition {
     scrollTop?: number;
 }
 export interface IScrollableOptions {
+    /**
+     * Define if the scroll values should always be integers.
+     */
     forceIntegerValues: boolean;
+    /**
+     * Set the duration (ms) used for smooth scroll animations.
+     */
     smoothScrollDuration: number;
+    /**
+     * A function to schedule an update at the next frame (used for smooth scroll animations).
+     */
     scheduleAtNextAnimationFrame: (callback: () => void) => IDisposable;
 }
 export declare class Scrollable extends Disposable {
@@ -88,7 +97,15 @@ export declare class Scrollable extends Disposable {
     validateScrollPosition(scrollPosition: INewScrollPosition): IScrollPosition;
     getScrollDimensions(): IScrollDimensions;
     setScrollDimensions(dimensions: INewScrollDimensions, useRawScrollPositions: boolean): void;
+    /**
+     * Returns the final scroll position that the instance will have once the smooth scroll animation concludes.
+     * If no scroll animation is occurring, it will return the current scroll position instead.
+     */
     getFutureScrollPosition(): IScrollPosition;
+    /**
+     * Returns the current scroll position.
+     * Note: This result might be an intermediate scroll position, as there might be an ongoing smooth scroll animation.
+     */
     getCurrentScrollPosition(): IScrollPosition;
     setScrollPositionNow(update: INewScrollPosition): void;
     setScrollPositionSmooth(update: INewScrollPosition, reuseAnimation?: boolean): void;

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

@@ -5,6 +5,10 @@ declare enum Severity {
     Error = 3
 }
 declare namespace Severity {
+    /**
+     * Parses 'error', 'warning', 'warn', 'info' in call casings
+     * and falls back to ignore.
+     */
     function fromValue(value: string): Severity;
     function toString(severity: Severity): string;
 }

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

@@ -5,6 +5,10 @@ export declare class SkipList<K, V> implements Map<K, V> {
     private _level;
     private _header;
     private _size;
+    /**
+     *
+     * @param capacity Capacity at which the list performs best
+     */
     constructor(comparator: (a: K, b: K) => number, capacity?: number);
     get size(): number;
     clear(): void;

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

@@ -1,10 +1,35 @@
+/**
+ * Parser for Server-Sent Events (SSE) streams according to the HTML specification.
+ * @see https://html.spec.whatwg.org/multipage/server-sent-events.html#event-stream-interpretation
+ */
+/**
+ * Represents an event dispatched from an SSE stream.
+ */
 export interface ISSEEvent {
+    /**
+     * The event type. If not specified, the type is "message".
+     */
     type: string;
+    /**
+     * The event data.
+     */
     data: string;
+    /**
+     * The last event ID, used for reconnection.
+     */
     id?: string;
+    /**
+     * Reconnection time in milliseconds.
+     */
     retry?: number;
 }
+/**
+ * Callback function type for event dispatch.
+ */
 export type SSEEventHandler = (event: ISSEEvent) => void;
+/**
+ * Parser for Server-Sent Events (SSE) streams.
+ */
 export declare class SSEParser {
     private dataBuffer;
     private eventTypeBuffer;
@@ -15,12 +40,38 @@ export declare class SSEParser {
     private endedOnCR;
     private readonly onEventHandler;
     private readonly decoder;
+    /**
+     * Creates a new SSE parser.
+     * @param onEvent The callback to invoke when an event is dispatched.
+     */
     constructor(onEvent: SSEEventHandler);
+    /**
+     * Gets the last event ID received by this parser.
+     */
     getLastEventId(): string | undefined;
+    /**
+     * Gets the reconnection time in milliseconds, if one was specified by the server.
+     */
     getReconnectionTime(): number | undefined;
+    /**
+     * Feeds a chunk of the SSE stream to the parser.
+     * @param chunk The chunk to parse as a Uint8Array of UTF-8 encoded data.
+     */
     feed(chunk: Uint8Array): void;
+    /**
+     * Processes a single line from the SSE stream.
+     */
     private processLine;
+    /**
+     * Processes a field with the given name and value.
+     */
     private processField;
+    /**
+     * Dispatches the event based on the current buffer states.
+     */
     private dispatchEvent;
+    /**
+     * Resets the parser state.
+     */
     reset(): void;
 }

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

@@ -1,28 +1,118 @@
 import { CancellationToken } from "./cancellation.js";
+/**
+ * The payload that flows in readable stream events.
+ */
 export type ReadableStreamEventPayload<T> = T | Error | "end";
 export interface ReadableStreamEvents<T> {
+    /**
+     * The 'data' event is emitted whenever the stream is
+     * relinquishing ownership of a chunk of data to a consumer.
+     *
+     * NOTE: PLEASE UNDERSTAND THAT ADDING A DATA LISTENER CAN
+     * TURN THE STREAM INTO FLOWING MODE. IT IS THEREFOR THE
+     * LAST LISTENER THAT SHOULD BE ADDED AND NOT THE FIRST
+     *
+     * Use `listenStream` as a helper method to listen to
+     * stream events in the right order.
+     */
     on(event: "data", callback: (data: T) => void): void;
+    /**
+     * Emitted when any error occurs.
+     */
     on(event: "error", callback: (err: Error) => void): void;
+    /**
+     * The 'end' event is emitted when there is no more data
+     * to be consumed from the stream. The 'end' event will
+     * not be emitted unless the data is completely consumed.
+     */
     on(event: "end", callback: () => void): void;
 }
+/**
+ * A interface that emulates the API shape of a node.js readable
+ * stream for use in native and web environments.
+ */
 export interface ReadableStream<T> extends ReadableStreamEvents<T> {
+    /**
+     * Stops emitting any events until resume() is called.
+     */
     pause(): void;
+    /**
+     * Starts emitting events again after pause() was called.
+     */
     resume(): void;
+    /**
+     * Destroys the stream and stops emitting any event.
+     */
     destroy(): void;
+    /**
+     * Allows to remove a listener that was previously added.
+     */
     removeListener(event: string, callback: Function): void;
 }
+/**
+ * A interface that emulates the API shape of a node.js readable
+ * for use in native and web environments.
+ */
 export interface Readable<T> {
+    /**
+     * Read data from the underlying source. Will return
+     * null to indicate that no more data can be read.
+     */
     read(): T | null;
 }
 export declare function isReadable<T>(obj: unknown): obj is Readable<T>;
+/**
+ * A interface that emulates the API shape of a node.js writeable
+ * stream for use in native and web environments.
+ */
 export interface WriteableStream<T> extends ReadableStream<T> {
+    /**
+     * Writing data to the stream will trigger the on('data')
+     * event listener if the stream is flowing and buffer the
+     * data otherwise until the stream is flowing.
+     *
+     * If a `highWaterMark` is configured and writing to the
+     * stream reaches this mark, a promise will be returned
+     * that should be awaited on before writing more data.
+     * Otherwise there is a risk of buffering a large number
+     * of data chunks without consumer.
+     */
     write(data: T): void | Promise<void>;
+    /**
+     * Signals an error to the consumer of the stream via the
+     * on('error') handler if the stream is flowing.
+     *
+     * NOTE: call `end` to signal that the stream has ended,
+     * this DOES NOT happen automatically from `error`.
+     */
     error(error: Error): void;
+    /**
+     * Signals the end of the stream to the consumer. If the
+     * result is provided, will trigger the on('data') event
+     * listener if the stream is flowing and buffer the data
+     * otherwise until the stream is flowing.
+     */
     end(result?: T): void;
 }
+/**
+ * A stream that has a buffer already read. Returns the original stream
+ * that was read as well as the chunks that got read.
+ *
+ * The `ended` flag indicates if the stream has been fully consumed.
+ */
 export interface ReadableBufferedStream<T> {
+    /**
+     * The original stream that is being read.
+     */
     stream: ReadableStream<T>;
+    /**
+     * An array of chunks already read from this stream.
+     */
     buffer: T[];
+    /**
+     * Signals if the stream has ended or not. If not, consumers
+     * should continue to read from the stream until consumed.
+     */
     ended: boolean;
 }
 export declare function isReadableStream<T>(obj: unknown): obj is ReadableStream<T>;
@@ -42,22 +132,80 @@ export interface ITransformer<Original, Transformed> {
 }
 export declare function newWriteableStream<T>(reducer: IReducer<T> | null, options?: WriteableStreamOptions): WriteableStream<T>;
 export interface WriteableStreamOptions {
+    /**
+     * The number of objects to buffer before WriteableStream#write()
+     * signals back that the buffer is full. Can be used to reduce
+     * the memory pressure when the stream is not flowing.
+     */
     highWaterMark?: number;
 }
+/**
+ * Helper to fully read a T readable into a T.
+ */
 export declare function consumeReadable<T>(readable: Readable<T>, reducer: IReducer<T>): T;
+/**
+ * Helper to read a T readable up to a maximum of chunks. If the limit is
+ * reached, will return a readable instead to ensure all data can still
+ * be read.
+ */
 export declare function peekReadable<T>(readable: Readable<T>, reducer: IReducer<T>, maxChunks: number): T | Readable<T>;
+/**
+ * Helper to fully read a T stream into a T or consuming
+ * a stream fully, awaiting all the events without caring
+ * about the data.
+ */
 export declare function consumeStream<T, R = T>(stream: ReadableStreamEvents<T>, reducer: IReducer<T, R>): Promise<R>;
 export declare function consumeStream(stream: ReadableStreamEvents<unknown>): Promise<undefined>;
 export interface IStreamListener<T> {
+    /**
+     * The 'data' event is emitted whenever the stream is
+     * relinquishing ownership of a chunk of data to a consumer.
+     */
     onData(data: T): void;
+    /**
+     * Emitted when any error occurs.
+     */
     onError(err: Error): void;
+    /**
+     * The 'end' event is emitted when there is no more data
+     * to be consumed from the stream. The 'end' event will
+     * not be emitted unless the data is completely consumed.
+     */
     onEnd(): void;
 }
+/**
+ * Helper to listen to all events of a T stream in proper order.
+ */
 export declare function listenStream<T>(stream: ReadableStreamEvents<T>, listener: IStreamListener<T>, token?: CancellationToken): void;
+/**
+ * Helper to peek up to `maxChunks` into a stream. The return type signals if
+ * the stream has ended or not. If not, caller needs to add a `data` listener
+ * to continue reading.
+ */
 export declare function peekStream<T>(stream: ReadableStream<T>, maxChunks: number): Promise<ReadableBufferedStream<T>>;
+/**
+ * Helper to create a readable stream from an existing T.
+ */
 export declare function toStream<T>(t: T, reducer: IReducer<T>): ReadableStream<T>;
+/**
+ * Helper to create an empty stream
+ */
 export declare function emptyStream(): ReadableStream<never>;
+/**
+ * Helper to convert a T into a Readable<T>.
+ */
 export declare function toReadable<T>(t: T): Readable<T>;
+/**
+ * Helper to transform a readable stream into another stream.
+ */
 export declare function transform<Original, Transformed>(stream: ReadableStreamEvents<Original>, transformer: ITransformer<Original, Transformed>, reducer: IReducer<Transformed>): ReadableStream<Transformed>;
+/**
+ * Helper to take an existing readable that will
+ * have a prefix injected to the beginning.
+ */
 export declare function prefixedReadable<T>(prefix: T, readable: Readable<T>, reducer: IReducer<T>): Readable<T>;
+/**
+ * Helper to take an existing stream that will
+ * have a prefix injected to the beginning.
+ */
 export declare function prefixedStream<T>(prefix: T, stream: ReadableStream<T>, reducer: IReducer<T>): ReadableStream<T>;