@gesslar/toolkit 0.2.9 → 0.4.0

package/package.json

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

package/src/lib/ActionRunner.js

@@ -19,7 +19,7 @@ export default class ActionRunner {
   constructor({action, build, logger}) {
     this.#action = action
     this.#build = build
-    this.#logger = logger ?? Glog.newDebug()
+    this.#logger = logger ?? {newDebug: () => () => {}}
   }
 
   /**

package/src/lib/BaseActionManager.js

@@ -0,0 +1,246 @@
+import Data from "./Data.js"
+import Sass from "./Sass.js"
+import ActionBuilder from "./ActionBuilder.js"
+import ActionRunner from "./ActionRunner.js"
+
+/**
+ * Generic base class for managing actions with lifecycle hooks.
+ * Provides common functionality for action setup, execution, and cleanup.
+ * Designed to be extended by specific implementations.
+ */
+export default class BaseActionManager {
+  #action = null
+  #hookManager = null
+  #contract = null
+  #log = null
+  #debug = null
+  #file = null
+  #variables = null
+  #runner = null
+  #id = null
+
+  /**
+   * @param {object} config - Configuration object
+   * @param {object} config.actionDefinition - Action definition with action, file, and contract
+   * @param {object} config.logger - Logger instance
+   * @param {object} [config.variables] - Variables to pass to action
+   */
+  constructor({actionDefinition, logger, variables}) {
+    this.#id = Symbol(performance.now())
+    this.#log = logger
+    this.#debug = this.#log.newDebug()
+    this.#variables = variables || {}
+
+    this.#initialize(actionDefinition)
+  }
+
+  get id() {
+    return this.#id
+  }
+
+  get action() {
+    return this.#action
+  }
+
+  get hookManager() {
+    return this.#hookManager
+  }
+
+  set hookManager(hookManager) {
+    if(this.hookManager)
+      throw new Error("Hook manager already set")
+
+    this.#hookManager = hookManager
+    this.#attachHooksToAction(hookManager)
+  }
+
+  get contract() {
+    return this.#contract
+  }
+
+  get meta() {
+    return this.#action?.meta
+  }
+
+  get log() {
+    return this.#log
+  }
+
+  get variables() {
+    return this.#variables
+  }
+
+  get runner() {
+    return this.#runner
+  }
+
+  get file() {
+    return this.#file
+  }
+
+  /**
+   * Initialize the action manager with the provided definition.
+   * Override in subclasses to add specific validation or setup.
+   *
+   * @param {object} actionDefinition - Action definition
+   * @protected
+   */
+  #initialize(actionDefinition) {
+    const debug = this.#debug
+
+    debug("Setting up action", 2)
+
+    const {action, file, contract} = actionDefinition
+
+    if(!action)
+      throw new Error("Action is required")
+
+    if(!contract)
+      throw new Error("Contract is required")
+
+    this.#action = action
+    this.#contract = contract
+    this.#file = file
+
+    debug("Action initialization complete", 2)
+  }
+
+  /**
+   * Attach hooks to the action instance.
+   * Override in subclasses to customize hook attachment.
+   *
+   * @param {object} hookManager - Hook manager instance
+   * @protected
+   */
+  #attachHooksToAction(hookManager) {
+    // Basic hook attachment - can be overridden by subclasses
+    this.action.hook = hookManager.on?.bind(hookManager)
+    this.action.hooks = hookManager.hooks
+  }
+
+  /**
+   * Setup the action by creating and configuring the runner.
+   * Override setupActionInstance() in subclasses for custom setup logic.
+   *
+   * @returns {Promise<void>}
+   */
+  async setupAction() {
+    this.#debug("Setting up action for %s on %s", 2, this.action.meta?.kind, this.id)
+
+    await this.#setupHooks()
+    await this.#setupActionInstance()
+  }
+
+  /**
+   * Setup the action instance and create the runner.
+   * Override in subclasses to customize action setup.
+   *
+   * @protected
+   */
+  async #setupActionInstance() {
+    const actionInstance = new this.action()
+    const setup = actionInstance?.setup
+
+    // Setup is required for actions.
+    if(Data.typeOf(setup) === "Function") {
+      const builder = new ActionBuilder(actionInstance)
+      const configuredBuilder = setup(builder)
+      const buildResult = configuredBuilder.build()
+      const runner = new ActionRunner({
+        action: buildResult.action,
+        build: buildResult.build,
+        logger: this.#log
+      })
+
+      this.#runner = runner
+    } else {
+      throw Sass.new("Action setup must be a function.")
+    }
+  }
+
+  /**
+   * 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)
+      throw new Error("Action not set up. Call setupAction() first.")
+
+    return await this.#runner.run(result)
+  }
+
+  /**
+   * Cleanup the action and hooks.
+   *
+   * @returns {Promise<void>}
+   */
+  async cleanupAction() {
+    this.#debug("Cleaning up action for %s on %s", 2, this.action.meta?.kind, this.id)
+
+    await this.#cleanupHooks()
+    await this.#cleanupActionInstance()
+  }
+
+  /**
+   * Setup hooks if hook manager is present.
+   * Override in subclasses to customize hook setup.
+   *
+   * @protected
+   */
+  async #setupHooks() {
+    const setup = this.#hookManager?.setup
+
+    const type = Data.typeOf(setup)
+
+    // No hooks attached.
+    if(type === "Null" || type === "Undefined")
+      return
+
+    if(type !== "Function")
+      throw Sass.new("Hook setup must be a function.")
+
+    await setup.call(
+      this.hookManager.hooks, {
+        action: this.action,
+        variables: this.#variables,
+        log: this.#log
+      }
+    )
+  }
+
+  /**
+   * Cleanup hooks if hook manager is present.
+   * Override in subclasses to customize hook cleanup.
+   *
+   * @protected
+   */
+  async #cleanupHooks() {
+    const cleanup = this.hookManager?.cleanup
+
+    if(!cleanup)
+      return
+
+    await cleanup.call(this.hookManager.hooks)
+  }
+
+  /**
+   * Cleanup the action instance.
+   * Override in subclasses to add custom cleanup logic.
+   *
+   * @protected
+   */
+  async #cleanupActionInstance() {
+    const cleanup = this.action?.cleanup
+
+    if(!cleanup)
+      return
+
+    await cleanup.call(this.action)
+  }
+
+  toString() {
+    return `${this.#file?.module || "UNDEFINED"} (${this.meta?.action || "UNDEFINED"})`
+  }
+}

package/src/lib/BaseHookManager.js

@@ -0,0 +1,209 @@
+import {setTimeout as timeoutPromise} from "timers/promises"
+import Collection from "./Collection.js"
+import Data from "./Data.js"
+import Sass from "./Sass.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 BaseHookManager {
+  #hooksFile = null
+  #log = null
+  #hooks = null
+  #action = null
+  #timeout = 1000 // Default 1 second timeout
+  #allowedEvents = []
+
+  /**
+   * @param {object} config - Configuration object
+   * @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] - 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
+    this.#hooksFile = hooksFile
+    this.#log = logger
+    this.#timeout = timeOut
+    this.#allowedEvents = allowedEvents
+  }
+
+  get action() {
+    return this.#action
+  }
+
+  get hooksFile() {
+    return this.#hooksFile
+  }
+
+  get hooks() {
+    return this.#hooks
+  }
+
+  get log() {
+    return this.#log
+  }
+
+  get timeout() {
+    return this.#timeout
+  }
+
+  get allowedEvents() {
+    return this.#allowedEvents
+  }
+
+  get setup() {
+    return this.hooks?.setup || null
+  }
+
+  get cleanup() {
+    return this.hooks?.cleanup || null
+  }
+
+  /**
+   * 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
+   */
+  static async new(config) {
+    const instance = new this(config)
+    const debug = instance.log.newDebug()
+
+    debug("Creating new HookManager instance with args: `%o`", 2, config)
+
+    const hooksFile = instance.hooksFile
+
+    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)
+        throw new Error(`Hooks file is empty: ${hooksFile.uri}`)
+
+      const hooks = await instance.loadHooks(hooksFileContent)
+
+      if(Data.isEmpty(hooks))
+        return null
+
+      debug("Hooks found for action: `%s`", 2, instance.action)
+
+      if(!hooks)
+        return null
+
+      // Attach common properties to hooks
+      hooks.log = instance.log
+      hooks.timeout = instance.timeout
+      instance.#hooks = hooks
+
+      debug("Hooks loaded successfully for `%s`", 2, instance.action)
+
+      return instance
+    } catch(error) {
+      debug("Failed to load hooks: %s", 1, error.message)
+
+      return null
+    }
+  }
+
+  /**
+   * 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
+   */
+  async loadHooks(hooksFileContent) {
+    const hooks = hooksFileContent.default || hooksFileContent.Hooks
+
+    if(!hooks)
+      throw new Error(`\`${this.hooksFile.uri}\` contains no hooks.`)
+
+    // Default implementation: look for hooks by action name
+    const hooksObj = hooks[this.action]
+
+    return hooksObj || null
+  }
+
+  /**
+   * 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
+   */
+  async on(event, args) {
+    const debug = this.log.newDebug()
+
+    debug("Triggering hook for event `%s`", 4, 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))
+      throw new Error(`Invalid event type: ${event}. Allowed events: ${this.#allowedEvents.join(", ")}`)
+
+    const hook = this.hooks?.[event]
+
+    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,
+          new Error(`Hook execution exceeded timeout of ${hookTimeout}ms`)
+        )
+
+      const result = await Promise.race([hookExecution, expireAsync()])
+
+      if(result?.status === "error")
+        throw Sass.new(result.error)
+
+      debug("Hook executed successfully for event: `%s`", 4, event)
+
+      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
+   */
+  hasHook(event) {
+    return !!(this.hooks?.[event])
+  }
+
+  /**
+   * 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)
+    ) : []
+  }
+}

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/Sass.js

@@ -102,10 +102,8 @@ export default class Sass extends Error {
    * @returns {string|undefined} Formatted stack trace or undefined
    */
   #fullBodyMassage(stack) {
-    // Remove the first line, it's already been reported
-
     stack = stack ?? ""
-
+    // Remove the first line, it's already been reported
     const {rest} = stack.match(/^.*?\n(?<rest>[\s\S]+)$/m)?.groups ?? {}
     const lines = []
 
@@ -114,7 +112,7 @@ export default class Sass extends Error {
         ...rest
           .split("\n")
           .map(line => {
-            const at = line.match(/^\s{4}at\s(?<at>.*)$/)?.groups?.at ?? {}
+            const at = line.match(/^\s{4}at\s(?<at>.*)$/)?.groups?.at ?? ""
 
             return at
               ? `* ${at}`

package/src/lib/Tantrum.js

@@ -26,13 +26,11 @@ export default class Tantrum extends AggregateError {
   constructor(message, errors = []) {
     // Auto-wrap plain errors in Sass, keep existing Sass instances
     const wrappedErrors = errors.map(error => {
-      if(error instanceof Sass) {
+      if(error instanceof Sass)
         return error
-      }
 
-      if(!(error instanceof Error)) {
+      if(!(error instanceof Error))
         throw new TypeError(`All items in errors array must be Error instances, got: ${typeof error}`)
-      }
 
       return Sass.new(error.message, error)
     })
@@ -51,8 +49,9 @@ export default class Tantrum extends AggregateError {
       this.message
     )
 
+    Term.error()
+
     this.errors.forEach(error => {
-      Term.error("\n")
       error.report(nerdMode)
     })
   }

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>
 
   /**