@gesslar/toolkit 3.12.3 → 3.14.0

package/README.md

@@ -35,10 +35,9 @@ Includes all browser functionality plus Node.js-specific modules for file I/O, l
 | Name | Description |
 | ---- | ----------- |
 | Cache | Cache management for file I/O operations |
-| CappedDirectoryObject | Directory operations constrained to a specific tree |
 | 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 |
+| FileSystem | Base class for file system operations with static utilities |
 | Glog | Logging framework |
 | Notify | Event system wrapper for Node.js events |
 | Sass | Custom Error class with enhanced features |
@@ -47,6 +46,8 @@ Includes all browser functionality plus Node.js-specific modules for file I/O, l
 | Term | Terminal formatting and output utilities |
 | Util | General utility functions (Node-enhanced version) |
 | Valid | Validation and assertion methods |
+| VDirectoryObject | Directory operations constrained to a specific tree |
+| VFileObject | Virtual file operations for in-memory file handling |
 
 ## Installation
 
@@ -99,8 +100,8 @@ import { Data, Collection, Util } from '@gesslar/toolkit/browser'
 
 The browser version includes: Collection, Data, Disposer, HTML, Notify, Sass,
 Tantrum, Type (TypeSpec), Util, and Valid. Node-only modules (Cache,
-CappedDirectoryObject, DirectoryObject, FileObject, FS, Glog,
-TempDirectoryObject, Term) are not available in the browser version.
+DirectoryObject, FileObject, FileSystem, Glog, TempDirectoryObject, Term,
+VDirectoryObject, VFileObject) are not available in the browser version.
 
 ## Post Partum
 

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "3.12.3",
+  "version": "3.14.0",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {
@@ -63,7 +63,7 @@
     "typescript": "^5.9.3"
   },
   "scripts": {
-    "types:build": "node -e \"require('fs').rmSync('src/types',{recursive:true,force:true});\" && tsc -p tsconfig.types.json",
+    "types": "node -e \"require('fs').rmSync('types',{recursive:true,force:true});\" && tsc -p tsconfig.types.json",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
     "submit": "pnpm publish --access public --//registry.npmjs.org/:_authToken=\"${NPM_ACCESS_TOKEN}\"",

package/src/{index.js → node/index.js}

@@ -1,11 +1,11 @@
 // Browser-compatible utilities (pure JS)
-export {default as Collection} from "./browser/lib/Collection.js"
-export {default as Data} from "./browser/lib/Data.js"
-export {default as Disposer} from "./browser/lib/Disposer.js"
-export {Disposer as DisposerClass} from "./browser/lib/Disposer.js"
-export {default as Promised} from "./browser/lib/Promised.js"
-export {default as Time} from "./browser/lib/Time.js"
-export {default as Type} from "./browser/lib/TypeSpec.js"
+export {default as Collection} from "../browser/lib/Collection.js"
+export {default as Data} from "../browser/lib/Data.js"
+export {default as Disposer} from "../browser/lib/Disposer.js"
+export {Disposer as DisposerClass} from "../browser/lib/Disposer.js"
+export {default as Promised} from "../browser/lib/Promised.js"
+export {default as Time} from "../browser/lib/Time.js"
+export {default as Type} from "../browser/lib/TypeSpec.js"
 export {default as Valid} from "./lib/Valid.js"
 
 // Node-enhanced versions (use Term for better formatting, crypto, etc.)
@@ -15,11 +15,12 @@ export {default as Util} from "./lib/Util.js"
 
 // Node-specific exports
 export {default as Cache} from "./lib/Cache.js"
-export {default as CappedDirectoryObject} from "./lib/CappedDirectoryObject.js"
 export {default as DirectoryObject} from "./lib/DirectoryObject.js"
-export {default as TempDirectoryObject} from "./lib/TempDirectoryObject.js"
 export {default as FileObject} from "./lib/FileObject.js"
-export {default as FS} from "./lib/FS.js"
+export {default as FS} from "./lib/FileSystem.js"
 export {default as Glog} from "./lib/Glog.js"
 export {default as Notify} from "./lib/Notify.js"
+export {default as TempDirectoryObject} from "./lib/TempDirectoryObject.js"
 export {default as Term} from "./lib/Term.js"
+export {default as VFileObject} from "./lib/VFileObject.js"
+export {default as VDirectoryObject} from "./lib/VDirectoryObject.js"

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

@@ -8,11 +8,12 @@ import {glob, mkdir, opendir, readdir, rmdir} from "node:fs/promises"
 import path from "node:path"
 import {URL} from "node:url"
 
-import Data from "../browser/lib/Data.js"
-import FS from "./FS.js"
+import Data from "../../browser/lib/Data.js"
+import FS from "./FileSystem.js"
 import FileObject from "./FileObject.js"
 import Sass from "./Sass.js"
 import Valid from "./Valid.js"
+import VFileObject from "./VFileObject.js"
 
 /**
  * DirectoryObject encapsulates metadata and operations for a directory,
@@ -33,7 +34,6 @@ import Valid from "./Valid.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} isFile - Always false (this is a directory)
  * @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)
@@ -71,22 +71,18 @@ export default class DirectoryObject extends FS {
    * @property {string|null} name - The file name
    * @property {string|null} module - The file name without extension
    * @property {string|null} extension - The file extension
-   * @property {boolean} isFile - Always false
    * @property {boolean} isDirectory - Always true
    */
   #meta = Object.seal({
-    supplied: null,
-    path: null,
-    url: null,
-    name: null,
-    module: null,
-    extension: null,
-    isFile: false,
     isDirectory: true,
-    trail: null,
-    sep: null,
+    name: null,
     parent: undefined,
     parentPath: undefined,
+    path: null,
+    sep: null,
+    supplied: null,
+    trail: null,
+    url: null,
   })
 
   // Not in the meta, because it gets frozen, and these are lazily
@@ -96,34 +92,30 @@ export default class DirectoryObject extends FS {
   /**
    * Constructs a DirectoryObject instance.
    *
-   * @param {string?} [directory="."] - The directory path or DirectoryObject (defaults to current directory)
+   * @param {string?} [supplied="."] - The directory path (defaults to current directory)
    */
-  constructor(directory) {
-    directory ||= "."
+  constructor(supplied) {
+    const fixedDir = supplied || "."
 
-    Valid.type(directory, "String")
+    Valid.type(fixedDir, "String")
 
     super()
 
-    const fixedDir = FS.fixSlashes(directory)
-    const resolved = path.resolve(fixedDir)
+    const normalizedDir = FS.fixSlashes(fixedDir)
+    const resolved = path.resolve(normalizedDir)
+    const {dir, name, root} = FS.pathParts(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.name = name
+    this.#meta.parentPath = dir == root
+      ? null
+      : dir
     this.#meta.path = resolved
-    this.#meta.url = url
-    this.#meta.name = baseName
-    this.#meta.extension = ""
-    this.#meta.module = baseName !== "." ? baseName : ""
+    this.#meta.sep = path.sep
+    this.#meta.supplied = supplied
     this.#meta.trail = trail
-    this.#meta.sep = sep
-    this.#meta.parentPath = pathParts.dir === pathParts.root
-      ? null
-      : pathParts.dir
+    this.#meta.url = url
 
     Object.freeze(this.#meta)
   }
@@ -148,43 +140,11 @@ export default class DirectoryObject extends FS {
    * @returns {string} string representation of the DirectoryObject
    */
   toString() {
-    return this.isCapped
-      ?`[${this.constructor.name}: ${this.path} → ${this.real.path}]`
-      :`[${this.constructor.name}: ${this.path}]`
-
-    return this.isCapped
+    return this.isVirtual
       ?`[${this.constructor.name}: ${this.path} → ${this.real.path}]`
       :`[${this.constructor.name}: ${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?.path ?? null,
-    }
-  }
-
-  /**
-   * Custom inspect method for Node.js console.
-   *
-   * @returns {object} JSON representation of this object.
-   */
-  // [util.inspect.custom]() {
-  //   return this.toJSON()
-  // }
-
   /**
    * Checks if the directory exists (async).
    *
@@ -298,15 +258,6 @@ export default class DirectoryObject extends FS {
     return this.#parent
   }
 
-  /**
-   * Returns false. Because this is a directory.
-   *
-   * @returns {boolean} Always false
-   */
-  get isFile() {
-    return this.#meta.isFile
-  }
-
   /**
    * We're a directory!
    *
@@ -322,9 +273,7 @@ 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
+    const path = this.real?.path ?? this.path
 
     try {
       (await opendir(path)).close()
@@ -338,9 +287,12 @@ 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>, directories: Array<DirectoryObject>}>} Object containing arrays of files and directories
+   * @returns {Promise<{files: Array<FileObject|VFileObject>, directories: Array<DirectoryObject|VDirectoryObject>}>} Object containing arrays of files and directories
    * @example
    * const dir = new DirectoryObject("./src")
    * const {files, directories} = await dir.read()
@@ -353,7 +305,7 @@ export default class DirectoryObject extends FS {
    */
   async read(pat="") {
     const withFileTypes = true
-    const url = this.isCapped
+    const url = this.isVirtual
       ? this.real?.url
       : this.url
 
@@ -364,7 +316,7 @@ export default class DirectoryObject extends FS {
       ? await readdir(url, {withFileTypes})
       : await Array.fromAsync(
         glob(pat, {
-          cwd: this.isCapped ? this.real?.path : this.path,
+          cwd: this.isVirtual ? this.real?.path : this.path,
           withFileTypes,
           // exclude: candidate => {
           // // Only allow entries within this directory's URL
@@ -378,7 +330,7 @@ export default class DirectoryObject extends FS {
 
     const files = found
       .filter(dirent => dirent.isFile())
-      .map(dirent => new FileObject(dirent.name, this))
+      .map(dirent => this.getFile(dirent.name))
 
     const directories = found
       .filter(dirent => dirent.isDirectory())
@@ -408,15 +360,17 @@ export default class DirectoryObject extends FS {
     if(await this.exists)
       return
 
+    const path = this.real?.path ?? this.path
+
     try {
-      await mkdir(this.path, options)
+      await mkdir(path, options)
     } catch(e) {
       if(e.code === "EEXIST") {
         // Directory already exists, ignore
         return
       }
 
-      throw Sass.new(`Unable to create directory '${this.path}': ${e.message}`)
+      throw Sass.new(`Unable to create directory '${path}': ${e.message}`)
     }
   }
 
@@ -479,7 +433,7 @@ export default class DirectoryObject extends FS {
    * await dir.delete() // Only works if directory is empty
    */
   async delete() {
-    const dirPath = this.path
+    const dirPath = this.real?.path ?? this.path
 
     if(!dirPath)
       throw Sass.new("This object does not represent a valid resource.")
@@ -487,7 +441,7 @@ export default class DirectoryObject extends FS {
     if(!(await this.exists))
       throw Sass.new(`No such resource '${this.url.href}'`)
 
-    return await rmdir(this.path)
+    return await rmdir(dirPath)
   }
 
   /**
@@ -509,8 +463,8 @@ export default class DirectoryObject extends FS {
    * @returns {Promise<boolean>} True if the directory exists, false otherwise
    */
   async hasDirectory(dirname) {
-    const resolved = FS.resolvePath(this.path, dirname)
-    const directory = new DirectoryObject(resolved)
+    const dir = FS.resolvePath(this.real?.path ?? this.path, dirname)
+    const directory = new DirectoryObject(dir)
 
     return await directory.exists
   }
@@ -561,8 +515,11 @@ export default class DirectoryObject extends FS {
    * duplication. The resulting FileObject can be used for reading, writing,
    * and other file operations.
    *
+   * When called on a VDirectoryObject, returns a VFileObject to maintain
+   * virtual path semantics.
+   *
    * @param {string} file - The filename to append (can include subdirectories like "src/index.js")
-   * @returns {FileObject} A new FileObject instance with the combined path
+   * @returns {FileObject|VFileObject} A new FileObject (or VFileObject if virtual)
    * @throws {Sass} If filename is not a string
    * @example
    * const dir = new DirectoryObject("/projects/git/toolkit")
@@ -581,6 +538,8 @@ export default class DirectoryObject extends FS {
 
     Valid.assert(this.#isLocal(newPath), `${newPath} would be out of bounds.`)
 
-    return new FileObject(newPath, this)
+    return this.isVirtual
+      ? new VFileObject(file, this)
+      : new FileObject(file, this)
   }
 }