@codingame/monaco-vscode-api 1.78.8 → 1.79.0

package/dist/event.d.ts

@@ -0,0 +1,581 @@
+import * as vscode from 'vscode';
+
+/**
+ * An object that performs a cleanup operation when `.dispose()` is called.
+ *
+ * Some examples of how disposables are used:
+ *
+ * - An event listener that removes itself when `.dispose()` is called.
+ * - A resource such as a file system watcher that cleans up the resource when `.dispose()` is called.
+ * - The return value from registering a provider. When `.dispose()` is called, the provider is unregistered.
+ */
+interface IDisposable {
+    dispose(): void;
+}
+/**
+ * Manages a collection of disposable values.
+ *
+ * This is the preferred way to manage multiple disposables. A `DisposableStore` is safer to work with than an
+ * `IDisposable[]` as it considers edge cases, such as registering the same value multiple times or adding an item to a
+ * store that has already been disposed of.
+ */
+declare class DisposableStore implements IDisposable {
+    static DISABLE_DISPOSED_WARNING: boolean;
+    private readonly _toDispose;
+    private _isDisposed;
+    constructor();
+    /**
+     * Dispose of all registered disposables and mark this object as disposed.
+     *
+     * Any future disposables added to this object will be disposed of on `add`.
+     */
+    dispose(): void;
+    /**
+     * @return `true` if this object has been disposed of.
+     */
+    get isDisposed(): boolean;
+    /**
+     * Dispose of all registered disposables but do not mark this object as disposed.
+     */
+    clear(): void;
+    /**
+     * Add a new {@link IDisposable disposable} to the collection.
+     */
+    add<T extends IDisposable>(o: T): T;
+}
+/**
+ * Abstract base class for a {@link IDisposable disposable} object.
+ *
+ * Subclasses can {@linkcode _register} disposables that will be automatically cleaned up when this object is disposed of.
+ */
+declare abstract class Disposable implements IDisposable {
+    /**
+     * A disposable that does nothing when it is disposed of.
+     *
+     * TODO: This should not be a static property.
+     */
+    static readonly None: Readonly<IDisposable>;
+    protected readonly _store: DisposableStore;
+    constructor();
+    dispose(): void;
+    /**
+     * Adds `o` to the collection of disposables managed by this object.
+     */
+    protected _register<T extends IDisposable>(o: T): T;
+}
+/**
+ * A safe disposable can be `unset` so that a leaked reference (listener)
+ * can be cut-off.
+ */
+declare class SafeDisposable implements IDisposable {
+    dispose: () => void;
+    unset: () => void;
+    isset: () => boolean;
+    constructor();
+    set(fn: Function): this;
+}
+interface IReference<T> extends IDisposable {
+    readonly object: T;
+}
+
+interface CancellationToken {
+    /**
+     * A flag signalling is cancellation has been requested.
+     */
+    readonly isCancellationRequested: boolean;
+    /**
+     * An event which fires when cancellation is requested. This event
+     * only ever fires `once` as cancellation can only happen once. Listeners
+     * that are registered after cancellation will be called (next event loop run),
+     * but also only once.
+     *
+     * @event
+     */
+    readonly onCancellationRequested: (listener: (e: any) => any, thisArgs?: any, disposables?: IDisposable[]) => IDisposable;
+}
+declare namespace CancellationToken {
+    function isCancellationToken(thing: unknown): thing is CancellationToken;
+    const None: Readonly<CancellationToken>;
+    const Cancelled: Readonly<CancellationToken>;
+}
+
+declare class LinkedList<E> {
+    private _first;
+    private _last;
+    private _size;
+    get size(): number;
+    isEmpty(): boolean;
+    clear(): void;
+    unshift(element: E): () => void;
+    push(element: E): () => void;
+    private _insert;
+    shift(): E | undefined;
+    pop(): E | undefined;
+    private _remove;
+    [Symbol.iterator](): Iterator<E>;
+}
+
+interface IObservable<T, TChange = unknown> {
+    /**
+     * Returns the current value.
+     *
+     * Calls {@link IObserver.handleChange} if the observable notices that the value changed.
+     * Must not be called from {@link IObserver.handleChange}!
+     */
+    get(): T;
+    /**
+     * Forces the observable to check for and report changes.
+     *
+     * Has the same effect as calling {@link IObservable.get}, but does not force the observable
+     * to actually construct the value, e.g. if change deltas are used.
+     * Calls {@link IObserver.handleChange} if the observable notices that the value changed.
+     * Must not be called from {@link IObserver.handleChange}!
+     */
+    reportChanges(): void;
+    /**
+     * Adds the observer to the set of subscribed observers.
+     * This method is idempotent.
+     */
+    addObserver(observer: IObserver): void;
+    /**
+     * Removes the observer from the set of subscribed observers.
+     * This method is idempotent.
+     */
+    removeObserver(observer: IObserver): void;
+    /**
+     * Reads the current value and subscribes to this observable.
+     *
+     * Just calls {@link IReader.readObservable} if a reader is given, otherwise {@link IObservable.get}
+     * (see {@link ConvenientObservable.read}).
+     */
+    read(reader: IReader | undefined): T;
+    /**
+     * Creates a derived observable that depends on this observable.
+     * Use the reader to read other observables
+     * (see {@link ConvenientObservable.map}).
+     */
+    map<TNew>(fn: (value: T, reader: IReader) => TNew): IObservable<TNew>;
+    /**
+     * A human-readable name for debugging purposes.
+     */
+    readonly debugName: string;
+    /**
+     * This property captures the type of the change object. Do not use it at runtime!
+     */
+    readonly TChange: TChange;
+}
+interface IReader {
+    /**
+     * Reads the value of an observable and subscribes to it.
+     */
+    readObservable<T>(observable: IObservable<T, any>): T;
+}
+/**
+ * Represents an observer that can be subscribed to an observable.
+ *
+ * If an observer is subscribed to an observable and that observable didn't signal
+ * a change through one of the observer methods, the observer can assume that the
+ * observable didn't change.
+ * If an observable reported a possible change, {@link IObservable.reportChanges} forces
+ * the observable to report an actual change if there was one.
+ */
+interface IObserver {
+    /**
+     * Signals that the given observable might have changed and a transaction potentially modifying that observable started.
+     * Before the given observable can call this method again, is must call {@link IObserver.endUpdate}.
+     *
+     * The method {@link IObservable.reportChanges} can be used to force the observable to report the changes.
+     */
+    beginUpdate<T>(observable: IObservable<T>): void;
+    /**
+     * Signals that the transaction that potentially modified the given observable ended.
+     */
+    endUpdate<T>(observable: IObservable<T>): void;
+    /**
+     * Signals that the given observable might have changed.
+     * The method {@link IObservable.reportChanges} can be used to force the observable to report the changes.
+     *
+     * Implementations must not call into other observables, as they might not have received this event yet!
+     * The change should be processed lazily or in {@link IObserver.endUpdate}.
+     */
+    handlePossibleChange<T>(observable: IObservable<T>): void;
+    /**
+     * Signals that the given observable changed.
+     *
+     * Implementations must not call into other observables, as they might not have received this event yet!
+     * The change should be processed lazily or in {@link IObserver.endUpdate}.
+     */
+    handleChange<T, TChange>(observable: IObservable<T, TChange>, change: TChange): void;
+}
+
+/**
+ * Can be passed into the Delayed to defer using a microtask
+ * */
+declare const MicrotaskDelay: unique symbol;
+
+/**
+ * An event with zero or one parameters that can be subscribed to. The event is a function itself.
+ */
+type Event<T> = vscode.Event<T>
+declare namespace Event {
+    const None: Event<any>;
+    /**
+     * Given an event, returns another event which debounces calls and defers the listeners to a later task via a shared
+     * `setTimeout`. The event is converted into a signal (`Event<void>`) to avoid additional object creation as a
+     * result of merging events and to try prevent race conditions that could arise when using related deferred and
+     * non-deferred events.
+     *
+     * This is useful for deferring non-critical work (eg. general UI updates) to ensure it does not block critical work
+     * (eg. latency of keypress to text rendered).
+     *
+     * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned
+     * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the
+     * returned event causes this utility to leak a listener on the original event.
+     *
+     * @param event The event source for the new event.
+     * @param disposable A disposable store to add the new EventEmitter to.
+     */
+    function defer(event: Event<unknown>, disposable?: DisposableStore): Event<void>;
+    /**
+     * Given an event, returns another event which only fires once.
+     *
+     * @param event The event source for the new event.
+     */
+    function once<T>(event: Event<T>): Event<T>;
+    /**
+     * Maps an event of one type into an event of another type using a mapping function, similar to how
+     * `Array.prototype.map` works.
+     *
+     * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned
+     * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the
+     * returned event causes this utility to leak a listener on the original event.
+     *
+     * @param event The event source for the new event.
+     * @param map The mapping function.
+     * @param disposable A disposable store to add the new EventEmitter to.
+     */
+    function map<I, O>(event: Event<I>, map: (i: I) => O, disposable?: DisposableStore): Event<O>;
+    /**
+     * Wraps an event in another event that performs some function on the event object before firing.
+     *
+     * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned
+     * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the
+     * returned event causes this utility to leak a listener on the original event.
+     *
+     * @param event The event source for the new event.
+     * @param each The function to perform on the event object.
+     * @param disposable A disposable store to add the new EventEmitter to.
+     */
+    function forEach<I>(event: Event<I>, each: (i: I) => void, disposable?: DisposableStore): Event<I>;
+    /**
+     * Wraps an event in another event that fires only when some condition is met.
+     *
+     * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned
+     * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the
+     * returned event causes this utility to leak a listener on the original event.
+     *
+     * @param event The event source for the new event.
+     * @param filter The filter function that defines the condition. The event will fire for the object if this function
+     * returns true.
+     * @param disposable A disposable store to add the new EventEmitter to.
+     */
+    function filter<T, U>(event: Event<T | U>, filter: (e: T | U) => e is T, disposable?: DisposableStore): Event<T>;
+    function filter<T>(event: Event<T>, filter: (e: T) => boolean, disposable?: DisposableStore): Event<T>;
+    function filter<T, R>(event: Event<T | R>, filter: (e: T | R) => e is R, disposable?: DisposableStore): Event<R>;
+    /**
+     * Given an event, returns the same event but typed as `Event<void>`.
+     */
+    function signal<T>(event: Event<T>): Event<void>;
+    /**
+     * Given a collection of events, returns a single event which emits whenever any of the provided events emit.
+     */
+    function any<T>(...events: Event<T>[]): Event<T>;
+    function any(...events: Event<any>[]): Event<void>;
+    /**
+     * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned
+     * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the
+     * returned event causes this utility to leak a listener on the original event.
+     */
+    function reduce<I, O>(event: Event<I>, merge: (last: O | undefined, event: I) => O, initial?: O, disposable?: DisposableStore): Event<O>;
+    /**
+     * Given an event, creates a new emitter that event that will debounce events based on {@link delay} and give an
+     * array event object of all events that fired.
+     *
+     * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned
+     * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the
+     * returned event causes this utility to leak a listener on the original event.
+     *
+     * @param event The original event to debounce.
+     * @param merge A function that reduces all events into a single event.
+     * @param delay The number of milliseconds to debounce.
+     * @param leading Whether to fire a leading event without debouncing.
+     * @param flushOnListenerRemove Whether to fire all debounced events when a listener is removed. If this is not
+     * specified, some events could go missing. Use this if it's important that all events are processed, even if the
+     * listener gets disposed before the debounced event fires.
+     * @param leakWarningThreshold See {@link EmitterOptions.leakWarningThreshold}.
+     * @param disposable A disposable store to register the debounce emitter to.
+     */
+    function debounce<T>(event: Event<T>, merge: (last: T | undefined, event: T) => T, delay?: number | typeof MicrotaskDelay, leading?: boolean, flushOnListenerRemove?: boolean, leakWarningThreshold?: number, disposable?: DisposableStore): Event<T>;
+    function debounce<I, O>(event: Event<I>, merge: (last: O | undefined, event: I) => O, delay?: number | typeof MicrotaskDelay, leading?: boolean, flushOnListenerRemove?: boolean, leakWarningThreshold?: number, disposable?: DisposableStore): Event<O>;
+    /**
+     * Debounces an event, firing after some delay (default=0) with an array of all event original objects.
+     *
+     * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned
+     * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the
+     * returned event causes this utility to leak a listener on the original event.
+     */
+    function accumulate<T>(event: Event<T>, delay?: number, disposable?: DisposableStore): Event<T[]>;
+    /**
+     * Filters an event such that some condition is _not_ met more than once in a row, effectively ensuring duplicate
+     * event objects from different sources do not fire the same event object.
+     *
+     * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned
+     * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the
+     * returned event causes this utility to leak a listener on the original event.
+     *
+     * @param event The event source for the new event.
+     * @param equals The equality condition.
+     * @param disposable A disposable store to add the new EventEmitter to.
+     *
+     * @example
+     * ```
+     * // Fire only one time when a single window is opened or focused
+     * Event.latch(Event.any(onDidOpenWindow, onDidFocusWindow))
+     * ```
+     */
+    function latch<T>(event: Event<T>, equals?: (a: T, b: T) => boolean, disposable?: DisposableStore): Event<T>;
+    /**
+     * Splits an event whose parameter is a union type into 2 separate events for each type in the union.
+     *
+     * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned
+     * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the
+     * returned event causes this utility to leak a listener on the original event.
+     *
+     * @example
+     * ```
+     * const event = new EventEmitter<number | undefined>().event;
+     * const [numberEvent, undefinedEvent] = Event.split(event, isUndefined);
+     * ```
+     *
+     * @param event The event source for the new event.
+     * @param isT A function that determines what event is of the first type.
+     * @param disposable A disposable store to add the new EventEmitter to.
+     */
+    function split<T, U>(event: Event<T | U>, isT: (e: T | U) => e is T, disposable?: DisposableStore): [Event<T>, Event<U>];
+    /**
+     * Buffers an event until it has a listener attached.
+     *
+     * *NOTE* that this function returns an `Event` and it MUST be called with a `DisposableStore` whenever the returned
+     * event is accessible to "third parties", e.g the event is a public property. Otherwise a leaked listener on the
+     * returned event causes this utility to leak a listener on the original event.
+     *
+     * @param event The event source for the new event.
+     * @param flushAfterTimeout Determines whether to flush the buffer after a timeout immediately or after a
+     * `setTimeout` when the first event listener is added.
+     * @param _buffer Internal: A source event array used for tests.
+     *
+     * @example
+     * ```
+     * // Start accumulating events, when the first listener is attached, flush
+     * // the event after a timeout such that multiple listeners attached before
+     * // the timeout would receive the event
+     * this.onInstallExtension = Event.buffer(service.onInstallExtension, true);
+     * ```
+     */
+    function buffer<T>(event: Event<T>, flushAfterTimeout?: boolean, _buffer?: T[]): Event<T>;
+    interface IChainableEvent<T> extends IDisposable {
+        event: Event<T>;
+        map<O>(fn: (i: T) => O): IChainableEvent<O>;
+        forEach(fn: (i: T) => void): IChainableEvent<T>;
+        filter(fn: (e: T) => boolean): IChainableEvent<T>;
+        filter<R>(fn: (e: T | R) => e is R): IChainableEvent<R>;
+        reduce<R>(merge: (last: R | undefined, event: T) => R, initial?: R): IChainableEvent<R>;
+        latch(): IChainableEvent<T>;
+        debounce(merge: (last: T | undefined, event: T) => T, delay?: number, leading?: boolean, flushOnListenerRemove?: boolean, leakWarningThreshold?: number): IChainableEvent<T>;
+        debounce<R>(merge: (last: R | undefined, event: T) => R, delay?: number, leading?: boolean, flushOnListenerRemove?: boolean, leakWarningThreshold?: number): IChainableEvent<R>;
+        on(listener: (e: T) => any, thisArgs?: any, disposables?: IDisposable[] | DisposableStore): IDisposable;
+        once(listener: (e: T) => any, thisArgs?: any, disposables?: IDisposable[]): IDisposable;
+    }
+    /**
+     * Wraps the event in an {@link IChainableEvent}, allowing a more functional programming style.
+     *
+     * @example
+     * ```
+     * // Normal
+     * const onEnterPressNormal = Event.filter(
+     *   Event.map(onKeyPress.event, e => new StandardKeyboardEvent(e)),
+     *   e.keyCode === KeyCode.Enter
+     * ).event;
+     *
+     * // Using chain
+     * const onEnterPressChain = Event.chain(onKeyPress.event)
+     *   .map(e => new StandardKeyboardEvent(e))
+     *   .filter(e => e.keyCode === KeyCode.Enter)
+     *   .event;
+     * ```
+     */
+    function chain<T>(event: Event<T>): IChainableEvent<T>;
+    interface NodeEventEmitter {
+        on(event: string | symbol, listener: Function): unknown;
+        removeListener(event: string | symbol, listener: Function): unknown;
+    }
+    /**
+     * Creates an {@link Event} from a node event emitter.
+     */
+    function fromNodeEventEmitter<T>(emitter: NodeEventEmitter, eventName: string, map?: (...args: any[]) => T): Event<T>;
+    interface DOMEventEmitter {
+        addEventListener(event: string | symbol, listener: Function): void;
+        removeEventListener(event: string | symbol, listener: Function): void;
+    }
+    /**
+     * Creates an {@link Event} from a DOM event emitter.
+     */
+    function fromDOMEventEmitter<T>(emitter: DOMEventEmitter, eventName: string, map?: (...args: any[]) => T): Event<T>;
+    /**
+     * Creates a promise out of an event, using the {@link Event.once} helper.
+     */
+    function toPromise<T>(event: Event<T>): Promise<T>;
+    /**
+     * Adds a listener to an event and calls the listener immediately with undefined as the event object.
+     *
+     * @example
+     * ```
+     * // Initialize the UI and update it when dataChangeEvent fires
+     * runAndSubscribe(dataChangeEvent, () => this._updateUI());
+     * ```
+     */
+    function runAndSubscribe<T>(event: Event<T>, handler: (e: T | undefined) => any): IDisposable;
+    /**
+     * Adds a listener to an event and calls the listener immediately with undefined as the event object. A new
+     * {@link DisposableStore} is passed to the listener which is disposed when the returned disposable is disposed.
+     */
+    function runAndSubscribeWithStore<T>(event: Event<T>, handler: (e: T | undefined, disposableStore: DisposableStore) => any): IDisposable;
+    /**
+     * Creates an event emitter that is fired when the observable changes.
+     * Each listeners subscribes to the emitter.
+     */
+    function fromObservable<T>(obs: IObservable<T, any>, store?: DisposableStore): Event<T>;
+    /**
+     * Each listener is attached to the observable directly.
+     */
+    function fromObservableLight(observable: IObservable<any>): Event<void>;
+}
+interface EmitterOptions {
+    /**
+     * Optional function that's called *before* the very first listener is added
+     */
+    onWillAddFirstListener?: Function;
+    /**
+     * Optional function that's called *after* the very first listener is added
+     */
+    onDidAddFirstListener?: Function;
+    /**
+     * Optional function that's called after a listener is added
+     */
+    onDidAddListener?: Function;
+    /**
+     * Optional function that's called *after* remove the very last listener
+     */
+    onDidRemoveLastListener?: Function;
+    /**
+     * Optional function that's called *before* a listener is removed
+     */
+    onWillRemoveListener?: Function;
+    /**
+     * Optional function that's called when a listener throws an error. Defaults to
+     * {@link onUnexpectedError}
+     */
+    onListenerError?: (e: any) => void;
+    /**
+     * Number of listeners that are allowed before assuming a leak. Default to
+     * a globally configured value
+     *
+     * @see setGlobalLeakWarningThreshold
+     */
+    leakWarningThreshold?: number;
+    /**
+     * Pass in a delivery queue, which is useful for ensuring
+     * in order event delivery across multiple emitters.
+     */
+    deliveryQueue?: EventDeliveryQueue;
+    /** ONLY enable this during development */
+    _profName?: string;
+}
+declare class Stacktrace {
+    readonly value: string;
+    static create(): Stacktrace;
+    private constructor();
+    print(): void;
+}
+declare class Listener<T> {
+    readonly callback: (e: T) => void;
+    readonly callbackThis: any | undefined;
+    readonly stack: Stacktrace | undefined;
+    readonly subscription: SafeDisposable;
+    constructor(callback: (e: T) => void, callbackThis: any | undefined, stack: Stacktrace | undefined);
+    invoke(e: T): void;
+}
+/**
+ * The Emitter can be used to expose an Event to the public
+ * to fire it from the insides.
+ * Sample:
+    class Document {
+
+        private readonly _onDidChange = new Emitter<(value:string)=>any>();
+
+        public onDidChange = this._onDidChange.event;
+
+        // getter-style
+        // get onDidChange(): Event<(value:string)=>any> {
+        // 	return this._onDidChange.event;
+        // }
+
+        private _doIt() {
+            //...
+            this._onDidChange.fire(value);
+        }
+    }
+ */
+declare class Emitter<T> {
+    private readonly _options?;
+    private readonly _leakageMon?;
+    private readonly _perfMon?;
+    private _disposed;
+    private _event?;
+    private _deliveryQueue?;
+    protected _listeners?: LinkedList<Listener<T>>;
+    constructor(options?: EmitterOptions);
+    dispose(): void;
+    /**
+     * For the public to allow to subscribe
+     * to events from this Emitter
+     */
+    get event(): Event<T>;
+    /**
+     * To be kept private to fire an event to
+     * subscribers
+     */
+    fire(event: T): void;
+    hasListeners(): boolean;
+}
+declare class EventDeliveryQueue {
+    private readonly _onListenerError;
+    protected _queue: LinkedList<EventDeliveryQueueElement<any>>;
+    constructor(_onListenerError?: (e: any) => void);
+    get size(): number;
+    push<T>(emitter: Emitter<T>, listener: Listener<T>, event: T): void;
+    clear<T>(emitter: Emitter<T>): void;
+    deliver(): void;
+}
+declare class EventDeliveryQueueElement<T = any> {
+    readonly emitter: Emitter<T>;
+    readonly listener: Listener<T>;
+    readonly event: T;
+    constructor(emitter: Emitter<T>, listener: Listener<T>, event: T);
+}
+interface IWaitUntil {
+    token: CancellationToken;
+    waitUntil(thenable: Promise<unknown>): void;
+}
+
+export { CancellationToken as C, Disposable as D, Event as E, IDisposable as I, IReference as a, Emitter as b, DisposableStore as c, IWaitUntil as d };