@gesslar/toolkit 2.0.0 → 2.2.0

package/README.md

@@ -31,7 +31,7 @@ Includes all browser functionality plus Node.js-specific modules for file I/O, l
 | Cache | Cache management for file I/O operations |
 | CappedDirectoryObject | Directory operations constrained to a specific tree |
 | Contract | Contract management and validation |
-| DirectoryObject | File system wrapper for directory operations |
+| DirectoryObject | Directory metadata and operations including path resolution, existence checks, and traversal |
 | FileObject | File system wrapper for file operations |
 | FS | Base class for file system operations with static utilities |
 | Glog | Logging framework |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "A collection of utilities for Node.js and browser environments.",
   "main": "./src/index.js",
   "type": "module",
@@ -28,14 +28,14 @@
   ],
   "sideEffects": false,
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "scripts": {
     "types:build": "node -e \"require('fs').rmSync('src/types',{recursive:true,force:true});\" && tsc -p tsconfig.types.json",
     "prepublishOnly": "npm run types:build",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
-    "submit": "npm publish --access public",
+    "submit": "npm publish --access public --//registry.npmjs.org/:_authToken=\"${NPM_ACCESS_TOKEN}\"",
     "update": "npx npm-check-updates -u && npm install",
     "test": "node --test tests/**/*.test.js",
     "pr": "gt submit --publish --restack --ai"

package/src/lib/CappedDirectoryObject.js

@@ -169,10 +169,10 @@ export default class CappedDirectoryObject extends DirectoryObject {
    * @throws {Sass} If the path contains traversal (..)
    * @example
    * const capped = new TempDirectoryObject("myapp")
-   * const subDir = capped.addDirectory("data")
+   * const subDir = capped.getDirectory("data")
    * console.log(subDir.path) // "/tmp/myapp-ABC123/data"
    */
-  addDirectory(newPath) {
+  getDirectory(newPath) {
     Valid.type(newPath, "String")
 
     // Prevent absolute paths
@@ -203,10 +203,10 @@ export default class CappedDirectoryObject extends DirectoryObject {
    * @throws {Sass} If the path contains traversal (..)
    * @example
    * const capped = new TempDirectoryObject("myapp")
-   * const file = capped.addFile("config.json")
+   * const file = capped.getFile("config.json")
    * console.log(file.path) // "/tmp/myapp-ABC123/config.json"
    */
-  addFile(filename) {
+  getFile(filename) {
     Valid.type(filename, "String")
 
     // Prevent absolute paths

package/src/lib/DirectoryObject.js

@@ -4,7 +4,7 @@
  * resolution and existence checks.
  */
 
-import {mkdir, opendir, readdir, rmdir} from "node:fs/promises"
+import {glob, mkdir, opendir, readdir, rmdir} from "node:fs/promises"
 import path from "node:path"
 import {URL} from "node:url"
 import util from "node:util"
@@ -16,17 +16,51 @@ import Sass from "./Sass.js"
 
 /**
  * DirectoryObject encapsulates metadata and operations for a directory,
- * including path resolution and existence checks.
+ * providing immutable path resolution, existence checks, and content enumeration.
  *
- * @property {string} supplied - The supplied directory
- * @property {string} path - The resolved path
- * @property {URL} url - The directory URL
- * @property {string} name - The directory name
- * @property {string} module - The directory name without extension
- * @property {string} extension - The directory extension (usually empty)
- * @property {boolean} isFile - Always false
+ * Features:
+ * - Immutable metadata (path, name, URL) sealed on construction
+ * - Async existence checking and directory creation
+ * - Pattern-based content filtering with glob support
+ * - Path traversal via walkUp generator
+ * - Intelligent path merging for subdirectories and files
+ * - Support for temporary directory management
+ *
+ * @property {string} supplied - The original directory path as supplied to constructor
+ * @property {string} path - The absolute resolved directory path
+ * @property {URL} url - The directory as a file:// URL
+ * @property {string} name - The directory name (basename)
+ * @property {string} module - The directory name without extension (same as name for directories)
+ * @property {string} extension - The directory extension (typically empty string)
+ * @property {string} sep - Platform-specific path separator ('/' or '\\')
+ * @property {Array<string>} trail - Path segments split by separator
+ * @property {boolean} temporary - Whether this is marked as a temporary directory
+ * @property {boolean} isFile - Always false (this is a directory)
  * @property {boolean} isDirectory - Always true
- * @property {Promise<boolean>} exists - Whether the directory exists (async)
+ * @property {Promise<boolean>} exists - Whether the directory exists (async getter)
+ * @property {Generator<DirectoryObject>} walkUp - Generator yielding parent directories up to root
+ *
+ * @example
+ * // Basic usage
+ * const dir = new DirectoryObject("/projects/myapp")
+ * console.log(dir.path) // "/projects/myapp"
+ * console.log(await dir.exists) // true/false
+ *
+ * @example
+ * // Read directory contents
+ * const {files, directories} = await dir.read()
+ * const {files: jsFiles} = await dir.read("*.js")
+ *
+ * @example
+ * // Path traversal
+ * for(const parent of dir.walkUp) {
+ *   console.log(parent.path)
+ * }
+ *
+ * @example
+ * // Working with subdirectories and files
+ * const subDir = dir.getDirectory("src/lib")
+ * const file = dir.getFile("package.json")
  */
 export default class DirectoryObject extends FS {
   /**
@@ -289,12 +323,32 @@ export default class DirectoryObject extends FS {
   }
 
   /**
-   * Lists the contents of a directory.
+   * Lists the contents of a directory, optionally filtered by a glob pattern.
    *
-   * @returns {Promise<{files: Array<FileObject>, directories: Array<DirectoryObject>}>} The files and directories in the directory.
+   * @async
+   * @param {string} [pat=""] - Optional glob pattern to filter results (e.g., "*.txt", "test-*")
+   * @returns {Promise<{files: Array<FileObject>, directories: Array<DirectoryObject>}>} Object containing arrays of files and directories
+   * @example
+   * const dir = new DirectoryObject("./src")
+   * const {files, directories} = await dir.read()
+   * console.log(files) // All files in ./src
+   *
+   * @example
+   * // Filter for specific files
+   * const {files} = await dir.read("*.js")
+   * console.log(files) // Only .js files in ./src
    */
-  async read() {
-    const found = await readdir(this.url, {withFileTypes: true})
+  async read(pat="") {
+    const cwd = this.path, withFileTypes = true
+    const found = !pat
+      ? await readdir(this.url, {withFileTypes})
+      : await Array.fromAsync(
+        glob(pat, {
+          cwd,
+          withFileTypes,
+          exclude: candidate => candidate.parentPath !== cwd
+        })
+      )
 
     const files = found
       .filter(dirent => dirent.isFile())
@@ -443,17 +497,25 @@ export default class DirectoryObject extends FS {
   /**
    * Creates a new DirectoryObject by extending this directory's path.
    *
-   * Uses overlapping path segment detection to intelligently combine paths.
-   * Preserves the temporary flag from the current directory.
+   * Uses intelligent path merging that detects overlapping segments to avoid
+   * duplication (e.g., "/projects/toolkit" + "toolkit/src" = "/projects/toolkit/src").
+   * The temporary flag is preserved from the parent directory.
    *
-   * @param {string} newPath - The path to append to this directory's path.
-   * @returns {DirectoryObject} A new DirectoryObject with the extended path.
+   * @param {string} newPath - The subdirectory path to append (can be nested like "src/lib")
+   * @returns {DirectoryObject} A new DirectoryObject instance with the combined path
+   * @throws {Sass} If newPath is not a string
    * @example
    * const dir = new DirectoryObject("/projects/git/toolkit")
-   * const subDir = dir.addDirectory("src/lib")
+   * const subDir = dir.getDirectory("src/lib")
    * console.log(subDir.path) // "/projects/git/toolkit/src/lib"
+   *
+   * @example
+   * // Handles overlapping segments intelligently
+   * const dir = new DirectoryObject("/projects/toolkit")
+   * const subDir = dir.getDirectory("toolkit/src")
+   * console.log(subDir.path) // "/projects/toolkit/src" (not /projects/toolkit/toolkit/src)
    */
-  addDirectory(newPath) {
+  getDirectory(newPath) {
     Valid.type(newPath, "String")
 
     const thisPath = this.path
@@ -465,16 +527,24 @@ export default class DirectoryObject extends FS {
   /**
    * Creates a new FileObject by extending this directory's path.
    *
-   * Uses overlapping path segment detection to intelligently combine paths.
+   * Uses intelligent path merging that detects overlapping segments to avoid
+   * duplication. The resulting FileObject can be used for reading, writing,
+   * and other file operations.
    *
-   * @param {string} filename - The filename to append to this directory's path.
-   * @returns {FileObject} A new FileObject with the extended path.
+   * @param {string} filename - The filename to append (can include subdirectories like "src/index.js")
+   * @returns {FileObject} A new FileObject instance with the combined path
+   * @throws {Sass} If filename is not a string
    * @example
    * const dir = new DirectoryObject("/projects/git/toolkit")
-   * const file = dir.addFile("package.json")
+   * const file = dir.getFile("package.json")
    * console.log(file.path) // "/projects/git/toolkit/package.json"
+   *
+   * @example
+   * // Can include nested paths
+   * const file = dir.getFile("src/index.js")
+   * const data = await file.read()
    */
-  addFile(filename) {
+  getFile(filename) {
     Valid.type(filename, "String")
 
     const thisPath = this.path

package/src/lib/FS.js

@@ -153,9 +153,8 @@ export default class FS {
     const to = path2.split(sep).filter(Boolean)
 
     // If they're the same, just return path1
-    if(to.length === from.length && from.every((f, i) => to[i] === f)) {
+    if(to.length === from.length && from.every((f, i) => to[i] === f))
       return path1
-    }
 
     const overlapIndex = from.findLastIndex(curr => curr === to.at(0))
 

package/src/lib/TempDirectoryObject.js

@@ -109,12 +109,12 @@ export default class TempDirectoryObject extends CappedDirectoryObject {
    * @throws {Sass} If the path contains traversal (..)
    * @example
    * const temp = new TempDirectoryObject("myapp")
-   * const subDir = temp.addDirectory("data")
+   * const subDir = temp.getDirectory("data")
    * console.log(subDir.path) // "/tmp/myapp-ABC123/data"
    */
-  addDirectory(newPath) {
-    // Delegate to base class addDirectory() which will call TempDirectoryObject constructor
-    return super.addDirectory(newPath)
+  getDirectory(newPath) {
+    // Delegate to base class getDirectory() which will call TempDirectoryObject constructor
+    return super.getDirectory(newPath)
   }
 
   /**
@@ -129,12 +129,12 @@ export default class TempDirectoryObject extends CappedDirectoryObject {
    * @throws {Sass} If the path contains traversal (..)
    * @example
    * const temp = new TempDirectoryObject("myapp")
-   * const file = temp.addFile("config.json")
+   * const file = temp.getFile("config.json")
    * console.log(file.path) // "/tmp/myapp-ABC123/config.json"
    */
-  addFile(filename) {
-    // Delegate to base class addFile() which handles security checks
-    return super.addFile(filename)
+  getFile(filename) {
+    // Delegate to base class getFile() which handles security checks
+    return super.getFile(filename)
   }
 
   /**

package/src/lib/Util.js

@@ -1,7 +1,10 @@
 import {createHash} from "node:crypto"
 import {EventEmitter} from "node:events"
-import Sass from "./Sass.js"
 import {Util as BrowserUtil} from "../browser/index.js"
+import Sass from "./Sass.js"
+import process from "node:process"
+import JSON5 from "json5"
+import Valid from "./Valid.js"
 
 /**
  * Utility class providing common helper functions for string manipulation,
@@ -152,4 +155,45 @@ export default class Util extends BrowserUtil {
       )
     }
   }
+
+  /**
+   * Retrieves an environment variable and parses it as JSON5.
+   *
+   * This method fetches the value of the specified environment variable and
+   * attempts to parse it using JSON5. If the variable doesn't exist or is
+   * empty, the default value is returned. If parsing fails, an error is
+   * thrown.
+   *
+   * Example:
+   *   // export MY_CONFIG='{"debug": true, timeout: 5000}'
+   *   Util.getEnv("MY_CONFIG", {debug: false})
+   *   → {debug: true, timeout: 5000}
+   *
+   * Edge cases:
+   *   - If the environment variable doesn't exist, returns the default value
+   *   - If the value is an empty string, returns the default value
+   *   - If JSON5 parsing fails, throws a Sass error with context
+   *
+   * @param {string} ev - Name of the environment variable to retrieve
+   * @param {unknown} [def=undefined] - Default value if variable doesn't exist or is empty
+   * @returns {unknown} Parsed JSON5 value or default
+   * @throws {Sass} If JSON5 parsing fails
+   */
+  static getEnv(ev, def=undefined) {
+    Valid.type(ev, "String")
+
+    const value = process.env[ev]
+
+    if(!value)
+      return def
+
+    try {
+      return JSON5.parse(value)
+    } catch(error) {
+      throw Sass.new(
+        `Failed to parse environment variable '${ev}' as JSON5`,
+        error
+      )
+    }
+  }
 }

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

@@ -50,10 +50,10 @@ export default class CappedDirectoryObject extends DirectoryObject {
      * @throws {Sass} If the path contains traversal (..)
      * @example
      * const capped = new TempDirectoryObject("myapp")
-     * const subDir = capped.addDirectory("data")
+     * const subDir = capped.getDirectory("data")
      * console.log(subDir.path) // "/tmp/myapp-ABC123/data"
      */
-    addDirectory(newPath: string): CappedDirectoryObject;
+    getDirectory(newPath: string): CappedDirectoryObject;
     #private;
 }
 import DirectoryObject from "./DirectoryObject.js";

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

@@ -1,16 +1,50 @@
 /**
  * DirectoryObject encapsulates metadata and operations for a directory,
- * including path resolution and existence checks.
+ * providing immutable path resolution, existence checks, and content enumeration.
  *
- * @property {string} supplied - The supplied directory
- * @property {string} path - The resolved path
- * @property {URL} url - The directory URL
- * @property {string} name - The directory name
- * @property {string} module - The directory name without extension
- * @property {string} extension - The directory extension (usually empty)
- * @property {boolean} isFile - Always false
+ * Features:
+ * - Immutable metadata (path, name, URL) sealed on construction
+ * - Async existence checking and directory creation
+ * - Pattern-based content filtering with glob support
+ * - Path traversal via walkUp generator
+ * - Intelligent path merging for subdirectories and files
+ * - Support for temporary directory management
+ *
+ * @property {string} supplied - The original directory path as supplied to constructor
+ * @property {string} path - The absolute resolved directory path
+ * @property {URL} url - The directory as a file:// URL
+ * @property {string} name - The directory name (basename)
+ * @property {string} module - The directory name without extension (same as name for directories)
+ * @property {string} extension - The directory extension (typically empty string)
+ * @property {string} sep - Platform-specific path separator ('/' or '\\')
+ * @property {Array<string>} trail - Path segments split by separator
+ * @property {boolean} temporary - Whether this is marked as a temporary directory
+ * @property {boolean} isFile - Always false (this is a directory)
  * @property {boolean} isDirectory - Always true
- * @property {Promise<boolean>} exists - Whether the directory exists (async)
+ * @property {Promise<boolean>} exists - Whether the directory exists (async getter)
+ * @property {Generator<DirectoryObject>} walkUp - Generator yielding parent directories up to root
+ *
+ * @example
+ * // Basic usage
+ * const dir = new DirectoryObject("/projects/myapp")
+ * console.log(dir.path) // "/projects/myapp"
+ * console.log(await dir.exists) // true/false
+ *
+ * @example
+ * // Read directory contents
+ * const {files, directories} = await dir.read()
+ * const {files: jsFiles} = await dir.read("*.js")
+ *
+ * @example
+ * // Path traversal
+ * for(const parent of dir.walkUp) {
+ *   console.log(parent.path)
+ * }
+ *
+ * @example
+ * // Working with subdirectories and files
+ * const subDir = dir.getDirectory("src/lib")
+ * const file = dir.getFile("package.json")
  */
 export default class DirectoryObject extends FS {
     [x: number]: () => object;
@@ -121,11 +155,22 @@ export default class DirectoryObject extends FS {
      */
     get isDirectory(): boolean;
     /**
-     * Lists the contents of a directory.
+     * Lists the contents of a directory, optionally filtered by a glob pattern.
      *
-     * @returns {Promise<{files: Array<FileObject>, directories: Array<DirectoryObject>}>} The files and directories in the directory.
+     * @async
+     * @param {string} [pat=""] - Optional glob pattern to filter results (e.g., "*.txt", "test-*")
+     * @returns {Promise<{files: Array<FileObject>, directories: Array<DirectoryObject>}>} Object containing arrays of files and directories
+     * @example
+     * const dir = new DirectoryObject("./src")
+     * const {files, directories} = await dir.read()
+     * console.log(files) // All files in ./src
+     *
+     * @example
+     * // Filter for specific files
+     * const {files} = await dir.read("*.js")
+     * console.log(files) // Only .js files in ./src
      */
-    read(): Promise<{
+    read(pat?: string): Promise<{
         files: Array<FileObject>;
         directories: Array<DirectoryObject>;
     }>;
@@ -193,30 +238,46 @@ export default class DirectoryObject extends FS {
     /**
      * Creates a new DirectoryObject by extending this directory's path.
      *
-     * Uses overlapping path segment detection to intelligently combine paths.
-     * Preserves the temporary flag from the current directory.
+     * Uses intelligent path merging that detects overlapping segments to avoid
+     * duplication (e.g., "/projects/toolkit" + "toolkit/src" = "/projects/toolkit/src").
+     * The temporary flag is preserved from the parent directory.
      *
-     * @param {string} newPath - The path to append to this directory's path.
-     * @returns {DirectoryObject} A new DirectoryObject with the extended path.
+     * @param {string} newPath - The subdirectory path to append (can be nested like "src/lib")
+     * @returns {DirectoryObject} A new DirectoryObject instance with the combined path
+     * @throws {Sass} If newPath is not a string
      * @example
      * const dir = new DirectoryObject("/projects/git/toolkit")
-     * const subDir = dir.addDirectory("src/lib")
+     * const subDir = dir.getDirectory("src/lib")
      * console.log(subDir.path) // "/projects/git/toolkit/src/lib"
+     *
+     * @example
+     * // Handles overlapping segments intelligently
+     * const dir = new DirectoryObject("/projects/toolkit")
+     * const subDir = dir.getDirectory("toolkit/src")
+     * console.log(subDir.path) // "/projects/toolkit/src" (not /projects/toolkit/toolkit/src)
      */
-    addDirectory(newPath: string): DirectoryObject;
+    getDirectory(newPath: string): DirectoryObject;
     /**
      * Creates a new FileObject by extending this directory's path.
      *
-     * Uses overlapping path segment detection to intelligently combine paths.
+     * Uses intelligent path merging that detects overlapping segments to avoid
+     * duplication. The resulting FileObject can be used for reading, writing,
+     * and other file operations.
      *
-     * @param {string} filename - The filename to append to this directory's path.
-     * @returns {FileObject} A new FileObject with the extended path.
+     * @param {string} filename - The filename to append (can include subdirectories like "src/index.js")
+     * @returns {FileObject} A new FileObject instance with the combined path
+     * @throws {Sass} If filename is not a string
      * @example
      * const dir = new DirectoryObject("/projects/git/toolkit")
-     * const file = dir.addFile("package.json")
+     * const file = dir.getFile("package.json")
      * console.log(file.path) // "/projects/git/toolkit/package.json"
+     *
+     * @example
+     * // Can include nested paths
+     * const file = dir.getFile("src/index.js")
+     * const data = await file.read()
      */
-    addFile(filename: string): FileObject;
+    getFile(filename: string): FileObject;
     #private;
 }
 import FS from "./FS.js";

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

@@ -1 +1 @@
-{"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;;;;;;;;;;;;;;;;OAgBG;IACH,UATa,OAAO,CAAC,IAAI,CAAC,CA0BzB;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;;;;;;;;;;;;OAYG;IACH,sBAPW,MAAM,GACJ,eAAe,CAa3B;IAED;;;;;;;;;;;OAWG;IACH,kBAPW,MAAM,GACJ,UAAU,CAatB;;CACF;eAxdc,SAAS;uBACD,iBAAiB"}
+{"version":3,"file":"DirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/DirectoryObject.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;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;;;;;;;;;;;;;;;;OAgBG;IACH,UATa,OAAO,CAAC,IAAI,CAAC,CA0BzB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAiBD;;;;;;;;;;;;;;;OAeG;IACH,WAZW,MAAM,GACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;KAAC,CAAC,CAoCpF;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;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,sBAdW,MAAM,GACJ,eAAe,CAoB3B;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,kBAbW,MAAM,GACJ,UAAU,CAmBtB;;CACF;eA9hBc,SAAS;uBACD,iBAAiB"}

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;;;;;;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;CACF;yBAzMa,OAAO,iBAAiB,EAAE,OAAO;8BACjC,OAAO,sBAAsB,EAAE,OAAO"}
+{"version":3,"file":"FS.d.ts","sourceRoot":"","sources":["../../lib/FS.js"],"names":[],"mappings":"AAwBA;;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,CA0BlB;IAED;;;;;;;;OAQG;IACH,6BAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAgClB;CACF;yBAxMa,OAAO,iBAAiB,EAAE,OAAO;8BACjC,OAAO,sBAAsB,EAAE,OAAO"}

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

@@ -56,10 +56,10 @@ export default class TempDirectoryObject extends CappedDirectoryObject {
      * @throws {Sass} If the path contains traversal (..)
      * @example
      * const temp = new TempDirectoryObject("myapp")
-     * const subDir = temp.addDirectory("data")
+     * const subDir = temp.getDirectory("data")
      * console.log(subDir.path) // "/tmp/myapp-ABC123/data"
      */
-    addDirectory(newPath: string): TempDirectoryObject;
+    getDirectory(newPath: string): TempDirectoryObject;
     /**
      * Creates a new FileObject by extending this directory's path.
      *
@@ -72,10 +72,10 @@ export default class TempDirectoryObject extends CappedDirectoryObject {
      * @throws {Sass} If the path contains traversal (..)
      * @example
      * const temp = new TempDirectoryObject("myapp")
-     * const file = temp.addFile("config.json")
+     * const file = temp.getFile("config.json")
      * console.log(file.path) // "/tmp/myapp-ABC123/config.json"
      */
-    addFile(filename: string): FileObject;
+    getFile(filename: string): FileObject;
     #private;
 }
 import CappedDirectoryObject from "./CappedDirectoryObject.js";

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

@@ -71,6 +71,30 @@ export default class Util extends BrowserUtil {
      * @returns {Promise<void>} Resolves when all listeners have completed, but no grapes.
      */
     static asyncEmitQuack(emitter: object, event: string, ...args: unknown[]): Promise<void>;
+    /**
+     * Retrieves an environment variable and parses it as JSON5.
+     *
+     * This method fetches the value of the specified environment variable and
+     * attempts to parse it using JSON5. If the variable doesn't exist or is
+     * empty, the default value is returned. If parsing fails, an error is
+     * thrown.
+     *
+     * Example:
+     *   // export MY_CONFIG='{"debug": true, timeout: 5000}'
+     *   Util.getEnv("MY_CONFIG", {debug: false})
+     *   → {debug: true, timeout: 5000}
+     *
+     * Edge cases:
+     *   - If the environment variable doesn't exist, returns the default value
+     *   - If the value is an empty string, returns the default value
+     *   - If JSON5 parsing fails, throws a Sass error with context
+     *
+     * @param {string} ev - Name of the environment variable to retrieve
+     * @param {unknown} [def=undefined] - Default value if variable doesn't exist or is empty
+     * @returns {unknown} Parsed JSON5 value or default
+     * @throws {Sass} If JSON5 parsing fails
+     */
+    static getEnv(ev: string, def?: unknown): unknown;
 }
 import { Util as BrowserUtil } from "../browser/index.js";
 //# 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"}
+{"version":3,"file":"Util.d.ts","sourceRoot":"","sources":["../../lib/Util.js"],"names":[],"mappings":"AAQA;;;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;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,kBALW,MAAM,QACN,OAAO,GACL,OAAO,CAmBnB;CACF;oCApMiC,qBAAqB"}