Path Utilities

/**
 * Path manipulation utilities using POSIX semantics
 * All functions preserve URI components other than path
 */
namespace Utils {
  /** Join one or more paths to a URI's path */
  function joinPath(uri: URI, ...paths: string[]): URI;
  /** Resolve paths against a URI's path */
  function resolvePath(uri: URI, ...paths: string[]): URI;
  /** Get directory name of URI's path */
  function dirname(uri: URI): URI;
  /** Get base name of URI's path */
  function basename(uri: URI): string;
  /** Get extension name of URI's path */
  function extname(uri: URI): string;
}

/**
 * Joins one or more input paths to the path of URI
 * Uses '/' as directory separator and normalizes the result
 * @param uri - Base URI to join paths to
 * @param paths - Path segments to join
 * @returns New URI with joined path, preserving other components
 */
function joinPath(uri: URI, ...paths: string[]): URI;

import { URI, Utils } from "vscode-uri";

const baseUri = URI.parse('https://example.com/api/v1');

// Join single path
const singleJoin = Utils.joinPath(baseUri, 'users');
console.log(singleJoin.toString()); // 'https://example.com/api/v1/users'

// Join multiple paths
const multiJoin = Utils.joinPath(baseUri, 'users', '123', 'profile');
console.log(multiJoin.toString()); // 'https://example.com/api/v1/users/123/profile'

// Join with leading/trailing slashes (normalized)
const normalized = Utils.joinPath(baseUri, '/users/', '/123/');
console.log(normalized.path); // '/api/v1/users/123'

// Join with relative paths
const relative = Utils.joinPath(baseUri, 'users', '..', 'admin');
console.log(relative.path); // '/api/v1/admin'

// File URI example
const fileUri = URI.file('/home/user/project');
const joined = Utils.joinPath(fileUri, 'src', 'main.ts');
console.log(joined.fsPath); // '/home/user/project/src/main.ts'

/**
 * Resolves one or more paths against the path of a URI
 * Uses '/' as directory separator and normalizes the result
 * @param uri - Base URI to resolve paths against
 * @param paths - Path segments to resolve
 * @returns New URI with resolved path, preserving other components
 */
function resolvePath(uri: URI, ...paths: string[]): URI;

import { URI, Utils } from "vscode-uri";

const baseUri = URI.parse('file:///home/user/project/src');

// Resolve relative path
const relative = Utils.resolvePath(baseUri, '../config/settings.json');
console.log(relative.path); // '/home/user/project/config/settings.json'

// Resolve absolute path
const absolute = Utils.resolvePath(baseUri, '/etc/hosts');
console.log(absolute.path); // '/etc/hosts'

// Resolve complex relative path
const complex = Utils.resolvePath(baseUri, '../..', 'other-project', 'file.txt');
console.log(complex.path); // '/home/user/other-project/file.txt'

// HTTP URI example
const httpUri = URI.parse('https://api.example.com/v1/users');
const resolved = Utils.resolvePath(httpUri, '../admin/settings');
console.log(resolved.toString()); // 'https://api.example.com/v1/admin/settings'

/**
 * Returns a URI where the path is the directory name of the input URI
 * Similar to Unix dirname command, ignoring trailing separators
 * @param uri - Input URI
 * @returns New URI with directory path, or original URI if path is empty
 */
function dirname(uri: URI): URI;

import { URI, Utils } from "vscode-uri";

// File path
const fileUri = URI.file('/home/user/documents/file.txt');
const dir = Utils.dirname(fileUri);
console.log(dir.fsPath); // '/home/user/documents'

// HTTP path
const httpUri = URI.parse('https://example.com/api/v1/users/123');
const httpDir = Utils.dirname(httpUri);
console.log(httpDir.path); // '/api/v1/users'

// Root directory
const rootUri = URI.file('/file.txt');
const rootDir = Utils.dirname(rootUri);
console.log(rootDir.path); // '/'

// Already directory (with trailing slash)
const dirUri = URI.parse('https://example.com/path/');
const dirParent = Utils.dirname(dirUri);
console.log(dirParent.path); // '/path' (same as input without trailing slash)

/**
 * Returns the last segment of the path of a URI
 * Similar to Unix basename command, ignoring trailing separators
 * @param uri - Input URI
 * @returns Base name of the URI's path, or empty string if no segments
 */
function basename(uri: URI): string;

import { URI, Utils } from "vscode-uri";

// File with extension
const fileUri = URI.file('/home/user/documents/report.pdf');
const filename = Utils.basename(fileUri);
console.log(filename); // 'report.pdf'

// Directory path
const dirUri = URI.parse('https://example.com/api/v1/users');
const dirname = Utils.basename(dirUri);
console.log(dirname); // 'users'

// Path with trailing slash
const trailingUri = URI.parse('file:///home/user/folder/');
const folderName = Utils.basename(trailingUri);
console.log(folderName); // 'folder'

// Root path
const rootUri = URI.file('/');
const rootName = Utils.basename(rootUri);
console.log(rootName); // '' (empty string)

// Single segment
const singleUri = URI.parse('file:///filename.txt');
const single = Utils.basename(singleUri);
console.log(single); // 'filename.txt'

/**
 * Returns the extension name of the path of a URI
 * Similar to Unix extname command, including the leading dot
 * @param uri - Input URI
 * @returns Extension name including dot, or empty string if no extension
 */
function extname(uri: URI): string;

import { URI, Utils } from "vscode-uri";

// File with extension
const jsFile = URI.file('/project/src/main.js');
const jsExt = Utils.extname(jsFile);
console.log(jsExt); // '.js'

// File with multiple dots
const configFile = URI.file('/project/config.prod.json');
const configExt = Utils.extname(configFile);
console.log(configExt); // '.json'

// File without extension
const noExt = URI.file('/project/README');
const emptyExt = Utils.extname(noExt);
console.log(emptyExt); // ''

// Hidden file with extension
const hiddenFile = URI.file('/home/user/.gitignore');
const hiddenExt = Utils.extname(hiddenFile);
console.log(hiddenExt); // ''

// Directory path
const dirUri = URI.parse('https://example.com/api/v1');
const dirExt = Utils.extname(dirUri);
console.log(dirExt); // ''

// Complex file path
const complexFile = URI.file('/path/file.backup.2023.tar.gz');
const complexExt = Utils.extname(complexFile);
console.log(complexExt); // '.gz'

import { URI, Utils } from "vscode-uri";

const messy = URI.parse('file:///project//src/./components/../utils//file.js');
const clean = Utils.joinPath(messy); // Normalize by joining with no additional paths
console.log(clean.path); // '/project/src/utils/file.js'