@gesslar/toolkit 3.22.1 → 3.23.0

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

@@ -1,5 +1,24 @@
 /**
- * DirectoryObject encapsulates metadata and operations for a directory,
+ * @typedef {object} GeneratorType
+ * @property {function(): {value: DirectoryObject, done: boolean}} next
+ * @property {function(): GeneratorType} [Symbol.iterator]
+ */
+/**
+ * @typedef {object} DirectoryMeta
+ *
+ * @property {boolean} isDirectory - Always true for directories
+ * @property {string|null} extension - The directory extension (if any)
+ * @property {string|null} module - The directory name without extension
+ * @property {string|null} name - The directory name
+ * @property {DirectoryObject|undefined} parent - The parent DirectoryObject
+ * @property {string|null} parentPath - The parent directory path
+ * @property {string|null} path - The absolute directory path
+ * @property {string|null} sep - Path separator
+ * @property {string|null} supplied - User-supplied path
+ * @property {Array<string>|null} trail - Path segments
+ * @property {URL|null} url - The directory URL
+ */
+/** * DirectoryObject encapsulates metadata and operations for a directory,
  * providing immutable path resolution, existence checks, and content enumeration.
  *
  * Features:
@@ -20,7 +39,6 @@
  * @property {boolean} isDirectory - Always true
  * @property {DirectoryObject|null} parent - The parent directory (null if root)
  * @property {Promise<boolean>} exists - Whether the directory exists (async getter)
- * @property {Generator<DirectoryObject>} walkUp - Generator yielding parent directories up to root
  *
  * @example
  * // Basic usage
@@ -93,15 +111,15 @@ export default class DirectoryObject extends FS {
      */
     get name(): string;
     /**
-     * Returns the directory name without the path or extension.
+     * Returns the directory name without extension.
      *
      * @returns {string} The directory name without extension
      */
     get module(): string;
     /**
-     * Returns the directory extension. Will be an empty string if unavailable.
+     * Returns the directory extension (if any).
      *
-     * @returns {string} The directory extension
+     * @returns {string} The directory extension including the dot (e.g., '.git')
      */
     get extension(): string;
     /**
@@ -143,11 +161,10 @@ export default class DirectoryObject extends FS {
      * Lists the contents of a directory, optionally filtered by a glob pattern.
      *
      * Returns FileObject and DirectoryObject instances for regular directories.
-     * Returns VFileObject and VDirectoryObject instances when called on virtual directories.
      *
      * @async
      * @param {string} [pat=""] - Optional glob pattern to filter results (e.g., "*.txt", "test-*")
-     * @returns {Promise<{files: Array<FileObject|VFileObject>, directories: Array<DirectoryObject|VDirectoryObject>}>} Object containing arrays of files and directories
+     * @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()
@@ -159,19 +176,18 @@ export default class DirectoryObject extends FS {
      * console.log(files) // Only .js files in ./src
      */
     read(pat?: string): Promise<{
-        files: Array<FileObject | VFileObject>;
-        directories: Array<DirectoryObject | VDirectoryObject>;
+        files: Array<FileObject>;
+        directories: Array<DirectoryObject>;
     }>;
     /**
      * Recursively searches directory tree for files and directories matching a glob pattern.
      * Unlike read(), this method searches recursively through subdirectories.
      *
      * Returns FileObject and DirectoryObject instances for regular directories.
-     * Returns VFileObject and VDirectoryObject instances when called on virtual directories.
      *
      * @async
      * @param {string} [pat=""] - Glob pattern to filter results
-     * @returns {Promise<{files: Array<FileObject|VFileObject>, directories: Array<DirectoryObject|VDirectoryObject>}>} Object containing arrays of matching files and directories
+     * @returns {Promise<{files: Array<FileObject|FileObject>, directories: Array<DirectoryObject>}>} Object containing arrays of matching files and directories
      * @throws {Sass} If an entry is neither a file nor directory
      * @example
      * const dir = new DirectoryObject("./src")
@@ -183,8 +199,8 @@ export default class DirectoryObject extends FS {
      * const {files} = await dir.glob("**\/package.json")
      */
     glob(pat?: string): Promise<{
-        files: Array<FileObject | VFileObject>;
-        directories: Array<DirectoryObject | VDirectoryObject>;
+        files: Array<FileObject | FileObject>;
+        directories: Array<DirectoryObject>;
     }>;
     /**
      * Ensures a directory exists, creating it if necessary.
@@ -250,58 +266,85 @@ export default class DirectoryObject extends FS {
     /**
      * Creates a new DirectoryObject by extending this directory's path.
      *
-     * 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.
+     * Uses overlapping path segment detection to intelligently combine paths.
+     * Preserves the temporary flag from the current directory.
      *
-     * @param {string} dir - 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
+     * @param {string} newPath - The path to append to this directory's path.
+     * @returns {DirectoryObject} A new DirectoryObject with the extended path.
      * @example
      * const dir = new DirectoryObject("/projects/git/toolkit")
-     * const subDir = dir.getDirectory("src/lib")
+     * const subDir = dir.addDirectory("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)
      */
-    getDirectory(dir: string): DirectoryObject;
+    getDirectory(newPath: string): DirectoryObject;
     /**
      * Creates a new FileObject by extending this directory's path.
      *
-     * Uses intelligent path merging that detects overlapping segments to avoid
-     * duplication. The resulting FileObject can be used for reading, writing,
-     * and other file operations.
-     *
-     * For regular DirectoryObject: only allows direct children (local only).
-     * For VDirectoryObject: supports absolute virtual paths (starting with "/")
-     * which resolve from cap root, and relative paths from current directory.
-     *
-     * When called on a VDirectoryObject, returns a VFileObject to maintain
-     * virtual path semantics.
+     * Uses overlapping path segment detection to intelligently combine paths.
      *
-     * @param {string} file - The filename to append
-     * @returns {FileObject|VFileObject} A new FileObject (or VFileObject if virtual)
-     * @throws {Sass} If filename is not a string
-     * @throws {Sass} If path would be out of bounds
+     * @param {string} filename - The filename to append to this directory's path.
+     * @returns {FileObject} A new FileObject with the extended path.
      * @example
      * const dir = new DirectoryObject("/projects/git/toolkit")
-     * const file = dir.getFile("package.json")
+     * const file = dir.addFile("package.json")
      * console.log(file.path) // "/projects/git/toolkit/package.json"
-     *
-     * @example
-     * // VDirectoryObject with absolute virtual path
-     * const vdo = new TempDirectoryObject("myapp")
-     * const file = vdo.getFile("/config/settings.json")
-     * // Virtual path: /config/settings.json, Real path: {vdo.real.path}/config/settings.json
      */
-    getFile(file: string): FileObject | VFileObject;
+    getFile(filename: string): FileObject;
     #private;
 }
+export type GeneratorType = {
+    next: () => {
+        value: DirectoryObject;
+        done: boolean;
+    };
+    iterator?: () => GeneratorType;
+};
+export type DirectoryMeta = {
+    /**
+     * - Always true for directories
+     */
+    isDirectory: boolean;
+    /**
+     * - The directory extension (if any)
+     */
+    extension: string | null;
+    /**
+     * - The directory name without extension
+     */
+    module: string | null;
+    /**
+     * - The directory name
+     */
+    name: string | null;
+    /**
+     * - The parent DirectoryObject
+     */
+    parent: DirectoryObject | undefined;
+    /**
+     * - The parent directory path
+     */
+    parentPath: string | null;
+    /**
+     * - The absolute directory path
+     */
+    path: string | null;
+    /**
+     * - Path separator
+     */
+    sep: string | null;
+    /**
+     * - User-supplied path
+     */
+    supplied: string | null;
+    /**
+     * - Path segments
+     */
+    trail: Array<string> | null;
+    /**
+     * - The directory URL
+     */
+    url: URL | null;
+};
 import FS from "./FileSystem.js";
 import FileObject from "./FileObject.js";
-import VFileObject from "./VFileObject.js";
 //# sourceMappingURL=DirectoryObject.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"DirectoryObject.d.ts","sourceRoot":"","sources":["../../../src/node/lib/DirectoryObject.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH;IA2DE;;;;;;;;;OASG;IACH,kBALa,eAAe,CAO3B;IA3CD;;;;OAIG;IACH,uBAFW,MAAM,OAAC,EA0BjB;IA2BD;;;;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;;;;;;;;;;;;OAYG;IACH,cARa,eAAe,GAAC,IAAI,CAsBhC;IAED;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAmBD;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAZW,MAAM,GACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,GAAC,WAAW,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,GAAC,gBAAgB,CAAC,CAAA;KAAC,CAAC,CA0CjH;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,WAZW,MAAM,GACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,GAAC,WAAW,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,GAAC,gBAAgB,CAAC,CAAA;KAAC,CAAC,CAgDjH;IAED;;;;;;;;;;;;OAYG;IACH,uBARW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAuBzB;IAyBD;;;;;;;;;;;;;;;OAeG;IACH,cAZa,eAAe,CAc3B;IAED;;;;;;;;;;;;;;OAcG;IACH,UARa,OAAO,CAAC,IAAI,CAAC,CAkBzB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAQ5B;IAED;;;;;OAKG;IACH,sBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAO5B;IAgED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,kBAdW,MAAM,GACJ,eAAe,CA6C3B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,cAfW,MAAM,GACJ,UAAU,GAAC,WAAW,CA6ClC;;CACF;eAnrBc,iBAAiB;uBADT,iBAAiB;wBAIhB,kBAAkB"}
+{"version":3,"file":"DirectoryObject.d.ts","sourceRoot":"","sources":["../../../src/node/lib/DirectoryObject.js"],"names":[],"mappings":"AAgBA;;;;GAIG;AAEH;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH;IAuDE;;;;;;;;;OASG;IACH,kBALa,eAAe,CAO3B;IA7CD;;;;OAIG;IACH,uBAFW,MAAM,OAAC,EA4BjB;IAyBD;;;;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;;;;;;;;;;;;OAYG;IACH,cARa,eAAe,GAAC,IAAI,CAsBhC;IAED;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAmBD;;;;;;;;;;;;;;;;;OAiBG;IACH,WAZW,MAAM,GACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;KAAC,CAAC,CAwCpF;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAZW,MAAM,GACJ,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,GAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;KAAC,CAAC,CA2C/F;IAED;;;;;;;;;;;;OAYG;IACH,uBARW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAuBzB;IAyBD;;;;;;;;;;;;;;;OAeG;IACH,cAZa,eAAe,CAc3B;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,CA6B3B;IAED;;;;;;;;;;;OAWG;IACH,kBAPW,MAAM,GACJ,UAAU,CA6BtB;;CACF;;UAvkBa,MAAY;QAAC,KAAK,EAAE,eAAe,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAC;eACnD,MAAY,aAAa;;;;;;iBAMzB,OAAO;;;;eACP,MAAM,GAAC,IAAI;;;;YACX,MAAM,GAAC,IAAI;;;;UACX,MAAM,GAAC,IAAI;;;;YACX,eAAe,GAAC,SAAS;;;;gBACzB,MAAM,GAAC,IAAI;;;;UACX,MAAM,GAAC,IAAI;;;;SACX,MAAM,GAAC,IAAI;;;;cACX,MAAM,GAAC,IAAI;;;;WACX,KAAK,CAAC,MAAM,CAAC,GAAC,IAAI;;;;SAClB,GAAG,GAAC,IAAI;;eAvBP,iBAAiB;uBADT,iBAAiB"}

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

@@ -22,16 +22,6 @@ export default class FileObject extends FS {
     static dataLoaderConfig: {
         [key: string]: Array<typeof JSON5 | typeof YAML>;
     };
-    /**
-     * Strip root from absolute path to make it relative.
-     * Used for virtual filesystem path resolution.
-     *
-     * @private
-     * @static
-     * @param {string} pathName - The path to convert
-     * @returns {string} Path with root stripped, or original if already relative
-     */
-    private static "__#private@#absoluteToRelative";
     /**
      * Constructs a FileObject instance.
      *
@@ -221,4 +211,6 @@ export default class FileObject extends FS {
 }
 import FS from "./FileSystem.js";
 import DirectoryObject from "./DirectoryObject.js";
+import JSON5 from "json5";
+import YAML from "yaml";
 //# sourceMappingURL=FileObject.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"FileObject.d.ts","sourceRoot":"","sources":["../../../src/node/lib/FileObject.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;GAaG;AAEH;IACE;;;;;OAKG;IACH,yBAFU;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,OAAO,KAAK,GAAG,OAAO,IAAI,CAAC,CAAA;KAAC,CAO1D;IA0BF;;;;;;;;OAQG;IACH,gDAOC;IAED;;;;;OAKG;IACH,uBAHW,MAAM,WACN,eAAe,GAAC,MAAM,GAAC,IAAI,EA6DrC;IAaD;;;;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;;;;;;;;;;;;;;OAcG;IACH,cAFa,eAAe,CAI3B;IAED;;;;OAIG;IACH,kBAFa,MAAM,CAIlB;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;IAED;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CAS3B;IAED;;;;;;;;;;;OAWG;IACH,cARa,OAAO,CAAC,MAAM,CAAC,CAe3B;IAED;;;;;;;;;;;OAWG;IACH,eARW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAiBzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,kBAXW,WAAW,GAAC,IAAI,GAAC,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAwBzB;IAED;;;;;;;;;;;;;;OAcG;IACH,gBAXW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAiC5B;IAED;;;;OAIG;IACH,UAFa,OAAO,CAAC,MAAM,CAAC,CAS3B;IAED;;;;;;;;;OASG;IACH,UAPa,OAAO,CAAC,IAAI,CAAC,CAczB;;CACF;eA9ec,iBAAiB;4BADJ,sBAAsB"}
+{"version":3,"file":"FileObject.d.ts","sourceRoot":"","sources":["../../../src/node/lib/FileObject.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;GAaG;AAEH;IACE;;;;;OAKG;IACH,yBAFU;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC,OAAO,KAAK,GAAG,OAAO,IAAI,CAAC,CAAA;KAAC,CAO1D;IA0BF;;;;;OAKG;IACH,uBAHW,MAAM,WACN,eAAe,GAAC,MAAM,GAAC,IAAI,EA+DrC;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;;;;;;;;;;;;;;OAcG;IACH,cAFa,eAAe,CAI3B;IAED;;;;OAIG;IACH,kBAFa,MAAM,CAIlB;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;IAED;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CAS3B;IAED;;;;;;;;;;;OAWG;IACH,cARa,OAAO,CAAC,MAAM,CAAC,CAe3B;IAED;;;;;;;;;;;OAWG;IACH,eARW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAiBzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,kBAXW,WAAW,GAAC,IAAI,GAAC,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAwBzB;IAED;;;;;;;;;;;;;;OAcG;IACH,gBAXW,MAAM,aACN,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAiC5B;IAED;;;;OAIG;IACH,UAFa,OAAO,CAAC,MAAM,CAAC,CAS3B;IAED;;;;;;;;;OASG;IACH,UAPa,OAAO,CAAC,IAAI,CAAC,CAczB;;CACF;eA5dc,iBAAiB;4BADJ,sBAAsB;kBAPhC,OAAO;iBAER,MAAM"}

package/types/node/lib/FileSystem.d.ts

@@ -126,6 +126,8 @@ export default class FileSystem {
      * @property {string} base - The file name with extension
      * @property {string} dir - The directory path
      * @property {string} ext - The file extension (including dot)
+     * @property {string} root - The root of the path
+     * @property {string} name - The file name without extension
      */
     /**
      * Deconstruct a file or directory name into parts.
@@ -148,26 +150,21 @@ export default class FileSystem {
          * - The file extension (including dot)
          */
         ext: string;
+        /**
+         * - The root of the path
+         */
+        root: string;
+        /**
+         * - The file name without extension
+         */
+        name: string;
     };
     /**
-     * Convert a virtual capped path to its real filesystem path.
-     * For capped objects, resolves the virtual path relative to the cap's real path.
-     * For uncapped objects, returns the path unchanged.
+     * Returns the current working directory as a string.
      *
-     * @static
-     * @param {FileObject|DirectoryObject} fileOrDirectoryObject - The file or directory object to convert
-     * @returns {string} The real filesystem path
-     * @throws {Sass} If parameter is not a FileObject or DirectoryObject
-     * @example
-     * const temp = new TempDirectoryObject("myapp")
-     * const file = temp.getFile("/config.json")
-     * FS.virtualToRealPath(file) // "/tmp/myapp-ABC123/config.json"
-     *
-     * @example
-     * const regular = new FileObject("/home/user/file.txt")
-     * FS.virtualToRealPath(regular) // "/home/user/file.txt"
+     * @returns {string} The current working directory
      */
-    static virtualToRealPath(fileOrDirectoryObject: FileObject | DirectoryObject): string;
+    static get cwd(): string;
     /**
      * Compute the relative path from another file or directory to this instance.
      *

package/types/node/lib/FileSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FileSystem.d.ts","sourceRoot":"","sources":["../../../src/node/lib/FileSystem.js"],"names":[],"mappings":"AA0BA;;GAEG;AACH;IACE,kCAAwB;IACxB,uCAAkC;IAClC,mBAAsB;IAsBtB;;;;;;OAMG;IACH,4BAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,2BAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;;;;OAMG;IACH,2BAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;;;;;;;;OAUG;IACH,gCAJW,UAAU,GAAC,eAAe,MAC1B,UAAU,GAAC,eAAe,GACxB,MAAM,CAYlB;IAED;;;;;;;;;;OAUG;IACH,oCAJW,MAAM,MACN,MAAM,GACJ,MAAM,CAQlB;IAED;;;;;;;;;OASG;IACH,oCALW,MAAM,SACN,MAAM,QACN,MAAM,GACJ,MAAM,CA0BlB;IAED;;;;;;;;OAQG;IACH,6BAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAmClB;IAED;;;;;;;;;;;;OAYG;IACH,+BATW,MAAM,aACN,MAAM,GACJ,OAAO,CAcnB;IAED;;;;;;;;;;;;;;OAcG;IACH,4BATW,MAAM,MACN,MAAM,QACN,MAAM,GACJ,MAAM,GAAC,IAAI,CAwBvB;IAED;;;;;;;;;;;;;;;OAeG;IACH,+BAXW,MAAM,MACN,MAAM,QACN,MAAM,GACJ,MAAM,GAAC,IAAI,CA+BvB;IAED;;;;;OAKG;IAEH;;;;;;;OAOG;IACH,2BAJW,MAAM;;;;cATH,MAAM;;;;aACN,MAAM;;;;aACN,MAAM;MAenB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,gDAZW,UAAU,GAAC,eAAe,GACxB,MAAM,CAiClB;IAtVD;;;;;;;;;OASG;IACH,kCAJW,UAAU,GAAC,eAAe,GACxB,MAAM,CAWlB;CAqUF;yBAxWa,OAAO,iBAAiB,EAAE,OAAO;8BACjC,OAAO,sBAAsB,EAAE,OAAO"}
+{"version":3,"file":"FileSystem.d.ts","sourceRoot":"","sources":["../../../src/node/lib/FileSystem.js"],"names":[],"mappings":"AA2BA;;GAEG;AACH;IACE,kCAAwB;IACxB,uCAAkC;IAClC,mBAAsB;IAsBtB;;;;;;OAMG;IACH,4BAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,2BAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;;;;OAMG;IACH,2BAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;;;;;;;;OAUG;IACH,gCAJW,UAAU,GAAC,eAAe,MAC1B,UAAU,GAAC,eAAe,GACxB,MAAM,CAYlB;IAED;;;;;;;;;;OAUG;IACH,oCAJW,MAAM,MACN,MAAM,GACJ,MAAM,CAQlB;IAED;;;;;;;;;OASG;IACH,oCALW,MAAM,SACN,MAAM,QACN,MAAM,GACJ,MAAM,CA0BlB;IAED;;;;;;;;OAQG;IACH,6BAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAmClB;IAED;;;;;;;;;;;;OAYG;IACH,+BATW,MAAM,aACN,MAAM,GACJ,OAAO,CAcnB;IAED;;;;;;;;;;;;;;OAcG;IACH,4BATW,MAAM,MACN,MAAM,QACN,MAAM,GACJ,MAAM,GAAC,IAAI,CAwBvB;IAED;;;;;;;;;;;;;;;OAeG;IACH,+BAXW,MAAM,MACN,MAAM,QACN,MAAM,GACJ,MAAM,GAAC,IAAI,CA+BvB;IAED;;;;;;;OAOG;IAEH;;;;;;;OAOG;IACH,2BAJW,MAAM;;;;cAXH,MAAM;;;;aACN,MAAM;;;;aACN,MAAM;;;;cACN,MAAM;;;;cACN,MAAM;MAenB;IAED;;;;OAIG;IACH,kBAFa,MAAM,CAIlB;IAvTD;;;;;;;;;OASG;IACH,kCAJW,UAAU,GAAC,eAAe,GACxB,MAAM,CAWlB;CAsSF;yBAzUa,OAAO,iBAAiB,EAAE,OAAO;8BACjC,OAAO,sBAAsB,EAAE,OAAO"}

package/types/node/lib/Glog.d.ts

@@ -348,13 +348,6 @@ declare class Glog {
      * @returns {boolean} return.stackTrace - Stack trace enabled
      */
     get options(): object;
-    /**
-     * Extract file and function information from stack trace
-     *
-     * @private
-     * @returns {string} Caller tag
-     */
-    private extractFileFunction;
     /**
      * Create a new debug function with a specific tag
      *

package/types/node/lib/Glog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Glog.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Glog.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"Glog.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Glog.js"],"names":[],"mappings":"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"}

package/types/node/lib/Valid.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Options for type validation methods.
+ *
+ * @typedef {object} TypeValidationOptions
+ * @property {boolean} [allowEmpty=true] - Whether empty values are allowed
+ */
 /**
  * Validation utility class providing type checking and assertion methods.
  */
@@ -8,9 +14,9 @@ export default class Valid {
      *
      * @param {unknown} value - The value to validate
      * @param {string} type - The expected type in the form of "object", "object[]", "object|object[]"
-     * @param {object} [options] - Additional options for validation.
+     * @param {TypeValidationOptions} [options] - Additional options for validation.
      */
-    static type(value: unknown, type: string, options?: object): void;
+    static type(value: unknown, type: string, options?: TypeValidationOptions): void;
     /**
      * Asserts a condition
      *
@@ -32,4 +38,13 @@ export default class Valid {
      */
     static prototypePollutionProtection(keys: Array<string>): void;
 }
+/**
+ * Options for type validation methods.
+ */
+export type TypeValidationOptions = {
+    /**
+     * - Whether empty values are allowed
+     */
+    allowEmpty?: boolean;
+};
 //# sourceMappingURL=Valid.d.ts.map

package/types/node/lib/Valid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Valid.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Valid.js"],"names":[],"mappings":"AAWA;;GAEG;AACH;IACE,+CAAmE;IAEnE;;;;;;OAMG;IACH,mBAJW,OAAO,QACP,MAAM,YACN,MAAM,QAYhB;IAED;;;;;;;;OAQG;IACH,yBANW,OAAO,WACP,MAAM,QAEN,MAAM,QAkBhB;IAED;;;;;;;;OAQG;IACH,0CAHW,KAAK,CAAC,MAAM,CAAC,QAYvB;CACF"}
+{"version":3,"file":"Valid.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Valid.js"],"names":[],"mappings":"AAWA;;;;;GAKG;AAEH;;GAEG;AACH;IACE,+CAAmE;IAEnE;;;;;;OAMG;IACH,mBAJW,OAAO,QACP,MAAM,YACN,qBAAqB,QAY/B;IAED;;;;;;;;OAQG;IACH,yBANW,OAAO,WACP,MAAM,QAEN,MAAM,QAkBhB;IAED;;;;;;;;OAQG;IACH,0CAHW,KAAK,CAAC,MAAM,CAAC,QAYvB;CACF;;;;;;;;iBAzEa,OAAO"}

package/src/node/lib/TempDirectoryObject.js

@@ -1,165 +0,0 @@
-/**
- * @file TempDirectoryObject.js
- * @description Class representing a temporary directory that is constrained
- * to the OS's temporary directory tree.
- */
-
-import fs, {mkdirSync, mkdtempSync} from "node:fs"
-import os from "node:os"
-import path from "node:path"
-
-import Data from "../../browser/lib/Data.js"
-import VDirectoryObject from "./VDirectoryObject.js"
-import DirectoryObject from "./DirectoryObject.js"
-import FileSystem from "./FileSystem.js"
-import Sass from "./Sass.js"
-import Valid from "./Valid.js"
-
-/**
- * TempDirectoryObject extends VDirectoryObject with the cap set to
- * the OS's temporary directory. Temporary directories are created
- * synchronously during construction and exist immediately.
- *
- * All path operations are validated to ensure they remain within the temp
- * directory hierarchy for security.
- *
- * @augments VDirectoryObject
- */
-export default class TempDirectoryObject extends VDirectoryObject {
-  #tmpReal
-  #tmpCap
-
-  /**
-   * Constructs a TempDirectoryObject instance and creates the directory.
-   *
-   * The directory is created synchronously during construction, so it will
-   * exist immediately after the constructor returns.
-   *
-   * If no name is provided, uses the OS temp directory directly. If a name
-   * is provided without a parent, creates a new directory with a unique suffix.
-   * If a parent is provided, creates a subdirectory within that parent.
-   *
-   * @param {string?} [directory] - Base name for the temp directory (if empty/null, uses OS temp dir)
-   * @param {TempDirectoryObject?} [parent] - Optional parent temporary directory
-   * @throws {Sass} If name is absolute
-   * @throws {Sass} If name is empty (when parent is provided)
-   * @throws {Sass} If name contains path separators
-   * @throws {Sass} If parent is provided but not a temporary directory
-   * @throws {Sass} If parent's lineage does not trace back to the OS temp directory
-   * @throws {Sass} If directory creation fails
-   * @example
-   * // Create with unique name
-   * const temp = new TempDirectoryObject("myapp")
-   * console.log(temp.path) // "/"
-   * console.log(temp.real.path) // "/tmp/myapp-ABC123"
-   */
-  constructor(directory, source=null) {
-    Valid.type(source, "Null|TempDirectoryObject")
-
-    directory ||= "temp"
-    directory = Data.append(directory, source ? "" : "-")
-
-    const parentRealPath = source?.real.path ?? os.tmpdir()
-
-    if(source && path.isAbsolute(directory)) {
-      const {root} = FileSystem.pathParts(directory)
-
-      directory = Data.chopLeft(directory, root)
-    }
-
-    let realTempDirectoryPath, toSuper
-
-    if(source) {
-      toSuper = `/${directory}`
-      realTempDirectoryPath =
-        FileSystem.mergeOverlappingPaths(parentRealPath, directory)
-      if(!fs.existsSync(realTempDirectoryPath))
-        mkdirSync(realTempDirectoryPath)
-    } else {
-      realTempDirectoryPath =
-        mkdtempSync(FileSystem.mergeOverlappingPaths(os.tmpdir(), directory))
-      toSuper = path.resolve(path.sep)
-    }
-
-    super(toSuper, source)
-
-    this.#tmpReal = new DirectoryObject(realTempDirectoryPath)
-    this.#tmpCap = source?.cap ?? this
-  }
-
-  get isTemporary() {
-    return true
-  }
-
-  /**
-   * Returns a plain DirectoryObject representing the actual filesystem location.
-   * This provides an "escape hatch" from the capped environment to interact
-   * with the real filesystem when needed.
-   *
-   * @returns {DirectoryObject} Uncapped directory object at the real filesystem path
-   * @example
-   * const temp = new TempDirectoryObject("myapp")
-   * const subdir = temp.getDirectory("data")
-   *
-   * // Work within the capped environment (virtual paths)
-   * console.log(subdir.path)        // "/data" (virtual)
-   * subdir.getFile("config.json")   // Stays within cap
-   *
-   * // Break out to real filesystem when needed
-   * console.log(subdir.real.path)   // "/tmp/myapp-ABC123/data" (real)
-   * subdir.real.parent              // Can traverse outside the cap
-   */
-  get real() {
-    return this.#tmpReal
-  }
-
-  get cap() {
-    return this.#tmpCap
-  }
-
-  /**
-   * 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 = new TempDirectoryObject("my-temp")
-   * await tempDir.assureExists()
-   * // ... use the directory ...
-   * await tempDir.remove() // Recursively deletes everything
-   */
-  async remove() {
-    await this.#recurseDelete(this.real)
-  }
-
-  async #recurseDelete(directory) {
-    const {files, directories} = await directory.read()
-
-    // files first
-    for(const file of files)
-      await file.delete()
-
-    // now dir-ty dirs
-    for(const dir of directories)
-      await this.#recurseDelete(dir)
-
-    // byebyebyeeee 🕺🏾
-    await directory.delete()
-  }
-
-  /**
-   * TempDirectoryObject does not support fromCwd() since it is specifically
-   * designed to work within the OS temporary directory tree.
-   *
-   * @throws {Sass} Always throws an error
-   */
-  static fromCwd() {
-    throw Sass.new("TempDirectoryObject.fromCwd() is not supported.")
-  }
-}