@gesslar/toolkit 1.8.0 → 1.9.0

package/README.md

@@ -1,23 +1,97 @@
-# `npm i @gesslar/toolkit`
+# Gesslar's Toolkit of Amazing ✌🏻
 
 This package is intended to be a collection of useful utilities for any
 project's consumption. Not the kind that gives you bleeding, hacking coughs,
-but the kind that says "yumyum."
+but the kind that gives "yumyum."
 
 There are file and directory abstractions, uhmm, there's also some terminal
 things and validity checkers, lots of data functions.
 
+## Included Classes
+
+### Browser
+
+These classes exist and function within the browser, or browser-like environment, such as
+a Tauri app.
+
+| Name | Description |
+| ---- | ----------- |
+| Collection | Array, Map, etc methods |
+| Data | Primitive manipulation and identification |
+| Disposer | Participate in lifecycle mechanics |
+| HTML | HTML-related methods |
+| Notify | Wrapper around DOM event system |
+| Sass | The best Error class this side of Tatooine |
+| Tantrum | Sass's louder, shoutier AggregateError cousin |
+| TypeSpec | String-based type management |
+| Util | Porn |
+| Valid | Assert methods for validation |
+
+### Node.js
+
+Everything included in the browser but more, and backendier.
+
+| Name | Description |
+| ---- | ----------- |
+| Cache | Cache management for use with file IO |
+| Contract | Contract management |
+| DirectoryObject | Wrapper around Node's fs for directories |
+| FileObject | Wrapper around Node's fs for directories |
+| FS | Base for DirectoryObject and FileObject, but with additional static methods |
+| Glog | The superior logging framework |
+| Notify | Wrapper around Node's event system |
+| Sass | The best Error class the other side of Tatooine |
+| Schemer | Schema management |
+| Tantrum | *crowd of wookiee roars* |
+| Term | Terminal based methods |
+| Terms | Terms for use with Contract |
+| Util | Not porn, promise 🤞🏼 |
+| Valid | Assert methods for validation |
+
+## Installation
+
+```shell
+npm i @gesslar/toolkit
+```
+
 ## Usage
 
-**For Node.js projects:**
+Toolkit is environment aware and knows whether it is being used in a web browser or in
+Node.js. It is not strictly necessary to specify whether you require the `node` or
+`browser` variant, but you may do so if you like to feel like a nice control daddy.
+
+### Browser-like
+
+TypeScript editors do not pick up types from jsDelivr. If you want inline types without
+installing from npm, use the esm.sh `?dts` URL or install the package locally for
+development and use the CDN at runtime.
+
+#### jsDelivr (runtime only)
+
+```html
+https://cdn.jsdelivr.net/npm/@gesslar/toolkit
+```
+
+#### esm.sh (runtime, types)
+
+```html
+https://esm.sh/@gesslar/toolkit
+https://esm.sh/@gesslar/toolkit?dts` (serves `.d.ts` for editors)
+```
+
+### Node.js
 
 ```javascript
-import { Data, FileObject, Cache } from '@gesslar/toolkit'
-// or explicitly:
-import { Data, FileObject } from '@gesslar/toolkit/node'
+import * as TK from "@gesslar/toolkit"
 ```
 
-**For browsers or Tauri apps:**
+```javascript
+import {Data, FileObject, Cache} from "@gesslar/toolkit"
+```
+
+```javascript
+import {Data, Filebject} from "@gesslar/toolkit/node"
+```
 
 ```javascript
 import { Data, Collection, Util } from '@gesslar/toolkit/browser'
@@ -27,31 +101,12 @@ The browser version includes: Data, Collection, Util, Type (TypeSpec), Valid,
 Sass, and Tantrum. Node-only modules (FileObject, Cache, FS, etc.) are not
 available in the browser version.
 
-**Browser via CDN (no install):**
-
-Substitute the `__VERSION__` below with the release version you are seeking.
-
-- jsDelivr (runtime only):
-  `https://cdn.jsdelivr.net/npm/@gesslar/toolkit@__VERSION__/browser`
-
-- esm.sh (runtime + optional types):
-  `https://esm.sh/@gesslar/toolkit@__VERSION__/browser`
-  `https://esm.sh/@gesslar/toolkit@__VERSION__/browser?dts` (serves `.d.ts` for editors)
-
-Notes:
-
-- Nothing to configure in this repo for CDN use; both URLs just work after
-  the version is published to npm.
-- TypeScript editors do not pick up types from jsDelivr. If you want inline
-  types without installing from npm, use the esm.sh `?dts` URL or install the
-  package locally for development and use the CDN at runtime.
-
 Basically, if you want it, it is most definitely here, and working 100% and
 absolutely none of that is true. There are only a few classes here, but they're
-pretty. And if you bug-shame them, I will _come for you like_ ...
+pretty. And if you bug-shame them, I will *come for you like* ...
 
 nah. Just don't be a dick, okay? Play nice, share, lick a veggie and gentlemen,
-spend less than 5 minutes washing your pits, chest, and downstairs and maybe
+spend fewer than 5 minutes washing your pits, chest, and downstairs and maybe
 give some time to the other parts. Like the parts that walk on things, sit
 on things. Some things that enjoy being sat upon do not enjoy being sat upon
 by gross sitter-upon-things.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Get in, bitches, we're going toolkitting.",
   "main": "./src/index.js",
   "type": "module",
@@ -70,12 +70,6 @@
   },
   "devDependencies": {
     "@gesslar/uglier": "^0.0.5",
-    "@stylistic/eslint-plugin": "^5.6.1",
-    "@types/node": "^24.10.1",
-    "@typescript-eslint/eslint-plugin": "^8.48.1",
-    "@typescript-eslint/parser": "^8.48.1",
-    "eslint": "^9.39.1",
-    "eslint-plugin-jsdoc": "^61.4.1",
-    "globals": "^16.5.0"
+    "typescript": "^5.9.3"
   }
 }

package/src/lib/DirectoryObject.js

@@ -4,14 +4,15 @@
  * resolution and existence checks.
  */
 
-import fs from "node:fs/promises"
+import {mkdir, opendir, readdir, rmdir} from "node:fs/promises"
 import path from "node:path"
-import util from "node:util"
 import {URL} from "node:url"
+import util from "node:util"
 
 import FS from "./FS.js"
 import FileObject from "./FileObject.js"
 import Sass from "./Sass.js"
+import {Data, Valid} from "../browser/index.js"
 
 /**
  * DirectoryObject encapsulates metadata and operations for a directory,
@@ -51,16 +52,24 @@ export default class DirectoryObject extends FS {
     isDirectory: true,
     trail: null,
     sep: null,
+    temporary: null,
   })
 
   /**
    * Constructs a DirectoryObject instance.
    *
-   * @param {string} directory - The directory path
+   * @param {string? | DirectoryObject?} directory - The directory path or DirectoryObject
+   * @param {boolean} [temporary] - Whether this is a temporary directory.
    */
-  constructor(directory) {
+  constructor(directory=null, temporary=false) {
     super()
 
+    Valid.type(directory, "String|DirectoryObject|Null")
+
+    // If passed a DirectoryObject, extract its path
+    if(Data.isType(directory, "DirectoryObject"))
+      directory = directory.path
+
     const fixedDir = FS.fixSlashes(directory ?? ".")
     const resolved = path.resolve(fixedDir)
     const url = new URL(FS.pathToUri(resolved))
@@ -76,6 +85,7 @@ export default class DirectoryObject extends FS {
     this.#meta.module = baseName
     this.#meta.trail = trail
     this.#meta.sep = sep
+    this.#meta.temporary = temporary
 
     Object.freeze(this.#meta)
   }
@@ -200,6 +210,50 @@ export default class DirectoryObject extends FS {
     return this.#meta.trail
   }
 
+  /**
+   * Returns whether this directory is marked as temporary.
+   *
+   * @returns {boolean} True if this is a temporary directory, false otherwise
+   */
+  get temporary() {
+    return this.#meta.temporary
+  }
+
+  /**
+   * Recursively removes a temporary directory and all its contents.
+   *
+   * This method will delete all files and subdirectories within this directory,
+   * then delete the directory itself. It only works on directories explicitly
+   * marked as temporary for safety.
+   *
+   * @async
+   * @returns {Promise<void>}
+   * @throws {Sass} If the directory is not marked as temporary
+   * @throws {Sass} If the directory deletion fails
+   * @example
+   * const tempDir = await FS.tempDirectory("my-temp")
+   * // ... use the directory ...
+   * await tempDir.remove() // Recursively deletes everything
+   */
+  async remove() {
+    if(!this.temporary)
+      throw Sass.new("This is not a temporary directory.")
+
+    /** @type {{files: Array<FileObject>, directories: Array<DirectoryObject>}} */
+    const {files, directories} = await this.read()
+
+    // Remove subdirectories recursively
+    for(const dir of directories)
+      await dir.remove()
+
+    // Remove files
+    for(const file of files)
+      await file.delete()
+
+    // Delete the now-empty directory
+    await this.delete()
+  }
+
   /**
    * Returns false. Because this is a directory.
    *
@@ -225,7 +279,7 @@ export default class DirectoryObject extends FS {
    */
   async #directoryExists() {
     try {
-      (await fs.opendir(this.path)).close()
+      (await opendir(this.path)).close()
 
       return true
     } catch(_) {
@@ -239,7 +293,7 @@ export default class DirectoryObject extends FS {
    * @returns {Promise<{files: Array<FileObject>, directories: Array<DirectoryObject>}>} The files and directories in the directory.
    */
   async read() {
-    const found = await fs.readdir(this.url, {withFileTypes: true})
+    const found = await readdir(this.url, {withFileTypes: true})
 
     const files = found
       .filter(dirent => dirent.isFile())
@@ -247,7 +301,11 @@ export default class DirectoryObject extends FS {
 
     const directories = found
       .filter(dirent => dirent.isDirectory())
-      .map(dirent => new DirectoryObject(path.join(this.path, dirent.name)))
+      .map(dirent => {
+        const dirPath = path.join(this.path, dirent.name)
+
+        return new DirectoryObject(dirPath, this.temporary)
+      })
 
     return {files, directories}
   }
@@ -270,7 +328,7 @@ export default class DirectoryObject extends FS {
       return
 
     try {
-      await fs.mkdir(this.path, options)
+      await mkdir(this.path, options)
     } catch(e) {
       if(e.code === "EEXIST") {
         // Directory already exists, ignore
@@ -353,7 +411,7 @@ export default class DirectoryObject extends FS {
     if(!(await this.exists))
       throw Sass.new(`No such resource '${this.url.href}'`)
 
-    return await fs.rmdir(this.path)
+    return await rmdir(this.path)
   }
 
   /**
@@ -380,4 +438,27 @@ export default class DirectoryObject extends FS {
 
     return await directory.exists
   }
+
+  /**
+   * Creates a new DirectoryObject by merging this directory's path with a new
+   * path.
+   *
+   * Uses overlapping path segment detection to intelligently combine paths.
+   * Preserves the temporary flag from the current directory.
+   *
+   * @param {string} newPath - The path to merge with this directory's path.
+   * @returns {DirectoryObject} A new DirectoryObject with the merged path.
+   * @example
+   * const dir = new DirectoryObject("/projects/git/toolkit")
+   * const subDir = dir.to("toolkit/src/lib")
+   * console.log(subDir.path) // "/projects/git/toolkit/src/lib"
+   */
+  to(newPath) {
+    Valid.type(newPath, "String")
+
+    const thisPath = this.path
+    const merged = FS.mergeOverlappingPaths(thisPath, newPath)
+
+    return new this(merged, this.temporary)
+  }
 }

package/src/lib/FS.js

@@ -8,10 +8,13 @@
 import {globby} from "globby"
 import path from "node:path"
 import url from "node:url"
+import fs from "node:fs/promises"
+import os from "node:os"
 
 import Collection from "../browser/lib/Collection.js"
 import Sass from "./Sass.js"
 import Valid from "./Valid.js"
+import DirectoryObject from "./DirectoryObject.js"
 
 /** @typedef {import("./FileObject.js").default} FileObject */
 /** @typedef {import("./DirectoryObject.js").default} DirectoryObject */
@@ -33,6 +36,7 @@ export default class FS {
   /**
    * Fix slashes in a path
    *
+   * @static
    * @param {string} pathName - The path to fix
    * @returns {string} The fixed path
    */
@@ -43,6 +47,7 @@ export default class FS {
   /**
    * Convert a path to a URI
    *
+   * @static
    * @param {string} pathName - The path to convert
    * @returns {string} The URI
    */
@@ -59,6 +64,7 @@ export default class FS {
   /**
    * Convert a URI to a path
    *
+   * @static
    * @param {string} pathName - The URI to convert
    * @returns {string} The path
    */
@@ -73,6 +79,7 @@ export default class FS {
   /**
    * Retrieve all files matching a specific glob pattern.
    *
+   * @static
    * @param {string|Array<string>} glob - The glob pattern(s) to search.
    * @returns {Promise<Array<FileObject>>} A promise that resolves to an array of file objects
    * @throws {Sass} If the input is not a string or array of strings.
@@ -117,6 +124,7 @@ export default class FS {
    * If the target is outside the source (i.e., the relative path starts with ".."),
    * returns the absolute path to the target instead.
    *
+   * @static
    * @param {FileObject|DirectoryObject} from - The source file or directory object
    * @param {FileObject|DirectoryObject} to - The target file or directory object
    * @returns {string} The relative path from `from` to `to`, or the absolute path if not reachable
@@ -136,6 +144,7 @@ export default class FS {
   /**
    * Merge two paths by finding overlapping segments and combining them efficiently
    *
+   * @static
    * @param {string} path1 - The first path
    * @param {string} path2 - The second path to merge with the first
    * @param {string} [sep] - The path separator to use (defaults to system separator)
@@ -172,6 +181,7 @@ export default class FS {
    * Resolve a path relative to another path using various strategies
    * Handles absolute paths, relative navigation, and overlap-based merging
    *
+   * @static
    * @param {string} fromPath - The base path to resolve from
    * @param {string} toPath - The target path to resolve
    * @returns {string} The resolved path
@@ -207,4 +217,88 @@ export default class FS {
     // join if no overlap
     return FS.mergeOverlappingPaths(from, normalizedTo)
   }
+
+  /**
+   * Creates a new temporary directory and wraps it in a DirectoryObject.
+   *
+   * When called without a parent, creates a new temporary directory in the OS
+   * temp folder with a unique name. When called with a parent DirectoryObject,
+   * creates a subdirectory within that parent.
+   *
+   * The parent directory (if provided) must:
+   * - Be marked as temporary
+   * - Actually exist on the filesystem
+   * - Have lineage tracing back to the OS temp directory
+   *
+   * These validations ensure that only legitimately temporary directories can
+   * be created and later removed with the remove() method.
+   *
+   * @static
+   * @async
+   * @param {string} name - The base name for the temporary directory. When creating a root temp directory, a random suffix will be appended for uniqueness.
+   * @param {DirectoryObject|null} [parent] - Optional parent DirectoryObject to create this directory within. Must be a temporary directory itself.
+   * @returns {Promise<DirectoryObject>} A DirectoryObject representing the created temporary directory, with the temporary flag set to true.
+   * @throws {Sass} If name is not a string
+   * @throws {Sass} If parent is provided but is not a DirectoryObject
+   * @throws {Sass} If parent is not marked as temporary
+   * @throws {Sass} If parent does not exist
+   * @throws {Sass} If parent's lineage does not trace back to the OS temp directory
+   * @example
+   * // Create a standalone temporary directory
+   * const tempDir = await FS.tempDirectory("my-temp")
+   * console.log(tempDir.temporary) // true
+   * console.log(tempDir.path) // /tmp/my-temp-abc123 (on Unix)
+   *
+   * @example
+   * // Create nested temporary directories
+   * const parent = await FS.tempDirectory("parent")
+   * const child = await FS.tempDirectory("child", parent)
+   * console.log(child.path.startsWith(parent.path)) // true
+   * await parent.remove() // Removes both parent and child
+   */
+  static async tempDirectory(name, parent=null) {
+    Valid.type(name, "String")
+    Valid.type(parent, "Null|DirectoryObject")
+
+    const temp = os.tmpdir()
+
+    if(parent) {
+      Valid.assert(parent.temporary, "Parent must be a temporary DirectoryObject.")
+      Valid.assert(await parent.exists, "Parent must exist.")
+
+      let found = false
+      for(const p of parent.walkUp) {
+        if(p.path === temp) {
+          found = true
+          break
+        }
+      }
+
+      Valid.assert(found, "The lineage of this directory must be the OS temp directory.")
+
+      // Security: Reject absolute paths, path traversal, and path separators
+      Valid.assert(
+        !path.isAbsolute(name),
+        "Temporary directory name must not be an absolute path."
+      )
+      Valid.assert(
+        !name.includes("/") && !name.includes("\\") && !name.includes(path.sep),
+        "Temporary directory name must not contain path separators."
+      )
+      Valid.assert(
+        name.length > 0,
+        "Temporary directory name must not be empty."
+      )
+
+      const dir = new DirectoryObject(path.join(parent.path, name), true)
+      await dir.assureExists()
+
+      return dir
+    }
+
+    const prefix = name.endsWith("-") ? name : `${name}-`
+    const dir = await fs.mkdtemp(path.join(temp, prefix))
+
+    return new DirectoryObject(dir, true)
+  }
 }

package/src/lib/FileObject.js

@@ -75,12 +75,16 @@ export default class FileObject extends FS {
   /**
    * Constructs a FileObject instance.
    *
-   * @param {string} fileName - The file path
+   * @param {string | FileObject} fileName - The file path or FileObject
    * @param {DirectoryObject|string|null} [directory] - The parent directory (object or string)
    */
   constructor(fileName, directory=null) {
     super()
 
+    // If passed a FileObject, extract its path
+    if(Data.isType(fileName, "FileObject"))
+      fileName = fileName.path
+
     if(!fileName || typeof fileName !== "string" || fileName.length === 0) {
       throw Sass.new("fileName must be a non-empty string")
     }

package/src/lib/Notify.js

@@ -6,6 +6,8 @@
 
 import {EventEmitter} from "node:events"
 
+import Valid from "./Valid.js"
+
 /**
  * @typedef {object} NotifyEventOptions
  * @property {boolean} [once] - Whether the listener should be invoked only once.
@@ -31,6 +33,9 @@ export default new class Notify {
    * @returns {void}
    */
   emit(type, payload=undefined) {
+    Valid.type(type, "String")
+    Valid.assert(type.length > 0, "Event type cannot be an empty string.")
+
     this.#emitter.emit(type, payload)
   }
 
@@ -43,6 +48,9 @@ export default new class Notify {
    * @returns {unknown} The payload after listeners have processed it.
    */
   request(type, payload={}) {
+    Valid.type(type, "String")
+    Valid.assert(type.length > 0, "Event type cannot be an empty string.")
+
     this.#emitter.emit(type, payload)
 
     return payload
@@ -58,11 +66,9 @@ export default new class Notify {
    * @returns {() => void} Dispose function to unregister the handler.
    */
   on(type, handler, emitter=this.#emitter, options=undefined) {
-    if(!(typeof type === "string" && type))
-      throw new Error("No event 'type' specified to listen for.")
-
-    if(typeof handler !== "function")
-      throw new Error("No handler function specified.")
+    Valid.type(type, "String")
+    Valid.assert(type.length > 0, "Event type cannot be an empty string.")
+    Valid.type(handler, "Function")
 
     if(options?.once) {
       emitter.once(type, handler, options)

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

@@ -13,12 +13,14 @@
  * @property {Promise<boolean>} exists - Whether the directory exists (async)
  */
 export default class DirectoryObject extends FS {
+    [x: number]: () => object;
     /**
      * Constructs a DirectoryObject instance.
      *
-     * @param {string} directory - The directory path
+     * @param {string? | DirectoryObject?} directory - The directory path or DirectoryObject
+     * @param {boolean} [temporary] - Whether this is a temporary directory.
      */
-    constructor(directory: string);
+    constructor(directory?: any, temporary?: boolean);
     /**
      * Returns a JSON representation of the DirectoryObject.
      *
@@ -82,6 +84,29 @@ export default class DirectoryObject extends FS {
      * console.log(dir.trail) // ['', 'path', 'to', 'directory']
      */
     get trail(): Array<string>;
+    /**
+     * Returns whether this directory is marked as temporary.
+     *
+     * @returns {boolean} True if this is a temporary directory, false otherwise
+     */
+    get temporary(): boolean;
+    /**
+     * Recursively removes a temporary directory and all its contents.
+     *
+     * This method will delete all files and subdirectories within this directory,
+     * then delete the directory itself. It only works on directories explicitly
+     * marked as temporary for safety.
+     *
+     * @async
+     * @returns {Promise<void>}
+     * @throws {Sass} If the directory is not marked as temporary
+     * @throws {Sass} If the directory deletion fails
+     * @example
+     * const tempDir = await FS.tempDirectory("my-temp")
+     * // ... use the directory ...
+     * await tempDir.remove() // Recursively deletes everything
+     */
+    remove(): Promise<void>;
     /**
      * Returns false. Because this is a directory.
      *
@@ -165,15 +190,22 @@ export default class DirectoryObject extends FS {
      */
     hasDirectory(dirname: string): Promise<boolean>;
     /**
-     * Custom inspect method for Node.js console.
+     * Creates a new DirectoryObject by merging this directory's path with a new
+     * path.
+     *
+     * Uses overlapping path segment detection to intelligently combine paths.
+     * Preserves the temporary flag from the current directory.
      *
-     * @returns {object} JSON representation of this object.
+     * @param {string} newPath - The path to merge with this directory's path.
+     * @returns {DirectoryObject} A new DirectoryObject with the merged path.
+     * @example
+     * const dir = new DirectoryObject("/projects/git/toolkit")
+     * const subDir = dir.to("toolkit/src/lib")
+     * console.log(subDir.path) // "/projects/git/toolkit/src/lib"
      */
-    [util.inspect.custom](): object;
+    to(newPath: string): DirectoryObject;
     #private;
 }
 import FS from "./FS.js";
-import { URL } from "node:url";
 import FileObject from "./FileObject.js";
-import util from "node:util";
 //# sourceMappingURL=DirectoryObject.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"DirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/DirectoryObject.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;GAaG;AACH;IA0BE;;;;OAIG;IACH,uBAFW,MAAM,EAsBhB;IAWD;;;;OAIG;IACH,UAFa,MAAM,CAalB;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;IAED;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,aALa,KAAK,CAAC,MAAM,CAAC,CAOzB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAiBD;;;;OAIG;IACH,QAFa,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;KAAC,CAAC,CAcpF;IAED;;;;;;;;;;;;OAYG;IACH,uBARW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAqBzB;IA8BD;;;;;;;;;;;;;;;OAeG;IACH,cAZa,MAAM,CAclB;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;IAhRD;;;;OAIG;IACH,yBAFa,MAAM,CAIlB;;CA0QF;eAnXc,SAAS;oBAFN,UAAU;uBAGL,iBAAiB;iBAJvB,WAAW"}
+{"version":3,"file":"DirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/DirectoryObject.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;GAaG;AACH;uBA4Fe,MAAM;IAjEnB;;;;;OAKG;IACH,yCAFW,OAAO,EA6BjB;IAWD;;;;OAIG;IACH,UAFa,MAAM,CAalB;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;IAED;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,aALa,KAAK,CAAC,MAAM,CAAC,CAOzB;IAED;;;;OAIG;IACH,iBAFa,OAAO,CAInB;IAED;;;;;;;;;;;;;;;OAeG;IACH,UARa,OAAO,CAAC,IAAI,CAAC,CAyBzB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAiBD;;;;OAIG;IACH,QAFa,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;KAAC,CAAC,CAkBpF;IAED;;;;;;;;;;;;OAYG;IACH,uBARW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAqBzB;IA8BD;;;;;;;;;;;;;;;OAeG;IACH,cAZa,MAAM,CAclB;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;;;;;;;;;;;;;OAaG;IACH,YAPW,MAAM,GACJ,eAAe,CAa3B;;CACF;eApcc,SAAS;uBACD,iBAAiB"}

package/src/types/lib/FS.d.ts

@@ -8,6 +8,7 @@ export default class FS {
     /**
      * Fix slashes in a path
      *
+     * @static
      * @param {string} pathName - The path to fix
      * @returns {string} The fixed path
      */
@@ -15,6 +16,7 @@ export default class FS {
     /**
      * Convert a path to a URI
      *
+     * @static
      * @param {string} pathName - The path to convert
      * @returns {string} The URI
      */
@@ -22,6 +24,7 @@ export default class FS {
     /**
      * Convert a URI to a path
      *
+     * @static
      * @param {string} pathName - The URI to convert
      * @returns {string} The path
      */
@@ -29,6 +32,7 @@ export default class FS {
     /**
      * Retrieve all files matching a specific glob pattern.
      *
+     * @static
      * @param {string|Array<string>} glob - The glob pattern(s) to search.
      * @returns {Promise<Array<FileObject>>} A promise that resolves to an array of file objects
      * @throws {Sass} If the input is not a string or array of strings.
@@ -41,6 +45,7 @@ export default class FS {
      * If the target is outside the source (i.e., the relative path starts with ".."),
      * returns the absolute path to the target instead.
      *
+     * @static
      * @param {FileObject|DirectoryObject} from - The source file or directory object
      * @param {FileObject|DirectoryObject} to - The target file or directory object
      * @returns {string} The relative path from `from` to `to`, or the absolute path if not reachable
@@ -49,6 +54,7 @@ export default class FS {
     /**
      * Merge two paths by finding overlapping segments and combining them efficiently
      *
+     * @static
      * @param {string} path1 - The first path
      * @param {string} path2 - The second path to merge with the first
      * @param {string} [sep] - The path separator to use (defaults to system separator)
@@ -59,12 +65,53 @@ export default class FS {
      * Resolve a path relative to another path using various strategies
      * Handles absolute paths, relative navigation, and overlap-based merging
      *
+     * @static
      * @param {string} fromPath - The base path to resolve from
      * @param {string} toPath - The target path to resolve
      * @returns {string} The resolved path
      */
     static resolvePath(fromPath: string, toPath: string): string;
+    /**
+     * Creates a new temporary directory and wraps it in a DirectoryObject.
+     *
+     * When called without a parent, creates a new temporary directory in the OS
+     * temp folder with a unique name. When called with a parent DirectoryObject,
+     * creates a subdirectory within that parent.
+     *
+     * The parent directory (if provided) must:
+     * - Be marked as temporary
+     * - Actually exist on the filesystem
+     * - Have lineage tracing back to the OS temp directory
+     *
+     * These validations ensure that only legitimately temporary directories can
+     * be created and later removed with the remove() method.
+     *
+     * @static
+     * @async
+     * @param {string} name - The base name for the temporary directory. When creating a root temp directory, a random suffix will be appended for uniqueness.
+     * @param {DirectoryObject|null} [parent] - Optional parent DirectoryObject to create this directory within. Must be a temporary directory itself.
+     * @returns {Promise<DirectoryObject>} A DirectoryObject representing the created temporary directory, with the temporary flag set to true.
+     * @throws {Sass} If name is not a string
+     * @throws {Sass} If parent is provided but is not a DirectoryObject
+     * @throws {Sass} If parent is not marked as temporary
+     * @throws {Sass} If parent does not exist
+     * @throws {Sass} If parent's lineage does not trace back to the OS temp directory
+     * @example
+     * // Create a standalone temporary directory
+     * const tempDir = await FS.tempDirectory("my-temp")
+     * console.log(tempDir.temporary) // true
+     * console.log(tempDir.path) // /tmp/my-temp-abc123 (on Unix)
+     *
+     * @example
+     * // Create nested temporary directories
+     * const parent = await FS.tempDirectory("parent")
+     * const child = await FS.tempDirectory("child", parent)
+     * console.log(child.path.startsWith(parent.path)) // true
+     * await parent.remove() // Removes both parent and child
+     */
+    static tempDirectory(name: string, parent?: DirectoryObject | null): Promise<DirectoryObject>;
 }
 export type FileObject = import("./FileObject.js").default;
 export type DirectoryObject = import("./DirectoryObject.js").default;
+import DirectoryObject from "./DirectoryObject.js";
 //# sourceMappingURL=FS.d.ts.map

package/src/types/lib/FS.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FS.d.ts","sourceRoot":"","sources":["../../lib/FS.js"],"names":[],"mappings":"AAwBA;;GAEG;AACH;IACE,kCAAwB;IACxB,uCAAkC;IAClC,mBAAsB;IAEtB;;;;;OAKG;IACH,4BAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,2BAHW,MAAM,GACJ,MAAM,CAUlB;IAED;;;;;OAKG;IACH,2BAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;;;;;OAOG;IACH,sBALW,MAAM,GAAC,KAAK,CAAC,MAAM,CAAC,GAClB,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAmCtC;IAED;;;;;;;;;OASG;IACH,oCAJW,UAAU,GAAC,eAAe,MAC1B,UAAU,GAAC,eAAe,GACxB,MAAM,CAYlB;IAED;;;;;;;OAOG;IACH,oCALW,MAAM,SACN,MAAM,QACN,MAAM,GACJ,MAAM,CA2BlB;IAED;;;;;;;OAOG;IACH,6BAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAgClB;CACF;yBAlMa,OAAO,iBAAiB,EAAE,OAAO;8BACjC,OAAO,sBAAsB,EAAE,OAAO"}
+{"version":3,"file":"FS.d.ts","sourceRoot":"","sources":["../../lib/FS.js"],"names":[],"mappings":"AA2BA;;GAEG;AACH;IACE,kCAAwB;IACxB,uCAAkC;IAClC,mBAAsB;IAEtB;;;;;;OAMG;IACH,4BAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,2BAHW,MAAM,GACJ,MAAM,CAUlB;IAED;;;;;;OAMG;IACH,2BAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;;;;;;OAQG;IACH,sBALW,MAAM,GAAC,KAAK,CAAC,MAAM,CAAC,GAClB,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAmCtC;IAED;;;;;;;;;;OAUG;IACH,oCAJW,UAAU,GAAC,eAAe,MAC1B,UAAU,GAAC,eAAe,GACxB,MAAM,CAYlB;IAED;;;;;;;;OAQG;IACH,oCALW,MAAM,SACN,MAAM,QACN,MAAM,GACJ,MAAM,CA2BlB;IAED;;;;;;;;OAQG;IACH,6BAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAgClB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH,2BArBW,MAAM,WACN,eAAe,GAAC,IAAI,GAClB,OAAO,CAAC,eAAe,CAAC,CA+DpC;CACF;yBA7Ra,OAAO,iBAAiB,EAAE,OAAO;8BACjC,OAAO,sBAAsB,EAAE,OAAO;4BAHxB,sBAAsB"}

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

@@ -14,6 +14,7 @@
  * @property {Promise<boolean>} exists - Whether the file exists (async)
  */
 export default class FileObject extends FS {
+    [x: number]: () => object;
     /**
      * Configuration mapping data types to their respective parser modules for loadData method.
      * Each parser module must have a .parse() method that accepts a string and returns parsed data.
@@ -26,10 +27,10 @@ export default class FileObject extends FS {
     /**
      * Constructs a FileObject instance.
      *
-     * @param {string} fileName - The file path
+     * @param {string | FileObject} fileName - The file path or FileObject
      * @param {DirectoryObject|string|null} [directory] - The parent directory (object or string)
      */
-    constructor(fileName: string, directory?: DirectoryObject | string | null);
+    constructor(fileName: string | FileObject, directory?: DirectoryObject | string | null);
     /**
      * Returns a JSON representation of the FileObject.
      *
@@ -214,18 +215,10 @@ export default class FileObject extends FS {
      * await file.delete()
      */
     delete(): Promise<void>;
-    /**
-     * Custom inspect method for Node.js console.
-     *
-     * @returns {object} JSON representation of this object.
-     */
-    [util.inspect.custom](): object;
     #private;
 }
 import FS from "./FS.js";
-import { URL } from "node:url";
 import DirectoryObject from "./DirectoryObject.js";
-import util from "node:util";
 import JSON5 from "json5";
 import YAML from "yaml";
 //# sourceMappingURL=FileObject.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"FileObject.d.ts","sourceRoot":"","sources":["../../lib/FileObject.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;GAcG;AAEH;IACE;;;;;OAKG;IACH,yBAFU;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,OAAO,KAAK,GAAG,OAAO,IAAI,CAAC,CAAA;KAAC,CAO1D;IA2BF;;;;;OAKG;IACH,sBAHW,MAAM,cACN,eAAe,GAAC,MAAM,GAAC,IAAI,EAsCrC;IAWD;;;;OAIG;IACH,UAFa,MAAM,CAclB;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;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAED;;;;;;;;;;;;;;OAcG;IACH,iBAFa,eAAe,CAI3B;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;IAsBD;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CAY3B;IAED;;;;;;;;;;;OAWG;IACH,cARa,OAAO,CAAC,MAAM,CAAC,CAkB3B;IAED;;;;;;;;;;;OAWG;IACH,eARW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAezB;IAED;;;;;;;;;;;;;;;OAeG;IACH,kBAXW,WAAW,GAAC,IAAI,GAAC,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAyBzB;IAED;;;;;;;;;;;;;;OAcG;IACH,gBAXW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAkC5B;IAED;;;;OAIG;IACH,UAFa,OAAO,CAAC,MAAM,CAAC,CAY3B;IAED;;;;;;;;;OASG;IACH,UAPa,OAAO,CAAC,IAAI,CAAC,CAiBzB;IA7XD;;;;OAIG;IACH,yBAFa,MAAM,CAIlB;;CAuXF;eAjgBc,SAAS;oBAJN,UAAU;4BAGA,sBAAsB;iBALjC,WAAW;kBAHV,OAAO;iBAIR,MAAM"}
+{"version":3,"file":"FileObject.d.ts","sourceRoot":"","sources":["../../lib/FileObject.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;GAcG;AAEH;uBAsHe,MAAM;IArHnB;;;;;OAKG;IACH,yBAFU;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,OAAO,KAAK,GAAG,OAAO,IAAI,CAAC,CAAA;KAAC,CAO1D;IA2BF;;;;;OAKG;IACH,sBAHW,MAAM,GAAG,UAAU,cACnB,eAAe,GAAC,MAAM,GAAC,IAAI,EA0CrC;IAWD;;;;OAIG;IACH,UAFa,MAAM,CAclB;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;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAED;;;;;;;;;;;;;;OAcG;IACH,iBAFa,eAAe,CAI3B;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;IAsBD;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CAY3B;IAED;;;;;;;;;;;OAWG;IACH,cARa,OAAO,CAAC,MAAM,CAAC,CAkB3B;IAED;;;;;;;;;;;OAWG;IACH,eARW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAezB;IAED;;;;;;;;;;;;;;;OAeG;IACH,kBAXW,WAAW,GAAC,IAAI,GAAC,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAyBzB;IAED;;;;;;;;;;;;;;OAcG;IACH,gBAXW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAkC5B;IAED;;;;OAIG;IACH,UAFa,OAAO,CAAC,MAAM,CAAC,CAY3B;IAED;;;;;;;;;OASG;IACH,UAPa,OAAO,CAAC,IAAI,CAAC,CAiBzB;;CACF;eArgBc,SAAS;4BADI,sBAAsB;kBARhC,OAAO;iBAIR,MAAM"}

package/src/types/lib/Notify.d.ts

@@ -51,5 +51,4 @@ export type NotifyEventOptions = {
      */
     signal?: AbortSignal;
 };
-import { EventEmitter } from "node:events";
 //# sourceMappingURL=Notify.d.ts.map

package/src/types/lib/Notify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Notify.d.ts","sourceRoot":"","sources":["../../lib/Notify.js"],"names":[],"mappings":";IAmBE,iDAAiD;UAAtC,MAAM;IAGjB,kDAAkD;2BAAvC,YAAY;IAGvB;;;;;;OAMG;eAHQ,MAAM,YACN,OAAO,GACL,IAAI;IAMjB;;;;;;;OAOG;kBAHQ,MAAM,YACN,OAAO,GACL,OAAO;IAQpB;;;;;;;;OAQG;aALQ,MAAM,WACN,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,YAC1B,YAAY,YACZ,kBAAkB,GAChB,MAAM,IAAI;IAkBvB;;;;;;;OAOG;cAJQ,MAAM,WACN,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,YAC1B,YAAY,GACV,IAAI;;;;;;;WAvEL,OAAO;;;;aACP,WAAW;;6BALE,aAAa"}
+{"version":3,"file":"Notify.d.ts","sourceRoot":"","sources":["../../lib/Notify.js"],"names":[],"mappings":";IAqBE,iDAAiD;UAAtC,MAAM;IAGjB,kDAAkD;2BAAvC,YAAY;IAGvB;;;;;;OAMG;eAHQ,MAAM,YACN,OAAO,GACL,IAAI;IASjB;;;;;;;OAOG;kBAHQ,MAAM,YACN,OAAO,GACL,OAAO;IAWpB;;;;;;;;OAQG;aALQ,MAAM,WACN,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,YAC1B,YAAY,YACZ,kBAAkB,GAChB,MAAM,IAAI;IAgBvB;;;;;;;OAOG;cAJQ,MAAM,WACN,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,YAC1B,YAAY,GACV,IAAI;;;;;;;WA3EL,OAAO;;;;aACP,WAAW"}

package/src/types/lib/Util.d.ts

@@ -73,5 +73,4 @@ export default class Util extends BrowserUtil {
     static asyncEmitQuack(emitter: object, event: string, ...args: unknown[]): Promise<void>;
 }
 import { Util as BrowserUtil } from "../browser/index.js";
-import { EventEmitter } from "node:events";
 //# sourceMappingURL=Util.d.ts.map

package/src/types/lib/Util.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Util.d.ts","sourceRoot":"","sources":["../../lib/Util.js"],"names":[],"mappings":"AAKA;;;GAGG;AACH;IACE;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,mCAHW,MAAM,GACJ,KAAK,CAAC,MAAM,CAAC,CAazB;IAED;;;;;;;;OAQG;IACH,+CALW,MAAM,SACN,MAAM,WACH,OAAO,EAAA,GACR,OAAO,CAAC,IAAI,CAAC,CAmBzB;IAED;;;;;;;;;;;;OAYG;IACH,0BALW,YAAY,SACZ,MAAM,WACH,OAAO,EAAA,GACR,OAAO,CAAC,IAAI,CAAC,CAqBzB;IAED;;;;;;;;;;OAUG;IACH,+BALW,MAAM,SACN,MAAM,WACH,OAAO,EAAA,GACR,OAAO,CAAC,IAAI,CAAC,CAyBzB;CACF;oCAvJiC,qBAAqB;6BAF5B,aAAa"}
+{"version":3,"file":"Util.d.ts","sourceRoot":"","sources":["../../lib/Util.js"],"names":[],"mappings":"AAKA;;;GAGG;AACH;IACE;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,mCAHW,MAAM,GACJ,KAAK,CAAC,MAAM,CAAC,CAazB;IAED;;;;;;;;OAQG;IACH,+CALW,MAAM,SACN,MAAM,WACH,OAAO,EAAA,GACR,OAAO,CAAC,IAAI,CAAC,CAmBzB;IAED;;;;;;;;;;;;OAYG;IACH,0BALW,YAAY,SACZ,MAAM,WACH,OAAO,EAAA,GACR,OAAO,CAAC,IAAI,CAAC,CAqBzB;IAED;;;;;;;;;;OAUG;IACH,+BALW,MAAM,SACN,MAAM,WACH,OAAO,EAAA,GACR,OAAO,CAAC,IAAI,CAAC,CAyBzB;CACF;oCAvJiC,qBAAqB"}