@gesslar/toolkit 0.3.0 → 0.5.0

package/src/lib/Data.js

@@ -160,7 +160,7 @@ export default class Data {
     // Special cases that need extra validation
     switch(valueType) {
       case "Number":
-        return valueType === "Number" && !isNaN(value) // Excludes NaN
+        return type === "Number" && !isNaN(value) // Excludes NaN
       default:
         return valueType === type
     }

package/src/lib/DirectoryObject.js

@@ -48,6 +48,8 @@ export default class DirectoryObject extends FS {
     extension: null,
     isFile: false,
     isDirectory: true,
+    trail: null,
+    sep: null,
   })
 
   /**
@@ -63,6 +65,8 @@ export default class DirectoryObject extends FS {
     const fileUri = FS.pathToUri(absolutePath)
     const filePath = FS.uriToPath(fileUri)
     const baseName = path.basename(absolutePath) || "."
+    const trail = filePath.split(path.sep)
+    const sep = path.sep
 
     this.#meta.supplied = fixedDir
     this.#meta.path = filePath
@@ -70,6 +74,8 @@ export default class DirectoryObject extends FS {
     this.#meta.name = baseName
     this.#meta.extension = ""
     this.#meta.module = baseName
+    this.#meta.trail = trail
+    this.#meta.sep = sep
 
     Object.freeze(this.#meta)
   }
@@ -173,6 +179,27 @@ export default class DirectoryObject extends FS {
     return this.#meta.extension
   }
 
+  /**
+   * Returns the platform-specific path separator.
+   *
+   * @returns {string} The path separator ('/' on Unix, '\\' on Windows)
+   */
+  get sep() {
+    return this.#meta.sep
+  }
+
+  /**
+   * Returns the directory path split into segments.
+   *
+   * @returns {string[]} Array of path segments
+   * @example
+   * const dir = new DirectoryObject('/path/to/directory')
+   * console.log(dir.trail) // ['', 'path', 'to', 'directory']
+   */
+  get trail() {
+    return this.#meta.trail
+  }
+
   /**
    * Returns false. Because this is a directory.
    *
@@ -217,33 +244,29 @@ export default class DirectoryObject extends FS {
       {withFileTypes: true}
     )
 
-    const results = await Promise.all(
-      found.map(async dirent => {
-        const fullPath = path.join(this.path, dirent.name)
-        const stat = await fs.stat(fullPath)
-
-        return {dirent, stat, fullPath}
-      }),
-    )
-
-    const files = results
-      .filter(({stat}) => stat.isFile())
-      .map(({fullPath}) => new FileObject(fullPath))
+    const files = found
+      .filter(dirent => dirent.isFile())
+      .map(dirent => new FileObject(path.join(this.path, dirent.name)))
 
-    const directories = results
-      .filter(({stat}) => stat.isDirectory())
-      .map(({fullPath}) => new DirectoryObject(fullPath))
+    const directories = found
+      .filter(dirent => dirent.isDirectory())
+      .map(dirent => new DirectoryObject(path.join(this.path, dirent.name)))
 
     return {files, directories}
   }
 
   /**
-   * Ensures a directory exists, creating it if necessary
+   * Ensures a directory exists, creating it if necessary.
+   * Gracefully handles the case where the directory already exists.
    *
    * @async
-   * @param {object} [options] - Any options to pass to mkdir
+   * @param {object} [options] - Options to pass to fs.mkdir (e.g., {recursive: true, mode: 0o755})
    * @returns {Promise<void>}
-   * @throws {Sass} If directory creation fails
+   * @throws {Sass} If directory creation fails for reasons other than already existing
+   * @example
+   * // Create directory recursively
+   * const dir = new DirectoryObject('./build/output')
+   * await dir.assureExists({recursive: true})
    */
   async assureExists(options = {}) {
     if(await this.exists)
@@ -252,7 +275,60 @@ export default class DirectoryObject extends FS {
     try {
       await fs.mkdir(this.path, options)
     } catch(e) {
+      if(e.code === "EEXIST") {
+        // Directory already exists, ignore
+        return
+      }
+
       throw Sass.new(`Unable to create directory '${this.path}': ${e.message}`)
     }
   }
+
+  /**
+   * Private generator that walks up the directory tree.
+   *
+   * @private
+   * @generator
+   * @yields {DirectoryObject} Parent directory objects from current to root
+   */
+  *#walkUp() {
+    if(!Array.isArray(this.trail))
+      return
+
+    const curr = structuredClone(this.trail)
+
+    while(curr.length > 0) {
+      const joined = curr.join(this.sep)
+
+      // Stop if we've reached an empty path (which would resolve to CWD)
+      if(joined === "" || joined === this.sep) {
+        // Yield the root and stop
+        yield new DirectoryObject(this.sep)
+        break
+      }
+
+      yield new DirectoryObject(joined)
+      curr.pop()
+    }
+  }
+
+  /**
+   * Generator that walks up the directory tree, yielding each parent directory.
+   * Starts from the current directory and yields each parent until reaching the root.
+   *
+   * @returns {object} Generator yielding parent DirectoryObject instances
+   * @example
+   * const dir = new DirectoryObject('/path/to/deep/directory')
+   * for(const parent of dir.walkUp) {
+   *   console.log(parent.path)
+   *   // /path/to/deep/directory
+   *   // /path/to/deep
+   *   // /path/to
+   *   // /path
+   *   // /
+   * }
+   */
+  get walkUp() {
+    return this.#walkUp()
+  }
 }

package/src/lib/FileObject.js

@@ -10,6 +10,7 @@ import path from "node:path"
 import util from "node:util"
 import YAML from "yaml"
 
+import Data from "./Data.js"
 import DirectoryObject from "./DirectoryObject.js"
 import FS from "./FS.js"
 import Sass from "./Sass.js"
@@ -87,13 +88,18 @@ export default class FileObject extends FS {
 
     const {dir,base,ext} = this.#deconstructFilenameToParts(fixedFile)
 
-    if(!directory) {
-      directory = new DirectoryObject(dir)
-    } else if(typeof directory === "string") {
-      directory = new DirectoryObject(directory)
-    }
+    const directoryObject = (() => {
+      switch(Data.typeOf(directory)) {
+        case "String":
+          return new DirectoryObject(directory)
+        case "DirectoryObject":
+          return directory
+        default:
+          return new DirectoryObject(dir)
+      }
+    })()
 
-    const final = FS.resolvePath(directory?.path ?? ".", fixedFile)
+    const final = FS.resolvePath(directoryObject.path ?? ".", fixedFile)
 
     const resolved = final
     const fileUri = FS.pathToUri(resolved)
@@ -104,10 +110,7 @@ export default class FileObject extends FS {
     this.#meta.name = base
     this.#meta.extension = ext
     this.#meta.module = path.basename(this.supplied, this.extension)
-
-    const {dir: newDir} = this.#deconstructFilenameToParts(this.path)
-
-    this.#meta.directory = new DirectoryObject(newDir)
+    this.#meta.directory = directoryObject
 
     Object.freeze(this.#meta)
   }
@@ -363,29 +366,46 @@ export default class FileObject extends FS {
   }
 
   /**
-   * Writes content to a file synchronously.
+   * Writes content to a file asynchronously.
+   * Validates that the parent directory exists before writing.
    *
    * @param {string} content - The content to write
-   * @param {string} encoding - The encoding in which to write.
+   * @param {string} [encoding] - The encoding in which to write (default: "utf8")
    * @returns {Promise<void>}
+   * @throws {Sass} If the file path is invalid or the parent directory doesn't exist
+   * @example
+   * const file = new FileObject('./output/data.json')
+   * await file.write(JSON.stringify({key: 'value'}))
    */
   async write(content, encoding="utf8") {
     if(!this.path)
       throw Sass.new("No absolute path in file")
 
-    await fs.writeFile(this.path, content, encoding)
+    if(await this.directory.exists)
+      await fs.writeFile(this.path, content, encoding)
+
+    else
+      throw Sass.new(`Invalid directory, ${this.directory.uri}`)
   }
 
   /**
-   * Loads an object from JSON or YAML provided a fileMap
+   * Loads an object from JSON or YAML file.
+   * Attempts to parse content as JSON5 first, then falls back to YAML if specified.
    *
-   * @param {string} [type] - The expected type of data to parse.
-   * @param {string} [encoding] - The encoding to read the file as.
-   * @returns {Promise<unknown>} The parsed data object.
+   * @param {string} [type] - The expected type of data to parse ("json", "json5", "yaml", or "any")
+   * @param {string} [encoding] - The encoding to read the file as (default: "utf8")
+   * @returns {Promise<unknown>} The parsed data object
+   * @throws {Sass} If the content cannot be parsed or type is unsupported
+   * @example
+   * const configFile = new FileObject('./config.json5')
+   * const config = await configFile.loadData('json5')
+   *
+   * // Auto-detect format
+   * const data = await configFile.loadData('any')
    */
   async loadData(type="any", encoding="utf8") {
     const content = await this.read(encoding)
-    const normalizedType = type.toLocaleLowerCase()
+    const normalizedType = type.toLowerCase()
     const toTry = {
       json5: [JSON5],
       json: [JSON5],
@@ -394,7 +414,7 @@ export default class FileObject extends FS {
     }[normalizedType]
 
     if(!toTry) {
-      throw Sass.new(`Unsupported data type '${type}'. Supported types: json, json5, yaml, any`)
+      throw Sass.new(`Unsupported data type '${type}'. Supported types: json, json5, yaml.`)
     }
 
     for(const format of toTry) {

package/src/lib/Glog.js

@@ -1,7 +1,8 @@
-import Data from "./Data.js"
-import Util from "./Util.js"
 import c from "@gesslar/colours"
+
+import Data from "./Data.js"
 import Term from "./Term.js"
+import Util from "./Util.js"
 // ErrorStackParser will be dynamically imported when needed
 
 /**

package/src/lib/Hooks.js

@@ -0,0 +1,194 @@
+import {setTimeout as timeout} from "timers/promises"
+
+import FileObject from "./FileObject.js"
+import Sass from "./Sass.js"
+import Util from "./Util.js"
+import Valid from "./Valid.js"
+
+/**
+ * Generic base class for managing hooks with configurable event types.
+ * Provides common functionality for hook registration, execution, and lifecycle management.
+ * Designed to be extended by specific implementations.
+ */
+export default class Hooks {
+  #hooksFile = null
+  #hooks = null
+  #actionKind = null
+  #timeout = 1000 // Default 1 second timeout
+  #debug = null
+
+  /**
+   * Creates a new BaseHookManager instance.
+   *
+   * @param {object} config - Configuration object
+   * @param {string} config.actionKind - Action identifier
+   * @param {FileObject} config.hooksFile - File object containing hooks with uri property
+   * @param {number} [config.hookTimeout] - Hook execution timeout in milliseconds
+   * @param {unknown} [config.hooks] - The hooks object
+   * @param {import('../types.js').DebugFunction} debug - Debug function from Glog.
+   */
+  constructor({actionKind, hooksFile, hooks, hookTimeout = 1000}, debug) {
+    this.#actionKind = actionKind
+    this.#hooksFile = hooksFile
+    this.#hooks = hooks
+    this.#timeout = hookTimeout
+    this.#debug = debug
+  }
+
+  /**
+   * Gets the action identifier.
+   *
+   * @returns {string} Action identifier or instance
+   */
+  get actionKind() {
+    return this.#actionKind
+  }
+
+  /**
+   * Gets the hooks file object.
+   *
+   * @returns {FileObject} File object containing hooks
+   */
+  get hooksFile() {
+    return this.#hooksFile
+  }
+
+  /**
+   * Gets the loaded hooks object.
+   *
+   * @returns {object|null} Hooks object or null if not loaded
+   */
+  get hooks() {
+    return this.#hooks
+  }
+
+  /**
+   * Gets the hook execution timeout in milliseconds.
+   *
+   * @returns {number} Timeout in milliseconds
+   */
+  get timeout() {
+    return this.#timeout
+  }
+
+  /**
+   * Gets the setup hook function if available.
+   *
+   * @returns {(args: object) => unknown|null} Setup hook function or null
+   */
+  get setup() {
+    return this.hooks?.setup || null
+  }
+
+  /**
+   * Gets the cleanup hook function if available.
+   *
+   * @returns {(args: object) => unknown|null} Cleanup hook function or null
+   */
+  get cleanup() {
+    return this.hooks?.cleanup || null
+  }
+
+  /**
+   * Static factory method to create and initialize a hook manager.
+   * Loads hooks from the specified file and returns an initialized instance.
+   * Override loadHooks() in subclasses to customize hook loading logic.
+   *
+   * @param {object} config - Same configuration object as constructor
+   * @param {string|object} config.actionKind - Action identifier or instance
+   * @param {FileObject} config.hooksFile - File object containing hooks with uri property
+   * @param {number} [config.timeOut] - Hook execution timeout in milliseconds
+   * @param {import('../types.js').DebugFunction} debug - The debug function.
+   * @returns {Promise<Hooks|null>} Initialized hook manager or null if no hooks found
+   */
+  static async new(config, debug) {
+    debug("Creating new HookManager instance with args: %o", 2, config)
+
+    const instance = new this(config, debug)
+    const hooksFile = instance.hooksFile
+
+    debug("Loading hooks from %o", 2, hooksFile.uri)
+
+    debug("Checking hooks file exists: %o", 2, hooksFile.uri)
+    if(!await hooksFile.exists)
+      throw Sass.new(`No such hooks file, ${hooksFile.uri}`)
+
+    try {
+      const hooksImport = await hooksFile.import()
+
+      if(!hooksImport)
+        return null
+
+      debug("Hooks file imported successfully as a module", 2)
+
+      const actionKind = instance.actionKind
+      if(!hooksImport[actionKind])
+        return null
+
+      const hooks = new hooksImport[actionKind]({debug})
+
+      debug(hooks.constructor.name, 4)
+
+      // Attach common properties to hooks
+      instance.#hooks = hooks
+
+      debug("Hooks %o loaded successfully for %o", 2, hooksFile.uri, instance.actionKind)
+
+      return instance
+    } catch(error) {
+      debug("Failed to load hooks %o: %o", 1, hooksFile.uri, error.message)
+
+      return null
+    }
+  }
+
+  async callHook(kind, activityName, context) {
+    try {
+      const debug = this.#debug
+      const hooks = this.#hooks
+
+      if(!hooks)
+        return
+
+      const hookName = `${kind}$${activityName}`
+
+      debug("Looking for hook: %o", 4, hookName)
+
+      const hook = hooks[hookName]
+      if(!hook)
+        return
+
+      debug("Triggering hook: %o", 4, hookName)
+      Valid.type(hook, "Function", `Hook "${hookName}" is not a function`)
+
+      const hookFunction = async() => {
+        debug("Hook function starting execution: %o", 4, hookName)
+
+        const duration = (await Util.time(() => hook.call(this.#hooks, context))).cost
+
+        debug("Hook function completed successfully: %o, after %oms", 4, hookName, duration)
+      }
+
+      const hookTimeout = this.timeout
+      const expireAsync = (async() => {
+        await timeout(hookTimeout)
+        throw Sass.new(`Hook ${hookName} execution exceeded timeout of ${hookTimeout}ms`)
+      })()
+
+      try {
+        debug("Starting Promise race for hook: %o", 4, hookName)
+        await Util.race([
+          hookFunction(),
+          expireAsync
+        ])
+      } catch(error) {
+        throw Sass.new(`Processing hook ${kind}$${activityName}`, error)
+      }
+
+      debug("We made it throoough the wildernessss", 4)
+
+    } catch(error) {
+      throw Sass.new(`Processing hook ${kind}$${activityName}`, error)
+    }
+  }
+}