@gesslar/toolkit 3.38.0 → 3.40.0

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "3.38.0",
+  "version": "3.40.0",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {

package/src/node/lib/Term.js

@@ -1,10 +1,12 @@
+import c from "@gesslar/colours"
 import console, {Console} from "node:console"
 import process from "node:process"
 import {Writable} from "node:stream"
-import supportsColor from "supports-color"
 import {stripVTControlCharacters} from "node:util"
-import c from "@gesslar/colours"
+import supportsColor from "supports-color"
 
+import Promised from "../../browser/lib/Promised.js"
+import Time from "../../browser/lib/Time.js"
 import Sass from "./Sass.js"
 
 c.alias.set("success", "{F035}")
@@ -488,13 +490,15 @@ export default class Term {
    * If in Char Mode, it resolves on Enter, Ctrl+D, or the ANSI 'R' terminator.
    *
    * @param {(text: string) => boolean} [terminator] - Optional callback to check if input is complete.
-   * @returns {Promise<string>} Resolves with the input data.
+   * @param {number} [timeoutMs=0] - Optional timeout in milliseconds. Resolves with empty string if exceeded.
+   * @returns {Promise<string>} Resolves with the input data, or empty string on timeout.
    */
-  static data(terminator = () => false) {
+  static data(terminator = () => false, timeoutMs = 0) {
     process.stdin.resume()
 
     return new Promise((resolve, reject) => {
       const chunks = []
+      let timer = null
 
       function onData(chunk) {
         const s = chunk.toString()
@@ -532,6 +536,7 @@ export default class Term {
       }
 
       function cleanup() {
+        clearTimeout(timer)
         process.stdin.off("data", onData)
         process.stdin.off("end", onEnd)
         process.stdin.off("error", onError)
@@ -544,11 +549,15 @@ export default class Term {
       process.stdin.on("data", onData)
       process.stdin.once("end", onEnd)
       process.stdin.once("error", onError)
+
+      if(timeoutMs > 0)
+        timer = setTimeout(onEnd, timeoutMs)
     })
   }
 
   /**
    * Gets the current cursor position in the terminal.
+   * Returns [0, 0] for non-interactive terminals or if the terminal does not respond within the timeout.
    *
    * @returns {Promise<[number, number]>} Resolves with [x, y] cursor position.
    */
@@ -567,13 +576,16 @@ export default class Term {
     // 2. Start the listener FIRST (do not await yet)
     const dataPromise = this.data((text => {
       return this.isCharMode && text.endsWith("R")
-    }).bind(this))
+    }).bind(this), 25)
 
     // 3. Write to stdout AFTER the listener is ready
     this.write("\x1b[6n")
 
     // 4. Now await the response
-    const positionData = await dataPromise
+    const positionData = await Promised.race([
+      Time.after(25),
+      dataPromise
+    ])
 
     // 5. Restore the previous mode
     prevRawMode ? this.setCharMode() : this.setLineMode()
@@ -601,8 +613,11 @@ export default class Term {
     })
   }
 
-  // Spinner frames - using Braille patterns (widely supported)
-  // Falls back to ASCII when spinimate is implemented with proper detection
+  /**
+   * Spinner animation frames using Braille patterns (widely supported).
+   *
+   * @type {readonly string[]}
+   */
   static spinFrames = Object.freeze(["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"])
 
   // static async spinimate(delay=300, options = {position: {x: 0,y: 0}}) {
@@ -648,4 +663,98 @@ export default class Term {
 
     return this
   }
+
+  /**
+   * Switch to the alternate screen buffer.
+   *
+   * @returns {typeof Term} The Term class for chaining.
+   */
+  static altScreen() {
+    this.write("\x1b[?1049h")
+
+    return this
+  }
+
+  /**
+   * Switch back to the main screen buffer.
+   *
+   * @returns {typeof Term} The Term class for chaining.
+   */
+  static mainScreen() {
+    this.write("\x1b[?1049l")
+
+    return this
+  }
+
+  /**
+   * Queries the terminal to determine whether the alternate screen buffer is currently active.
+   * Returns undefined for non-interactive terminals or if the terminal does not respond within the timeout.
+   *
+   * @returns {Promise<boolean|undefined>} true if in alt screen, false if in main screen, undefined if unknown.
+   */
+  static async isAltScreen() {
+    if(!this.isInteractive)
+      return undefined
+
+    const prevRawMode = this.isCharMode
+
+    // 1. Force Raw Mode so the terminal sends the report immediately
+    this.setCharMode()
+    process.stdin.setEncoding("utf8")
+
+    // 2. Start the listener FIRST (do not await yet)
+    const dataPromise = this.data((text => {
+      return this.isCharMode && text.endsWith("$y")
+    }).bind(this), 25)
+
+    this.write("\x1b[?1049$p")
+
+    const response = await Promised.race([
+      Time.after(25),
+      dataPromise
+    ])
+
+    prevRawMode ? this.setCharMode() : this.setLineMode()
+
+    if(response === "\x1b[?1049;1$y")
+      return true
+
+    if(response === "\x1b[?1049;2$y")
+      return false
+
+    return undefined
+  }
+
+  /**
+   * Save the current screen contents.
+   *
+   * @returns {typeof Term} The Term class for chaining.
+   */
+  static saveScreen() {
+    this.write("\x1b[?47h")
+
+    return this
+  }
+
+  /**
+   * Restore previously saved screen contents.
+   *
+   * @returns {typeof Term} The Term class for chaining.
+   */
+  static restoreScreen() {
+    this.write("\x1b[?47l")
+
+    return this
+  }
+
+  /**
+   * Clear the entire screen and move cursor to the home position.
+   *
+   * @returns {typeof Term} The Term class for chaining.
+   */
+  static cls() {
+    this.write("\x1b[2J\x1b[H")
+
+    return this
+  }
 }

package/types/node/lib/Term.d.ts

@@ -266,11 +266,13 @@ export default class Term {
      * If in Char Mode, it resolves on Enter, Ctrl+D, or the ANSI 'R' terminator.
      *
      * @param {(text: string) => boolean} [terminator] - Optional callback to check if input is complete.
-     * @returns {Promise<string>} Resolves with the input data.
+     * @param {number} [timeoutMs=0] - Optional timeout in milliseconds. Resolves with empty string if exceeded.
+     * @returns {Promise<string>} Resolves with the input data, or empty string on timeout.
      */
-    static data(terminator?: (text: string) => boolean): Promise<string>;
+    static data(terminator?: (text: string) => boolean, timeoutMs?: number): Promise<string>;
     /**
      * Gets the current cursor position in the terminal.
+     * Returns [0, 0] for non-interactive terminals or if the terminal does not respond within the timeout.
      *
      * @returns {Promise<[number, number]>} Resolves with [x, y] cursor position.
      */
@@ -282,6 +284,11 @@ export default class Term {
      * @returns {Promise<void>} Resolves when write completes.
      */
     static directWrite(output: string): Promise<void>;
+    /**
+     * Spinner animation frames using Braille patterns (widely supported).
+     *
+     * @type {readonly string[]}
+     */
     static spinFrames: readonly string[];
     /**
      * Pause stdin, preventing it from emitting data events.
@@ -301,5 +308,42 @@ export default class Term {
      * @returns {typeof Term} The Term class for chaining.
      */
     static utf8(): typeof Term;
+    /**
+     * Switch to the alternate screen buffer.
+     *
+     * @returns {typeof Term} The Term class for chaining.
+     */
+    static altScreen(): typeof Term;
+    /**
+     * Switch back to the main screen buffer.
+     *
+     * @returns {typeof Term} The Term class for chaining.
+     */
+    static mainScreen(): typeof Term;
+    /**
+     * Queries the terminal to determine whether the alternate screen buffer is currently active.
+     * Returns undefined for non-interactive terminals or if the terminal does not respond within the timeout.
+     *
+     * @returns {Promise<boolean|undefined>} true if in alt screen, false if in main screen, undefined if unknown.
+     */
+    static isAltScreen(): Promise<boolean | undefined>;
+    /**
+     * Save the current screen contents.
+     *
+     * @returns {typeof Term} The Term class for chaining.
+     */
+    static saveScreen(): typeof Term;
+    /**
+     * Restore previously saved screen contents.
+     *
+     * @returns {typeof Term} The Term class for chaining.
+     */
+    static restoreScreen(): typeof Term;
+    /**
+     * Clear the entire screen and move cursor to the home position.
+     *
+     * @returns {typeof Term} The Term class for chaining.
+     */
+    static cls(): typeof Term;
 }
 //# sourceMappingURL=Term.d.ts.map

package/types/node/lib/Term.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Term.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Term.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"Term.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Term.js"],"names":[],"mappings":"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"}