@synstack/path/dist/path.index.d.ts

Advanced path manipulation utilities

/**
 * Type representing an absolute file system path.
 * Used for type safety when working with paths.
 */
type AbsolutePath = string & {
    ABSOLUTE_PATH: true;
};
/**
 * Type representing a relative file system path.
 * Used for type safety when working with paths.
 */
type RelativePath = string & {
    RELATIVE_PATH: true;
};
/**
 * Type representing any kind of file system path (absolute or relative).
 */
type AnyPath = string;
/**
 * Exception thrown when a path operation is attempted outside the current working directory.
 */
declare class PathNotInCwdException extends Error {
    constructor(path: string, cwd: string);
}
/**
 * Resolves a sequence of paths or path segments into an absolute path.
 *
 * @param paths - One or more path segments to resolve
 * @returns An absolute path string
 *
 * ```typescript
 * const absolutePath = resolve("/base", "subdir", "file.txt");
 * console.log(absolutePath); // "/base/subdir/file.txt"
 * ```
 */
declare function resolve(...paths: Array<AnyPath>): AbsolutePath;
/**
 * Determines if the given path is absolute.
 *
 * @param path - The path to check
 * @returns True if the path is absolute, false otherwise
 *
 * ```typescript
 * console.log(isAbsolute("/absolute/path")); // true
 * console.log(isAbsolute("relative/path")); // false
 * ```
 */
declare function isAbsolute(path: AnyPath): path is AbsolutePath;
/**
 * Returns the directory name of a path.
 * The result is always an absolute path.
 *
 * @param path - The path to get the directory name from
 * @returns The absolute path of the directory containing the path
 *
 * ```typescript
 * const dir = dirname("/path/to/file.txt");
 * console.log(dir); // "/path/to"
 * ```
 */
declare function dirname(path: AnyPath): AbsolutePath;
/**
 * Checks if a path is contained within a base path.
 *
 * @param basePath - The base path to check against
 * @param path - The path to check
 * @returns True if the path is within the base path, false otherwise
 *
 * ```typescript
 * console.log(isInPath("/base", "/base/subdir")); // true
 * console.log(isInPath("/base", "/other")); // false
 * ```
 */
declare function isInPath(basePath: AnyPath, path: AnyPath): boolean;
/**
 * Creates a relative path from one location to another.
 *
 * @param basePath - The base path to create the relative path from
 * @param path - The target path to create the relative path to
 * @returns A relative path from basePath to path
 *
 * ```typescript
 * const rel = relative("/base/dir", "/base/dir/subdir/file.txt");
 * console.log(rel); // "subdir/file.txt"
 * ```
 */
declare function relative(basePath: AnyPath, path: AnyPath): RelativePath;
/**
 * Adds a file extension to a path if it's not already present.
 *
 * @param path - The path to add the extension to
 * @param ext - The extension to add (without the leading dot)
 * @returns The path with the extension added
 *
 * ```typescript
 * const withExt = addMissingExtension("/path/to/file", "txt");
 * console.log(withExt); // "/path/to/file.txt"
 *
 * const alreadyHasExt = addMissingExtension("/path/to/file.txt", "txt");
 * console.log(alreadyHasExt); // "/path/to/file.txt"
 * ```
 */
declare function addMissingExtension(path: AbsolutePath, ext: string): AbsolutePath;
declare function addMissingExtension(path: RelativePath, ext: string): RelativePath;
/**
 * Joins path segments together.
 * The type of the first argument determines the type of the result.
 *
 * @param cwd - The base path (determines return type)
 * @param paths - Additional path segments to join
 * @returns The joined path
 *
 * ```typescript
 * const abs = join("/absolute", "path", "file.txt");
 * console.log(abs); // "/absolute/path/file.txt"
 *
 * const rel = join("relative", "path", "file.txt");
 * console.log(rel); // "relative/path/file.txt"
 * ```
 */
declare function join(cwd: AbsolutePath, ...paths: Array<AnyPath>): AbsolutePath;
declare function join(cwd: RelativePath, ...paths: Array<AnyPath>): RelativePath;
declare function join(...paths: Array<AnyPath>): AnyPath;
/**
 * Removes the leading "./" from a path if present.
 * Preserves the path type (absolute or relative).
 *
 * @param path - The path to process
 * @returns The path without the leading "./"
 *
 * ```typescript
 * console.log(removeRelativeIndicator("./file.txt")); // "file.txt"
 * console.log(removeRelativeIndicator("file.txt")); // "file.txt"
 * ```
 */
declare function removeRelativeIndicator(path: AbsolutePath): AbsolutePath;
declare function removeRelativeIndicator(path: RelativePath): RelativePath;
declare function removeRelativeIndicator(path: AnyPath): AnyPath;
/**
 * Ensures a file path has a specific extension.
 * If the path already ends with the extension, it is returned unchanged.
 *
 * @param filePath - The file path to process
 * @param extension - The extension to ensure (including the dot)
 * @returns The path with the specified extension
 *
 * ```typescript
 * const path = ensureFileExtension("/path/to/file", ".txt");
 * console.log(path); // "/path/to/file.txt"
 * ```
 */
declare function ensureFileExtension(filePath: AbsolutePath, extension: string): AbsolutePath;
declare function ensureFileExtension(filePath: RelativePath, extension: string): RelativePath;
declare function ensureFileExtension(filePath: AnyPath, extension: string): AnyPath;
/**
 * Converts an import URL to an absolute file system path.
 * Useful when working with ES modules and import.meta.url.
 *
 * @param importUrl - The import URL to convert
 * @returns The absolute path corresponding to the import URL
 *
 * ```typescript
 * const path = importUrlToAbsolutePath(import.meta.url);
 * console.log(path); // "/absolute/path/to/current/file"
 * ```
 */
declare const importUrlToAbsolutePath: (importUrl: string) => AbsolutePath;
/**
 * Gets the filename with extension from a path.
 *
 * @param path - The path to extract the filename from
 * @returns The filename with extension
 *
 * ```typescript
 * console.log(filename("/path/to/file.txt")); // "file.txt"
 * ```
 */
declare const filename: (path: AnyPath) => string;
/**
 * Gets the filename without extension from a path.
 *
 * @param path - The path to extract the filename from
 * @returns The filename without extension
 *
 * ```typescript
 * console.log(filenameWithoutExtension("/path/to/file.txt")); // "file"
 * ```
 */
declare const filenameWithoutExtension: (path: AnyPath) => string;
/**
 * Gets the file extension from a path.
 *
 * @param path - The path to extract the extension from
 * @returns The file extension (including the dot)
 *
 * ```typescript
 * console.log(fileExtension("/path/to/file.txt")); // ".txt"
 * ```
 */
declare const fileExtension: (path: AnyPath) => string;
/**
 * Gets the MIME type for a file based on its extension.
 *
 * @param path - The path to get the MIME type for
 * @returns The MIME type string or null if it cannot be determined
 *
 * ```typescript
 * console.log(mimeType("/path/to/image.png")); // "image/png"
 * console.log(mimeType("/path/to/unknown")); // null
 * ```
 */
declare const mimeType: (path: AnyPath) => string | null;

declare const path_bundle_addMissingExtension: typeof addMissingExtension;
declare const path_bundle_dirname: typeof dirname;
declare const path_bundle_ensureFileExtension: typeof ensureFileExtension;
declare const path_bundle_fileExtension: typeof fileExtension;
declare const path_bundle_filename: typeof filename;
declare const path_bundle_filenameWithoutExtension: typeof filenameWithoutExtension;
declare const path_bundle_importUrlToAbsolutePath: typeof importUrlToAbsolutePath;
declare const path_bundle_isAbsolute: typeof isAbsolute;
declare const path_bundle_isInPath: typeof isInPath;
declare const path_bundle_join: typeof join;
declare const path_bundle_mimeType: typeof mimeType;
declare const path_bundle_relative: typeof relative;
declare const path_bundle_removeRelativeIndicator: typeof removeRelativeIndicator;
declare const path_bundle_resolve: typeof resolve;
declare namespace path_bundle {
  export { path_bundle_addMissingExtension as addMissingExtension, path_bundle_dirname as dirname, path_bundle_ensureFileExtension as ensureFileExtension, path_bundle_fileExtension as fileExtension, path_bundle_filename as filename, path_bundle_filenameWithoutExtension as filenameWithoutExtension, path_bundle_importUrlToAbsolutePath as importUrlToAbsolutePath, path_bundle_isAbsolute as isAbsolute, path_bundle_isInPath as isInPath, path_bundle_join as join, path_bundle_mimeType as mimeType, path_bundle_relative as relative, path_bundle_removeRelativeIndicator as removeRelativeIndicator, path_bundle_resolve as resolve };
}

export { type AbsolutePath, type AnyPath, PathNotInCwdException, type RelativePath, addMissingExtension, dirname, ensureFileExtension, fileExtension, filename, filenameWithoutExtension, importUrlToAbsolutePath, isAbsolute, isInPath, join, mimeType, path_bundle as path, relative, removeRelativeIndicator, resolve };