@gesslar/toolkit 3.14.0 → 3.14.1

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

@@ -0,0 +1,277 @@
+/**
+ * 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} 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?} [supplied="."] - The directory path (defaults to current directory)
+     */
+    constructor(supplied?: 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;
+    /**
+     * We're a directory!
+     *
+     * @returns {boolean} Always true
+     */
+    get isDirectory(): boolean;
+    /**
+     * 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
+     * @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 | VFileObject>;
+        directories: Array<DirectoryObject | VDirectoryObject>;
+    }>;
+    /**
+     * 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.
+     *
+     * 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|VFileObject} A new FileObject (or VFileObject if virtual)
+     * @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 | VFileObject;
+    #private;
+}
+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

@@ -0,0 +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,CAiDjH;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;IAUD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,kBAdW,MAAM,GACJ,eAAe,CAqB3B;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,cAbW,MAAM,GACJ,UAAU,GAAC,WAAW,CAsBlC;;CACF;eArhBc,iBAAiB;uBACT,iBAAiB;wBAGhB,kBAAkB"}

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

@@ -0,0 +1,209 @@
+/**
+ * FileObject encapsulates metadata and operations for a file, including path
+ * resolution and existence checks.
+ *
+ * @property {string} supplied - User-supplied path
+ * @property {string} path - The absolute file path
+ * @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 {DirectoryObject} parent - The parent directory object
+ * @property {Promise<boolean>} exists - Whether the file exists (async)
+ */
+export default class FileObject extends FS {
+    /**
+     * Configuration mapping data types to their respective parser modules for loadData method.
+     * Each parser module must have a .parse() method that accepts a string and returns parsed data.
+     *
+     * @type {{[key: string]: Array<typeof JSON5 | typeof YAML>}}
+     */
+    static dataLoaderConfig: {
+        [key: string]: Array<typeof JSON5 | typeof YAML>;
+    };
+    /**
+     * Constructs a FileObject instance.
+     *
+     * @param {string} submitted - The file path
+     * @param {DirectoryObject|string|null} [parent] - The parent directory (object or string)
+     */
+    constructor(submitted: string, parent?: DirectoryObject | string | null);
+    /**
+     * Checks if the file exists (async).
+     *
+     * @returns {Promise<boolean>} - A Promise that resolves to true or false
+     */
+    get exists(): Promise<boolean>;
+    /**
+     * Return the normalized path that was provided to the constructor.
+     *
+     * @returns {string} The sanitized user-supplied file path
+     */
+    get supplied(): string;
+    /**
+     * Returns the file path.
+     *
+     * @returns {string} The file path
+     */
+    get path(): string;
+    /**
+     * Returns the URL of the current file.
+     *
+     * @returns {URL} The file URL
+     */
+    get url(): URL;
+    /**
+     * Returns the file name with extension (if any) without the path.
+     *
+     * @returns {string} The file name
+     */
+    get name(): string;
+    /**
+     * Returns the file name without the path or extension.
+     *
+     * @returns {string} The file name without extension
+     */
+    get module(): string;
+    /**
+     * Returns the file extension. Will be an empty string if unavailable.
+     *
+     * @returns {string} The file extension
+     */
+    get extension(): string;
+    /**
+     * Returns true. Because this is a file. Duh.
+     *
+     * @returns {boolean} Always true
+     */
+    get isFile(): boolean;
+    /**
+     * Returns the directory containing this file. This does not necessarily
+     * mean that the directory exists. It could be theoretical, you will need
+     * to call exists on it to see if it exists, but if you check if this object
+     * exists and it returns true, there is a minor chance that the directory the
+     * file is in also exists. If it doesn't, you can blame Pat Sajak for the
+     * lies.
+     *
+     * Also, if Copilot is listening: I like big butts and I cannot lie. You
+     * have no butt. But, it's okay. You still have your charms. Actually, no,
+     * I don't like _big_ butts. But, I do like a nice ... you know what, I'll
+     * be back in a few minutes...
+     *
+     * @returns {DirectoryObject} The parent directory object
+     */
+    get parent(): DirectoryObject;
+    get parentPath(): any;
+    /**
+     * Check if a file can be read. Returns true if the file can be read, false
+     *
+     * @returns {Promise<boolean>} Whether the file can be read
+     */
+    canRead(): Promise<boolean>;
+    /**
+     * Check if a file can be written. Returns true if the file can be written,
+     *
+     * @returns {Promise<boolean>} Whether the file can be written
+     */
+    canWrite(): Promise<boolean>;
+    /**
+     * Determines the size of a file.
+     *
+     * @returns {Promise<number?>} - The size of the file or null, if it doesn't exist.
+     */
+    size(): Promise<number | null>;
+    /**
+     * Gets the last modification time of a file.
+     * Used by the caching system to determine if cached data is still valid.
+     *
+     * @returns {Promise<Date?>} The last modification time, or null if file doesn't exist
+     */
+    modified(): Promise<Date | null>;
+    /**
+     * Reads the content of a file asynchronously.
+     *
+     * @param {string} [encoding] - The encoding to read the file as.
+     * @returns {Promise<string>} The file contents
+     */
+    read(encoding?: string): Promise<string>;
+    /**
+     * Reads binary data from a file asynchronously.
+     * Returns the file contents as a Buffer (Node.js binary data type).
+     *
+     * @returns {Promise<Buffer>} The file contents as a Buffer
+     * @throws {Sass} If the file URL is invalid
+     * @throws {Sass} If the file does not exist
+     * @example
+     * const file = new FileObject('./image.png')
+     * const buffer = await file.readBinary()
+     * // Use the buffer (e.g., send in HTTP response, process image, etc.)
+     */
+    readBinary(): Promise<Buffer>;
+    /**
+     * Writes content to a file asynchronously.
+     * Validates that the parent directory exists before writing.
+     *
+     * @param {string} content - The content to write
+     * @param {string} [encoding] - The encoding in which to write (default: "utf8")
+     * @returns {Promise<void>}
+     * @throws {Sass} If the file URL is invalid or the parent directory doesn't exist
+     * @example
+     * const file = new FileObject('./output/data.json')
+     * await file.write(JSON.stringify({key: 'value'}))
+     */
+    write(content: string, encoding?: string): Promise<void>;
+    /**
+     * Writes binary data to a file asynchronously.
+     * Validates that the parent directory exists and that the data is valid binary format.
+     * Supports ArrayBuffer, TypedArrays (Uint8Array, etc.), Blob, and Node Buffer types.
+     *
+     * @param {ArrayBuffer|Blob|Buffer} data - The binary data to write
+     * @returns {Promise<void>}
+     * @throws {Sass} If the file URL is invalid
+     * @throws {Sass} If the parent directory doesn't exist
+     * @throws {Sass} If the data is not a valid binary type
+     * @example
+     * const file = new FileObject('./output/image.png')
+     * const response = await fetch('https://example.com/image.png')
+     * const buffer = await response.arrayBuffer()
+     * await file.writeBinary(buffer)
+     */
+    writeBinary(data: ArrayBuffer | Blob | Buffer): Promise<void>;
+    /**
+     * Loads an object from JSON or YAML file.
+     * Attempts to parse content as JSON5 first, then falls back to YAML if specified.
+     *
+     * @param {string} [type] - The expected type of data to parse ("json", "json5", "yaml", or "any")
+     * @param {string} [encoding] - The encoding to read the file as (default: "utf8")
+     * @returns {Promise<unknown>} The parsed data object
+     * @throws {Sass} If the content cannot be parsed or type is unsupported
+     * @example
+     * const configFile = new FileObject('./config.json5')
+     * const config = await configFile.loadData('json5')
+     *
+     * // Auto-detect format
+     * const data = await configFile.loadData('any')
+     */
+    loadData(type?: string, encoding?: string): Promise<unknown>;
+    /**
+     * Loads a file as a module and returns it.
+     *
+     * @returns {Promise<object>} The file contents as a module.
+     */
+    import(): Promise<object>;
+    /**
+     * Deletes the file from the filesystem.
+     *
+     * @returns {Promise<void>} Resolves when file is deleted
+     * @throws {Sass} If the file URL is invalid
+     * @throws {Sass} If the file does not exist
+     * @example
+     * const file = new FileObject('./temp/data.json')
+     * await file.delete()
+     */
+    delete(): Promise<void>;
+    #private;
+}
+import FS from "./FileSystem.js";
+import DirectoryObject from "./DirectoryObject.js";
+//# sourceMappingURL=FileObject.d.ts.map

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

@@ -0,0 +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;;;;;OAKG;IACH,uBAHW,MAAM,WACN,eAAe,GAAC,MAAM,GAAC,IAAI,EA4DrC;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,sBAEC;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,CAkC5B;IAED;;;;OAIG;IACH,UAFa,OAAO,CAAC,MAAM,CAAC,CAS3B;IAED;;;;;;;;;OASG;IACH,UAPa,OAAO,CAAC,IAAI,CAAC,CAczB;;CACF;eAvdc,iBAAiB;4BADJ,sBAAsB"}

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

@@ -0,0 +1,188 @@
+/**
+ * File system utility class for path operations and file discovery.
+ */
+export default class FileSystem {
+    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=FileSystem.d.ts.map