@gesslar/toolkit 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Get in, bitches, we're going toolkitting.",
   "main": "./src/index.js",
   "type": "module",
@@ -26,7 +26,7 @@
     "update": "npx npm-check-updates -u && npm install",
     "test": "node --test tests/unit/*.test.js",
     "test:unit": "node --test tests/unit/*.test.js",
-    "pr": "gt submit --cli --publish --restack --ai --merge-when-ready"
+    "pr": "gt submit --publish --restack --ai"
   },
   "repository": {
     "type": "git",

package/src/lib/BaseActionManager.js

@@ -47,7 +47,7 @@ export default class BaseActionManager {
   }
 
   set hookManager(hookManager) {
-    if (this.hookManager)
+    if(this.hookManager)
       throw new Error("Hook manager already set")
 
     this.#hookManager = hookManager
@@ -81,7 +81,7 @@ export default class BaseActionManager {
   /**
    * Initialize the action manager with the provided definition.
    * Override in subclasses to add specific validation or setup.
-   * 
+   *
    * @param {object} actionDefinition - Action definition
    * @protected
    */
@@ -92,10 +92,10 @@ export default class BaseActionManager {
 
     const {action, file, contract} = actionDefinition
 
-    if (!action)
+    if(!action)
       throw new Error("Action is required")
 
-    if (!contract)
+    if(!contract)
       throw new Error("Contract is required")
 
     this.#action = action
@@ -108,7 +108,7 @@ export default class BaseActionManager {
   /**
    * Attach hooks to the action instance.
    * Override in subclasses to customize hook attachment.
-   * 
+   *
    * @param {object} hookManager - Hook manager instance
    * @protected
    */
@@ -121,7 +121,7 @@ export default class BaseActionManager {
   /**
    * Setup the action by creating and configuring the runner.
    * Override setupActionInstance() in subclasses for custom setup logic.
-   * 
+   *
    * @returns {Promise<void>}
    */
   async setupAction() {
@@ -134,7 +134,7 @@ export default class BaseActionManager {
   /**
    * Setup the action instance and create the runner.
    * Override in subclasses to customize action setup.
-   * 
+   *
    * @protected
    */
   async #setupActionInstance() {
@@ -142,7 +142,7 @@ export default class BaseActionManager {
     const setup = actionInstance?.setup
 
     // Setup is required for actions.
-    if (Data.typeOf(setup) === "Function") {
+    if(Data.typeOf(setup) === "Function") {
       const builder = new ActionBuilder(actionInstance)
       const configuredBuilder = setup(builder)
       const buildResult = configuredBuilder.build()
@@ -160,12 +160,12 @@ export default class BaseActionManager {
 
   /**
    * Run the action with the provided input.
-   * 
+   *
    * @param {unknown} result - Input to pass to the action
    * @returns {Promise<unknown>} Action result
    */
   async runAction(result) {
-    if (!this.#runner)
+    if(!this.#runner)
       throw new Error("Action not set up. Call setupAction() first.")
 
     return await this.#runner.run(result)
@@ -173,7 +173,7 @@ export default class BaseActionManager {
 
   /**
    * Cleanup the action and hooks.
-   * 
+   *
    * @returns {Promise<void>}
    */
   async cleanupAction() {
@@ -186,7 +186,7 @@ export default class BaseActionManager {
   /**
    * Setup hooks if hook manager is present.
    * Override in subclasses to customize hook setup.
-   * 
+   *
    * @protected
    */
   async #setupHooks() {
@@ -195,10 +195,10 @@ export default class BaseActionManager {
     const type = Data.typeOf(setup)
 
     // No hooks attached.
-    if (type === "Null" || type === "Undefined")
+    if(type === "Null" || type === "Undefined")
       return
 
-    if (type !== "Function")
+    if(type !== "Function")
       throw Sass.new("Hook setup must be a function.")
 
     await setup.call(
@@ -213,13 +213,13 @@ export default class BaseActionManager {
   /**
    * Cleanup hooks if hook manager is present.
    * Override in subclasses to customize hook cleanup.
-   * 
+   *
    * @protected
    */
   async #cleanupHooks() {
     const cleanup = this.hookManager?.cleanup
 
-    if (!cleanup)
+    if(!cleanup)
       return
 
     await cleanup.call(this.hookManager.hooks)
@@ -228,13 +228,13 @@ export default class BaseActionManager {
   /**
    * Cleanup the action instance.
    * Override in subclasses to add custom cleanup logic.
-   * 
+   *
    * @protected
    */
   async #cleanupActionInstance() {
     const cleanup = this.action?.cleanup
 
-    if (!cleanup)
+    if(!cleanup)
       return
 
     await cleanup.call(this.action)
@@ -243,4 +243,4 @@ export default class BaseActionManager {
   toString() {
     return `${this.#file?.module || "UNDEFINED"} (${this.meta?.action || "UNDEFINED"})`
   }
-}
+}

package/src/lib/BaseHookManager.js

@@ -1,4 +1,4 @@
-import { setTimeout as timeoutPromise } from "timers/promises"
+import {setTimeout as timeoutPromise} from "timers/promises"
 import Collection from "./Collection.js"
 import Data from "./Data.js"
 import Sass from "./Sass.js"
@@ -22,8 +22,8 @@ export default class BaseHookManager {
    * @param {string|object} config.action - Action identifier or instance
    * @param {object} config.hooksFile - File object containing hooks
    * @param {object} config.logger - Logger instance
-   * @param {number} [config.timeOut=1000] - Hook execution timeout in milliseconds
-   * @param {string[]} [config.allowedEvents=[]] - Array of allowed event types for validation
+   * @param {number} [config.timeOut] - Hook execution timeout in milliseconds
+   * @param {string[]} [config.allowedEvents] - Array of allowed event types for validation
    */
   constructor({action, hooksFile, logger, timeOut = 1000, allowedEvents = []}) {
     this.#action = action
@@ -68,7 +68,7 @@ export default class BaseHookManager {
   /**
    * Static factory method to create and initialize a hook manager.
    * Override loadHooks() in subclasses to customize hook loading logic.
-   * 
+   *
    * @param {object} config - Same as constructor config
    * @returns {Promise<BaseHookManager|null>} Initialized hook manager or null if no hooks found
    */
@@ -83,22 +83,23 @@ export default class BaseHookManager {
     debug("Loading hooks from `%s`", 2, hooksFile.uri)
 
     debug("Checking hooks file exists: %j", 2, hooksFile)
-    
+
     try {
       const hooksFileContent = await import(hooksFile.uri)
+
       debug("Hooks file loaded successfully", 2)
 
-      if (!hooksFileContent)
+      if(!hooksFileContent)
         throw new Error(`Hooks file is empty: ${hooksFile.uri}`)
 
       const hooks = await instance.loadHooks(hooksFileContent)
-      
-      if (Data.isEmpty(hooks))
+
+      if(Data.isEmpty(hooks))
         return null
 
       debug("Hooks found for action: `%s`", 2, instance.action)
 
-      if (!hooks)
+      if(!hooks)
         return null
 
       // Attach common properties to hooks
@@ -109,8 +110,9 @@ export default class BaseHookManager {
       debug("Hooks loaded successfully for `%s`", 2, instance.action)
 
       return instance
-    } catch (error) {
+    } catch(error) {
       debug("Failed to load hooks: %s", 1, error.message)
+
       return null
     }
   }
@@ -118,7 +120,7 @@ export default class BaseHookManager {
   /**
    * Load hooks from the imported hooks file content.
    * Override in subclasses to customize hook loading logic.
-   * 
+   *
    * @param {object} hooksFileContent - Imported hooks file content
    * @returns {Promise<object|null>} Loaded hooks object or null if no hooks found
    * @protected
@@ -126,7 +128,7 @@ export default class BaseHookManager {
   async loadHooks(hooksFileContent) {
     const hooks = hooksFileContent.default || hooksFileContent.Hooks
 
-    if (!hooks)
+    if(!hooks)
       throw new Error(`\`${this.hooksFile.uri}\` contains no hooks.`)
 
     // Default implementation: look for hooks by action name
@@ -137,7 +139,7 @@ export default class BaseHookManager {
 
   /**
    * Trigger a hook by event name.
-   * 
+   *
    * @param {string} event - The type of hook to trigger
    * @param {object} args - The hook arguments as an object
    * @returns {Promise<unknown>} The result of the hook
@@ -147,21 +149,21 @@ export default class BaseHookManager {
 
     debug("Triggering hook for event `%s`", 4, event)
 
-    if (!event)
+    if(!event)
       throw new Error("Event type is required for hook invocation")
 
     // Validate event type if allowed events are configured
-    if (this.#allowedEvents.length > 0 && !this.#allowedEvents.includes(event))
+    if(this.#allowedEvents.length > 0 && !this.#allowedEvents.includes(event))
       throw new Error(`Invalid event type: ${event}. Allowed events: ${this.#allowedEvents.join(", ")}`)
 
     const hook = this.hooks?.[event]
 
-    if (hook) {
+    if(hook) {
       Valid.type(hook, "function", `Hook "${event}" is not a function`)
 
       const hookExecution = hook.call(this.hooks, args)
       const hookTimeout = this.timeout
-      
+
       const expireAsync = () =>
         timeoutPromise(
           hookTimeout,
@@ -170,7 +172,7 @@ export default class BaseHookManager {
 
       const result = await Promise.race([hookExecution, expireAsync()])
 
-      if (result?.status === "error")
+      if(result?.status === "error")
         throw Sass.new(result.error)
 
       debug("Hook executed successfully for event: `%s`", 4, event)
@@ -178,13 +180,14 @@ export default class BaseHookManager {
       return result
     } else {
       debug("No hook found for event: `%s`", 4, event)
+
       return null
     }
   }
 
   /**
    * Check if a hook exists for the given event.
-   * 
+   *
    * @param {string} event - Event name to check
    * @returns {boolean} True if hook exists
    */
@@ -194,13 +197,13 @@ export default class BaseHookManager {
 
   /**
    * Get all available hook events.
-   * 
+   *
    * @returns {string[]} Array of available hook event names
    */
   getAvailableEvents() {
-    return this.hooks ? Object.keys(this.hooks).filter(key => 
-      typeof this.hooks[key] === 'function' && 
-      !['setup', 'cleanup', 'log', 'timeout'].includes(key)
+    return this.hooks ? Object.keys(this.hooks).filter(key =>
+      typeof this.hooks[key] === "function" &&
+      !["setup", "cleanup", "log", "timeout"].includes(key)
     ) : []
   }
-}
+}

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/types/DirectoryObject.d.ts

@@ -40,6 +40,12 @@ export default class DirectoryObject extends FS {
   /** The directory extension (usually empty) */
   readonly extension: string
 
+  /** The platform-specific path separator (e.g., '/' on Unix, '\\' on Windows) */
+  readonly sep: string
+
+  /** Array of directory path segments split by separator */
+  readonly trail: string[]
+
   /** Always false for directories */
   readonly isFile: false
 
@@ -49,6 +55,25 @@ export default class DirectoryObject extends FS {
   /** Whether the directory exists (async) */
   readonly exists: Promise<boolean>
 
+  /**
+   * Generator that walks up the directory tree, yielding parent directories.
+   * Starts from the current directory and yields each parent until reaching the root.
+   *
+   * @example
+   * ```typescript
+   * 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
+   *   // /
+   * }
+   * ```
+   */
+  readonly walkUp: Generator<DirectoryObject, void, unknown>
+
   /** Returns a string representation of the DirectoryObject */
   toString(): string
 
@@ -64,9 +89,47 @@ export default class DirectoryObject extends FS {
     isDirectory: boolean
   }
 
-  /** List the contents of this directory */
+  /**
+   * Lists the contents of this directory.
+   * Returns FileObject instances for files and DirectoryObject instances for subdirectories.
+   *
+   * @returns Promise resolving to object with files and directories arrays
+   * @throws {Error} If directory cannot be read
+   *
+   * @example
+   * ```typescript
+   * const dir = new DirectoryObject('./src')
+   * const {files, directories} = await dir.read()
+   *
+   * console.log(`Found ${files.length} files`)
+   * files.forEach(file => console.log(file.name))
+   *
+   * console.log(`Found ${directories.length} subdirectories`)
+   * directories.forEach(subdir => console.log(subdir.name))
+   * ```
+   */
   read(): Promise<DirectoryListing>
 
-  /** Ensure this directory exists, creating it if necessary */
+  /**
+   * Ensures this directory exists, creating it if necessary.
+   * Gracefully handles the case where the directory already exists (EEXIST error).
+   * Pass options to control directory creation behavior (e.g., recursive, mode).
+   *
+   * @param options - Options to pass to fs.mkdir (e.g., {recursive: true, mode: 0o755})
+   * @returns Promise that resolves when directory exists or has been created
+   * @throws {Sass} If directory creation fails for reasons other than already existing
+   *
+   * @example
+   * ```typescript
+   * const dir = new DirectoryObject('./build/output')
+   *
+   * // Create directory recursively
+   * await dir.assureExists({recursive: true})
+   *
+   * // Now safe to write files
+   * const file = new FileObject('result.json', dir)
+   * await file.write(JSON.stringify(data))
+   * ```
+   */
   assureExists(options?: any): Promise<void>
 }

package/src/types/FileObject.d.ts

@@ -321,10 +321,46 @@ export default class FileObject extends FS {
   /** Read the content of a file */
   read(encoding?: string): Promise<string>
 
-  /** Write content to a file */
+  /**
+   * Write content to a file asynchronously.
+   * Validates that the parent directory exists before writing.
+   *
+   * @param content - The content to write
+   * @param encoding - The encoding in which to write (default: "utf8")
+   * @throws {Sass} If the file path is invalid or the parent directory doesn't exist
+   *
+   * @example
+   * ```typescript
+   * const file = new FileObject('./output/data.json')
+   * await file.write(JSON.stringify({key: 'value'}))
+   *
+   * // With custom encoding
+   * await file.write('content', 'utf16le')
+   * ```
+   */
   write(content: string, encoding?: string): Promise<void>
 
-  /** Load an object from JSON5 or YAML file with type specification */
+  /**
+   * Load and parse data from JSON5 or YAML file.
+   * Attempts to parse content as JSON5 first, then falls back to YAML if type is "any".
+   *
+   * @param type - The expected data format: "json", "json5", "yaml", or "any" (default: "any")
+   * @param encoding - The file encoding (default: "utf8")
+   * @returns The parsed data object
+   * @throws {Sass} If the content cannot be parsed or type is unsupported
+   *
+   * @example
+   * ```typescript
+   * // Load JSON5 config
+   * const config = await configFile.loadData('json5')
+   *
+   * // Auto-detect format (tries JSON5, then YAML)
+   * const data = await dataFile.loadData('any')
+   *
+   * // Load YAML explicitly
+   * const yaml = await yamlFile.loadData('yaml')
+   * ```
+   */
   loadData(type?: 'json' | 'json5' | 'yaml' | 'any', encoding?: string): Promise<unknown>
 
   /**