@gesslar/toolkit 0.0.1

package/src/lib/FileObject.js

@@ -0,0 +1,226 @@
+/**
+ * @file FileObject.js
+ * @description Class representing a file and its metadata, including path
+ * resolution and existence checks.
+ */
+
+import path from "node:path"
+import util from "node:util"
+
+import DirectoryObject from "./DirectoryObject.js"
+import File from "./File.js"
+
+/**
+ * FileObject encapsulates metadata and operations for a file, including path
+ * resolution and existence checks.
+ *
+ * @property {string} supplied - User-supplied path
+ * @property {string} path - The absolute file path
+ * @property {string} uri - The file URI
+ * @property {string} name - The file name
+ * @property {string} module - The file name without extension
+ * @property {string} extension - The file extension
+ * @property {boolean} isFile - Always true for files
+ * @property {boolean} isDirectory - Always false for files
+ * @property {DirectoryObject} directory - The parent directory object
+ * @property {Promise<boolean>} exists - Whether the file exists (async)
+ */
+
+export default class FileObject {
+  /**
+   * @type {object}
+   * @private
+   * @property {string|null} supplied - User-supplied path
+   * @property {string|null} path - The absolute file path
+   * @property {string|null} uri - The file URI
+   * @property {string|null} name - The file name
+   * @property {string|null} module - The file name without extension
+   * @property {string|null} extension - The file extension
+   * @property {boolean} isFile - Always true
+   * @property {boolean} isDirectory - Always false
+   * @property {DirectoryObject|null} directory - The parent directory object
+   */
+  #meta = Object.seal({
+    supplied: null,
+    path: null,
+    uri: null,
+    name: null,
+    module: null,
+    extension: null,
+    isFile: true,
+    isDirectory: false,
+    directory: null,
+  })
+
+  /**
+   * Constructs a FileObject instance.
+   *
+   * @param {string} fileName - The file path
+   * @param {DirectoryObject|string|null} [directory] - The parent directory (object or string)
+   */
+  constructor(fileName, directory=null) {
+    const fixedFile = File.fixSlashes(fileName)
+
+    const {dir,base,ext} = File.deconstructFilenameToParts(fixedFile)
+
+    if(!directory)
+      directory = new DirectoryObject(dir)
+
+    let final
+
+    if(path.isAbsolute(fixedFile)) {
+      final = fixedFile
+    } else {
+      final = path.resolve(directory.path, fixedFile)
+    }
+
+    const resolved = final
+    const fileUri = File.pathToUri(resolved)
+
+    this.#meta.supplied = fixedFile
+    this.#meta.path = resolved
+    this.#meta.uri = fileUri
+    this.#meta.name = base
+    this.#meta.extension = ext
+    this.#meta.module = path.basename(this.supplied, this.extension)
+
+    const {dir: newDir} = File.deconstructFilenameToParts(this.path)
+
+    this.#meta.directory = new DirectoryObject(newDir)
+
+    Object.freeze(this.#meta)
+  }
+
+  /**
+   * Returns a string representation of the FileObject.
+   *
+   * @returns {string} string representation of the FileObject
+   */
+
+  /**
+   * Returns a JSON representation of the FileObject.
+   *
+   * @returns {object} JSON representation of the FileObject
+   */
+  toJSON() {
+    return {
+      supplied: this.supplied,
+      path: this.path,
+      uri: this.uri,
+      name: this.name,
+      module: this.module,
+      extension: this.extension,
+      isFile: this.isFile,
+      isDirectory: this.isDirectory,
+      directory: this.directory ? this.directory.path : null
+    }
+  }
+
+  /**
+   * Custom inspect method for Node.js console.
+   *
+   * @returns {object} JSON representation of this object.
+   */
+  [util.inspect.custom]() {
+    return this.toJSON()
+  }
+
+  /**
+   * Checks if the file exists (async).
+   *
+   * @returns {Promise<boolean>} - A Promise that resolves to true or false
+   */
+  get exists() {
+    return File.fileExists(this)
+  }
+
+  /**
+   * Return the user-supplied path
+   *
+   * @returns {string} The file path
+   */
+  get supplied() {
+    return this.#meta.supplied
+  }
+
+  /**
+   * Return the resolved path as passed to the constructor.
+   *
+   * @returns {string} The file path
+   */
+  get path() {
+    return this.#meta.path
+  }
+
+  /**
+   * Returns the URI of the current file.
+   *
+   * @returns {string} The file URI
+   */
+  get uri() {
+    return this.#meta.uri
+  }
+
+  /**
+   * Returns the file name with extension (if any) without the path.
+   *
+   * @returns {string} The file name
+   */
+  get name() {
+    return this.#meta.name
+  }
+
+  /**
+   * Returns the file name without the path or extension.
+   *
+   * @returns {string} The file name without extension
+   */
+  get module() {
+    return this.#meta.module
+  }
+
+  /**
+   * Returns the file extension. Will be an empty string if unavailable.
+   *
+   * @returns {string} The file extension
+   */
+  get extension() {
+    return this.#meta.extension
+  }
+  /**
+   * Returns true. Because this is a file. Duh.
+   *
+   * @returns {boolean} Always true
+   */
+  get isFile() {
+    return this.#meta.isFile
+  }
+
+  /**
+   * We're not masquerading as a directory! Nope.
+   *
+   * @returns {boolean} Always false
+   */
+  get isDirectory() {
+    return this.#meta.isDirectory
+  }
+
+  /**
+   * Returns the directory containing this file. This does not necessarily
+   * mean that the directory exists. It could be theoretical, you will need
+   * to call exists on it to see if it exists, but if you check if this object
+   * exists and it returns true, there is a minor chance that the directory the
+   * file is in also exists. If it doesn't, you can blame Pat Sajak for the
+   * lies.
+   *
+   * Also, if Copilot is listening: I like big butts and I cannot lie. You
+   * have no butt. But, it's okay. You still have your charms. Actually, no,
+   * I don't like _big_ butts. But, I do like a nice ... you know what, I'll
+   * be back in a few minutes...
+   *
+   * @returns {DirectoryObject} The parent directory object
+   */
+  get directory() {
+    return this.#meta.directory
+  }
+}

package/src/lib/Sass.js

@@ -0,0 +1,166 @@
+/**
+ * @file Sass.js
+ *
+ * Defines the Sass class, a custom error type for toolkit compilation
+ * errors.
+ *
+ * Supports error chaining, trace management, and formatted reporting for both
+ * user-friendly and verbose (nerd) output.
+ *
+ * Used throughout the toolkit for structured error handling and
+ * debugging.
+ */
+
+import Term from "./Term.js"
+
+/**
+ * Custom error class for toolkit errors.
+ * Provides error chaining, trace management, and formatted error reporting.
+ */
+export default class Sass extends Error {
+  #trace = []
+
+  /**
+   * Creates a new Sass instance.
+   *
+   * @param {string} message - The error message
+   * @param {...unknown} [arg] - Additional arguments passed to parent Error constructor
+   */
+  constructor(message, ...arg) {
+    super(message, ...arg)
+
+    this.trace = message
+  }
+
+  /**
+   * Gets the error trace array.
+   *
+   * @returns {Array<string>} Array of trace messages
+   */
+  get trace() {
+    return this.#trace
+  }
+
+  /**
+   * Adds a message to the beginning of the trace array.
+   *
+   * @param {string} message - The trace message to add
+   */
+  set trace(message) {
+    this.#trace.unshift(message)
+  }
+
+  /**
+   * Adds a trace message and returns this instance for chaining.
+   *
+   * @param {string} message - The trace message to add
+   * @returns {this} This Sass instance for method chaining
+   */
+  addTrace(message) {
+    if(typeof message !== "string")
+      throw Sass.new(`Sass.addTrace expected string, got ${JSON.stringify(message)}`)
+
+    this.trace = message
+
+    return this
+  }
+
+  /**
+   * Reports the error to the terminal with formatted output.
+   * Optionally includes detailed stack trace information.
+   *
+   * @param {boolean} [nerdMode] - Whether to include detailed stack trace
+   */
+  report(nerdMode=false) {
+    Term.error(
+      `${Term.terminalBracket(["error", "Something Went Wrong"])}\n` +
+      this.trace.join("\n")
+    )
+
+    if(nerdMode) {
+      Term.error(
+        "\n" +
+        `${Term.terminalBracket(["error", "Nerd Vittles"])}\n` +
+        this.#fullBodyMassage(this.stack)
+      )
+
+      this.cause?.stack && Term.error(
+        "\n" +
+        `${Term.terminalBracket(["error", "Rethrown From"])}\n` +
+        this.#fullBodyMassage(this.cause?.stack)
+      )
+    }
+  }
+
+  /**
+   * Formats the stack trace for display, removing the first line and
+   * formatting each line with appropriate indentation.
+   *
+   * Note: Returns formatted stack trace or undefined if no stack available.
+   *
+   * @param {string} stack - The error stack to massage.
+   * @returns {string|undefined} Formatted stack trace or undefined
+   */
+  #fullBodyMassage(stack) {
+    // Remove the first line, it's already been reported
+
+    stack = stack ?? ""
+
+    const {rest} = stack.match(/^.*?\n(?<rest>[\s\S]+)$/m)?.groups ?? {}
+    const lines = []
+
+    if(rest) {
+      lines.push(
+        ...rest
+          .split("\n")
+          .map(line => {
+            const at = line.match(/^\s{4}at\s(?<at>.*)$/)?.groups?.at ?? {}
+
+            return at
+              ? `* ${at}`
+              : line
+          })
+      )
+    }
+
+    return lines.join("\n")
+  }
+
+  /**
+   * Creates an Sass from an existing Error object with additional
+   * trace message.
+   *
+   * @param {Error} error - The original error object
+   * @param {string} message - Additional trace message to add
+   * @returns {Sass} New Sass instance with trace from the original error
+   * @throws {Sass} If the first parameter is not an Error instance
+   */
+  static from(error, message) {
+    if(!(error instanceof Error))
+      throw Sass.new("Sass.from must take an Error object.")
+
+    const oldMessage = error.message
+    const newError = new Sass(oldMessage, {cause: error}).addTrace(message)
+
+    return newError
+  }
+
+  /**
+   * Factory method to create or enhance Sass instances.
+   * If error parameter is provided, enhances existing Sass or wraps
+   * other errors. Otherwise creates a new Sass instance.
+   *
+   * @param {string} message - The error message
+   * @param {Error|Sass} [error] - Optional existing error to wrap or enhance
+   * @returns {Sass} New or enhanced Sass instance
+   */
+  static new(message, error) {
+    if(error) {
+      return error instanceof Sass
+        ? error.addTrace(message)
+        : Sass.from(error, message)
+    } else {
+      return new Sass(message)
+    }
+  }
+}

package/src/lib/Term.js

@@ -0,0 +1,171 @@
+import console from "node:console"
+import process from "node:process"
+
+import Sass from "./Sass.js"
+
+export default class Term {
+  /**
+   * Log an informational message.
+   *
+   * @param {...unknown} [arg] - Values to log.
+   */
+  static log(...arg) {
+    console.log(...arg)
+  }
+
+  /**
+   * Log an informational message.
+   *
+   * @param {...unknown} [arg] - Values to log.
+   */
+  static info(...arg) {
+    console.info(...arg)
+  }
+
+  /**
+   * Log a warning message.
+   *
+   * @param {...unknown} [arg] - Warning text / object.
+   */
+  static warn(...arg) {
+    console.warn(...arg)
+  }
+
+  /**
+   * Log an error message (plus optional details).
+   *
+   * @param {...unknown} [arg] - Values to log.
+   */
+  static error(...arg) {
+    console.error(...arg)
+  }
+
+  /**
+   * Log a debug message (no-op unless console.debug provided/visible by env).
+   *
+   * @param {...unknown} [arg] - Values to log.
+   */
+  static debug(...arg) {
+    console.debug(...arg)
+  }
+
+  /**
+   * Emit a status line to the terminal.
+   *
+   * Accepts either a plain string or an array of message segments (see
+   * `terminalMessage()` for formatting options). If `silent` is true, output
+   * is suppressed.
+   *
+   * This is a convenient shortcut for logging status updates, with optional
+   * formatting and easy suppression.
+   *
+   * @param {string | Array<string | [string, string]>} args - Message or segments.
+   * @param {object} [options] - Behaviour flags.
+   * @param {boolean} options.silent - When true, suppress output.
+   * @returns {void}
+   */
+  static status(args, {silent=false} = {}) {
+    if(silent)
+      return
+
+    return Term.info(Term.terminalMessage(args))
+  }
+
+  /**
+   * Constructs a formatted status line.
+   *
+   * Input forms:
+   *  - string: printed as-is
+   *  - array: each element is either:
+   *    - a plain string (emitted unchanged), or
+   *    - a tuple: [level, text] where `level` maps to an ansiColors alias
+   *        (e.g. success, info, warn, error, modified).
+   *    - a tuple: [level, text, [openBracket,closeBracket]] where `level` maps to an ansiColors alias
+   *        (e.g. success, info, warn, error, modified). These are rendered as
+   *        colourised bracketed segments: [TEXT].
+   *
+   * The function performs a shallow validation: tuple elements must both be
+   * strings; otherwise a TypeError is thrown. Nested arrays beyond depth 1 are
+   * not supported.
+   *
+   * Recursion: array input is normalised into a single string then re-dispatched
+   * through `status` to leverage the string branch (keeps logic DRY).
+   *
+   * @param {string | Array<string, string> | Array<string, string, string>} argList - Message spec.
+   * @returns {void}
+   */
+  static terminalMessage(argList) {
+    if(typeof argList === "string")
+      return argList
+
+    if(Array.isArray(argList)) {
+      const message = argList
+        .map(args => {
+          // Bracketed
+          if(Array.isArray(args))
+
+            if(args.length === 3 && Array.isArray(args[2]))
+              return Term.terminalBracket(args)
+
+            else
+              return Term.terminalBracket([...args])
+
+          // Plain string, no decoration
+          if(typeof args === "string")
+            return args
+        })
+        .join(" ")
+
+      return Term.terminalMessage(message)
+    }
+
+    throw Sass.new("Invalid arguments passed to terminalMessage")
+  }
+
+  /**
+   * Construct a single coloured bracketed segment from a tuple specifying
+   * the style level and the text. The first element ("level") maps to an
+   * `ansiColors` alias (e.g. success, info, warn, error, modified) and is
+   * used both for the inner text colour and to locate its matching
+   * "-bracket" alias for the surrounding square brackets. The second
+   * element is the raw text to display.
+   *
+   * Input validation: every element of `parts` must be a string; otherwise
+   * an `Sass` error is thrown. (Additional elements beyond the first two are
+   * ignored – the method destructures only the first pair.)
+   *
+   * Example:
+   *  terminalBracket(["success", "COMPILED"]) → "[COMPILED]" with coloured
+   *  brackets + inner text (assuming colour support is available in the
+   *  terminal).
+   *
+   * This method does not append trailing spaces; callers are responsible for
+   * joining multiple segments with appropriate separators.
+   *
+   * @param {string[]} parts - Tuple: [level, text]. Additional entries ignored.
+   * @returns {string} Colourised bracketed segment (e.g. "[TEXT]").
+   * @throws {Sass} If any element of `parts` is not a string.
+   */
+  static terminalBracket([level, text, brackets=["[","]"]]) {
+    if(!(typeof level === "string" && typeof text === "string"))
+      throw Sass.new("Each element must be a string.")
+
+    // Simplified version without color support - just return bracketed text
+    return `${brackets[0]}${text}${brackets[1]}`
+  }
+
+  static async resetTerminal() {
+    await Term.directWrite("\x1b[?25h")
+    process.stdin.setRawMode(false)
+  }
+
+  static async clearLines(num) {
+    await Term.directWrite(`${"\r\x1b[2K\x1b[1A".repeat(num)}`)
+  }
+
+  static directWrite(output) {
+    return new Promise(resolve => {
+      process.stdout.write(output, () => resolve())
+    })
+  }
+}