@gesslar/toolkit 3.12.3 → 3.14.0

package/src/node/lib/VDirectoryObject.js

@@ -0,0 +1,198 @@
+/**
+ * @file VDirectoryObject.js
+ * @description Abstract base class for directory objects that are constrained
+ * to a specific directory tree (the "cap"). This provides security by ensuring
+ * all operations remain within the capped directory hierarchy.
+ *
+ * This class is not intended to be instantiated directly. Use subclasses like
+ * TempDirectoryObject that define specific caps.
+ */
+
+import path from "node:path"
+
+import DirectoryObject from "./DirectoryObject.js"
+import FileSystem from "./FileSystem.js"
+import Valid from "./Valid.js"
+
+/**
+ * VDirectoryObject extends DirectoryObject with constraints that ensure
+ * all operations are restricted to a specific directory tree (the "cap").
+ *
+ * All path operations are validated to ensure they remain within the
+ * cap directory hierarchy for security.
+ *
+ * @augments DirectoryObject
+ */
+export default class VDirectoryObject extends DirectoryObject {
+  #real
+  #cap
+  #cappedParentPath
+  #cappedParent
+
+  /**
+   * Constructs a VDirectoryObject instance.
+   *
+   * Without a parent, creates a new cap at the specified real directory location
+   * with virtual path "/". With a parent, the path is resolved relative to the
+   * parent's virtual path (absolute paths treated as cap-relative).
+   *
+   * @param {string} [directory="."] - Real directory path when no parent (becomes cap), or relative/absolute virtual path when parent provided
+   * @param {VDirectoryObject?} [parent] - Optional parent capped directory
+   * @throws {Sass} If parent is provided but not a VDirectoryObject
+   * @example
+   * // Create new capped directory at current directory
+   * const cwd = new VDirectoryObject()
+   * // Virtual path: "/", Real path: process.cwd(), Cap: itself
+   *
+   * @example
+   * // Create new capped directory
+   * const cache = new VDirectoryObject("/home/user/.cache")
+   * // Virtual path: "/", Real path: /home/user/.cache, Cap: itself
+   *
+   * @example
+   * // Create subdirectory with parent
+   * const data = new VDirectoryObject("data", cache)
+   * // Virtual path: /data, Real path: /home/user/.cache/data, Cap: cache
+   *
+   * @example
+   * // Virtual absolute path with parent (treated as cap-relative)
+   * const config = new VDirectoryObject("/etc/config", cache)
+   * // Virtual path: /etc/config, Real path: /home/user/.cache/etc/config, Cap: cache
+   */
+  constructor(directory, source=null) {
+    Valid.type(source, "Null|VDirectoryObject")
+
+    directory ||= "."
+
+    const baseLocalPath = source?.path ?? "/"
+    const baseRealPath = source?.real.path ?? directory
+
+    if(source && directory.startsWith("/"))
+      directory = directory.slice(1)
+
+    // Find out what directory means to the basePath
+    const realResolved = FileSystem.resolvePath(baseRealPath, directory)
+    const localResolved = source
+      ? FileSystem.resolvePath(baseLocalPath, directory)
+      : path.parse(path.resolve("")).root
+
+    super(localResolved)
+
+    this.#real = new DirectoryObject(realResolved)
+    this.#cap = source?.cap ?? this
+
+    if(source) {
+      this.#cappedParent = source
+      this.#cappedParentPath = source.path
+    } else {
+      this.#cappedParent = null
+      this.#cappedParentPath = null
+    }
+  }
+
+  /**
+   * Creates a VDirectoryObject from the current working directory.
+   * This is useful when working with pnpx or other tools where you need to
+   * cap at the project's root directory determined at runtime.
+   *
+   * @returns {VDirectoryObject} A VDirectoryObject capped at the current working directory
+   * @example
+   * // When using pnpx or similar tools
+   * const projectRoot = VDirectoryObject.fromCwd()
+   * const srcDir = projectRoot.getDirectory("src")
+   * // srcDir is capped at the project root
+   */
+  static fromCwd() {
+    return new this(process.cwd())
+  }
+
+  /**
+   * Indicates whether this directory is capped (constrained to a specific tree).
+   * Always returns true for VDirectoryObject instances.
+   *
+   * @returns {boolean} True for all VDirectoryObject instances
+   * @example
+   * const capped = new TempDirectoryObject("myapp")
+   * console.log(capped.isVirtual) // true
+   *
+   * const regular = new DirectoryObject("/tmp")
+   * console.log(regular.isVirtual) // false
+   */
+  get isVirtual() {
+    return true
+  }
+
+  /**
+   * Returns the cap (root) of the capped directory tree.
+   * For root VDirectoryObject instances, returns itself.
+   * For children, returns the inherited cap from the parent chain.
+   *
+   * @returns {VDirectoryObject} The cap directory object (root of the capped tree)
+   * @example
+   * const temp = new TempDirectoryObject("myapp")
+   * console.log(temp.cap === temp) // true (root is its own cap)
+   *
+   * const subdir = temp.getDirectory("data")
+   * console.log(subdir.cap === temp) // true (child inherits parent's cap)
+   */
+  get cap() {
+    return this.#cap
+  }
+
+  /**
+   * 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.#real
+  }
+
+  /**
+   * Returns the parent directory of this capped directory.
+   * Returns null only if this directory is at the cap (the "root" of the capped tree).
+   *
+   * Note: The returned parent is a VDirectoryObject with the same cap.
+   * This maintains the capping behavior throughout the directory hierarchy.
+   *
+   * @returns {VDirectoryObject|null} Parent directory or null if at cap root
+   * @example
+   * const capped = new TempDirectoryObject("myapp")
+   * const subdir = capped.getDirectory("data")
+   * console.log(subdir.parent.path) // Returns parent VDirectoryObject
+   * console.log(capped.parent) // null (at cap root)
+   */
+  get parent() {
+    return this.#cappedParent
+  }
+
+  /**
+   * Returns the path of the parent directory.
+   * Returns null if this directory is at the cap root (no parent).
+   *
+   * @returns {string|null} The parent directory path, or null if at cap root
+   * @example
+   * const temp = new TempDirectoryObject("myapp")
+   * console.log(temp.parentPath) // null (at cap root)
+   *
+   * const subdir = temp.getDirectory("data")
+   * console.log(subdir.parentPath) // "/" (parent's virtual path)
+   */
+  get parentPath() {
+    return this.#cappedParentPath
+  }
+
+}

package/src/node/lib/VFileObject.js

@@ -0,0 +1,61 @@
+/**
+ * @file VFileObject.js
+ * @description Class representing a virtual file within a capped directory tree.
+ * Extends FileObject with virtual path support and real filesystem mapping.
+ */
+
+import FileObject from "./FileObject.js"
+import FS from "./FileSystem.js"
+import Valid from "./Valid.js"
+
+/**
+ * VFileObject extends FileObject with virtual path support, maintaining both
+ * a virtual path (relative to cap) and a real filesystem path.
+ *
+ * Virtual files must have a VDirectoryObject parent and cannot exist independently.
+ * All file operations use the real filesystem path while exposing clean virtual paths.
+ *
+ * @property {string} supplied - User-supplied path
+ * @property {string} path - The virtual file path (relative to cap)
+ * @property {URL} url - The file URL
+ * @property {string} name - The file name
+ * @property {string} module - The file name without extension
+ * @property {string} extension - The file extension
+ * @property {boolean} isFile - Always true for files
+ * @property {boolean} isVirtual - Always true for VFileObject instances
+ * @property {VDirectoryObject} parent - The parent virtual directory object
+ * @property {FileObject} real - The real filesystem FileObject
+ * @property {Promise<boolean>} exists - Whether the file exists (async)
+ */
+
+export default class VFileObject extends FileObject {
+  #real
+
+  /**
+   * Constructs a VFileObject instance.
+   *
+   * @param {string} fileName - The file path
+   * @param {VDirectoryObject} parent - The parent virtual directory (required)
+   */
+  constructor(fileName, parent) {
+    Valid.type(fileName, "String", {allowEmpty: false})
+    Valid.type(parent, "VDirectoryObject")
+
+    super(fileName, parent)
+
+    const parentRealPath = this.parent.real.path
+    const relative = FS.absoluteToRelative(this.path, true)
+    const resolved = FS.resolvePath(parentRealPath, relative)
+    const {base, dir} = FS.pathParts(resolved)
+
+    this.#real = new FileObject(base, dir)
+  }
+
+  get isVirtual() {
+    return true
+  }
+
+  get real() {
+    return this.#real
+  }
+}

package/src/{lib → node/lib}/Valid.js

@@ -6,8 +6,8 @@
  */
 
 import Sass from "./Sass.js"
-import Data from "../browser/lib/Data.js"
-import Collection from "../browser/lib/Collection.js"
+import Data from "../../browser/lib/Data.js"
+import Collection from "../../browser/lib/Collection.js"
 
 /**
  * Validation utility class providing type checking and assertion methods.
@@ -23,10 +23,14 @@ export default class Valid {
    * @param {object} [options] - Additional options for validation.
    */
   static type(value, type, options) {
+    const expected = [type]
+
+    if(options?.allowEmpty !== true)
+      expected.push("[no empty values]")
+
     Valid.assert(
       Data.isType(value, type, options),
-      `Invalid type. Expected ${type}, got ${Data.typeOf(value)}`,
-      1,
+      `Invalid type. Expected ${expected.join(" ")}, got ${Data.typeOf(value)}`
     )
   }
 
@@ -57,7 +61,9 @@ export default class Valid {
   }
 
   /**
-   * Protects against prototype pollution by checking keys for dangerous property names.
+   * Protects against prototype pollution by checking keys for dangerous
+   * property names.
+   *
    * Throws if any restricted prototype properties are found in the keys array.
    *
    * @param {Array<string>} keys - Array of property keys to validate

package/src/lib/CappedDirectoryObject.js

@@ -1,276 +0,0 @@
-/**
- * @file CappedDirectoryObject.js
- * @description Abstract base class for directory objects that are constrained
- * to a specific directory tree (the "cap"). This provides security by ensuring
- * all operations remain within the capped directory hierarchy.
- *
- * This class is not intended to be instantiated directly. Use subclasses like
- * TempDirectoryObject that define specific caps.
- */
-
-import path from "node:path"
-
-import DirectoryObject from "./DirectoryObject.js"
-import FileObject from "./FileObject.js"
-import FS from "./FS.js"
-import Valid from "./Valid.js"
-
-/**
- * CappedDirectoryObject extends DirectoryObject with constraints that ensure
- * all operations are restricted to a specific directory tree (the "cap").
- *
- * All path operations are validated to ensure they remain within the
- * cap directory hierarchy for security.
- *
- * @augments DirectoryObject
- */
-export default class CappedDirectoryObject extends DirectoryObject {
-  #real
-  #cap
-  #cappedParentPath
-  #cappedParent
-
-  /**
-   * Constructs a CappedDirectoryObject instance.
-   *
-   * Without a parent, the path becomes both the directory location and the cap
-   * (virtual root). With a parent, the path is resolved relative to the parent's
-   * cap using virtual path semantics (absolute paths treated as cap-relative).
-   *
-   * @param {string} [directory="."] - Directory path (becomes cap if no parent, else relative to parent's cap, defaults to current directory)
-   * @param {CappedDirectoryObject?} [parent] - Optional parent capped directory
-   * @throws {Sass} If parent is provided but not a CappedDirectoryObject
-   * @throws {Sass} If the resulting path would escape the cap
-   * @example
-   * // Create new capped directory at current directory
-   * const cwd = new CappedDirectoryObject()
-   * // path: process.cwd(), cap: process.cwd()
-   *
-   * @example
-   * // Create new capped directory
-   * const cache = new CappedDirectoryObject("/home/user/.cache")
-   * // path: /home/user/.cache, cap: /home/user/.cache
-   *
-   * @example
-   * // Create subdirectory with parent
-   * const data = new CappedDirectoryObject("data", cache)
-   * // path: /home/user/.cache/data, cap: /home/user/.cache
-   *
-   * @example
-   * // Virtual absolute path with parent
-   * const config = new CappedDirectoryObject("/etc/config", cache)
-   * // path: /home/user/.cache/etc/config, cap: /home/user/.cache
-   */
-  constructor(directory, source=null) {
-    Valid.type(source, "Null|CappedDirectoryObject")
-
-    directory ||= "."
-
-    const baseLocalPath = source?.path ?? "/"
-    const baseRealPath = source?.real.path ?? directory
-
-    if(source && directory.startsWith("/"))
-      directory = directory.slice(1)
-
-    // Find out what directory means to the basePath
-    const realResolved = FS.resolvePath(baseRealPath, directory)
-    const localResolved = source
-      ? FS.resolvePath(baseLocalPath, directory)
-      : path.parse(path.resolve("")).root
-
-    super(localResolved)
-
-    this.#real = new DirectoryObject(realResolved)
-    this.#cap = source?.cap ?? this
-
-    if(source) {
-      this.#cappedParent = source
-      this.#cappedParentPath = source.path
-    } else {
-      this.#cappedParent = null
-      this.#cappedParentPath = null
-    }
-  }
-
-  /**
-   * Creates a CappedDirectoryObject from the current working directory.
-   * This is useful when working with pnpx or other tools where you need to
-   * cap at the project's root directory determined at runtime.
-   *
-   * @returns {CappedDirectoryObject} A CappedDirectoryObject capped at the current working directory
-   * @example
-   * // When using pnpx or similar tools
-   * const projectRoot = CappedDirectoryObject.fromCwd()
-   * const srcDir = projectRoot.getDirectory("src")
-   * // srcDir is capped at the project root
-   */
-  static fromCwd() {
-    return new this(process.cwd())
-  }
-
-  /**
-   * Indicates whether this directory is capped (constrained to a specific tree).
-   * Always returns true for CappedDirectoryObject instances.
-   *
-   * @returns {boolean} True for all CappedDirectoryObject instances
-   * @example
-   * const capped = new TempDirectoryObject("myapp")
-   * console.log(capped.isCapped) // true
-   *
-   * const regular = new DirectoryObject("/tmp")
-   * console.log(regular.isCapped) // false
-   */
-  get isCapped() {
-    return true
-  }
-
-  /**
-   * Returns the cap (root) of the capped directory tree.
-   * For root CappedDirectoryObject instances, returns itself.
-   * For children, returns the inherited cap from the parent chain.
-   *
-   * @returns {CappedDirectoryObject} The cap directory object (root of the capped tree)
-   * @example
-   * const temp = new TempDirectoryObject("myapp")
-   * console.log(temp.cap === temp) // true (root is its own cap)
-   *
-   * const subdir = temp.getDirectory("data")
-   * console.log(subdir.cap === temp) // true (child inherits parent's cap)
-   */
-  get cap() {
-    return this.#cap
-  }
-
-  /**
-   * 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.#real
-  }
-
-  /**
-   * Returns the parent directory of this capped directory.
-   * Returns null only if this directory is at the cap (the "root" of the capped tree).
-   *
-   * Note: The returned parent is a CappedDirectoryObject with the same cap.
-   * This maintains the capping behavior throughout the directory hierarchy.
-   *
-   * @returns {CappedDirectoryObject|null} Parent directory or null if at cap root
-   * @example
-   * const capped = new TempDirectoryObject("myapp")
-   * const subdir = capped.getDirectory("data")
-   * console.log(subdir.parent.path) // Returns parent CappedDirectoryObject
-   * console.log(capped.parent) // null (at cap root)
-   */
-  get parent() {
-    return this.#cappedParent
-  }
-
-  /**
-   * Returns the path of the parent directory.
-   * Returns null if this directory is at the cap root (no parent).
-   *
-   * @returns {string|null} The parent directory path, or null if at cap root
-   * @example
-   * const temp = new TempDirectoryObject("myapp")
-   * console.log(temp.parentPath) // null (at cap root)
-   *
-   * const subdir = temp.getDirectory("data")
-   * console.log(subdir.parentPath) // "/data" or similar (parent's virtual path)
-   */
-  get parentPath() {
-    return this.#cappedParentPath
-  }
-
-  /**
-   * 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,
-      parentPath: this.parentPath,
-      capped: this.isCapped,
-      cap: this.cap,
-      real: this.real
-    }
-  }
-
-  /**
-   * Override exists to use real filesystem path.
-   *
-   * @returns {Promise<boolean>} Whether the directory exists
-   */
-  get exists() {
-    return this.real.exists
-  }
-
-  /**
-   * Override read to use real filesystem path and return capped objects.
-   *
-   * @param {string} [pat=""] - Optional glob pattern
-   * @returns {Promise<{files: Array<FileObject>, directories: Array}>} Directory contents
-   */
-  async read(...arg) {
-    const {files, directories} = await this.real.read(...arg)
-
-    // we need to re-cast
-    const recastDirs = directories.map(e => this.getDirectory(e.name))
-    const recastFiles = files.map(f => new FileObject(f.name, this))
-
-    return {files: recastFiles, directories: recastDirs}
-  }
-
-  /**
-   * Override hasDirectory to use real filesystem path.
-   *
-   * @param {string} dirname - Directory name to check
-   * @returns {Promise<boolean>} True if directory exists
-   */
-  async hasDirectory(dirname) {
-    return await this.real.hasDirectory(dirname)
-  }
-
-  /**
-   * Override assureExists to use real filesystem path.
-   *
-   * @param {object} [options] - Options for mkdir
-   * @returns {Promise<void>}
-   */
-  async assureExists(options = {}) {
-    return await this.real.assureExists(options)
-  }
-
-  /**
-   * Override delete to use real filesystem path.
-   *
-   * @returns {Promise<void>}
-   */
-  async delete() {
-    return await this.real.delete()
-  }
-}

package/src/types/browser/index.d.ts

@@ -1,13 +0,0 @@
-export { default as Collection } from "./lib/Collection.js";
-export { default as Data } from "./lib/Data.js";
-export { default as Notify } from "./lib/Notify.js";
-export { default as Promised } from "./lib/Promised.js";
-export { default as Sass } from "./lib/Sass.js";
-export { default as Tantrum } from "./lib/Tantrum.js";
-export { default as Time } from "./lib/Time.js";
-export { default as Type } from "./lib/TypeSpec.js";
-export { default as Util } from "./lib/Util.js";
-export { default as Valid } from "./lib/Valid.js";
-export { default as Disposer, Disposer as DisposerClass } from "./lib/Disposer.js";
-export { default as HTML, HTML as HTMLClass } from "./lib/HTML.js";
-//# sourceMappingURL=index.d.ts.map

package/src/types/browser/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../browser/index.js"],"names":[],"mappings":""}