@gesslar/toolkit 3.37.0 → 3.39.1

package/package.json

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

package/src/node/lib/DirectoryObject.js

@@ -7,6 +7,7 @@
 import {glob, mkdir, opendir, readdir, rmdir, stat} from "node:fs/promises"
 import path, {relative} from "node:path"
 import {URL} from "node:url"
+import {inspect} from "node:util"
 
 import Data from "../../browser/lib/Data.js"
 import FileObject from "./FileObject.js"
@@ -158,6 +159,62 @@ export default class DirectoryObject extends FS {
     return `[${this.constructor.name}: ${this.path}]`
   }
 
+  /**
+   * Returns a JSON-serializable representation of the DirectoryObject.
+   *
+   * @returns {object} Plain object with directory metadata
+   */
+  toJSON() {
+    return {
+      supplied: this.supplied,
+      path: this.path,
+      name: this.name,
+      module: this.module,
+      extension: this.extension,
+      isDirectory: this.isDirectory,
+      parentPath: this.#meta.parentPath,
+      sep: this.sep,
+      trail: this.trail,
+    }
+  }
+
+  /**
+   * Custom Node.js inspect implementation for console.log output.
+   *
+   * @param {number} depth - Inspection depth
+   * @param {object} options - Inspect options
+   * @param {Function} ins - The inspect function
+   * @returns {string} Formatted string representation
+   */
+  [inspect.custom](depth, options, ins) {
+    return `${this.constructor.name} ${ins(this.toJSON(), options)}`
+  }
+
+  /**
+   * Returns the directory path as a primitive value, enabling natural use in
+   * string contexts. String and default hints return the directory path; number
+   * hint returns NaN.
+   *
+   * @param {"string"|"number"|"default"} hint - The coercion type hint
+   * @returns {string|number} The directory path, or NaN for numeric coercion
+   */
+  [Symbol.toPrimitive](hint) {
+    if(hint === "number") {
+      return NaN
+    }
+
+    return this.path
+  }
+
+  /**
+   * Returns the directory path as a primitive string value.
+   *
+   * @returns {string} The directory path
+   */
+  valueOf() {
+    return this.path
+  }
+
   /**
    * Checks if the directory exists (async).
    *

package/src/node/lib/FileObject.js

@@ -9,6 +9,7 @@ import fs from "node:fs/promises"
 import YAML from "yaml"
 import {URL} from "node:url"
 import {Buffer} from "node:buffer"
+import {inspect} from "node:util"
 
 import Data from "../../browser/lib/Data.js"
 import DirectoryObject from "./DirectoryObject.js"
@@ -147,6 +148,60 @@ export default class FileObject extends FS {
     return `[${this.constructor.name}: ${this.path}]`
   }
 
+  /**
+   * Returns a JSON-serializable representation of the FileObject.
+   *
+   * @returns {object} Plain object with file metadata
+   */
+  toJSON() {
+    return {
+      supplied: this.supplied,
+      path: this.path,
+      name: this.name,
+      module: this.module,
+      extension: this.extension,
+      isFile: this.isFile,
+      parentPath: this.parentPath,
+    }
+  }
+
+  /**
+   * Custom Node.js inspect implementation for console.log output.
+   *
+   * @param {number} depth - Inspection depth
+   * @param {object} options - Inspect options
+   * @param {Function} ins - The inspect function
+   * @returns {string} Formatted string representation
+   */
+  [inspect.custom](depth, options, ins) {
+    return `${this.constructor.name} ${ins(this.toJSON(), options)}`
+  }
+
+  /**
+   * Returns the file path as a primitive value, enabling natural use in
+   * string contexts. String and default hints return the file path; number
+   * hint returns NaN.
+   *
+   * @param {"string"|"number"|"default"} hint - The coercion type hint
+   * @returns {string|number} The file path, or NaN for numeric coercion
+   */
+  [Symbol.toPrimitive](hint) {
+    if(hint === "number") {
+      return NaN
+    }
+
+    return this.path
+  }
+
+  /**
+   * Returns the file path as a primitive string value.
+   *
+   * @returns {string} The file path
+   */
+  valueOf() {
+    return this.path
+  }
+
   /**
    * Checks if the file exists (async).
    *

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,79 @@ export default class Term {
 
     return this
   }
+
+  /**
+   * Switch to the alternate screen buffer.
+   *
+   * @returns {void}
+   */
+  static altScreen() {
+    this.write("\x1b[?1049h")
+  }
+
+  /**
+   * Switch back to the main screen buffer.
+   *
+   * @returns {void}
+   */
+  static mainScreen() {
+    this.write("\x1b[?1049l")
+  }
+
+  /**
+   * 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 {void}
+   */
+  static saveScreen() {
+    this.write("\x1b[?47h")
+  }
+
+  /**
+   * Restore previously saved screen contents.
+   *
+   * @returns {void}
+   */
+  static restoreScreen() {
+    this.write("\x1b[?47l")
+  }
 }

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

@@ -80,6 +80,18 @@ export default class DirectoryObject extends FS {
      * @param {string?} [supplied="."] - The directory path (defaults to current directory)
      */
     constructor(supplied?: string | null);
+    /**
+     * Returns a JSON-serializable representation of the DirectoryObject.
+     *
+     * @returns {object} Plain object with directory metadata
+     */
+    toJSON(): object;
+    /**
+     * Returns the directory path as a primitive string value.
+     *
+     * @returns {string} The directory path
+     */
+    valueOf(): string;
     /**
      * Checks if the directory exists (async).
      *
@@ -322,6 +334,24 @@ export default class DirectoryObject extends FS {
      * console.log(escaped.path) // "/projects/git/toolkit/foo/bar.js"
      */
     getFile(filename: string): FileObject;
+    /**
+     * Custom Node.js inspect implementation for console.log output.
+     *
+     * @param {number} depth - Inspection depth
+     * @param {object} options - Inspect options
+     * @param {Function} ins - The inspect function
+     * @returns {string} Formatted string representation
+     */
+    [inspect.custom](depth: number, options: object, ins: Function): string;
+    /**
+     * Returns the directory path as a primitive value, enabling natural use in
+     * string contexts. String and default hints return the directory path; number
+     * hint returns NaN.
+     *
+     * @param {"string"|"number"|"default"} hint - The coercion type hint
+     * @returns {string|number} The directory path, or NaN for numeric coercion
+     */
+    [Symbol.toPrimitive](hint: "string" | "number" | "default"): string | number;
     #private;
 }
 export type GeneratorType = {
@@ -380,4 +410,5 @@ export type DirectoryMeta = {
 import FS from "./FileSystem.js";
 import { URL } from "node:url";
 import FileObject from "./FileObject.js";
+import { inspect } from "node:util";
 //# sourceMappingURL=DirectoryObject.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"DirectoryObject.d.ts","sourceRoot":"","sources":["../../../src/node/lib/DirectoryObject.js"],"names":[],"mappings":"AAgBA;;;;GAIG;AAEH;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH;IAuDE;;;;;;;;;OASG;IACH,kBALa,eAAe,CAO3B;IA7CD;;;;OAIG;IACH,uBAFW,MAAM,OAAC,EA4BjB;IAyBD;;;;OAIG;IACH,cAFa,OAAO,CAAC,OAAO,CAAC,CAI5B;IAED;;;;OAIG;IACH,gBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,GAAG,CAIf;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,aALa,KAAK,CAAC,MAAM,CAAC,CAOzB;IAED;;;;;;;;;;;;OAYG;IACH,cARa,eAAe,GAAC,IAAI,CAsBhC;IAED;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAmBD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,WAZW,MAAM,iBACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;KAAC,CAAC,CAkCpF;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,WAXW,MAAM,iBACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;KAAC,CAAC,CA0BpF;IAqCD;;;;;;;;;;;;OAYG;IACH,uBARW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAuBzB;IAyBD;;;;;;;;;;;;;;;OAeG;IACH,cAZa,eAAe,CAc3B;IAED;;;;;;;;;;;;;;OAcG;IACH,UARa,OAAO,CAAC,IAAI,CAAC,CAkBzB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAM5B;IAED;;;;;OAKG;IACH,sBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAO5B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,sBAbW,MAAM,GACJ,eAAe,CAkC3B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,kBAbW,MAAM,GACJ,UAAU,CAkCtB;;CACF;;UAlnBa,MAAY;QAAC,KAAK,EAAE,eAAe,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAC;eACnD,MAAY,aAAa;;;;;;iBAMzB,OAAO;;;;eACP,MAAM,GAAC,IAAI;;;;YACX,MAAM,GAAC,IAAI;;;;UACX,MAAM,GAAC,IAAI;;;;YACX,eAAe,GAAC,SAAS;;;;gBACzB,MAAM,GAAC,IAAI;;;;UACX,MAAM,GAAC,IAAI;;;;SACX,MAAM,GAAC,IAAI;;;;cACX,MAAM,GAAC,IAAI;;;;WACX,KAAK,CAAC,MAAM,CAAC,GAAC,IAAI;;;;SAClB,GAAG,GAAC,IAAI;;eAvBP,iBAAiB;oBAJd,UAAU;uBAGL,iBAAiB"}
+{"version":3,"file":"DirectoryObject.d.ts","sourceRoot":"","sources":["../../../src/node/lib/DirectoryObject.js"],"names":[],"mappings":"AAiBA;;;;GAIG;AAEH;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH;IAuDE;;;;;;;;;OASG;IACH,kBALa,eAAe,CAO3B;IA7CD;;;;OAIG;IACH,uBAFW,MAAM,OAAC,EA4BjB;IAyBD;;;;OAIG;IACH,UAFa,MAAM,CAclB;IA8BD;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAAC,OAAO,CAAC,CAI5B;IAED;;;;OAIG;IACH,gBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,GAAG,CAIf;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,aALa,KAAK,CAAC,MAAM,CAAC,CAOzB;IAED;;;;;;;;;;;;OAYG;IACH,cARa,eAAe,GAAC,IAAI,CAsBhC;IAED;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAmBD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,WAZW,MAAM,iBACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;KAAC,CAAC,CAkCpF;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,WAXW,MAAM,iBACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;KAAC,CAAC,CA0BpF;IAqCD;;;;;;;;;;;;OAYG;IACH,uBARW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAuBzB;IAyBD;;;;;;;;;;;;;;;OAeG;IACH,cAZa,eAAe,CAc3B;IAED;;;;;;;;;;;;;;OAcG;IACH,UARa,OAAO,CAAC,IAAI,CAAC,CAkBzB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAM5B;IAED;;;;;OAKG;IACH,sBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAO5B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,sBAbW,MAAM,GACJ,eAAe,CAkC3B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,kBAbW,MAAM,GACJ,UAAU,CAkCtB;IAxgBD;;;;;;;OAOG;IACH,wBALW,MAAM,WACN,MAAM,kBAEJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,2BAHW,QAAQ,GAAC,QAAQ,GAAC,SAAS,GACzB,MAAM,GAAC,MAAM,CAQzB;;CA+eF;;UA1qBa,MAAY;QAAC,KAAK,EAAE,eAAe,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAC;eACnD,MAAY,aAAa;;;;;;iBAMzB,OAAO;;;;eACP,MAAM,GAAC,IAAI;;;;YACX,MAAM,GAAC,IAAI;;;;UACX,MAAM,GAAC,IAAI;;;;YACX,eAAe,GAAC,SAAS;;;;gBACzB,MAAM,GAAC,IAAI;;;;UACX,MAAM,GAAC,IAAI;;;;SACX,MAAM,GAAC,IAAI;;;;cACX,MAAM,GAAC,IAAI;;;;WACX,KAAK,CAAC,MAAM,CAAC,GAAC,IAAI;;;;SAClB,GAAG,GAAC,IAAI;;eAvBP,iBAAiB;oBALd,UAAU;uBAIL,iBAAiB;wBAHlB,WAAW"}

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

@@ -42,6 +42,18 @@ export default class FileObject extends FS {
      * @param {DirectoryObject|string|null} [parent] - The parent directory (object or string)
      */
     constructor(submitted: string, parent?: DirectoryObject | string | null);
+    /**
+     * Returns a JSON-serializable representation of the FileObject.
+     *
+     * @returns {object} Plain object with file metadata
+     */
+    toJSON(): object;
+    /**
+     * Returns the file path as a primitive string value.
+     *
+     * @returns {string} The file path
+     */
+    valueOf(): string;
     /**
      * Checks if the file exists (async).
      *
@@ -249,12 +261,31 @@ export default class FileObject extends FS {
      * await file.delete()
      */
     delete(): Promise<void>;
+    /**
+     * Custom Node.js inspect implementation for console.log output.
+     *
+     * @param {number} depth - Inspection depth
+     * @param {object} options - Inspect options
+     * @param {Function} ins - The inspect function
+     * @returns {string} Formatted string representation
+     */
+    [inspect.custom](depth: number, options: object, ins: Function): string;
+    /**
+     * Returns the file path as a primitive value, enabling natural use in
+     * string contexts. String and default hints return the file path; number
+     * hint returns NaN.
+     *
+     * @param {"string"|"number"|"default"} hint - The coercion type hint
+     * @returns {string|number} The file path, or NaN for numeric coercion
+     */
+    [Symbol.toPrimitive](hint: "string" | "number" | "default"): string | number;
     #private;
 }
 import FS from "./FileSystem.js";
 import { URL } from "node:url";
 import DirectoryObject from "./DirectoryObject.js";
 import { Buffer } from "node:buffer";
+import { inspect } from "node:util";
 import JSON5 from "json5";
 import YAML from "yaml";
 //# sourceMappingURL=FileObject.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"FileObject.d.ts","sourceRoot":"","sources":["../../../src/node/lib/FileObject.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;GAaG;AAEH;IACE;;;;;OAKG;IACH,yBAFU;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,OAAO,KAAK,GAAG,OAAO,IAAI,CAAC,CAAA;KAAC,CAO1D;IAghBF;;;;;;;;;;;OAWG;IACH,kBAPa,UAAU,CAsCtB;IAjiBD;;;;;OAKG;IACH,uBAHW,MAAM,WACN,eAAe,GAAC,MAAM,GAAC,IAAI,EA+DrC;IAWD;;;;OAIG;IACH,cAFa,OAAO,CAAC,OAAO,CAAC,CAI5B;IAED;;;;OAIG;IACH,gBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,GAAG,CAIf;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IACD;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;;;;;;;;;;;OAcG;IACH,cAFa,eAAe,CAI3B;IAED;;;;OAIG;IACH,kBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,OAAO,CAAC,OAAO,CAAC,CAU5B;IAED;;;;OAIG;IACH,YAFa,OAAO,CAAC,OAAO,CAAC,CAU5B;IAiBD;;;;OAIG;IACH,QAFa,OAAO,CAAC,MAAM,OAAC,CAAC,CAU5B;IAED;;;;;OAKG;IACH,YAFa,OAAO,CAAC,IAAI,OAAC,CAAC,CAU1B;IAED;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CAS3B;IAED;;;;;;;;;;;OAWG;IACH,cARa,OAAO,CAAC,MAAM,CAAC,CAe3B;IAED;;;;;;;;;;;OAWG;IACH,eARW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAiBzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,kBAXW,WAAW,GAAC,IAAI,GAAC,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAwBzB;IAED;;;;;;;;;;;;;;OAcG;IACH,gBAXW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAiC5B;IAED;;;;OAIG;IACH,UAFa,OAAO,CAAC,MAAM,CAAC,CAS3B;IAED;;;;;;;;;;;;OAYG;IACH,kBATW,MAAM,GACJ,OAAO,CAAC,UAAU,CAAC,CAyB/B;IAED;;;;;;;;;;;;;OAaG;IACH,kBATW,MAAM,GACJ,OAAO,CAAC,UAAU,CAAC,CA0C/B;IAED;;;;;;;;;OASG;IACH,UAPa,OAAO,CAAC,IAAI,CAAC,CAczB;;CA8CF;eA3lBc,iBAAiB;oBALd,UAAU;4BAIA,sBAAsB;uBAH7B,aAAa;kBAJhB,OAAO;iBAER,MAAM"}
+{"version":3,"file":"FileObject.d.ts","sourceRoot":"","sources":["../../../src/node/lib/FileObject.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;GAaG;AAEH;IACE;;;;;OAKG;IACH,yBAFU;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,OAAO,KAAK,GAAG,OAAO,IAAI,CAAC,CAAA;KAAC,CAO1D;IAskBF;;;;;;;;;;;OAWG;IACH,kBAPa,UAAU,CAsCtB;IAvlBD;;;;;OAKG;IACH,uBAHW,MAAM,WACN,eAAe,GAAC,MAAM,GAAC,IAAI,EA+DrC;IAWD;;;;OAIG;IACH,UAFa,MAAM,CAYlB;IA8BD;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAAC,OAAO,CAAC,CAI5B;IAED;;;;OAIG;IACH,gBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,GAAG,CAIf;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IACD;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;;;;;;;;;;;OAcG;IACH,cAFa,eAAe,CAI3B;IAED;;;;OAIG;IACH,kBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,OAAO,CAAC,OAAO,CAAC,CAU5B;IAED;;;;OAIG;IACH,YAFa,OAAO,CAAC,OAAO,CAAC,CAU5B;IAiBD;;;;OAIG;IACH,QAFa,OAAO,CAAC,MAAM,OAAC,CAAC,CAU5B;IAED;;;;;OAKG;IACH,YAFa,OAAO,CAAC,IAAI,OAAC,CAAC,CAU1B;IAED;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CAS3B;IAED;;;;;;;;;;;OAWG;IACH,cARa,OAAO,CAAC,MAAM,CAAC,CAe3B;IAED;;;;;;;;;;;OAWG;IACH,eARW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAiBzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,kBAXW,WAAW,GAAC,IAAI,GAAC,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAwBzB;IAED;;;;;;;;;;;;;;OAcG;IACH,gBAXW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAiC5B;IAED;;;;OAIG;IACH,UAFa,OAAO,CAAC,MAAM,CAAC,CAS3B;IAED;;;;;;;;;;;;OAYG;IACH,kBATW,MAAM,GACJ,OAAO,CAAC,UAAU,CAAC,CAyB/B;IAED;;;;;;;;;;;;;OAaG;IACH,kBATW,MAAM,GACJ,OAAO,CAAC,UAAU,CAAC,CA0C/B;IAED;;;;;;;;;OASG;IACH,UAPa,OAAO,CAAC,IAAI,CAAC,CAczB;IA3cD;;;;;;;OAOG;IACH,wBALW,MAAM,WACN,MAAM,kBAEJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,2BAHW,QAAQ,GAAC,QAAQ,GAAC,SAAS,GACzB,MAAM,GAAC,MAAM,CAQzB;;CA+dF;eAjpBc,iBAAiB;oBANd,UAAU;4BAKA,sBAAsB;uBAJ7B,aAAa;wBACZ,WAAW;kBALf,OAAO;iBAER,MAAM"}

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,36 @@ export default class Term {
      * @returns {typeof Term} The Term class for chaining.
      */
     static utf8(): typeof Term;
+    /**
+     * Switch to the alternate screen buffer.
+     *
+     * @returns {void}
+     */
+    static altScreen(): void;
+    /**
+     * Switch back to the main screen buffer.
+     *
+     * @returns {void}
+     */
+    static mainScreen(): void;
+    /**
+     * 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 {void}
+     */
+    static saveScreen(): void;
+    /**
+     * Restore previously saved screen contents.
+     *
+     * @returns {void}
+     */
+    static restoreScreen(): void;
 }
 //# 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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"}