@gesslar/toolkit 3.13.0 → 3.14.0

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

@@ -1,277 +0,0 @@
-/**
- * DirectoryObject encapsulates metadata and operations for a directory,
- * providing immutable path resolution, existence checks, and content enumeration.
- *
- * 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
- *
- * @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} 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)
- * @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 {
-    /**
-     * Creates a DirectoryObject from the current working directory.
-     * Useful when working with pnpx or other tools where the project root
-     * needs to be determined at runtime.
-     *
-     * @returns {DirectoryObject} A DirectoryObject representing the current working directory
-     * @example
-     * const projectRoot = DirectoryObject.fromCwd()
-     * console.log(projectRoot.path) // process.cwd()
-     */
-    static fromCwd(): DirectoryObject;
-    /**
-     * Constructs a DirectoryObject instance.
-     *
-     * @param {string?} [directory="."] - The directory path or DirectoryObject (defaults to current directory)
-     */
-    constructor(directory?: string | null);
-    /**
-     * Checks if the directory exists (async).
-     *
-     * @returns {Promise<boolean>} - A Promise that resolves to true or false
-     */
-    get exists(): Promise<boolean>;
-    /**
-     * Return the path as passed to the constructor.
-     *
-     * @returns {string} The directory path
-     */
-    get supplied(): string;
-    /**
-     * Return the resolved path
-     *
-     * @returns {string} The directory path
-     */
-    get path(): string;
-    /**
-     * Returns the URL of the current directory.
-     *
-     * @returns {URL} The directory URL
-     */
-    get url(): URL;
-    /**
-     * Returns the directory name with extension (if any) without the path.
-     *
-     * @returns {string} The directory name
-     */
-    get name(): string;
-    /**
-     * Returns the directory name without the path or extension.
-     *
-     * @returns {string} The directory name without extension
-     */
-    get module(): string;
-    /**
-     * Returns the directory extension. Will be an empty string if unavailable.
-     *
-     * @returns {string} The directory extension
-     */
-    get extension(): string;
-    /**
-     * Returns the platform-specific path separator.
-     *
-     * @returns {string} The path separator ('/' on Unix, '\\' on Windows)
-     */
-    get sep(): string;
-    /**
-     * Returns the directory path split into segments.
-     *
-     * @returns {Array<string>} Array of path segments
-     * @example
-     * const dir = new DirectoryObject('/path/to/directory')
-     * console.log(dir.trail) // ['', 'path', 'to', 'directory']
-     */
-    get trail(): Array<string>;
-    /**
-     * Returns the parent directory of this directory.
-     * Returns null if this directory is the root directory.
-     * Computed lazily on first access and cached.
-     *
-     * @returns {DirectoryObject|null} The parent directory or null if root
-     * @example
-     * const dir = new DirectoryObject('/path/to/directory')
-     * console.log(dir.parent.path) // '/path/to'
-     *
-     * const root = new DirectoryObject('/')
-     * console.log(root.parent) // null
-     */
-    get parent(): DirectoryObject | null;
-    /**
-     * Returns false. Because this is a directory.
-     *
-     * @returns {boolean} Always false
-     */
-    get isFile(): boolean;
-    /**
-     * We're a directory!
-     *
-     * @returns {boolean} Always true
-     */
-    get isDirectory(): boolean;
-    /**
-     * Lists the contents of a directory, optionally filtered by a glob pattern.
-     *
-     * @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(pat?: string): Promise<{
-        files: Array<FileObject>;
-        directories: Array<DirectoryObject>;
-    }>;
-    /**
-     * Ensures a directory exists, creating it if necessary.
-     * Gracefully handles the case where the directory already exists.
-     *
-     * @async
-     * @param {object} [options] - Options to pass to fs.mkdir (e.g., {recursive: true, mode: 0o755})
-     * @returns {Promise<void>}
-     * @throws {Sass} If directory creation fails for reasons other than already existing
-     * @example
-     * // Create directory recursively
-     * const dir = new DirectoryObject('./build/output')
-     * await dir.assureExists({recursive: true})
-     */
-    assureExists(options?: object): Promise<void>;
-    /**
-     * 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 {DirectoryObject} Generator yielding parent DirectoryObject instances
-     * @example
-     * const dir = new DirectoryObject('/path/to/deep/directory')
-     * for(const parent of dir.walkUp) {
-     *   console.log(parent.path)
-     *   // /path/to/deep/directory
-     *   // /path/to/deep
-     *   // /path/to
-     *   // /path
-     *   // /
-     * }
-     */
-    get walkUp(): DirectoryObject;
-    /**
-     * Deletes an empty directory from the filesystem.
-     *
-     * Recursive deletion is intentionally not supported. If you need to delete
-     * a directory with contents, you must imperatively decide your deletion
-     * strategy and handle it explicitly.
-     *
-     * @returns {Promise<void>} Resolves when directory is deleted
-     * @throws {Sass} If the directory URL is invalid
-     * @throws {Sass} If the directory does not exist
-     * @throws {Error} If the directory is not empty (from fs.rmdir)
-     * @example
-     * const dir = new DirectoryObject('./temp/cache')
-     * await dir.delete() // Only works if directory is empty
-     */
-    delete(): Promise<void>;
-    /**
-     * Checks if a file exists within this directory.
-     *
-     * @param {string} filename - The filename to check for
-     * @returns {Promise<boolean>} True if the file exists, false otherwise
-     */
-    hasFile(filename: string): Promise<boolean>;
-    /**
-     * Checks if a subdirectory exists within this directory.
-     *
-     * @param {string} dirname - The directory name to check for
-     * @returns {Promise<boolean>} True if the directory exists, false otherwise
-     */
-    hasDirectory(dirname: string): Promise<boolean>;
-    /**
-     * 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.
-     *
-     * @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
-     * const dir = new DirectoryObject("/projects/git/toolkit")
-     * 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)
-     */
-    getDirectory(dir: 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.
-     *
-     * @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
-     * const dir = new DirectoryObject("/projects/git/toolkit")
-     * 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()
-     */
-    getFile(file: string): FileObject;
-    #private;
-}
-import FS from "./FS.js";
-import FileObject from "./FileObject.js";
-//# sourceMappingURL=DirectoryObject.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"DirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/DirectoryObject.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH;IAmEE;;;;;;;;;OASG;IACH,kBALa,eAAe,CAO3B;IA/CD;;;;OAIG;IACH,wBAFW,MAAM,OAAC,EA8BjB;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,cAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAqBD;;;;;;;;;;;;;;;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,CAiDpF;IAED;;;;;;;;;;;;OAYG;IACH,uBARW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAqBzB;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;IAUD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,kBAdW,MAAM,GACJ,eAAe,CAqB3B;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,cAbW,MAAM,GACJ,UAAU,CAoBtB;;CACF;eA9hBc,SAAS;uBACD,iBAAiB"}

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

@@ -1,188 +0,0 @@
-/**
- * File system utility class for path operations and file discovery.
- */
-export default class FS {
-    static fdTypes: readonly string[];
-    static upperFdTypes: readonly string[];
-    static fdType: any;
-    /**
-     * Fix slashes in a path
-     *
-     * @static
-     * @param {string} pathName - The path to fix
-     * @returns {string} The fixed path
-     */
-    static fixSlashes(pathName: string): string;
-    /**
-     * Convert a path to a URI
-     *
-     * @static
-     * @param {string} pathName - The path to convert
-     * @returns {string} The URI
-     */
-    static pathToUrl(pathName: string): string;
-    /**
-     * Convert a URI to a path
-     *
-     * @static
-     * @param {string} pathName - The URI to convert
-     * @returns {string} The path
-     */
-    static urlToPath(pathName: string): string;
-    /**
-     * Computes the relative path from one file or directory to another.
-     *
-     * If the target is outside the source (i.e., the relative path starts with
-     * ".."), returns the absolute path to the target instead.
-     *
-     * @static
-     * @param {FileObject|DirectoryObject} from - The source file or directory object
-     * @param {FileObject|DirectoryObject} to - The target file or directory object
-     * @returns {string} The relative path from `from` to `to`, or the absolute path if not reachable
-     */
-    static relativeOrAbsolutePath(from: FileObject | DirectoryObject, to: FileObject | DirectoryObject): string;
-    /**
-     * Merge two paths by finding overlapping segments and combining them
-     * efficiently
-     *
-     * @static
-     * @param {string} path1 - The first path
-     * @param {string} path2 - The second path to merge with the first
-     * @param {string} [sep] - The path separator to use (defaults to system separator)
-     * @returns {string} The merged path
-     */
-    static mergeOverlappingPaths(path1: string, path2: string, sep?: string): string;
-    /**
-     * Resolve a path relative to another path using various strategies
-     * Handles absolute paths, relative navigation, and overlap-based merging
-     *
-     * @static
-     * @param {string} fromPath - The base path to resolve from
-     * @param {string} toPath - The target path to resolve
-     * @returns {string} The resolved path
-     */
-    static resolvePath(fromPath: string, toPath: string): string;
-    /**
-     * Check if a candidate path is contained within a container path.
-     *
-     * @static
-     * @param {string} container - The container path to check against
-     * @param {string} candidate - The candidate path that might be contained
-     * @returns {boolean} True if candidate is within container, false otherwise
-     * @throws {Sass} If container is not a non-empty string
-     * @throws {Sass} If candidate is not a non-empty string
-     * @example
-     * FS.pathContains("/home/user", "/home/user/docs") // true
-     * FS.pathContains("/home/user", "/home/other") // false
-     */
-    static pathContains(container: string, candidate: string): boolean;
-    /**
-     * Convert an absolute path to a relative path by finding overlapping segments.
-     * Returns the relative portion of the 'to' path after the last occurrence
-     * of the final segment from the 'from' path.
-     *
-     * @static
-     * @param {string} from - The base path to calculate relative from
-     * @param {string} to - The target path to make relative
-     * @param {string} [sep=path.sep] - The path separator to use (defaults to system separator)
-     * @returns {string|null} The relative path, empty string if paths are identical, or null if no overlap found
-     * @example
-     * FS.toRelativePath("/projects/toolkit", "/projects/toolkit/src") // "src"
-     * FS.toRelativePath("/home/user", "/home/user") // ""
-     * FS.toRelativePath("/projects/app", "/other/path") // null
-     */
-    static toRelativePath(from: string, to: string, sep?: string): string | null;
-    /**
-     * Find the common root path between two paths by identifying overlapping segments.
-     * Returns the portion of 'from' that matches up to the overlap point in 'to'.
-     *
-     * @static
-     * @param {string} from - The first path to compare
-     * @param {string} to - The second path to find common root with
-     * @param {string} [sep=path.sep] - The path separator to use (defaults to system separator)
-     * @returns {string|null} The common root path, the original path if identical, or null if no overlap found
-     * @throws {Sass} If from is not a non-empty string
-     * @throws {Sass} If to is not a non-empty string
-     * @example
-     * FS.getCommonRootPath("/projects/toolkit/src", "/projects/toolkit/tests") // "/projects/toolkit"
-     * FS.getCommonRootPath("/home/user", "/home/user") // "/home/user"
-     * FS.getCommonRootPath("/projects/app", "/other/path") // null
-     */
-    static getCommonRootPath(from: string, to: string, sep?: string): string | null;
-    /**
-     * @typedef {object} PathParts
-     * @property {string} base - The file name with extension
-     * @property {string} dir - The directory path
-     * @property {string} ext - The file extension (including dot)
-     */
-    /**
-     * Deconstruct a file or directory name into parts.
-     *
-     * @static
-     * @param {string} pathName - The file/directory name to deconstruct
-     * @returns {PathParts} The filename parts
-     * @throws {Sass} If not a string of more than 1 character
-     */
-    static pathParts(pathName: string): {
-        /**
-         * - The file name with extension
-         */
-        base: string;
-        /**
-         * - The directory path
-         */
-        dir: string;
-        /**
-         * - The file extension (including dot)
-         */
-        ext: 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.
-     *
-     * @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"
-     */
-    static virtualToRealPath(fileOrDirectoryObject: FileObject | DirectoryObject): string;
-    /**
-     * Convert an absolute path to a relative format by removing the root component.
-     * By default, keeps a leading separator (making it "absolute-like relative").
-     * Use forceActuallyRelative to get a truly relative path without leading separator.
-     *
-     * @static
-     * @param {string} pathToCheck - The path to convert (returned unchanged if already relative)
-     * @param {boolean} [forceActuallyRelative=false] - If true, removes leading separator for truly relative path
-     * @returns {string} The relative path (with or without leading separator based on forceActuallyRelative)
-     * @example
-     * FS.absoluteToRelative("/home/user/docs") // "/home/user/docs" (with leading /)
-     * FS.absoluteToRelative("/home/user/docs", true) // "home/user/docs" (truly relative)
-     * FS.absoluteToRelative("relative/path") // "relative/path" (unchanged)
-     */
-    static absoluteToRelative(pathToCheck: string, forceActuallyRelative?: boolean): string;
-    /**
-     * Compute the relative path from another file or directory to this instance.
-     *
-     * If the target is outside the source (i.e., the relative path starts with ".."),
-     * returns the absolute path to this instance instead.
-     *
-     * @param {FileObject|DirectoryObject} fileOrDirectoryObject - The source file or directory object
-     * @returns {string} The relative path from the source to this instance, or the absolute path if not reachable
-     * @throws {Sass} If the parameter is not a FileObject or DirectoryObject
-     */
-    relativeTo(fileOrDirectoryObject: FileObject | DirectoryObject): string;
-}
-export type FileObject = import("./FileObject.js").default;
-export type DirectoryObject = import("./DirectoryObject.js").default;
-//# sourceMappingURL=FS.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"FS.d.ts","sourceRoot":"","sources":["../../lib/FS.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,oCAJW,UAAU,GAAC,eAAe,MAC1B,UAAU,GAAC,eAAe,GACxB,MAAM,CAYlB;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;IAED;;;;;;;;;;;;;OAaG;IACH,uCARW,MAAM,0BACN,OAAO,GACL,MAAM,CAkBlB;IA/VD;;;;;;;;;OASG;IACH,kCAJW,UAAU,GAAC,eAAe,GACxB,MAAM,CAWlB;CA8UF;yBAjXa,OAAO,iBAAiB,EAAE,OAAO;8BACjC,OAAO,sBAAsB,EAAE,OAAO"}