Add a proposed API check option

Part of #2826

src/browser/public/Terminal.ts

@@ -24,6 +24,12 @@ export class Terminal implements ITerminalApi {
     this._addonManager = new AddonManager();
   }
 
+  private _checkProposedApi(): void {
+    if (!this._core.optionsService.options.allowProposedApi) {
+      throw new Error('You must set the allowProposedApi option to true to use proposed API');
+    }
+  }
+
   public get onCursorMove(): IEvent<void> { return this._core.onCursorMove; }
   public get onLineFeed(): IEvent<void> { return this._core.onLineFeed; }
   public get onSelectionChange(): IEvent<void> { return this._core.onSelectionChange; }
@@ -37,19 +43,27 @@ export class Terminal implements ITerminalApi {
 
   public get element(): HTMLElement | undefined { return this._core.element; }
   public get parser(): IParser {
+    this._checkProposedApi();
     if (!this._parser) {
       this._parser = new ParserApi(this._core);
     }
     return this._parser;
   }
   public get unicode(): IUnicodeHandling {
+    this._checkProposedApi();
     return new UnicodeApi(this._core);
   }
   public get textarea(): HTMLTextAreaElement | undefined { return this._core.textarea; }
   public get rows(): number { return this._core.rows; }
   public get cols(): number { return this._core.cols; }
-  public get buffer(): IBufferNamespaceApi { return new BufferNamespaceApi(this._core.buffers); }
-  public get markers(): ReadonlyArray<IMarker> { return this._core.markers; }
+  public get buffer(): IBufferNamespaceApi {
+    this._checkProposedApi();
+    return new BufferNamespaceApi(this._core.buffers);
+  }
+  public get markers(): ReadonlyArray<IMarker> {
+    this._checkProposedApi();
+    return this._core.markers;
+  }
   public blur(): void {
     this._core.blur();
   }
@@ -67,21 +81,27 @@ export class Terminal implements ITerminalApi {
     this._core.attachCustomKeyEventHandler(customKeyEventHandler);
   }
   public registerLinkMatcher(regex: RegExp, handler: (event: MouseEvent, uri: string) => void, options?: ILinkMatcherOptions): number {
+    this._checkProposedApi();
     return this._core.registerLinkMatcher(regex, handler, options);
   }
   public deregisterLinkMatcher(matcherId: number): void {
+    this._checkProposedApi();
     this._core.deregisterLinkMatcher(matcherId);
   }
   public registerLinkProvider(linkProvider: ILinkProvider): IDisposable {
+    this._checkProposedApi();
     return this._core.registerLinkProvider(linkProvider);
   }
   public registerCharacterJoiner(handler: (text: string) => [number, number][]): number {
+    this._checkProposedApi();
     return this._core.registerCharacterJoiner(handler);
   }
   public deregisterCharacterJoiner(joinerId: number): void {
+    this._checkProposedApi();
     this._core.deregisterCharacterJoiner(joinerId);
   }
   public registerMarker(cursorYOffset: number): IMarker | undefined {
+    this._checkProposedApi();
     this._verifyIntegers(cursorYOffset);
     return this._core.addMarker(cursorYOffset);
   }

src/common/services/OptionsService.ts

@@ -41,6 +41,7 @@ export const DEFAULT_OPTIONS: ITerminalOptions = Object.freeze({
   macOptionClickForcesSelection: false,
   minimumContrastRatio: 1,
   disableStdin: false,
+  allowProposedApi: true,
   allowTransparency: false,
   tabStopWidth: 8,
   theme: {},

src/common/services/Services.ts

@@ -218,6 +218,7 @@ export interface IPartialTerminalOptions {
 }
 
 export interface ITerminalOptions {
+  allowProposedApi: boolean;
   allowTransparency: boolean;
   bellSound: string;
   bellStyle: 'none' | 'sound' /* | 'visual' | 'both' */;

test/api/Terminal.api.ts

@@ -33,6 +33,18 @@ describe('API Integration Tests', function(): void {
     assert.equal(await page.evaluate(`window.term.rows`), 24);
   });
 
+  it('Proposed API check', async () => {
+    await openTerminal(page, { allowProposedApi: false });
+    await page.evaluate(`
+      try {
+        window.term.buffer;
+      } catch (e) {
+        window.throwMessage = e.message;
+      }
+    `);
+    await pollFor(page, 'window.throwMessage', 'You must set the allowProposedApi option to true to use proposed API');
+  });
+
   it('write', async () => {
     await openTerminal(page);
     await page.evaluate(`

typings/xterm.d.ts

@@ -29,6 +29,13 @@ declare module 'xterm' {
    * An object containing start up options for the terminal.
    */
   export interface ITerminalOptions {
+    /**
+     * Whether to allow the use of proposed API. When false, any usage of APIs
+     * marked as experimental/proposed will throw an error. This defaults to
+     * true currently, but will change to false in v5.0.
+     */
+    allowProposedApi?: boolean;
+
     /**
      * Whether background should support non-opaque color. It must be set before
      * executing the `Terminal.open()` method and can't be changed later without