@gesslar/toolkit 3.9.0 → 3.13.0

package/src/lib/DirectoryObject.js

@@ -7,12 +7,12 @@
 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"
 
-import {Data, Valid} from "../browser/index.js"
+import Data from "../browser/lib/Data.js"
 import FS from "./FS.js"
 import FileObject from "./FileObject.js"
 import Sass from "./Sass.js"
+import Valid from "./Valid.js"
 
 /**
  * DirectoryObject encapsulates metadata and operations for a directory,
@@ -24,7 +24,6 @@ import Sass from "./Sass.js"
  * - 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
@@ -34,7 +33,6 @@ import Sass from "./Sass.js"
  * @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 {DirectoryObject|null} parent - The parent directory (null if root)
@@ -87,48 +85,45 @@ export default class DirectoryObject extends FS {
     isDirectory: true,
     trail: null,
     sep: null,
-    temporary: null,
+    parent: undefined,
+    parentPath: undefined,
   })
 
-  /**
-   * Cached parent directory object
-   *
-   * @type {DirectoryObject|null|undefined}
-   * @private
-   */
+  // Not in the meta, because it gets frozen, and these are lazily
+  // set.
   #parent = undefined
 
   /**
    * Constructs a DirectoryObject instance.
    *
-   * @param {string? | DirectoryObject?} [directory="."] - The directory path or DirectoryObject (defaults to current directory)
-   * @param {boolean} [temporary] - Whether this is a temporary directory.
+   * @param {string?} [directory="."] - The directory path or DirectoryObject (defaults to current directory)
    */
-  constructor(directory=".", temporary=false) {
-    super()
+  constructor(directory) {
+    directory ||= "."
 
-    Valid.type(directory, "String|TempDirectoryObject|DirectoryObject")
+    Valid.type(directory, "String")
 
-    // If passed a DirectoryObject, extract its path
-    if(Data.isType(directory, "DirectoryObject") || Data.isType(directory, "TempDirectoryObject"))
-      directory = directory.path
+    super()
 
     const fixedDir = FS.fixSlashes(directory)
     const resolved = path.resolve(fixedDir)
-    const url = new URL(FS.pathToUri(resolved))
-    const baseName = path.basename(resolved) || "."
+    const url = new URL(FS.pathToUrl(resolved))
+    const baseName = path.basename(resolved) || ""
     const trail = resolved.split(path.sep)
     const sep = path.sep
+    const pathParts = FS.pathParts(resolved)
 
     this.#meta.supplied = fixedDir
     this.#meta.path = resolved
     this.#meta.url = url
     this.#meta.name = baseName
     this.#meta.extension = ""
-    this.#meta.module = baseName
+    this.#meta.module = baseName !== "." ? baseName : ""
     this.#meta.trail = trail
     this.#meta.sep = sep
-    this.#meta.temporary = temporary
+    this.#meta.parentPath = pathParts.dir === pathParts.root
+      ? null
+      : pathParts.dir
 
     Object.freeze(this.#meta)
   }
@@ -153,36 +148,9 @@ export default class DirectoryObject extends FS {
    * @returns {string} string representation of the DirectoryObject
    */
   toString() {
-    return `[DirectoryObject: ${this.path}]`
-  }
-
-  /**
-   * Returns a JSON representation of the DirectoryObject.
-   *
-   * @returns {object} JSON representation of the DirectoryObject
-   */
-  toJSON() {
-    return {
-      supplied: this.supplied,
-      path: this.path,
-      url: this.url.toString(),
-      name: this.name,
-      module: this.module,
-      extension: this.extension,
-      isFile: this.isFile,
-      isDirectory: this.isDirectory,
-      parent: this.parent ? this.parent.path : null,
-      root: this.root.path
-    }
-  }
-
-  /**
-   * Custom inspect method for Node.js console.
-   *
-   * @returns {object} JSON representation of this object.
-   */
-  [util.inspect.custom]() {
-    return this.toJSON()
+    return this.isCapped
+      ?`[${this.constructor.name}: ${this.path} → ${this.real.path}]`
+      :`[${this.constructor.name}: ${this.path}]`
   }
 
   /**
@@ -269,15 +237,6 @@ 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
-  }
-
   /**
    * Returns the parent directory of this directory.
    * Returns null if this directory is the root directory.
@@ -293,84 +252,18 @@ export default class DirectoryObject extends FS {
    */
   get parent() {
     // Return cached value if available
-    if(this.#parent !== undefined) {
+    if(this.#parent !== undefined)
       return this.#parent
-    }
 
-    // Compute parent directory (null if we're at root)
-    const parentPath = path.dirname(this.path)
-    const isRoot = parentPath === this.path
-
-    // Cache and return
-    this.#parent = isRoot
-      ? null
-      : new DirectoryObject(parentPath, this.temporary)
+    if(this.#meta.parentPath === null) {
+      this.#parent = null
 
-    return this.#parent
-  }
-
-  /**
-   * Returns the root directory of the filesystem.
-   *
-   * For DirectoryObject, this walks up to the filesystem root.
-   * For CappedDirectoryObject, this returns the cap root.
-   *
-   * @returns {DirectoryObject} The root directory
-   * @example
-   * const dir = new DirectoryObject("/usr/local/bin")
-   * console.log(dir.root.path)  // "/"
-   *
-   * @example
-   * const capped = new CappedDirectoryObject("/projects/myapp")
-   * const sub = capped.getDirectory("src/lib")
-   * console.log(sub.root.path)  // "/" (virtual, cap root)
-   * console.log(sub.root.real.path)  // "/projects/myapp"
-   */
-  get root() {
-    // Walk up until we find a directory with no parent
-    let current = this
-
-    while(current.parent !== null) {
-      current = current.parent
+      return this.#parent
     }
 
-    return current
-  }
+    this.#parent = new this.constructor(this.#meta.parentPath)
 
-  /**
-   * 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() {
-    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()
+    return this.#parent
   }
 
   /**
@@ -397,11 +290,15 @@ export default class DirectoryObject extends FS {
    * @returns {Promise<boolean>} Whether the directory exists
    */
   async #directoryExists() {
+    const path = this.isCapped
+      ? this.cap?.real.path
+      : this.path
+
     try {
-      (await opendir(this.path)).close()
+      (await opendir(path)).close()
 
       return true
-    } catch(_) {
+    } catch {
       return false
     }
   }
@@ -423,14 +320,27 @@ export default class DirectoryObject extends FS {
    * console.log(files) // Only .js files in ./src
    */
   async read(pat="") {
-    const cwd = this.path, withFileTypes = true
+    const withFileTypes = true
+    const url = this.isCapped
+      ? this.real?.url
+      : this.url
+
+    Valid.type(url, "URL")
+    // const href = url.href
+
     const found = !pat
-      ? await readdir(this.url, {withFileTypes})
+      ? await readdir(url, {withFileTypes})
       : await Array.fromAsync(
         glob(pat, {
-          cwd,
+          cwd: this.isCapped ? this.real?.path : this.path,
           withFileTypes,
-          exclude: candidate => candidate.parentPath !== cwd
+          // exclude: candidate => {
+          // // Only allow entries within this directory's URL
+          //   const candidateHref = candidate.url.href
+
+          //   // Must start with our URL + path separator, or be exactly our URL
+          //   return !candidateHref.startsWith(href + "/") && candidateHref !== href
+          // }
         })
       )
 
@@ -441,9 +351,9 @@ export default class DirectoryObject extends FS {
     const directories = found
       .filter(dirent => dirent.isDirectory())
       .map(dirent => {
-        const dirPath = path.join(this.path, dirent.name)
+        const dirPath = FS.resolvePath(this.path, dirent.name)
 
-        return new DirectoryObject(dirPath, this.temporary)
+        return new this.constructor(dirPath, this)
       })
 
     return {files, directories}
@@ -486,31 +396,26 @@ export default class DirectoryObject extends FS {
    * @yields {DirectoryObject} Parent directory objects from current to root
    */
   *#walkUp() {
-    if(!Array.isArray(this.trail))
-      return
-
-    const curr = structuredClone(this.trail)
+    const {root, base, dir} = FS.pathParts(this.path)
+    const sep = path.sep
+    // Remove the root and then re-add it every loop, because that's fun!
+    const choppedDir = Data.chopLeft(dir, root)
+    const trail = [...choppedDir.split(sep).filter(Boolean), base]
 
-    while(curr.length > 0) {
-      const joined = curr.join(this.sep)
+    if(trail.length === 0)
+      return yield this
 
-      // Stop if we've reached an empty path (which would resolve to CWD)
-      if(joined === "" || joined === this.sep) {
-        // Yield the root and stop
-        yield new DirectoryObject(this.sep)
-        break
-      }
+    do
+      yield new this.constructor(path.join(root, ...trail), this.cap)
 
-      yield new DirectoryObject(joined)
-      curr.pop()
-    }
+    while(trail.pop())
   }
 
   /**
    * Generator that walks up the directory tree, yielding each parent directory.
    * Starts from the current directory and yields each parent until reaching the root.
    *
-   * @returns {object} Generator yielding parent DirectoryObject instances
+   * @returns {DirectoryObject} Generator yielding parent DirectoryObject instances
    * @example
    * const dir = new DirectoryObject('/path/to/deep/directory')
    * for(const parent of dir.walkUp) {
@@ -578,6 +483,14 @@ export default class DirectoryObject extends FS {
     return await directory.exists
   }
 
+  #isLocal = candidate => {
+    Valid.type(candidate, "String", {allowEmpty: false})
+
+    const {dir: candidateDir} = FS.pathParts(candidate)
+
+    return candidateDir === this.path
+  }
+
   /**
    * Creates a new DirectoryObject by extending this directory's path.
    *
@@ -585,7 +498,7 @@ export default class DirectoryObject extends FS {
    * duplication (e.g., "/projects/toolkit" + "toolkit/src" = "/projects/toolkit/src").
    * The temporary flag is preserved from the parent directory.
    *
-   * @param {string} newPath - The subdirectory path to append (can be nested like "src/lib")
+   * @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
    * @example
@@ -599,13 +512,14 @@ export default class DirectoryObject extends FS {
    * const subDir = dir.getDirectory("toolkit/src")
    * console.log(subDir.path) // "/projects/toolkit/src" (not /projects/toolkit/toolkit/src)
    */
-  getDirectory(newPath) {
-    Valid.type(newPath, "String")
+  getDirectory(dir) {
+    Valid.type(dir, "String", {allowEmpty: false})
+
+    const newPath = FS.resolvePath(this.path, dir)
 
-    const thisPath = this.path
-    const merged = FS.mergeOverlappingPaths(thisPath, newPath)
+    Valid.assert(this.#isLocal(newPath), `${newPath} would be out of bounds.`)
 
-    return new this.constructor(merged, this.temporary)
+    return new this.constructor(newPath, this)
   }
 
   /**
@@ -615,7 +529,7 @@ export default class DirectoryObject extends FS {
    * duplication. The resulting FileObject can be used for reading, writing,
    * and other file operations.
    *
-   * @param {string} filename - The filename to append (can include subdirectories like "src/index.js")
+   * @param {string} file - 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
@@ -628,11 +542,13 @@ export default class DirectoryObject extends FS {
    * const file = dir.getFile("src/index.js")
    * const data = await file.read()
    */
-  getFile(filename) {
-    Valid.type(filename, "String")
+  getFile(file) {
+    Valid.type(file, "String", {allowEmpty: false})
+
+    const newPath = FS.resolvePath(this.path, file)
+
+    Valid.assert(this.#isLocal(newPath), `${newPath} would be out of bounds.`)
 
-    // Pass the filename and this directory as parent
-    // This ensures the FileObject maintains the correct parent reference
-    return new FileObject(filename, this)
+    return new FileObject(newPath, this)
   }
 }