Utility Functions

/**
 * Converts a file URL to a local file system path with normalized slashes
 * @param id - The file URL or local path to convert
 * @returns A normalized file system path
 */
function fileURLToPath(id: string | URL): string;

import { fileURLToPath } from "mlly";

// Convert file URL to path
console.log(fileURLToPath("file:///foo/bar.js")); // "/foo/bar.js"

// Handles Windows paths
console.log(fileURLToPath("file:///C:/path/")); // "C:/path"

// Pass through regular paths
console.log(fileURLToPath("/already/a/path")); // "/already/a/path"

/**
 * Converts a local file system path to a file URL
 * @param id - The file system path to convert
 * @returns The resulting file URL as a string
 */
function pathToFileURL(id: string | URL): string;

import { pathToFileURL } from "mlly";

// Convert path to file URL
console.log(pathToFileURL("/foo/bar.js")); // "file:///foo/bar.js"

// Handles Windows paths
console.log(pathToFileURL("C:\\path\\file.js")); // "file:///C:/path/file.js"

/**
 * Sanitises a component of a URI by replacing invalid characters
 * @param name - The URI component to sanitise
 * @param replacement - The string to replace invalid characters with
 * @returns The sanitised URI component
 */
function sanitizeURIComponent(name?: string, replacement?: string): string;

import { sanitizeURIComponent } from "mlly";

// Replace invalid URI characters
console.log(sanitizeURIComponent("foo:bar")); // "foo_bar"
console.log(sanitizeURIComponent("hello world", "-")); // "hello-world"

/**
 * Cleans a file path string by sanitising each component of the path
 * @param filePath - The file path to sanitise
 * @returns The sanitised file path
 */
function sanitizeFilePath(filePath?: string): string;

import { sanitizeFilePath } from "mlly";

// Sanitize problematic file path
console.log(sanitizeFilePath("C:\\te#st\\[...slug].jsx"));
// Result: "C:/te_st/_...slug_.jsx"

/**
 * Normalises a module identifier to ensure it has a protocol if missing, handling built-in modules and file paths
 * @param id - The identifier to normalise
 * @returns The normalised identifier with the appropriate protocol
 */
function normalizeid(id: string): string;

import { normalizeid } from "mlly";

// Add file protocol to paths
console.log(normalizeid("/foo/bar.js")); // "file:///foo/bar.js"

// Handle built-in modules
console.log(normalizeid("fs")); // "node:fs"

// Pass through existing protocols
console.log(normalizeid("https://example.com")); // "https://example.com"

/**
 * Loads the contents of a file from a URL into a string
 * @param url - The URL of the file to load
 * @returns A promise that resolves to the content of the file
 */
function loadURL(url: string): Promise<string>;

import { loadURL, resolve } from "mlly";

// Load file contents
const url = await resolve("./config.json", { url: import.meta.url });
const content = await loadURL(url);
console.log(JSON.parse(content));

/**
 * Converts a string of code into a data URL that can be used for dynamic imports
 * @param code - The string of code to convert
 * @returns The data URL containing the encoded code
 */
function toDataURL(code: string): string;

import { toDataURL } from "mlly";

// Convert code to data URL
const code = `export const greeting = "Hello World!";`;
const dataUrl = toDataURL(code);

// Use with dynamic import
const module = await import(dataUrl);
console.log(module.greeting); // "Hello World!"

/**
 * Checks if a module identifier matches a Node.js built-in module
 * @param id - The identifier to check
 * @returns `true` if the identifier is a built-in module, otherwise `false`
 */
function isNodeBuiltin(id?: string): boolean;

import { isNodeBuiltin } from "mlly";

console.log(isNodeBuiltin("fs")); // true
console.log(isNodeBuiltin("node:path")); // true
console.log(isNodeBuiltin("fs/promises")); // true
console.log(isNodeBuiltin("lodash")); // false

/**
 * Extracts the protocol portion of a given identifier string
 * @param id - The identifier from which to extract the protocol
 * @returns The protocol part of the identifier, or undefined if no protocol is present
 */
function getProtocol(id: string): string | undefined;

import { getProtocol } from "mlly";

console.log(getProtocol("https://example.com")); // "https"
console.log(getProtocol("file:///path/to/file")); // "file"
console.log(getProtocol("node:fs")); // "node"
console.log(getProtocol("relative/path")); // undefined