{"version":3,"file":"TerminalWritable.js","sourceRoot":"","sources":["../src/TerminalWritable.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D;;;AAwB3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAsB,gBAAgB;IAKpC,YAAmB,OAAkC;QACnD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QAEpB,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,GAAG,EAAE,CAAC;QACf,CAAC;QAED,IAAI,CAAC,gBAAgB,GAAG,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAC;IACrD,CAAC;IAED;;;;OAIG;IACH,IAAW,MAAM;QACf,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;;;;;;;;;;;OAYG;IACI,UAAU,CAAC,KAAqB;QACrC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;QAC/C,CAAC;QACD,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IAOD;;;;;;;;;;;;OAYG;IACI,KAAK;QACV,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,IAAI,CAAC,OAAO,EAAE,CAAC;YACf,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACvB,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACO,OAAO,KAAU,CAAC;CAC7B;AAhFD,4CAgFC","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport type { ITerminalChunk } from './ITerminalChunk';\n\n/**\n * Constructor options for {@link TerminalWritable}\n *\n * @public\n */\nexport interface ITerminalWritableOptions {\n  /**\n   * When this object is the {@link TerminalTransform.destination} for a transform,\n   * the transform will automatically close this object.  Set `preventAutoclose` to `true`\n   * to prevent that behavior.\n   *\n   * @remarks\n   * When a transform is closed, normally it will automatically close its destination\n   * `TerminalWritable` object.  There are two ways to prevent that: either by setting\n   * `preventDestinationAutoclose` to `true` for the transform, or by setting\n   * {@link TerminalWritable.preventAutoclose} to `true` for the `destination` object.\n   */\n  preventAutoclose?: boolean;\n}\n\n/**\n * The abstract base class for objects that can present, route, or process text output for\n * a console application.  This output is typically prepared using\n * the {@link Terminal} API.\n *\n * @remarks\n *\n * The design is based loosely on the `WritableStream` and `TransformStream` classes from\n * the system {@link https://developer.mozilla.org/en-US/docs/Web/API/Streams_API/Concepts\n * | Streams API}, except that instead of asynchronous byte streams, the `TerminalWritable`\n * system synchronously transmits human readable messages intended to be rendered on a text\n * console or log file.\n *\n * Consider a console application whose output may need to be processed in different ways\n * before finally being output.  The conceptual block diagram might look like this:\n *\n * ```\n *          [Terminal API]\n *                 |\n *                 V\n *        [normalize newlines]\n *                 |\n *                 V\n *       +----[splitter]-------+\n *       |                     |\n *       V                     V\n *   [shell console]     [remove ANSI colors]\n *                             |\n *                             V\n *                       [write to build.log]\n * ```\n *\n * The application uses the `Terminal` API to print `stdout` and `stderr` messages, for example with standardized\n * formatting for errors and warnings, and ANSI escapes to make nice colors.  Maybe it also includes text\n * received from external processes, whose newlines may be inconsistent.  Ultimately we want to write the\n * output to the shell console and a `build.log` file, but we don't want to put ANSI colors in the build log.\n *\n * For the above example, `[shell console]` and `[write to build.log]` would be modeled as subclasses of\n * `TerminalWritable`.  The `[normalize newlines]` and `[remove ANSI colors]` steps are modeled as subclasses\n * of {@link TerminalTransform}, because they output to a \"destination\" object.  The `[splitter]` would be\n * implemented using {@link SplitterTransform}.\n *\n * The stream of messages are {@link ITerminalChunk} objects, which can represent both `stdout` and `stderr`\n * channels.  The pipeline operates synchronously on each chunk, but by processing one chunk at a time,\n * it avoids storing the entire output in memory.  This means that operations like `[remove ANSI colors]`\n * cannot be simple regular expressions -- they must be implemented as state machines ({@link TextRewriter}\n * subclasses) capable of matching substrings that span multiple chunks.\n *\n * @public\n */\nexport abstract class TerminalWritable {\n  private _isOpen: boolean;\n\n  public readonly preventAutoclose: boolean;\n\n  public constructor(options?: ITerminalWritableOptions) {\n    this._isOpen = true;\n\n    if (!options) {\n      options = {};\n    }\n\n    this.preventAutoclose = !!options.preventAutoclose;\n  }\n\n  /**\n   * This property is initially `true` when the object is constructed, and becomes `false`\n   * when `close()` is called.\n   * @sealed\n   */\n  public get isOpen(): boolean {\n    return this._isOpen;\n  }\n\n  /**\n   * Upstream objects call this method to provide inputs to this object.\n   *\n   * @remarks\n   * The subclass provides its implementation via the the {@link TerminalWritable.onWriteChunk}\n   * method, which is called by `writeChunk()`.\n   *\n   * The object that calls `writeChunk()` must call `close()` when it is finished;\n   * failing to do so may introduce a resource leak, or may prevent some buffered data from\n   * being written.\n   *\n   * @sealed\n   */\n  public writeChunk(chunk: ITerminalChunk): void {\n    if (!this._isOpen) {\n      throw new Error('Writer was already closed');\n    }\n    this.onWriteChunk(chunk);\n  }\n\n  /**\n   * Subclasses should implement this `abstract` method to process the chunk.\n   */\n  protected abstract onWriteChunk(chunk: ITerminalChunk): void;\n\n  /**\n   * Calling this method flushes any remaining outputs and permanently transitions the\n   * `TerminalWritable` to a \"closed\" state, where no further chunks can be written.\n   *\n   * @remarks\n   * The subclass provides its implementation via the the {@link TerminalWritable.onClose}\n   * method, which is called by `close()`.\n   *\n   * If this method is called more than once, the additional calls are ignored;\n   * `TerminalWritable.onClose` will be called at most once.\n   *\n   * @sealed\n   */\n  public close(): void {\n    if (this._isOpen) {\n      this.onClose();\n      this._isOpen = false;\n    }\n  }\n\n  /**\n   * Subclasses can override this empty method to perform additional operations\n   * such as closing a file handle.\n   *\n   * @remarks\n   * It is guaranteed that this method will be called at most once during the lifetime\n   * of a `TerminalWritable` object.\n   *\n   * @virtual\n   */\n  protected onClose(): void {}\n}\n"]}