@xterm/xterm 5.4.0-beta.1

package/src/common/Lifecycle.ts

@@ -0,0 +1,108 @@
+/**
+ * Copyright (c) 2018 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { IDisposable } from 'common/Types';
+
+/**
+ * A base class that can be extended to provide convenience methods for managing the lifecycle of an
+ * object and its components.
+ */
+export abstract class Disposable implements IDisposable {
+  protected _disposables: IDisposable[] = [];
+  protected _isDisposed: boolean = false;
+
+  /**
+   * Disposes the object, triggering the `dispose` method on all registered IDisposables.
+   */
+  public dispose(): void {
+    this._isDisposed = true;
+    for (const d of this._disposables) {
+      d.dispose();
+    }
+    this._disposables.length = 0;
+  }
+
+  /**
+   * Registers a disposable object.
+   * @param d The disposable to register.
+   * @returns The disposable.
+   */
+  public register<T extends IDisposable>(d: T): T {
+    this._disposables.push(d);
+    return d;
+  }
+
+  /**
+   * Unregisters a disposable object if it has been registered, if not do
+   * nothing.
+   * @param d The disposable to unregister.
+   */
+  public unregister<T extends IDisposable>(d: T): void {
+    const index = this._disposables.indexOf(d);
+    if (index !== -1) {
+      this._disposables.splice(index, 1);
+    }
+  }
+}
+
+export class MutableDisposable<T extends IDisposable> implements IDisposable {
+  private _value?: T;
+  private _isDisposed = false;
+
+  /**
+   * Gets the value if it exists.
+   */
+  public get value(): T | undefined {
+    return this._isDisposed ? undefined : this._value;
+  }
+
+  /**
+   * Sets the value, disposing of the old value if it exists.
+   */
+  public set value(value: T | undefined) {
+    if (this._isDisposed || value === this._value) {
+      return;
+    }
+    this._value?.dispose();
+    this._value = value;
+  }
+
+  /**
+   * Resets the stored value and disposes of the previously stored value.
+   */
+  public clear(): void {
+    this.value = undefined;
+  }
+
+  public dispose(): void {
+    this._isDisposed = true;
+    this._value?.dispose();
+    this._value = undefined;
+  }
+}
+
+/**
+ * Wrap a function in a disposable.
+ */
+export function toDisposable(f: () => void): IDisposable {
+  return { dispose: f };
+}
+
+/**
+ * Dispose of all disposables in an array and set its length to 0.
+ */
+export function disposeArray(disposables: IDisposable[]): void {
+  for (const d of disposables) {
+    d.dispose();
+  }
+  disposables.length = 0;
+}
+
+/**
+ * Creates a disposable that will dispose of an array of disposables when disposed.
+ */
+export function getDisposeArrayDisposable(array: IDisposable[]): IDisposable {
+  return { dispose: () => disposeArray(array) };
+}

package/src/common/MultiKeyMap.ts

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) 2022 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+export class TwoKeyMap<TFirst extends string | number, TSecond extends string | number, TValue> {
+  private _data: { [bg: string | number]: { [fg: string | number]: TValue | undefined } | undefined } = {};
+
+  public set(first: TFirst, second: TSecond, value: TValue): void {
+    if (!this._data[first]) {
+      this._data[first] = {};
+    }
+    this._data[first as string | number]![second] = value;
+  }
+
+  public get(first: TFirst, second: TSecond): TValue | undefined {
+    return this._data[first as string | number] ? this._data[first as string | number]![second] : undefined;
+  }
+
+  public clear(): void {
+    this._data = {};
+  }
+}
+
+export class FourKeyMap<TFirst extends string | number, TSecond extends string | number, TThird extends string | number, TFourth extends string | number, TValue> {
+  private _data: TwoKeyMap<TFirst, TSecond, TwoKeyMap<TThird, TFourth, TValue>> = new TwoKeyMap();
+
+  public set(first: TFirst, second: TSecond, third: TThird, fourth: TFourth, value: TValue): void {
+    if (!this._data.get(first, second)) {
+      this._data.set(first, second, new TwoKeyMap());
+    }
+    this._data.get(first, second)!.set(third, fourth, value);
+  }
+
+  public get(first: TFirst, second: TSecond, third: TThird, fourth: TFourth): TValue | undefined {
+    return this._data.get(first, second)?.get(third, fourth);
+  }
+
+  public clear(): void {
+    this._data.clear();
+  }
+}

package/src/common/Platform.ts

@@ -0,0 +1,44 @@
+/**
+ * Copyright (c) 2016 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+interface INavigator {
+  userAgent: string;
+  language: string;
+  platform: string;
+}
+
+// We're declaring a navigator global here as we expect it in all runtimes (node and browser), but
+// we want this module to live in common.
+declare const navigator: INavigator;
+declare const process: unknown;
+
+export const isNode = (typeof process !== 'undefined') ? true : false;
+const userAgent = (isNode) ? 'node' : navigator.userAgent;
+const platform = (isNode) ? 'node' : navigator.platform;
+
+export const isFirefox = userAgent.includes('Firefox');
+export const isLegacyEdge = userAgent.includes('Edge');
+export const isSafari = /^((?!chrome|android).)*safari/i.test(userAgent);
+export function getSafariVersion(): number {
+  if (!isSafari) {
+    return 0;
+  }
+  const majorVersion = userAgent.match(/Version\/(\d+)/);
+  if (majorVersion === null || majorVersion.length < 2) {
+    return 0;
+  }
+  return parseInt(majorVersion[1]);
+}
+
+// Find the users platform. We use this to interpret the meta key
+// and ISO third level shifts.
+// http://stackoverflow.com/q/19877924/577598
+export const isMac = ['Macintosh', 'MacIntel', 'MacPPC', 'Mac68K'].includes(platform);
+export const isIpad = platform === 'iPad';
+export const isIphone = platform === 'iPhone';
+export const isWindows = ['Windows', 'Win16', 'Win32', 'WinCE'].includes(platform);
+export const isLinux = platform.indexOf('Linux') >= 0;
+// Note that when this is true, isLinux will also be true.
+export const isChromeOS = /\bCrOS\b/.test(userAgent);

package/src/common/SortedList.ts

@@ -0,0 +1,118 @@
+/**
+ * Copyright (c) 2022 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+// Work variables to avoid garbage collection.
+let i = 0;
+
+/**
+ * A generic list that is maintained in sorted order and allows values with duplicate keys. This
+ * list is based on binary search and as such locating a key will take O(log n) amortized, this
+ * includes the by key iterator.
+ */
+export class SortedList<T> {
+  private readonly _array: T[] = [];
+
+  constructor(
+    private readonly _getKey: (value: T) => number
+  ) {
+  }
+
+  public clear(): void {
+    this._array.length = 0;
+  }
+
+  public insert(value: T): void {
+    if (this._array.length === 0) {
+      this._array.push(value);
+      return;
+    }
+    i = this._search(this._getKey(value));
+    this._array.splice(i, 0, value);
+  }
+
+  public delete(value: T): boolean {
+    if (this._array.length === 0) {
+      return false;
+    }
+    const key = this._getKey(value);
+    if (key === undefined) {
+      return false;
+    }
+    i = this._search(key);
+    if (i === -1) {
+      return false;
+    }
+    if (this._getKey(this._array[i]) !== key) {
+      return false;
+    }
+    do {
+      if (this._array[i] === value) {
+        this._array.splice(i, 1);
+        return true;
+      }
+    } while (++i < this._array.length && this._getKey(this._array[i]) === key);
+    return false;
+  }
+
+  public *getKeyIterator(key: number): IterableIterator<T> {
+    if (this._array.length === 0) {
+      return;
+    }
+    i = this._search(key);
+    if (i < 0 || i >= this._array.length) {
+      return;
+    }
+    if (this._getKey(this._array[i]) !== key) {
+      return;
+    }
+    do {
+      yield this._array[i];
+    } while (++i < this._array.length && this._getKey(this._array[i]) === key);
+  }
+
+  public forEachByKey(key: number, callback: (value: T) => void): void {
+    if (this._array.length === 0) {
+      return;
+    }
+    i = this._search(key);
+    if (i < 0 || i >= this._array.length) {
+      return;
+    }
+    if (this._getKey(this._array[i]) !== key) {
+      return;
+    }
+    do {
+      callback(this._array[i]);
+    } while (++i < this._array.length && this._getKey(this._array[i]) === key);
+  }
+
+  public values(): IterableIterator<T> {
+    // Duplicate the array to avoid issues when _array changes while iterating
+    return [...this._array].values();
+  }
+
+  private _search(key: number): number {
+    let min = 0;
+    let max = this._array.length - 1;
+    while (max >= min) {
+      let mid = (min + max) >> 1;
+      const midKey = this._getKey(this._array[mid]);
+      if (midKey > key) {
+        max = mid - 1;
+      } else if (midKey < key) {
+        min = mid + 1;
+      } else {
+        // key in list, walk to lowest duplicate
+        while (mid > 0 && this._getKey(this._array[mid - 1]) === key) {
+          mid--;
+        }
+        return mid;
+      }
+    }
+    // key not in list
+    // still return closest min (also used as insert position)
+    return min;
+  }
+}

package/src/common/TaskQueue.ts

@@ -0,0 +1,166 @@
+/**
+ * Copyright (c) 2022 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { isNode } from 'common/Platform';
+
+interface ITaskQueue {
+  /**
+   * Adds a task to the queue which will run in a future idle callback.
+   * To avoid perceivable stalls on the mainthread, tasks with heavy workload
+   * should split their work into smaller pieces and return `true` to get
+   * called again until the work is done (on falsy return value).
+   */
+  enqueue(task: () => boolean | void): void;
+
+  /**
+   * Flushes the queue, running all remaining tasks synchronously.
+   */
+  flush(): void;
+
+  /**
+   * Clears any remaining tasks from the queue, these will not be run.
+   */
+  clear(): void;
+}
+
+interface ITaskDeadline {
+  timeRemaining(): number;
+}
+type CallbackWithDeadline = (deadline: ITaskDeadline) => void;
+
+abstract class TaskQueue implements ITaskQueue {
+  private _tasks: (() => boolean | void)[] = [];
+  private _idleCallback?: number;
+  private _i = 0;
+
+  protected abstract _requestCallback(callback: CallbackWithDeadline): number;
+  protected abstract _cancelCallback(identifier: number): void;
+
+  public enqueue(task: () => boolean | void): void {
+    this._tasks.push(task);
+    this._start();
+  }
+
+  public flush(): void {
+    while (this._i < this._tasks.length) {
+      if (!this._tasks[this._i]()) {
+        this._i++;
+      }
+    }
+    this.clear();
+  }
+
+  public clear(): void {
+    if (this._idleCallback) {
+      this._cancelCallback(this._idleCallback);
+      this._idleCallback = undefined;
+    }
+    this._i = 0;
+    this._tasks.length = 0;
+  }
+
+  private _start(): void {
+    if (!this._idleCallback) {
+      this._idleCallback = this._requestCallback(this._process.bind(this));
+    }
+  }
+
+  private _process(deadline: ITaskDeadline): void {
+    this._idleCallback = undefined;
+    let taskDuration = 0;
+    let longestTask = 0;
+    let lastDeadlineRemaining = deadline.timeRemaining();
+    let deadlineRemaining = 0;
+    while (this._i < this._tasks.length) {
+      taskDuration = Date.now();
+      if (!this._tasks[this._i]()) {
+        this._i++;
+      }
+      // other than performance.now, Date.now might not be stable (changes on wall clock changes),
+      // this is not an issue here as a clock change during a short running task is very unlikely
+      // in case it still happened and leads to negative duration, simply assume 1 msec
+      taskDuration = Math.max(1, Date.now() - taskDuration);
+      longestTask = Math.max(taskDuration, longestTask);
+      // Guess the following task will take a similar time to the longest task in this batch, allow
+      // additional room to try avoid exceeding the deadline
+      deadlineRemaining = deadline.timeRemaining();
+      if (longestTask * 1.5 > deadlineRemaining) {
+        // Warn when the time exceeding the deadline is over 20ms, if this happens in practice the
+        // task should be split into sub-tasks to ensure the UI remains responsive.
+        if (lastDeadlineRemaining - taskDuration < -20) {
+          console.warn(`task queue exceeded allotted deadline by ${Math.abs(Math.round(lastDeadlineRemaining - taskDuration))}ms`);
+        }
+        this._start();
+        return;
+      }
+      lastDeadlineRemaining = deadlineRemaining;
+    }
+    this.clear();
+  }
+}
+
+/**
+ * A queue of that runs tasks over several tasks via setTimeout, trying to maintain above 60 frames
+ * per second. The tasks will run in the order they are enqueued, but they will run some time later,
+ * and care should be taken to ensure they're non-urgent and will not introduce race conditions.
+ */
+export class PriorityTaskQueue extends TaskQueue {
+  protected _requestCallback(callback: CallbackWithDeadline): number {
+    return setTimeout(() => callback(this._createDeadline(16)));
+  }
+
+  protected _cancelCallback(identifier: number): void {
+    clearTimeout(identifier);
+  }
+
+  private _createDeadline(duration: number): ITaskDeadline {
+    const end = Date.now() + duration;
+    return {
+      timeRemaining: () => Math.max(0, end - Date.now())
+    };
+  }
+}
+
+class IdleTaskQueueInternal extends TaskQueue {
+  protected _requestCallback(callback: IdleRequestCallback): number {
+    return requestIdleCallback(callback);
+  }
+
+  protected _cancelCallback(identifier: number): void {
+    cancelIdleCallback(identifier);
+  }
+}
+
+/**
+ * A queue of that runs tasks over several idle callbacks, trying to respect the idle callback's
+ * deadline given by the environment. The tasks will run in the order they are enqueued, but they
+ * will run some time later, and care should be taken to ensure they're non-urgent and will not
+ * introduce race conditions.
+ *
+ * This reverts to a {@link PriorityTaskQueue} if the environment does not support idle callbacks.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const IdleTaskQueue = (!isNode && 'requestIdleCallback' in window) ? IdleTaskQueueInternal : PriorityTaskQueue;
+
+/**
+ * An object that tracks a single debounced task that will run on the next idle frame. When called
+ * multiple times, only the last set task will run.
+ */
+export class DebouncedIdleTask {
+  private _queue: ITaskQueue;
+
+  constructor() {
+    this._queue = new IdleTaskQueue();
+  }
+
+  public set(task: () => boolean | void): void {
+    this._queue.clear();
+    this._queue.enqueue(task);
+  }
+
+  public flush(): void {
+    this._queue.flush();
+  }
+}

package/src/common/TypedArrayUtils.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) 2018 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+export type TypedArray = Uint8Array | Uint16Array | Uint32Array | Uint8ClampedArray | Int8Array | Int16Array | Int32Array | Float32Array | Float64Array;
+
+/**
+ * Concat two typed arrays `a` and `b`.
+ * Returns a new typed array.
+ */
+export function concat<T extends TypedArray>(a: T, b: T): T {
+  const result = new (a.constructor as any)(a.length + b.length);
+  result.set(a);
+  result.set(b, a.length);
+  return result;
+}